Skip to content

Latest commit

 

History

History
303 lines (199 loc) · 9.75 KB

using-atlantis.md

File metadata and controls

303 lines (199 loc) · 9.75 KB
Raw

Using Atlantis

Atlantis triggers commands via pull request comments. Help Command

::: tip You can use following executable names.

  • atlantis help
  • run help
    • run is a global executable name.
  • @GithubUser help
    • @GithubUser is the VCS host user which you connected to Atlantis by user token. :::

Currently, Atlantis supports the following commands.

atlantis help

atlantis help

Explanation

View help

atlantis version

atlantis version

Explanation

Print the output of 'terraform version'.

atlantis plan

atlantis plan [options] -- [terraform plan flags]

Explanation

Runs terraform plan on the pull request's branch. You may wish to re-run plan after Atlantis has already done so if you've changed some resources manually.

Examples

# Runs plan for any projects that Atlantis thinks were modified.
# If an `atlantis.yaml` file is specified, runs plan on the projects that
# were modified as determined by the `when_modified` config.
atlantis plan

# Runs plan in the root directory of the repo with workspace `default`.
atlantis plan -d .

# Runs plan in the `project1` directory of the repo with workspace `default`
atlantis plan -p project1

# Runs plan in the root directory of the repo with workspace `staging`
atlantis plan -w staging

Options

  • -d directory Which directory to run plan in relative to root of repo. Use . for root.
    • Ex. atlantis plan -d child/dir
  • -p project Which project to run plan for. Refers to the name of the project configured in the repo's atlantis.yaml file. Cannot be used at same time as -d or -w because the project defines this already.
  • -w workspace Switch to this Terraform workspace before planning. Defaults to default. Ignore this if Terraform workspaces are unused.
  • --verbose Append Atlantis log to comment.

::: warning NOTE A atlantis plan (without flags), like autoplans, discards all plans previously created with atlantis plan -p/-d/-w :::

Additional Terraform flags

If terraform plan requires additional arguments, like -target=resource or -var 'foo=bar' or -var-file myfile.tfvars you can append them to the end of the comment after --, ex.

atlantis plan -d dir -- -var foo='bar'

If you always need to append a certain flag, see Custom Workflow Use Cases.

Using the -destroy Flag

Example

To perform a destructive plan that will destroy resources you can use the -destroy flag like this:

atlantis plan -- -destroy
atlantis plan -d dir -- -destroy

::: warning NOTE The -destroy flag generates a destroy plan, If this plan is applied it can result in data loss or service disruptions. Ensure that you have thoroughly reviewed your Terraform configuration and intend to remove the specified resources before using this flag. :::

atlantis apply

atlantis apply [options] -- [terraform apply flags]

Explanation

Runs terraform apply for the plan that matches the directory/project/workspace.

::: tip If no directory/project/workspace is specified, ex. atlantis apply, this command will apply all unapplied plans from this pull request. This includes all projects that have been planned manually with atlantis plan -p/-d/-w since the last autoplan or atlantis plan command. For Atlantis commands to work, Atlantis needs to know the location where the plan file is. For that, you can use $PLANFILE which will contain the path of the plan file to be used in your custom steps. i.e terraform plan -out $PLANFILE :::

Examples

# Runs apply for all unapplied plans from this pull request.
atlantis apply

# Runs apply in the root directory of the repo with workspace `default`.
atlantis apply -d .

# Runs apply in the `project1` directory of the repo with workspace `default`
atlantis apply -p project1

# Runs apply in the root directory of the repo with workspace `staging`
atlantis apply -w staging

Options

  • -d directory Apply the plan for this directory, relative to root of repo. Use . for root.
  • -p project Apply the plan for this project. Refers to the name of the project configured in the repo's atlantis.yaml file. Cannot be used at same time as -d or -w.
  • -w workspace Apply the plan for this Terraform workspace. Ignore this if Terraform workspaces are unused.
  • --auto-merge-disabled Disable automerge for this apply command.
  • --auto-merge-method method Specify which merge method use for the apply command if automerge is enabled. Implemented only for GitHub.
  • --verbose Append Atlantis log to comment.

