terraform/website/source/docs/enterprise/runs/index.html.md

71 lines
3.0 KiB
Markdown
Raw Normal View History

2017-03-16 20:42:33 +01:00
---
2017-03-17 18:16:46 +01:00
layout: "runs"
2017-03-17 00:06:46 +01:00
page_title: "About Terraform Enterprise Runs"
sidebar_current: "docs-enterprise-runs"
description: |-
A "run" in Atlas represents the logical grouping of two Terraform steps - a "plan" and an "apply".
2017-03-16 20:42:33 +01:00
---
2017-03-17 00:06:46 +01:00
# About Terraform Enterprise Runs
2017-03-16 20:42:33 +01:00
2017-03-17 00:06:46 +01:00
A "run" represents the logical grouping of two Terraform steps - a
2017-03-16 20:42:33 +01:00
"plan" and an "apply". The distinction between these two phases of a Terraform
run are documented below.
2017-03-17 00:06:46 +01:00
When a [new run is created](/docs/enterprise/runs/starting.html), Terraform Enterprise automatically
2017-03-16 20:42:33 +01:00
queues a Terraform plan. Because a plan does not change the state of
infrastructure, it is safe to execute a plan multiple times without
consequence. An apply executes the output of a plan and actively changes
2017-03-17 00:06:46 +01:00
infrastructure. To prevent race conditions, the platform will only execute one
2017-03-16 20:42:33 +01:00
plan/apply at a time (plans for validating GitHub Pull Requests are allowed to
happen concurrently, as they do not modify state). You can read more about
Terraform plans and applies below.
## Plan
2017-03-17 00:06:46 +01:00
During the plan phase of a run, the command `terraform plan` is executed.
2017-03-16 20:42:33 +01:00
Terraform performs a refresh and then determines what actions are necessary to
reach the desired state specified in the Terraform configuration files. A
2017-03-20 19:44:03 +01:00
successful plan outputs an executable file that is securely stored in Terrafrom Enterprise
2017-03-16 20:42:33 +01:00
and may be used in the subsequent apply.
2017-03-17 00:06:46 +01:00
Terraform plans do not change the state of infrastructure, so it is
2017-03-16 20:42:33 +01:00
safe to execute a plan multiple times. In fact, there are a number of components
2017-03-17 00:06:46 +01:00
that can trigger a Terraform plan. You can read more about this in the
2017-03-17 00:48:57 +01:00
[starting runs](/docs/enterprise/runs/starting.html) section.
2017-03-16 20:42:33 +01:00
## Apply
2017-03-17 00:06:46 +01:00
During the apply phase of a run, the command `terraform apply` is executed
2017-03-16 20:42:33 +01:00
with the executable result of the prior Terraform plan. This phase **can change
infrastructure** by applying the changes required to reach the desired state
specified in the Terraform configuration file.
While Terraform plans are safe to run multiple times, Terraform applies often
2017-03-17 00:06:46 +01:00
change active infrastructure. Because of this, the default behavior
2017-03-16 20:42:33 +01:00
is to require user confirmation as part of the
2017-03-17 00:06:46 +01:00
[Terraform run execution](/docs/enterprise/runs/how-runs-execute.html). Upon
2017-03-20 19:44:03 +01:00
user confirmation, the Terraform apply will be queued and executed. It is also
possible to configure
[automatic applies](/docs/enterprise/runs/automatic-applies.html), but this option is
2017-03-16 20:42:33 +01:00
disabled by default.
## Environment Locking
2017-03-17 00:06:46 +01:00
During run execution, the environment will lock to prevent other plans
2017-03-16 20:42:33 +01:00
and applies from executing simultaneously. When the run completes, the next
pending run, if any, will be started.
An administrator of the environment can also manually lock the environment, for
example during a maintenance period.
You can see the lock status of an environment, and lock/unlock the environment
by visiting that environment's settings page.
## Notifications
To receive alerts when user confirmation is needed or for any other phase of the
run process, you can
2017-03-17 00:06:46 +01:00
[enable run notifications](/docs/enterprise/runs/notifications.html) for your
2017-03-16 20:42:33 +01:00
organization or environment.