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