terraform/website/docs/commands/push.html.markdown

145 lines
6.5 KiB
Markdown
Raw Normal View History

2015-03-09 19:06:25 +01:00
---
layout: "docs"
page_title: "Command: push"
sidebar_current: "docs-commands-push"
description: |-
2017-03-23 20:28:10 +01:00
The `terraform push` command is used to upload the Terraform configuration to HashiCorp's Terraform Enterprise service for automatically managing your infrastructure in the cloud.
2015-03-09 19:06:25 +01:00
---
# Command: push
The `terraform push` command uploads your Terraform configuration to
2017-03-23 20:28:10 +01:00
be managed by HashiCorp's [Terraform Enterprise](https://www.hashicorp.com/products/terraform/).
By uploading your configuration to Terraform Enterprise, you can automatically run
2015-03-09 19:06:25 +01:00
Terraform for you, will save all state transitions, will save plans,
and will keep a history of all Terraform runs.
This makes it significantly easier to use Terraform as a team: team
members modify the Terraform configurations locally and continue to
use normal version control. When the Terraform configurations are ready
2017-03-23 20:28:10 +01:00
to be run, they are pushed to Terraform Enterprise, and any member of your team can
2015-03-09 19:06:25 +01:00
run Terraform with the push of a button.
2017-03-23 20:28:10 +01:00
Terraform Enterprise can also be used to set ACLs on who can run Terraform, and a
future update of Terraform Enterprise will allow parallel Terraform runs and automatically
2015-03-09 19:06:25 +01:00
perform infrastructure locking so only one run is modifying the same
infrastructure at a time.
~> When using this command, it is important to match your local Terraform version with
the version selected for the target workspace in Terraform Enterprise, since
otherwise the uploaded configuration archive may not be compatible with the remote
Terraform process.
2015-03-09 19:06:25 +01:00
## Usage
Usage: `terraform push [options] [path]`
The `path` argument is the same as for the
[apply](/docs/commands/apply.html) command.
The command-line flags are all optional. The list of available flags are:
2017-03-23 20:28:10 +01:00
* `-atlas-address=<url>` - An alternate address to an instance.
2015-03-25 01:45:19 +01:00
Defaults to `https://atlas.hashicorp.com`.
2015-03-25 01:42:40 +01:00
* `-upload-modules=true` - If true (default), then the
2015-03-09 19:06:25 +01:00
[modules](/docs/modules/index.html)
being used are all locked at their current checkout and uploaded
2017-03-23 20:28:10 +01:00
completely. This prevents Terraform Enterprise from running `terraform get`
2015-03-09 19:06:25 +01:00
for you.
2017-03-23 20:28:10 +01:00
* `-name=<name>` - Name of the infrastructure configuration in Terraform Enterprise.
2015-03-09 19:06:25 +01:00
The format of this is: "username/name" so that you can upload
configurations not just to your account but to other accounts and
organizations. This setting can also be set in the configuration
in the
2017-04-07 06:14:57 +02:00
[Terraform Enterprise section](/docs/configuration/terraform-enterprise.html).
2015-03-09 19:06:25 +01:00
* `-no-color` - Disables output with coloring
2015-06-29 22:45:35 +02:00
2017-03-23 20:28:10 +01:00
* `-overwrite=foo` - Marks a specific variable to be updated.
Normally, if a variable is already set Terraform will not
2015-06-29 22:45:35 +02:00
send the local value (even if it is different). This forces it to
2017-03-23 20:28:10 +01:00
send the local value to Terraform Enterprise. This flag can be repeated multiple times.
2015-06-29 22:45:35 +02:00
2017-03-23 20:28:10 +01:00
* `-token=<token>` - Terraform Enterprise API token to use to authorize the upload.
2016-07-12 00:37:51 +02:00
If blank or unspecified, the `ATLAS_TOKEN` environment variable
2015-03-25 01:41:26 +01:00
will be used.
2015-03-25 01:00:24 +01:00
2015-06-29 22:45:35 +02:00
* `-var='foo=bar'` - Set the value of a variable for the Terraform configuration.
* `-var-file=foo` - Set the value of variables using a variable file. This flag
can be used multiple times.
2015-06-29 22:45:35 +02:00
2015-03-25 01:03:59 +01:00
* `-vcs=true` - If true (default), then Terraform will detect if a VCS
2015-09-11 20:56:20 +02:00
is in use, such as Git, and will only upload files that are committed to
2015-03-25 01:03:59 +01:00
version control. If no version control system is detected, Terraform will
upload all files in `path` (parameter to the command).
2015-03-25 01:00:24 +01:00
## Packaged Files
The files that are uploaded and packaged with a `push` are all the
files in the `path` given as the parameter to the command, recursively.
By default (unless `-vcs=false` is specified), Terraform will automatically
detect when a VCS such as Git is being used, and in that case will only
2015-09-11 20:56:20 +02:00
upload the files that are committed. Because of this built-in intelligence,
2015-03-25 01:00:24 +01:00
you don't have to worry about excluding folders such as ".git" or ".hg" usually.
If Terraform doesn't detect a VCS, it will upload all files.
The reason Terraform uploads all of these files is because Terraform
cannot know what is and isn't being used for provisioning, so it uploads
all the files to be safe. To exclude certain files, specify the `-exclude`
flag when pushing, or specify the `exclude` parameter in the
2017-04-07 06:14:57 +02:00
[Terraform Enterprise configuration section](/docs/configuration/terraform-enterprise.html).
2015-03-25 01:00:24 +01:00
Terraform also includes in the package all of the modules that were installed
during the most recent `terraform init` or `terraform get` command. Since the
details of how modules are cached in the filesystem vary between Terraform versions,
it is important to use the same version of Terraform both locally (when running
`terraform init` and then `terraform push`) and in your remote Terraform Enterprise
workspace.
2015-06-29 22:45:35 +02:00
## Terraform Variables
When you `push`, Terraform will automatically set the local values of
2017-03-23 20:28:10 +01:00
your Terraform variables on Terraform Enterprise. The values are only set if they
don't already exist. If you want to force push a certain
variable value to update it, use the `-overwrite` flag.
2015-06-29 22:45:35 +02:00
2017-03-23 20:28:10 +01:00
All the variable values stored are encrypted and secured
2016-01-14 21:55:39 +01:00
using [Vault](https://www.vaultproject.io). We blogged about the
[architecture of our secure storage system](https://www.hashicorp.com/blog/how-atlas-uses-vault-for-managing-secrets.html) if you want more detail.
2015-06-29 22:45:35 +02:00
The variable values can be updated using the `-overwrite` flag or via
2017-03-23 20:28:10 +01:00
the [Terraform Enterprise website](https://www.hashicorp.com/products/terraform/). An example of updating
just a single variable `foo` is shown below:
```shell
$ terraform push -var 'foo=bar' -overwrite foo
```
Both the `-var` and `-overwrite` flag are required. The `-var` flag
sets the value locally (the exact same process as commands such as apply
2017-03-23 20:28:10 +01:00
or plan), and the `-overwrite` flag tells the push command to update Terraform Enterprise.
2015-06-29 22:45:35 +02:00
2015-03-25 01:00:24 +01:00
## Remote State Requirement
`terraform push` requires that
[remote state](/docs/state/remote.html)
2015-03-25 01:00:24 +01:00
is enabled. The reasoning for this is simple: `terraform push` sends your
configuration to be managed remotely. For it to keep the state in sync
and for you to be able to easily access that state, remote state must
be enabled instead of juggling local files.
2017-03-23 20:28:10 +01:00
While `terraform push` sends your configuration to be managed by Terraform Enterprise,
the remote state backend _does not_ have to be Terraform Enterprise. It can be anything
as long as it is accessible by the public internet, since Terraform Enterprise will need
2015-03-25 01:00:24 +01:00
to be able to communicate to it.
**Warning:** The credentials for accessing the remote state will be
2017-03-23 20:28:10 +01:00
sent up to Terraform Enterprise as well. Therefore, we recommend you use access keys
2015-03-25 01:00:24 +01:00
that are restricted if possible.