119 lines
5.1 KiB
Markdown
Executable File
119 lines
5.1 KiB
Markdown
Executable File
---
|
|
layout: "runs"
|
|
page_title: "Runs: Starting"
|
|
sidebar_current: "docs-enterprise-runs-starting"
|
|
description: |-
|
|
How to start runs in Terraform Enterprise.
|
|
---
|
|
|
|
|
|
# Starting Terraform Runs in Atlas
|
|
|
|
There are a variety of ways to queue a Terraform run in Atlas. In addition to
|
|
`terraform push`, you can connect your [environment](/help/glossary#environment)
|
|
to GitHub and have Atlas queue Terraform runs based on new commits. Atlas can
|
|
also intelligently queue new runs when linked artifacts are uploaded or changed.
|
|
Remember from the [previous section about Terraform runs](/help/terraform/runs)
|
|
that it is safe to trigger many plans without consequence since Terraform plans
|
|
do not change infrastructure.
|
|
|
|
|
|
## Terraform Push
|
|
|
|
Terraform `push` is a [Terraform command](https://terraform.io/docs/commands/push.html)
|
|
that packages and uploads a set of Terraform configuration and directory to Atlas. This then creates a run
|
|
in Atlas, which performs `terraform plan` and `terraform apply` against the uploaded
|
|
configuration.
|
|
|
|
The directory is included in order to run any associated provisioners,
|
|
that might use local files. For example, a remote-exec provisioner
|
|
that executes a shell script.
|
|
|
|
By default, everything in your directory is uploaded as part of the push.
|
|
|
|
However, it's not always the case that the entire directory should be uploaded. Often,
|
|
temporary or cache directories and files like `.git`, `.tmp` will be included by default. This
|
|
can cause Atlas to fail at certain sizes and should be avoided. You can
|
|
specify [exclusions](https://terraform.io/docs/commands/push.html) to avoid this situation.
|
|
|
|
Terraform also allows for a [VCS option](https://terraform.io/docs/commands/push.html#_vcs_true)
|
|
that will detect your VCS (if there is one) and only upload the files that are tracked by the VCS. This is
|
|
useful for automatically excluding ignored files. In a VCS like git, this
|
|
basically does a `git ls-files`.
|
|
|
|
|
|
## GitHub Webhooks
|
|
|
|
Optionally, GitHub can be used to import Terraform configuration. When used
|
|
within an organization, this can be extremely valuable for keeping differences
|
|
in environments and last mile changes from occurring before an upload to Atlas.
|
|
|
|
After you have [connected your GitHub account to Atlas](/settings/connections),
|
|
you can connect your [environment](/help/glossary#environment) to the target
|
|
GitHub repository. The GitHub repository will be linked to the Atlas Terraform
|
|
configuration, and GitHub will start sending webhooks to Atlas. Certain
|
|
GitHub webhook events, detailed below, will cause the repository to be
|
|
automatically ingressed into Atlas and stored, along with references to the
|
|
GitHub commits and authorship information.
|
|
|
|
Currently, an environment must already exist to be connected to GitHub. You can
|
|
create the environment with `terraform push`, detailed above, and then link it
|
|
to GitHub.
|
|
|
|
Each ingress will trigger a Terraform plan. If you have auto-apply enabled then
|
|
the plan will also be applied.
|
|
|
|
You can disable an ingress by adding the text `[atlas skip]` or `[ci skip]` to
|
|
your commit message.
|
|
|
|
Supported GitHub webhook events:
|
|
|
|
- pull_request (on by default)
|
|
- ingress when opened or reopened
|
|
- ingress when synchronized (new commits are pushed to the branch)
|
|
- push (on by default)
|
|
- ingress when a tag is created
|
|
- ingress when the default branch is updated
|
|
- note: the default branch is either configured on your configuration's
|
|
integrations tab in Atlas, or if that is blank it is the GitHub
|
|
repository's default branch
|
|
- create (off by default)
|
|
- ingress when a tag is created
|
|
- note: if you want to only run on tag creation, turn on create events and
|
|
turn off push events
|
|
|
|
## Artifact Uploads
|
|
|
|
Upon successful completion of a Terraform run, Atlas parses the remote state and
|
|
detects any [Atlas artifacts](/help/terraform/artifacts/artifact-provider) that
|
|
were referenced. When new versions of those referenced artifacts are uploaded
|
|
to Atlas, you have the option to automatically queue a new Terraform run.
|
|
|
|
For example, consider the following Terraform configuration which references an
|
|
Atlas artifact named "worker":
|
|
|
|
resource "aws_instance" "worker" {
|
|
ami = "${atlas_artifact.worker.metadata_full.region-us-east-1}"
|
|
instance_type = "m1.small"
|
|
}
|
|
|
|
When a new version of the Atlas artifact "worker" is uploaded either manually
|
|
or as the output of a [Packer build](/help/packer/builds/starting.html), Atlas
|
|
can automatically trigger a Terraform plan with this new artifact version.
|
|
You can enable this feature on a per-environment basis from the
|
|
[environment](/help/glossary#environment) settings page in Atlas.
|
|
|
|
Combined with
|
|
[Terraform auto apply](/help/terraform/runs/automatic-applies), you can
|
|
continuously deliver infrastructure using Terraform and Atlas.
|
|
|
|
## Terraform Plugins
|
|
|
|
If you are using a custom [Terraform Plugin](https://www.terraform.io/docs/plugins/index.html)
|
|
binary for a provider or provisioner that's not currently in a released
|
|
version of Terraform, you can still use this in Atlas.
|
|
|
|
All you need to do is include a Linux AMD64 binary for the plugin in the
|
|
directory in which Terraform commands are run from; Atlas will then use
|
|
the plugin the next time you `terraform push` or ingress from GitHub.
|