github.com/jmbataller/terraform@v0.6.8-0.20151125192640-b7a12e3a580c/website/source/docs/commands/remote-config.html.markdown

github.com/jmbataller/terraform@v0.6.8-0.20151125192640-b7a12e3a580c/website/source/docs/commands/remote-config.html.markdown (about)

1 ---
2 layout: "docs"
3 page_title: "Command: remote config"
4 sidebar_current: "docs-commands-remote-config"
5 description: |-
6 The `terraform remote config` command is used to configure Terraform to make
7 use of remote state storage, change remote storage configuration, or
8 to disable it.
9 ---
10
11 # Command: remote config
12
13 The `terraform remote config` command is used to configure use of remote
14 state storage. By default, Terraform persists its state only to a local
15 disk. When remote state storage is enabled, Terraform will automatically
16 fetch the latest state from the remote server when necessary and if any
17 updates are made, the newest state is persisted back to the remote server.
18 In this mode, users do not need to durably store the state using version
19 control or shared storage.
20
21 ## Usage
22
23 Usage: `terraform remote config [options]`
24
25 The `remote config` command can be used to enable remote storage, change
26 configuration or disable the use of remote storage. Terraform supports multiple types
27 of storage backends, specified by using the `-backend` flag. By default,
28 Atlas is assumed to be the storage backend. Each backend expects different,
29 configuration arguments documented below.
30
31 When remote storage is enabled, an existing local state file can be migrated.
32 By default, `remote config` will look for the "terraform.tfstate" file, but that
33 can be specified by the `-state` flag. If no state file exists, a blank
34 state will be configured.
35
36 When enabling remote storage, use the `-backend-config` flag to set
37 the required configuration variables as documented below. See the example
38 below this section for more details.
39
40 When remote storage is disabled, the existing remote state is migrated
41 to a local file. This defaults to the `-state` path during restore.
42
43 The following backends are supported:
44
45 * Atlas - Stores the state in Atlas. Requires the `name` and `access_token`
46 variables. The `address` variable can optionally be provided.
47
48 * Consul - Stores the state in the KV store at a given path. Requires the
49 `path` variable. Supports the `CONSUL_HTTP_TOKEN` environment variable
50 for specifying access credentials, or the `access_token` variable may
51 be provided, but this is not recommended since it would be included in
52 cleartext inside the persisted, shard state. Other supported parameters
53 include:
54 * `address` - DNS name and port of your Consul endpoint specified in the
55 format `dnsname:port`. Defaults to the local agent HTTP listener. This
56 may also be specified using the `CONSUL_HTTP_ADDR` environment variable.
57 * `scheme` - Specifies what protocol to use when talking to the given
58 `address`, either `http` or `https`. SSL support can also be triggered
59 by setting then environment variable `CONSUL_HTTP_SSL` to `true`.
60
61 * Etcd - Stores the state in etcd at a given path.
62 Requires the `path` and `endpoints` variables. The `username` and `password`
63 variables can optionally be provided. `endpoints` is assumed to be a
64 space-separated list of etcd endpoints.
65
66 * S3 - Stores the state as a given key in a given bucket on Amazon S3.
67 Requires the `bucket` and `key` variables. Supports and honors the standard
68 AWS environment variables `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`
69 and `AWS_DEFAULT_REGION`. These can optionally be provided as parameters
70 in the `access_key`, `secret_key` and `region` variables
71 respectively, but passing credentials this way is not recommended since they
72 will be included in cleartext inside the persisted state.
73 Other supported parameters include:
74 * `bucket` - the name of the S3 bucket
75 * `key` - path where to place/look for state file inside the bucket
76 * `encrypt` - whether to enable [server side encryption](http://docs.aws.amazon.com/AmazonS3/latest/dev/UsingServerSideEncryption.html)
77 of the state file
78 * `acl` - [Canned ACL](http://docs.aws.amazon.com/AmazonS3/latest/dev/acl-overview.html#canned-acl)
79 to be applied to the state file.
80
81 * HTTP - Stores the state using a simple REST client. State will be fetched
82 via GET, updated via POST, and purged with DELETE. Requires the `address` variable.
83
84 The command-line flags are all optional. The list of available flags are:
85
86 * `-backend=Atlas` - The remote backend to use. Must be one of the above
87 supported backends.
88
89 * `-backend-config="k=v"` - Specify a configuration variable for a backend.
90 This is how you set the required variables for the backends above.
91
92 * `-backup=path` - Path to backup the existing state file before
93 modifying. Defaults to the "-state" path with ".backup" extension.
94 Set to "-" to disable backup.
95
96 * `-disable` - Disables remote state management and migrates the state
97 to the `-state` path.
98
99 * `-pull=true` - Controls if the remote state is pulled before disabling
100 or after enabling. This defaults to true to ensure the latest state
101 is available under both conditions.
102
103 * `-state=path` - Path to read state. Defaults to "terraform.tfstate"
104 unless remote state is enabled.
105
106 ## Example: Consul
107
108 The example below will push your remote state to Consul. Note that for
109 this example, it would go to the public Consul demo. In practice, you
110 should use your own private Consul server:
111
112 ```
113 $ terraform remote config \
114 -backend=consul \
115 -backend-config="address=demo.consul.io:80" \
116 -backend-config="path=tf"
117 ```