github.com/danp/terraform@v0.9.5-0.20170426144147-39d740081351/website/source/docs/enterprise/runs/how-runs-execute.html.md (about)

     1  ---
     2  layout: "enterprise"
     3  page_title: "Execution - Runs - Terraform Enterprise"
     4  sidebar_current: "docs-enterprise-runs-execute"
     5  description: |-
     6    How runs execute in Terraform Enterprise.
     7  ---
     8  
     9  # How Terraform Runs Execute
    10  
    11  This briefly covers the internal process of running Terraform plan and applies.
    12  It is not necessary to know this information, but may be valuable to help
    13  understand implications of running or debugging failed runs.
    14  
    15  ## Steps of Execution
    16  
    17  1. A set of Terraform configuration and directory of files is uploaded via Terraform Push or GitHub
    18  2. Terraform Enterprise creates a version of the Terraform configuration and waits for the upload
    19  to complete. At this point, the version will be visible in the UI even if the upload has
    20  not completed
    21  3. Once the upload finishes, Terraform Enterprise creates a run and queues a `terraform plan`
    22  4. In the run environment, the package including the files and Terraform
    23  configuration are downloaded
    24  5. `terraform plan` is run against the configuration in the run environment
    25  6. Logs are streamed into the UI and stored
    26  7. The `.tfplan` file created in the plan is uploaded and stored
    27  8. Once the plan completes, the environment is torn down and status is
    28  updated in the UI
    29  9. The plan then requires confirmation by an operator. It can optionally
    30  be discarded and ignored at this stage
    31  10. Once confirmed, the run then executes a `terraform apply` in a new
    32  environment against the saved `.tfplan` file
    33  11. The logs are streamed into the UI and stored
    34  12. Once the apply completes, the environment is torn down, status is
    35  updated in the UI and changed state is saved back
    36  
    37  Note: In the case of a failed apply, it's safe to re-run. This is possible
    38  because Terraform saves partial state and can "pick up where it left off".
    39  
    40  ### Customizing Terraform Execution
    41  
    42  As described in the steps above, Terraform will be run against your configuration
    43  when changes are pushed via GitHub, `terraform push`, or manually queued in the
    44  UI. There are a few options available to customize the execution of Terraform.
    45  These are:
    46  
    47  - The directory that contains your environment's Terraform configuration can be customized
    48  to support directory structures with more than one set of Terraform configuration files.
    49  To customize the directory for your Environment, set the _Terraform Directory_
    50  property in the [_GitHub Integration_](/docs/enterprise/vcs/github.html) settings for your environment. This is equivalent to
    51  passing the `[dir]` argument when running Terraform in your local shell.
    52  - The directory in which Terraform is executed from can be customized to support directory
    53  structures with nested sub-directories or configurations that use Terraform modules with
    54  relative paths. To customize the directory used for Terraform execution in your Environment, set the `TF_ATLAS_DIR`
    55  [environment variable](/docs/enterprise/runs/variables-and-configuration.html#environment-variables)
    56  to the relative path of the directory - ie. `terraform/production`. This is equivalent to
    57  changing directories to the appropriate path in your local shell and then executing Terraform.