Run States and Stages

Each run passes through several stages of action (pending, plan, cost estimation, policy check, apply, and completion), and Terraform Cloud shows the progress through those stages as run states.

In the list of workspaces on Terraform Cloud's main page, each workspace shows the state of the run it's currently processing. (Or, if no run is in progress, the state of the most recent completed run.)

1. The Pending Stage

States in this stage:

• Pending: Terraform Cloud hasn't started action on a run yet. Terraform Cloud processes each workspace's runs in the order they were queued, and a run remains pending until every run before it has completed.

Leaving this stage:

• If the user discards the run before it starts, the run does not continue (Discarded state).
• If the run is first in the queue, it proceeds automatically to the plan stage (Planning state).

2. The Fetching Stage

Terraform Cloud may need to fetch the configuration from VCS prior to starting the plan. Terraform Cloud automatically archives configuration versions created through VCS when all runs are complete and then re-fetches the files for subsequent runs.

States in this stage:

• Fetching: If Terraform Cloud has not yet fetched the configuration from VCS, the run will go into this state until the configuration is available.

Leaving this stage:

• If Terraform Cloud encounters an error when fetching the configuration from VCS, the run does not continue (Plan Errored state).
• If Terraform successfully fetches the configuration, the run moves to the next stage.

3. The Pre-Plan Stage

The pre-plan phase only occurs if there are enabled run tasks in the workspace that are configured to begin before Terraform creates the plan. Terraform Cloud sends information about the run to the configured external system and waits for a passed or failed response to determine whether the run can continue. The information sent to the external system includes the configuration version of the run.

All runs can enter this phase, including speculative plans.

States in this stage:

• Pre-plan running: Terraform Cloud is waiting for a response from the configured external system(s).
  • External systems must respond initially with a 200 OK acknowledging the request is in progress. After that, they have 10 minutes to return a status of passed, running, or failed. If the timeout expires, Terraform Cloud assumes that the run tasks is in the failed status.

Leaving this stage:

• If any mandatory tasks failed, the run skips to completion (Plan Errored state).
• If any advisory tasks failed, the run proceeds to the Planning state, with a visible warning regarding the failed task.
• If a combination of mandatory and advisory tasks are configured for a single run, Terraform takes the most restrictive action. For example, the run fails if there are two advisory tasks that succeed and one mandatory task that fails.
• If a user canceled the run, the run ends in the Canceled state.

4. The Plan Stage

A run goes through different steps during the plan stage depending on whether or not Terraform Cloud needs to fetch the configuration from VCS. Terraform Cloud automatically archives configuration versions created through VCS when all runs are complete and then re-fetches the files for subsequent runs.

States in this stage:

• Planning: Terraform Cloud is currently running terraform plan.
• Needs Confirmation: terraform plan has finished. Runs sometimes pause in this state, depending on the workspace and organization settings.

Leaving this stage:

• If the terraform plan command failed, the run does not continue (Plan Errored state).
• If a user canceled the plan by pressing the "Cancel Run" button, the run does not continue (Canceled state).
• If the plan succeeded with no changes and neither cost estimation nor Sentinel policy checks will be done, Terraform Cloud considers the run complete (Planned and Finished state).
• If the plan succeeded and requires changes:
  • If cost estimation is enabled, the run proceeds automatically to the cost estimation stage.
  • If cost estimation is disabled and Sentinel policies are enabled, the run proceeds automatically to the policy check stage.
  • If there are no Sentinel policies and the plan can be auto-applied, the run proceeds automatically to the apply stage. Plans can be auto-applied if the auto-apply setting is enabled on the workspace and the plan was queued by a new VCS commit or by a user with permission to apply runs. (More about permissions.)
  • If there are no Sentinel policies and Terraform Cloud cannot auto-apply the plan, the run pauses in the Needs Confirmation state until a user with permission to apply runs takes action. (More about permissions.) If an authorized user approves the apply, the run proceeds to the apply stage. If an authorized user rejects the apply, the run does not continue (Discarded state).

5. The Post-Plan Stage

The post-plan phase executes any configured run tasks after the plan is complete, so it only occurs if there are run tasks enabled for the workspace. All runs can enter this phase, including speculative plans. During this phase, Terraform Cloud sends information about the run to the configured external system and waits for a passed or failed response to determine whether the run can continue.

