github.com/Kevinklinger/open_terraform@v0.11.12-beta1/website/docs/commands/push.html.markdown (about)

     1  ---
     2  layout: "docs"
     3  page_title: "Command: push"
     4  sidebar_current: "docs-commands-push"
     5  description: |-
     6    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.
     7  ---
     8  
     9  # Command: push
    10  
    11  ~> **Important:** The `terraform push` command is deprecated, and only works with [the legacy version of Terraform Enterprise](/docs/enterprise-legacy/index.html). In the current version of Terraform Enterprise, you can upload configurations using the API. See [the docs about API-driven runs](/docs/enterprise/run/api.html) for more details.
    12  
    13  The `terraform push` command uploads your Terraform configuration to
    14  be managed by HashiCorp's [Terraform Enterprise](https://www.hashicorp.com/products/terraform/).
    15  Terraform Enterprise can automatically run
    16  Terraform for you, save all state transitions, save plans,
    17  and keep a history of all Terraform runs.
    18  
    19  This makes it significantly easier to use Terraform as a team: team
    20  members modify the Terraform configurations locally and continue to
    21  use normal version control. When the Terraform configurations are ready
    22  to be run, they are pushed to Terraform Enterprise, and any member of your team can
    23  run Terraform with the push of a button.
    24  
    25  Terraform Enterprise can also be used to set ACLs on who can run Terraform, and a
    26  future update of Terraform Enterprise will allow parallel Terraform runs and automatically
    27  perform infrastructure locking so only one run is modifying the same
    28  infrastructure at a time.
    29  
    30  ~> When using this command, it is important to match your local Terraform version with
    31     the version selected for the target workspace in Terraform Enterprise, since
    32     otherwise the uploaded configuration archive may not be compatible with the remote
    33     Terraform process.
    34  
    35  ## Usage
    36  
    37  Usage: `terraform push [options] [path]`
    38  
    39  The `path` argument is the same as for the
    40  [apply](/docs/commands/apply.html) command.
    41  
    42  The command-line flags are all optional. The list of available flags are:
    43  
    44  * `-atlas-address=<url>` - An alternate address to an instance.
    45    Defaults to `https://atlas.hashicorp.com`.
    46  
    47  * `-upload-modules=true` - If true (default), then the
    48    [modules](/docs/modules/index.html)
    49    being used are all locked at their current checkout and uploaded
    50    completely. This prevents Terraform Enterprise from running `terraform get`
    51    for you.
    52  
    53  * `-name=<name>` - Name of the infrastructure configuration in Terraform Enterprise.
    54    The format of this is: "username/name" so that you can upload
    55    configurations not just to your account but to other accounts and
    56    organizations. This setting can also be set in the configuration
    57    in the
    58    [Terraform Enterprise section](/docs/configuration/terraform-enterprise.html).
    59  
    60  * `-no-color` - Disables output with coloring
    61  
    62  
    63  * `-overwrite=foo` - Marks a specific variable to be updated.
    64    Normally, if a variable is already set Terraform will not
    65    send the local value (even if it is different). This forces it to
    66    send the local value to Terraform Enterprise. This flag can be repeated multiple times.
    67  
    68  * `-token=<token>` - Terraform Enterprise API token to use to authorize the upload.
    69    If blank or unspecified, the `ATLAS_TOKEN` environment variable
    70    will be used.
    71  
    72  * `-var='foo=bar'` - Set the value of a variable for the Terraform configuration.
    73  
    74  * `-var-file=foo` - Set the value of variables using a variable file. This flag
    75    can be used multiple times.
    76  
    77  
    78  * `-vcs=true` - If true (default), then Terraform will detect if a VCS
    79    is in use, such as Git, and will only upload files that are committed to
    80    version control. If no version control system is detected, Terraform will
    81    upload all files in `path` (parameter to the command).
    82  
    83  ## Packaged Files
    84  
    85  The files that are uploaded and packaged with a `push` are all the
    86  files in the `path` given as the parameter to the command, recursively.
    87  By default (unless `-vcs=false` is specified), Terraform will automatically
    88  detect when a VCS such as Git is being used, and in that case will only
    89  upload the files that are committed. Because of this built-in intelligence,
    90  you don't have to worry about excluding folders such as ".git" or ".hg" usually.
    91  
    92  If Terraform doesn't detect a VCS, it will upload all files.
    93  
    94  The reason Terraform uploads all of these files is because Terraform
    95  cannot know what is and isn't being used for provisioning, so it uploads
    96  all the files to be safe. To exclude certain files, specify the `-exclude`
    97  flag when pushing, or specify the `exclude` parameter in the
    98  [Terraform Enterprise configuration section](/docs/configuration/terraform-enterprise.html).
    99  
   100  Terraform also includes in the package all of the modules that were installed
   101  during the most recent `terraform init` or `terraform get` command. Since the
   102  details of how modules are cached in the filesystem vary between Terraform versions,
   103  it is important to use the same version of Terraform both locally (when running
   104  `terraform init` and then `terraform push`) and in your remote Terraform Enterprise
   105  workspace.
   106  
   107  ## Terraform Variables
   108  
   109  When you `push`, Terraform will automatically set the local values of
   110  your Terraform variables on Terraform Enterprise. The values are only set if they
   111  don't already exist. If you want to force push a certain
   112  variable value to update it, use the `-overwrite` flag.
   113  
   114  All the variable values stored are encrypted and secured
   115  using [Vault](https://www.vaultproject.io). We blogged about the
   116  [architecture of our secure storage system](https://www.hashicorp.com/blog/how-atlas-uses-vault-for-managing-secrets.html) if you want more detail.
   117  
   118  The variable values can be updated using the `-overwrite` flag or via
   119  the [Terraform Enterprise website](https://www.hashicorp.com/products/terraform/). An example of updating
   120  just a single variable `foo` is shown below:
   121  
   122  ```shell
   123  $ terraform push -var 'foo=bar' -overwrite foo
   124  ```
   125  
   126  Both the `-var` and `-overwrite` flag are required. The `-var` flag
   127  sets the value locally (the exact same process as commands such as apply
   128  or plan), and the `-overwrite` flag tells the push command to update Terraform Enterprise.
   129  
   130  ## Remote State Requirement
   131  
   132  ~> **Important:** This section only refers to the legacy version of Terraform Enterprise. The current version of Terraform Enterprise always manages its own state, and does not support arbitrary remote state backends.
   133  
   134  `terraform push` requires that
   135  [remote state](/docs/state/remote.html)
   136  is enabled. The reasoning for this is simple: `terraform push` sends your
   137  configuration to be managed remotely. For it to keep the state in sync
   138  and for you to be able to easily access that state, remote state must
   139  be enabled instead of juggling local files.
   140  
   141  While `terraform push` sends your configuration to be managed by Terraform Enterprise,
   142  the remote state backend _does not_ have to be Terraform Enterprise. It can be anything
   143  as long as it is accessible by the public internet, since Terraform Enterprise will need
   144  to be able to communicate to it.
   145  
   146  **Warning:** The credentials for accessing the remote state will be
   147  sent up to Terraform Enterprise as well. Therefore, we recommend you use access keys
   148  that are restricted if possible.