Skip to content

README.md

Latest commit

 

History

History
145 lines (120 loc) · 5.08 KB

README.md

File metadata and controls

145 lines (120 loc) · 5.08 KB
Raw

Local Import Loop

This example exercises every resource type currently registered for Terraform Query and imports the discovered objects into disposable local Terraform state. It covers:

  • ona_announcement_banner
  • ona_automation
  • ona_integration
  • ona_github_app_integration
  • ona_runner
  • ona_runner_llm_integration
  • ona_scm_integration
  • ona_git_authentication
  • ona_environment_class
  • ona_group_membership
  • ona_team_membership
  • ona_custom_domain
  • ona_group
  • ona_team
  • ona_sso_configuration
  • ona_terms_of_service
  • ona_oidc_config
  • ona_organization_policies
  • ona_organization_role_assignment
  • ona_project
  • ona_warm_pool
  • ona_scim_configuration
  • ona_security_policy
  • ona_secret
  • ona_service_account
  • ona_skill

The example only generates imports for objects that already exist and can be represented by the provider. To exercise the complete workflow, use an Ona organization containing at least one importable object of each type.

For a repeatable fixture, apply the local development loop first. Its default configuration creates runners, SCM integrations, an environment class, a project, and a warm pool. The import loop can also discover other matching objects in the organization, so review the generated configuration before applying it.

Git authentication is opt-in in the local development loop. Enable its ona_git_authentication.devloop resource and supply the ephemeral personal access token when you need a repeatable Git-authentication import fixture.

Prepare the Local Provider

From the repository root, build the provider and configure a development override:

mkdir -p .bin
go build -o .bin/terraform-provider-ona .
cat >terraformrc <<EOF
provider_installation {
  dev_overrides {
    "gitpod-io/ona" = "${PWD}/.bin"
  }
  direct {}
}
EOF

export ONA_TOKEN="<service-account-or-personal-access-token>"
export ONA_HOST="${ONA_HOST:-https://app.gitpod.io}"
export TF_CLI_CONFIG_FILE="${PWD}/terraformrc"

Do not commit .bin/, terraformrc, credentials, generated configuration, plans, or Terraform state.

Discover and Import Every Supported Type

Run Query to generate resource blocks and identity-based import blocks for all registered list resources. Set TF_VAR_group_membership_group_id to a customer-managed group whose user and service-account memberships should be included. Set TF_VAR_team_membership_team_id to a team whose user memberships should be included:

export TF_VAR_group_membership_group_id="<group-id>"
export TF_VAR_team_membership_team_id="<team-id>"
terraform -chdir=dev/local-importloop query \
  -generate-config-out=generated.tf

An organization-owned GitHub App can appear in both ona_integration and ona_github_app_integration results. Keep only the dedicated resource and its import block for each App; remove the matching generic resource and import block before applying. Leave App credentials and credentials_version unset when adopting existing Apps. See the resource guidance for migration from an existing generic resource.

The dedicated Query uses the dashboard's App metadata comparison. An integration matching the shared definition's App ID, slug, and client ID is excluded even when its credentials were configured locally.

Review the generated configuration, then create and inspect the import plan:

terraform -chdir=dev/local-importloop plan \
  -input=false \
  -out=import.tfplan
terraform -chdir=dev/local-importloop show import.tfplan

Proceed only when the plan contains imports and no remote create, update, replace, or delete actions. Apply the saved plan and verify that the imported configuration is stable:

terraform -chdir=dev/local-importloop apply -input=false import.tfplan
terraform -chdir=dev/local-importloop plan -detailed-exitcode -input=false

The final command exits with status 0 when the imported configuration is a no-op. Status 1 means Terraform failed, while status 2 means Terraform still proposes changes and the generated configuration or provider mapping needs investigation.

Terraform Query is read-only. Applying the generated import blocks writes only the local state in this directory, but that state then represents real remote objects. When the local development loop supplied the fixtures, both directories temporarily track the same objects. Never run terraform destroy from the import loop.

Reset the import loop by removing its generated configuration, saved plan, and state together without running another plan or apply:

rm -f \
  dev/local-importloop/generated.tf \
  dev/local-importloop/import.tfplan \
  dev/local-importloop/terraform.tfstate \
  dev/local-importloop/terraform.tfstate.backup

After removing the import-loop state, the local development loop remains the sole owner of its fixtures and can destroy them normally.

The list-resource coverage test fails when a future Query-enabled resource is registered without a matching block in query.tfquery.hcl.