States in this stage:

• Post-plan running: Terraform Cloud is waiting for a response from the configured external system(s).
  • External systems must respond initially with a 200 OK acknowledging the request is in progress. After that, they have 10 minutes to return a status of passed, running, or failed, or the timeout will expire and the task will be assumed to be in the failed status.

Leaving this stage:

• If any mandatory tasks failed, the run skips to completion (Plan Errored state).
• If any advisory tasks failed, the run proceeds to the Applying state, with a visible warning regarding the failed task.
• If a combination of mandatory and advisory tasks are configured for a single run, Terraform will take the most restrictive action. This means that if there are two advisory tasks that succeed and one mandatory task that failed, the run will fail. If one mandatory task succeeds and two advisory tasks fail, the run will succeed with a warning.
• If a user canceled the run, the run ends in the Canceled state.

6. The Cost Estimation Stage

This stage only occurs if cost estimation is enabled. After a successful terraform plan, Terraform Cloud uses plan data to estimate costs for each resource found in the plan.

States in this stage:

• Cost Estimating: Terraform Cloud is currently estimating the resources in the plan.
• Cost Estimated: The cost estimate completed.

Leaving this stage:

• If cost estimation succeeded or errors, the run moves to the next stage.
• If there are no policy checks or applies, the run does not continue (Planned and Finished state).

7. The Policy Check Stage

This stage only occurs if Sentinel policies are enabled. After a successful terraform plan, Terraform Cloud checks whether the plan obeys policy to determine whether it can be applied.

States in this stage:

• Policy Check: Terraform Cloud is currently checking the plan against the organization's policies.
• Policy Override: The policy check finished, but a soft-mandatory policy failed, so an apply cannot proceed without approval from a user with permission to manage policy overrides for the organization. (More about permissions.) The run pauses in this state.
• Policy Checked: The policy check succeeded, and Sentinel will allow an apply to proceed. The run sometimes pauses in this state, depending on workspace settings.

Leaving this stage:

• If any hard-mandatory policies failed, the run does not continue (Plan Errored state).
• If any soft-mandatory policies failed, the run pauses in the Policy Override state.
  • If a user with permission to manage policy overrides, overrides the failed policy, the run proceeds to the Policy Checked state. (More about permissions.)
  • If a user with permission to apply runs discards the run, the run does not continue (Discarded state). (More about permissions.)
• If the run reaches the Policy Checked state (no mandatory policies failed, or soft-mandatory policies were overridden):
  • If the plan can be auto-applied, the run proceeds automatically to the apply stage. Plans can be auto-applied if the auto-apply setting is enabled on the workspace and the plan was queued by a new VCS commit or by a user with permission to apply runs. (More about permissions.)
  • If the plan can't be auto-applied, the run pauses in the Policy Checked state until a user with permission to apply runs takes action. (More about permissions.) The run proceeds to the apply stage if they approve the apply, or does not continue (Discarded state) if they reject the apply.

8. The Apply Stage

States in this stage:

• Applying: Terraform Cloud is currently running terraform apply.

Leaving this stage:

After applying, the run proceeds automatically to completion.

• If the apply succeeded, the run ends in the Applied state.
• If the apply failed, the run ends in the Apply Errored state.
• If a user canceled the apply by pressing the "Cancel Run" button, the run ends in the Canceled state.

9. Completion

A run is considered completed if it finishes applying, if any part of the run fails, if there's nothing to do, or if a user chooses not to continue. Once a run is completed, the next run in the queue can enter the plan stage.

States in this stage:

• Applied: The run was successfully applied.
• Planned and Finished: terraform plan's output already matches the current infrastructure state, so terraform apply doesn't need to do anything.
• Apply Errored: The terraform apply command failed, possibly due to a missing or misconfigured provider or an illegal operation on a provider.
• Plan Errored: The terraform plan command failed (usually requiring fixes to variables or code), or a hard-mandatory Sentinel policy failed. The run cannot be applied.
• Discarded: A user chose not to continue this run.
• Canceled: A user interrupted the terraform plan or terraform apply command with the "Cancel Run" button.