Additional Terraform flags

Because Atlantis under the hood is running terraform apply plan.tfplan, any Terraform options that would change the plan are ignored, ex:

  • -target=resource
  • -var 'foo=bar'
  • -var-file=myfile.tfvars

They're ignored because they can't be specified for an already generated planfile. If you would like to specify these flags, do it while running atlantis plan.

atlantis import

atlantis import [options] ADDRESS ID -- [terraform import flags]

Explanation

Runs terraform import that matches the directory/project/workspace. This command discards the terraform plan result. After an import and before an apply, another atlantis plan must be run again.

To allow the import command requires --allow-commands configuration.

Examples

# Runs import
atlantis import ADDRESS ID

# Runs import in the root directory of the repo with workspace `default`
atlantis import -d . ADDRESS ID

# Runs import in the `project1` directory of the repo with workspace `default`
atlantis import -p project1 ADDRESS ID

# Runs import in the root directory of the repo with workspace `staging`
atlantis import -w staging ADDRESS ID

::: tip

  • If import for_each resources, it requires a single quoted address.
    • ex. atlantis import 'aws_instance.example["foo"]' i-1234567890abcdef0 :::

Options

  • -d directory Import a resource for this directory, relative to root of repo. Use . for root.
  • -p project Import a resource for this project. Refers to the name of the project configured in the repo's atlantis.yaml repo configuration file. This cannot be used at the same time as -d or -w.
  • -w workspace Import a resource for a specific Terraform workspace. Ignore this if Terraform workspaces are unused.

Additional Terraform flags

If terraform import requires additional arguments, like -var 'foo=bar' or -var-file myfile.tfvars append them to the end of the comment after --, e.g.

atlantis import -d dir 'aws_instance.example["foo"]' i-1234567890abcdef0 -- -var foo='bar'

If a flag is needed to be always appended, see Custom Workflow Use Cases.

atlantis state rm

atlantis state [options] rm ADDRESS... -- [terraform state rm flags]

Explanation

Runs terraform state rm that matches the directory/project/workspace. This command discards the terraform plan result. After run state rm and before an apply, another atlantis plan must be run again.

To allow the state command requires --allow-commands configuration.

Examples

# Runs state rm
atlantis state rm ADDRESS1 ADDRESS2

# Runs state rm in the root directory of the repo with workspace `default`
atlantis state -d . rm ADDRESS

# Runs state rm in the `project1` directory of the repo with workspace `default`
atlantis state -p project1 rm ADDRESS

# Runs state rm in the root directory of the repo with workspace `staging`
atlantis state -w staging rm ADDRESS

::: tip

  • If run state rm to for_each resources, it requires a single quoted address.
    • ex. atlantis state rm 'aws_instance.example["foo"]' :::

Options

  • -d directory Run state rm a resource for this directory, relative to root of repo. Use . for root.
  • -p project Run state rm a resource for this project. Refers to the name of the project configured in the repo's atlantis.yaml repo configuration file. This cannot be used at the same time as -d or -w.
  • -w workspace Run state rm a resource for a specific Terraform workspace. Ignore this if Terraform workspaces are unused.

Additional Terraform flags

If terraform state rm requires additional arguments, like -lock=false' append them to the end of the comment after --, e.g.

atlantis state -d dir rm 'aws_instance.example["foo"]' -- -lock=false

If a flag is needed to be always appended, see Custom Workflow Use Cases.

atlantis unlock

atlantis unlock

Explanation

Removes all atlantis locks and discards all plans for this PR. To unlock a specific plan you can use the Atlantis UI.

atlantis approve_policies

atlantis approve_policies

Explanation

Approves all current policy checking failures for the PR.

See also policy checking.

Options

  • --verbose Append Atlantis log to comment.