Skip to content

Terraform Troubleshooting

For the shared debugging workflow, start with Debugging and Troubleshooting. It explains Debug Events, instance debug, and the relationship between workflow state and live resource state.

Terraform Execution Model and Debugging Expectations

Omnistrate executes Terraform and OpenTofu autonomously as part of the instance workflow. The platform does not support a manual review or approval gate for terraform plan before terraform apply.

The recommended operating model is:

  1. Test the change in a lower environment first.
  2. Pin the Terraform source with a Git tag or commit SHA.
  3. Promote the same tested artifacts to production.

Troubleshooting Terraform Deployments

If a Terraform-based deployment fails, start from Debug Events to identify whether the failure happened during artifact rendering, terraform plan, terraform apply, or a later dependent resource. Then inspect the Terraform resource’s operation history with:

omnistrate-ctl instance debug <instance-id>

Use the instance debug output to investigate:

  1. Rendered Terraform files after Omnistrate substitutes system parameters, API parameters, secrets, and dependency outputs.
  2. Captured terraform plan output to confirm Terraform intended to create, update, or delete the resources you expected.
  3. Terraform apply logs for cloud provider errors such as missing IAM permissions, quota limits, unavailable regions or SKUs, invalid networking inputs, and resource name conflicts.
  4. Provider configuration and credentials, especially when using custom Terraform permissions, BYOC onboarding, control-plane-targeted Terraform, or Nebius service-account authentication.
  5. Terraform outputs that feed downstream Helm, Operator, Kustomize, or Terraform resources.

The shared Terraform Troubleshooting Checklist contains the same checks alongside the other deployment strategies.

If the rendered artifacts are wrong, update the Plan spec, Terraform source, parameter mappings, or Git reference and publish a new Plan version before retrying. If the plan looks correct but apply fails, fix the cloud-side permission, quota, naming, or provider issue and retry the workflow when the same released artifacts are still valid.

Restarting a Workflow vs Publishing a New Version

Restarting a failed workflow is best for transient issues when you want to retry the same released artifacts again.

If you changed the Plan specification, a parameterDependencyMap, the referenced Git branch/tag/commit, or Terraform or Helm artifacts that must be re-rendered, publish a new Plan version and trigger a fresh workflow instead of restarting the old one.

As a rule of thumb, assume a workflow restart retries the artifacts already captured for that workflow. For deterministic behavior, pin the Git source to a tag or commit SHA.