From 22dd47c8af28a4bfa0c113e5be12b4d6132c5b62 Mon Sep 17 00:00:00 2001 From: Mitchell Hashimoto Date: Wed, 15 Feb 2017 12:58:52 -0800 Subject: [PATCH] website: document state locking and remote state page --- website/source/docs/backends/state.html.md | 10 ++ .../docs/commands/remote-config.html.markdown | 60 ---------- .../docs/commands/remote-pull.html.markdown | 23 ---- .../docs/commands/remote-push.html.markdown | 27 ----- .../source/docs/commands/remote.html.markdown | 33 ------ website/source/docs/state/locking.html.md | 32 +++++- .../{remote/index.html.md => remote.html.md} | 40 +++---- .../docs/state/remote/artifactory.html.md | 54 --------- .../source/docs/state/remote/atlas.html.md | 43 -------- .../source/docs/state/remote/azure.html.md | 51 --------- .../source/docs/state/remote/consul.html.md | 49 --------- website/source/docs/state/remote/etcd.html.md | 41 ------- website/source/docs/state/remote/gcs.html.md | 56 ---------- website/source/docs/state/remote/http.html.md | 42 ------- .../source/docs/state/remote/local.html.md | 36 ------ .../source/docs/state/remote/manta.html.md | 46 -------- website/source/docs/state/remote/s3.html.md | 103 ------------------ .../source/docs/state/remote/swift.html.md | 92 ---------------- website/source/layouts/docs.erb | 6 +- 19 files changed, 57 insertions(+), 787 deletions(-) delete mode 100644 website/source/docs/commands/remote-config.html.markdown delete mode 100644 website/source/docs/commands/remote-pull.html.markdown delete mode 100644 website/source/docs/commands/remote-push.html.markdown delete mode 100644 website/source/docs/commands/remote.html.markdown rename website/source/docs/state/{remote/index.html.md => remote.html.md} (57%) delete mode 100644 website/source/docs/state/remote/artifactory.html.md delete mode 100644 website/source/docs/state/remote/atlas.html.md delete mode 100644 website/source/docs/state/remote/azure.html.md delete mode 100644 website/source/docs/state/remote/consul.html.md delete mode 100644 website/source/docs/state/remote/etcd.html.md delete mode 100644 website/source/docs/state/remote/gcs.html.md delete mode 100644 website/source/docs/state/remote/http.html.md delete mode 100644 website/source/docs/state/remote/local.html.md delete mode 100644 website/source/docs/state/remote/manta.html.md delete mode 100644 website/source/docs/state/remote/s3.html.md delete mode 100644 website/source/docs/state/remote/swift.html.md diff --git a/website/source/docs/backends/state.html.md b/website/source/docs/backends/state.html.md index d9431a8b6..936367201 100644 --- a/website/source/docs/backends/state.html.md +++ b/website/source/docs/backends/state.html.md @@ -61,3 +61,13 @@ Both of these protections can be bypassed with the `-force` flag if you're confident you're making the right decision. Even if using the `-force` flag, we recommend making a backup of the state with `terraform state pull` prior to forcing the overwrite. + +## State Locking + +Backends are responsible for supporting [state locking](/docs/state/locking.html) +if possible. Not all backend types support state locking. In the +[list of supported backend types](/docs/backends/types) we explicitly note +whether locking is supported. + +For more information on state locking, view the +[page dedicated to state locking](/docs/state/locking.html). diff --git a/website/source/docs/commands/remote-config.html.markdown b/website/source/docs/commands/remote-config.html.markdown deleted file mode 100644 index d07a53d1a..000000000 --- a/website/source/docs/commands/remote-config.html.markdown +++ /dev/null @@ -1,60 +0,0 @@ ---- -layout: "docs" -page_title: "Command: remote config" -sidebar_current: "docs-commands-remote-config" -description: |- - The `terraform remote config` command is used to configure Terraform to make - use of remote state storage, change remote storage configuration, or - to disable it. ---- - -# Command: remote config - -The `terraform remote config` command is used to configure the use of remote state storage. By default, Terraform persists its state to a local disk. When remote state storage is enabled, Terraform will automatically fetch the latest state from the remote server when required. If updates are made, the newest state is persisted back to the remote server. In this mode, users do not need to store the state using version control or shared storage. - -## Usage - -Usage: `terraform remote config [options]` - -The `remote config` command can be used to enable remote storage, change configuration or disable the use of remote storage. Terraform supports multiple types of storage backends, specified by using the `-backend` flag. By default, Atlas is assumed to be the storage backend. Each backend expects different configuration arguments documented below. - -When remote storage is enabled, the existing local state file will be migrated. By default, `remote config` will look for the `terraform.tfstate` file, but that can be specified by the `-state` flag. If no state file exists, a blank state will be configured. - -When remote storage is disabled, the existing remote state is migrated back to a local file. The location of the new local state file defaults to the path specified in the `-state` flag. - -When enabling remote storage, we use the `-backend-config` flag to set any required configuration variables. - -Supported storage backends and supported features of each backend are documented in the [Remote State](/docs/state/remote/index.html) section. - -The command-line flags are all optional. The list of available flags are: - -* `-backend=Atlas` - The remote backend to use. Must be one of the - supported backends. - -* `-backend-config="k=v"` - Specify a configuration variable for a backend. - This is how you set any required variables for the backend. - -* `-backup=path` - Path to backup the existing state file before - modifying. Defaults to the "-state" path with ".backup" extension. - Set to "-" to disable backup. - -* `-disable` - Disables remote state management and migrates the state - to the `-state` path. - -* `-pull=true` - Controls if the remote state is pulled before disabling - or after enabling. This defaults to true to ensure the latest state - is available under both conditions. - -* `-state=path` - Path to read state. Defaults to `terraform.tfstate` - unless remote state is enabled. - -## Example: Consul - -This example below will push your remote state to a Consul server. - -``` -$ terraform remote config \ - -backend=consul \ - -backend-config="address=consul.example.com:80" \ - -backend-config="path=tf" -``` diff --git a/website/source/docs/commands/remote-pull.html.markdown b/website/source/docs/commands/remote-pull.html.markdown deleted file mode 100644 index db74689fe..000000000 --- a/website/source/docs/commands/remote-pull.html.markdown +++ /dev/null @@ -1,23 +0,0 @@ ---- -layout: "docs" -page_title: "Command: remote pull" -sidebar_current: "docs-commands-remote-pull" -description: |- - The `terraform remote pull` refreshes the cached state file from the - remote server when remote state storage is enabled. ---- - -# Command: remote pull - -The `terraform remote pull` refreshes the cached state file from the -remote server when remote state storage is enabled. The [`remote config` -command](/docs/commands/remote-config.html) should be used to enable -remote state storage. - -## Usage - -Usage: `terraform remote pull` - -The `remote pull` command is invoked without options to refresh the -cache copy of the state. - diff --git a/website/source/docs/commands/remote-push.html.markdown b/website/source/docs/commands/remote-push.html.markdown deleted file mode 100644 index fa0cc4c0c..000000000 --- a/website/source/docs/commands/remote-push.html.markdown +++ /dev/null @@ -1,27 +0,0 @@ ---- -layout: "docs" -page_title: "Command: remote push" -sidebar_current: "docs-commands-remote-push" -description: |- - The `terraform remote push` command is used to push a cached local copy - of the state to a remote storage server. ---- - -# Command: remote push - -The `terraform remote push` uploads the cached state file to the -remote server when remote state storage is enabled. The [`remote config` -command](/docs/commands/remote-config.html) should be used to enable -remote state storage. - -Uploading is typically done automatically when running a Terraform -command that modifies state, but this can be used to retry uploads -if a transient failure occurs. - -## Usage - -Usage: `terraform remote push` - -The `remote push` command is invoked without options to upload the -local cached state to the remote storage server. - diff --git a/website/source/docs/commands/remote.html.markdown b/website/source/docs/commands/remote.html.markdown deleted file mode 100644 index 22d341891..000000000 --- a/website/source/docs/commands/remote.html.markdown +++ /dev/null @@ -1,33 +0,0 @@ ---- -layout: "docs" -page_title: "Command: remote" -sidebar_current: "docs-commands-remote" -description: |- - The `terraform remote` command is used to configure Terraform to make - use of remote state storage, change remote storage configuration, or - to disable it. ---- - -# Command: remote - -The `terraform remote` command is used to configure all aspects of -remote state storage. When remote state storage is enabled, -Terraform will automatically fetch the latest state from the remote -server when necessary and if any updates are made, the newest state -is persisted back to the remote server. -In this mode, users do not need to durably store the state using version -control or shared storage. - -## Usage - -Usage: `terraform remote SUBCOMMAND [options]` - -The `remote` command behaves as another command that further has more -subcommands. The subcommands available are: - - * [config](/docs/commands/remote-config.html) - Configure the remote storage, - including enabling/disabling it. - * [pull](/docs/commands/remote-pull.html) - Sync the remote storage to - the local storage (download). - * [push](/docs/commands/remote-push.html) - Sync the local storage to - remote storage (upload). diff --git a/website/source/docs/state/locking.html.md b/website/source/docs/state/locking.html.md index acfd6985b..99b635f4d 100644 --- a/website/source/docs/state/locking.html.md +++ b/website/source/docs/state/locking.html.md @@ -8,4 +8,34 @@ description: |- # State Locking -TODO +If supported by your [backend](/docs/backends), Terraform will lock your +state for all operations that could write state. This prevents +others from acquiring the lock and potentially corrupting your state. + +State locking happens automatically on all operations that could write +state. You won't see any message that it is happening. If state locking fails, +Terraform will not continue. You can disable state locking for most commands +with the `-lock` flag but it is not recommended. + +If acquiring the lock is taking longer than expected, Terraform will output +a status message. If Terraform doesn't output a message, state locking is +still occuring if your backend supports it. + +Not all [backends](/docs/backends) support locking. Please view the list +of [backend types](/docs/backends/types) for details on whether a backend +supports locking or not. + +## Force Unlock + +Terraform has a [force-unlock command](/docs/commands/force-unlock.html) +to manually unlock the state if unlocking failed. + +**Be very careful with this command.** If you unlock the state when someone +else is holding the lock it could cause multiple writers. Force unlock should +only be used to unlock your own lock in the situation where automatic +unlocking failed. + +To protect you, the `force-unlock` command requires a unique lock ID. Terraform +will output this lock ID if unlocking fails. This lock ID acts as a +[nonce](https://en.wikipedia.org/wiki/Cryptographic_nonce), ensuring +that locks and unlocks target the correct lock. diff --git a/website/source/docs/state/remote/index.html.md b/website/source/docs/state/remote.html.md similarity index 57% rename from website/source/docs/state/remote/index.html.md rename to website/source/docs/state/remote.html.md index 519900246..246462c7f 100644 --- a/website/source/docs/state/remote/index.html.md +++ b/website/source/docs/state/remote.html.md @@ -1,7 +1,7 @@ --- -layout: "remotestate" -page_title: "Remote State" -sidebar_current: "docs-state-remote_index" +layout: "docs" +page_title: "State: Remote Storage" +sidebar_current: "docs-state-remote" description: |- Terraform can store the state remotely, making it easier to version and work with in a team. --- @@ -17,18 +17,10 @@ With remote state, Terraform stores the state in a remote store. Terraform supports storing state in [Atlas](https://atlas.hashicorp.com), [Consul](https://www.consul.io), S3, and more. -You can begin using remote state from the beginning with flags to the -[init](/docs/commands/init.html) command, or you can migrate an existing -local state to remote state using the -[remote config](/docs/commands/remote-config.html) command. You can also -use the remote config to disable remote state and move back to local -state. - -### Example Usage - -``` -$ terraform remote config -disable -``` +Remote state is a feature of [backends](/docs/backends). Configuring and +using backends is easy and you can get started with remote state quickly. +If you want to migrate back to using local state, backends make that +easy as well. ## Delegation and Teamwork @@ -47,18 +39,16 @@ teams to run their own infrastructure. As a more specific example with AWS: you can expose things such as VPC IDs, subnets, NAT instance IDs, etc. through remote state and have other Terraform states consume that. -For example usage see the [terraform_remote_state](/docs/providers/terraform/d/remote_state.html) data source. +For example usage see the +[terraform_remote_state](/docs/providers/terraform/d/remote_state.html) data source. ## Locking and Teamwork -Remote state currently **does not** lock regions of your infrastructure -to allow parallel modification using Terraform. Therefore, you must still -collaborate with teammates to safely run Terraform. +Terraform will automatic lock state depending on the +[backend](/docs/backends) used. Please see the full page dedicated +to [state locking](/docs/state/locking.html). [Atlas by HashiCorp](https://atlas.hashicorp.com) is a commercial offering -that does safely allow parallel Terraform runs and handles infrastructure -locking for you. - -In the future, we'd like to extend the remote state system to allow some -minimal locking functionality, but it is a difficult problem without a -central system that we currently aren't focused on solving. +that in addition to locking supports remote operations that allow you to +safely queue Terraform operations in a central location. This enables +teams to safely modify infrastructure concurrently. diff --git a/website/source/docs/state/remote/artifactory.html.md b/website/source/docs/state/remote/artifactory.html.md deleted file mode 100644 index 77e790850..000000000 --- a/website/source/docs/state/remote/artifactory.html.md +++ /dev/null @@ -1,54 +0,0 @@ ---- -layout: "remotestate" -page_title: "Remote State Backend: artifactory" -sidebar_current: "docs-state-remote-artifactory" -description: |- - Terraform can store the state remotely, making it easier to version and work with in a team. ---- - -# artifactory - -Stores the state as an artifact in a given repository in [Artifactory](https://www.jfrog.com/artifactory/). - -Generic HTTP repositories are supported, and state from different -configurations may be kept at different subpaths within the repository. - --> **Note:** The URL must include the path to the Artifactory installation. -It will likely end in `/artifactory`. - -## Example Usage - -``` -terraform remote config \ - -backend=artifactory \ - -backend-config="username=SheldonCooper" \ - -backend-config="password=AmyFarrahFowler" \ - -backend-config="url=https://custom.artifactoryonline.com/artifactory" \ - -backend-config="repo=foo" \ - -backend-config="subpath=terraform-bar" -``` - -## Example Referencing - -``` -data "terraform_remote_state" "foo" { - backend = "artifactory" - config { - username = "SheldonCooper" - password = "AmyFarrahFowler" - url = "https://custom.artifactoryonline.com/artifactory" - repo = "foo" - subpath = "terraform-bar" - } -} -``` - -## Configuration variables - -The following configuration options / environment variables are supported: - - * `username` / `ARTIFACTORY_USERNAME` (Required) - The username - * `password` / `ARTIFACTORY_PASSWORD` (Required) - The password - * `url` / `ARTIFACTORY_URL` (Required) - The URL. Note that this is the base url to artifactory not the full repo and subpath. - * `repo` (Required) - The repository name - * `subpath` (Required) - Path within the repository diff --git a/website/source/docs/state/remote/atlas.html.md b/website/source/docs/state/remote/atlas.html.md deleted file mode 100644 index 0cefaf933..000000000 --- a/website/source/docs/state/remote/atlas.html.md +++ /dev/null @@ -1,43 +0,0 @@ ---- -layout: "remotestate" -page_title: "Remote State Backend: atlas" -sidebar_current: "docs-state-remote-atlas" -description: |- - Terraform can store the state remotely, making it easier to version and work with in a team. ---- - -# atlas - -Stores the state in [Atlas](https://atlas.hashicorp.com/). - -You can create a new environment in the [Environments section](https://atlas.hashicorp.com/environments) -and generate new token in the [Tokens page](https://atlas.hashicorp.com/settings/tokens) under Settings. - -## Example Usage - -``` -terraform remote config \ - -backend=atlas \ - -backend-config="name=bigbang/example" \ - -backend-config="access_token=X2iTFefU5aWOjg.atlasv1.YaDa" \ -``` - -## Example Referencing - -``` -data "terraform_remote_state" "foo" { - backend = "atlas" - config { - name = "bigbang/example" - access_token = "X2iTFefU5aWOjg.atlasv1.YaDa" - } -} -``` - -## Configuration variables - -The following configuration options / environment variables are supported: - - * `name` - (Required) Full name of the environment (`/`) - * `access_token` / `ATLAS_TOKEN` - (Required) Atlas API token - * `address` - (Optional) Address to alternative Atlas location (Atlas Enterprise endpoint) diff --git a/website/source/docs/state/remote/azure.html.md b/website/source/docs/state/remote/azure.html.md deleted file mode 100644 index 0decbe1ad..000000000 --- a/website/source/docs/state/remote/azure.html.md +++ /dev/null @@ -1,51 +0,0 @@ ---- -layout: "remotestate" -page_title: "Remote State Backend: azure" -sidebar_current: "docs-state-remote-azure" -description: |- - Terraform can store the state remotely, making it easier to version and work with in a team. ---- - -# azure - -Stores the state as a given key in a given bucket on [Microsoft Azure Storage](https://azure.microsoft.com/en-us/documentation/articles/storage-introduction/). - --> **Note:** Passing credentials directly via config options will -make them included in cleartext inside the persisted state. -Access key should, ideally, be passed using the environment variable -`ARM_ACCESS_KEY` to follow this convention. - -## Example Usage - - -``` -terraform remote config \ - -backend=azure \ - -backend-config="storage_account_name=terraform123abc" \ - -backend-config="container_name=terraform-state" \ - -backend-config="key=prod.terraform.tfstate" -``` - -## Example Referencing - -```hcl -# setup remote state data source -data "terraform_remote_state" "foo" { - backend = "azure" - config { - storage_account_name = "terraform123abc" - container_name = "terraform-state" - key = "prod.terraform.tfstate" - } -} -``` - -## Configuration variables - -The following configuration options are supported: - - * `storage_account_name` - (Required) The name of the storage account - * `container_name` - (Required) The name of the container to use within the storage account - * `key` - (Required) The key where to place/look for state file inside the container - * `access_key` / `ARM_ACCESS_KEY` - (Required) Storage account access key - * `lease_id` / `ARM_LEASE_ID` - (Optional) If set, will be used when writing to storage blob. diff --git a/website/source/docs/state/remote/consul.html.md b/website/source/docs/state/remote/consul.html.md deleted file mode 100644 index d5c30878a..000000000 --- a/website/source/docs/state/remote/consul.html.md +++ /dev/null @@ -1,49 +0,0 @@ ---- -layout: "remotestate" -page_title: "Remote State Backend: consul" -sidebar_current: "docs-state-remote-consul" -description: |- - Terraform can store the state remotely, making it easier to version and work with in a team. ---- - -# consul - -Stores the state in the [Consul](https://www.consul.io/) KV store at a given path. - --> **Note:** Specifying `access_token` directly makes it included in -cleartext inside the persisted, shard state. -Use of the environment variable `CONSUL_HTTP_TOKEN` is recommended. - -## Example Usage - -``` -terraform remote config \ - -backend=consul \ - -backend-config="path=full/path" -``` - -## Example Referencing - -``` -data "terraform_remote_state" "foo" { - backend = "consul" - config { - path = "full/path" - } -} -``` - -## Configuration variables - -The following configuration options / environment variables are supported: - - * `path` - (Required) Path in the Consul KV store - * `access_token` / `CONSUL_HTTP_TOKEN` - (Required) Access token - * `address` / `CONSUL_HTTP_ADDR` - (Optional) DNS name and port of your Consul endpoint specified in the - format `dnsname:port`. Defaults to the local agent HTTP listener. - * `scheme` - (Optional) Specifies what protocol to use when talking to the given - `address`, either `http` or `https`. SSL support can also be triggered - by setting then environment variable `CONSUL_HTTP_SSL` to `true`. - * `datacenter` - (Optional) The datacenter to use. Defaults to that of the agent. - * `http_auth` / `CONSUL_HTTP_AUTH` - (Optional) HTTP Basic Authentication credentials to be used when - communicating with Consul, in the format of either `user` or `user:pass`. diff --git a/website/source/docs/state/remote/etcd.html.md b/website/source/docs/state/remote/etcd.html.md deleted file mode 100644 index 797a3f7cb..000000000 --- a/website/source/docs/state/remote/etcd.html.md +++ /dev/null @@ -1,41 +0,0 @@ ---- -layout: "remotestate" -page_title: "Remote State Backend: etcd" -sidebar_current: "docs-state-remote-etcd" -description: |- - Terraform can store the state remotely, making it easier to version and work with in a team. ---- - -# etcd - -Stores the state in [etcd](https://coreos.com/etcd/) at a given path. - -## Example Usage - -``` -terraform remote config \ - -backend=etcd \ - -backend-config="path=path/to/terraform.tfstate" \ - -backend-config="endpoints=http://one:4001 http://two:4001" -``` - -## Example Referencing - -``` -data "terraform_remote_state" "foo" { - backend = "etcd" - config { - path = "path/to/terraform.tfstate" - endpoints = "http://one:4001 http://two:4001" - } -} -``` - -## Configuration variables - -The following configuration options are supported: - - * `path` - (Required) The path where to store the state - * `endpoints` - (Required) A space-separated list of the etcd endpoints - * `username` - (Optional) The username - * `password` - (Optional) The password diff --git a/website/source/docs/state/remote/gcs.html.md b/website/source/docs/state/remote/gcs.html.md deleted file mode 100644 index 868db31da..000000000 --- a/website/source/docs/state/remote/gcs.html.md +++ /dev/null @@ -1,56 +0,0 @@ ---- -layout: "remotestate" -page_title: "Remote State Backend: gcs" -sidebar_current: "docs-state-remote-gcs" -description: |- - Terraform can store the state remotely, making it easier to version and work with in a team. ---- - -# gcs - -Stores the state as a given key in a given bucket on [Google Cloud Storage](https://cloud.google.com/storage/). - --> **Note:** Passing credentials directly via config options will -make them included in cleartext inside the persisted state. -Use of environment variables or config file is recommended. - -## Example Usage - -``` -terraform remote config \ - -backend=gcs \ - -backend-config="bucket=terraform-state-prod" \ - -backend-config="path=network/terraform.tfstate" \ - -backend-config="project=goopro" -``` - -## Example Referencing - -```hcl -# setup remote state data source -data "terraform_remote_state" "foo" { - backend = "gcs" - config { - bucket = "terraform-state-prod" - path = "network/terraform.tfstate" - project = "goopro" - } -} - -# read value from data source -resource "template_file" "bar" { - template = "${greeting}" - - vars { - greeting = "${data.terraform_remote_state.foo.greeting}" - } -} -``` - -## Configuration variables - -The following configuration options are supported: - - * `bucket` - (Required) The name of the GCS bucket - * `path` - (Required) The path where to place/look for state file inside the bucket - * `credentials` / `GOOGLE_CREDENTIALS` - (Required) Google Cloud Platform account credentials in json format diff --git a/website/source/docs/state/remote/http.html.md b/website/source/docs/state/remote/http.html.md deleted file mode 100644 index 9c03185b9..000000000 --- a/website/source/docs/state/remote/http.html.md +++ /dev/null @@ -1,42 +0,0 @@ ---- -layout: "remotestate" -page_title: "Remote State Backend: http" -sidebar_current: "docs-state-remote-http" -description: |- - Terraform can store the state remotely, making it easier to version and work with in a team. ---- - -# http - -Stores the state using a simple [REST](https://en.wikipedia.org/wiki/Representational_state_transfer) client. - -State will be fetched via GET, updated via POST, and purged with DELETE. - -## Example Usage - -``` -terraform remote config \ - -backend=http \ - -backend-config="address=http://my.rest.api.com" -``` - -## Example Referencing - -``` -data "terraform_remote_state" "foo" { - backend = "http" - config { - address = "http://my.rest.api.com" - } -} -``` - -## Configuration variables - -The following configuration options are supported: - - * `address` - (Required) The address of the REST endpoint - * `username` - (Optional) The username for HTTP basic authentication - * `password` - (Optional) The password for HTTP basic authentication - * `skip_cert_verification` - (Optional) Whether to skip TLS verification. - Defaults to `false`. diff --git a/website/source/docs/state/remote/local.html.md b/website/source/docs/state/remote/local.html.md deleted file mode 100644 index b8495a2f5..000000000 --- a/website/source/docs/state/remote/local.html.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -layout: "remotestate" -page_title: "Remote State Backend: local" -sidebar_current: "docs-state-remote-local" -description: |- - Remote state stored using the local file system. ---- - -# local - -Remote state backend that uses the local file system. - -## Example Usage - -``` -terraform remote config \ - -backend=local \ - -backend-config="path=/path/to/terraform.tfstate" -``` - -## Example Reference - -``` -data "terraform_remote_state" "foo" { - backend = "local" - config { - path = "${path.module}/../../terraform.tfstate" - } -} -``` - -## Configuration variables - -The following configuration options are supported: - - * `path` - (Required) The path to the `tfstate` file. diff --git a/website/source/docs/state/remote/manta.html.md b/website/source/docs/state/remote/manta.html.md deleted file mode 100644 index 05ca012bb..000000000 --- a/website/source/docs/state/remote/manta.html.md +++ /dev/null @@ -1,46 +0,0 @@ ---- -layout: "remotestate" -page_title: "Remote State Backend: manta" -sidebar_current: "docs-state-remote-manta" -description: |- - Terraform can store the state remotely, making it easier to version and work with in a team. ---- - -# manta - -Stores the state as an artifact in [Manta](https://www.joyent.com/manta). - -## Example Usage - -``` -terraform remote config \ - -backend=manta \ - -backend-config="path=random/path" \ - -backend-config="objecName=terraform.tfstate" -``` - -## Example Referencing - -``` -data "terraform_remote_state" "foo" { - backend = "manta" - config { - path = "random/path" - objectName = "terraform.tfstate" - } -} -``` - -## Configuration variables - -The following configuration options are supported: - - * `path` - (Required) The path relative to your private storage directory (`/$MANTA_USER/stor`) where the state file will be stored - * `objectName` - (Optional) The name of the state file (defaults to `terraform.tfstate`) - -The following [Manta environment variables](https://apidocs.joyent.com/manta/#setting-up-your-environment) are supported: - - * `MANTA_URL` - (Required) The API endpoint - * `MANTA_USER` - (Required) The Manta user - * `MANTA_KEY_ID` - (Required) The MD5 fingerprint of your SSH key - * `MANTA_KEY_MATERIAL` - (Required) The path to the private key for accessing Manta (must align with the `MANTA_KEY_ID`). This key must *not* be protected by passphrase. diff --git a/website/source/docs/state/remote/s3.html.md b/website/source/docs/state/remote/s3.html.md deleted file mode 100644 index 6abb430f1..000000000 --- a/website/source/docs/state/remote/s3.html.md +++ /dev/null @@ -1,103 +0,0 @@ ---- -layout: "remotestate" -page_title: "Remote State Backend: s3" -sidebar_current: "docs-state-remote-s3" -description: |- - Terraform can store the state remotely, making it easier to version and work with in a team. ---- - -# S3 - -Stores the state as a given key in a given bucket on [Amazon -S3](https://aws.amazon.com/s3/). - -~> **Warning!** It is highly recommended that you enable -[Bucket Versioning](http://docs.aws.amazon.com/AmazonS3/latest/UG/enable-bucket-versioning.html) -on the S3 bucket to allow for state recovery in the case of accidental deletions and human error. - -## Using S3 for Remote State - -To enable remote state on S3 we run the `terraform remote config` -command like so: - -``` -terraform remote config \ - -backend=s3 \ - -backend-config="bucket=terraform-state-prod" \ - -backend-config="key=network/terraform.tfstate" \ - -backend-config="region=us-east-1" -``` - -This assumes we have a bucket created called `terraform-state-prod`. The -Terraform state is written to the file `terraform.tfstate` in a folder -called `network`. - --> **Note:** Passing credentials directly via configuration options will -make them included in cleartext inside the persisted state. Use of -environment variables or a configuration file is recommended. - -## Using the S3 remote state - -To make use of the S3 remote state we can use the -[`terraform_remote_state` data -source](/docs/providers/terraform/d/remote_state.html). - -``` -data "terraform_remote_state" "foo" { - backend = "s3" - config { - bucket = "terraform-state-prod" - key = "network/terraform.tfstate" - region = "us-east-1" - } -} -``` - -The `terraform_remote_state` data source will return all of the root outputs -defined in the referenced remote state, an example output might look like: - -``` -data.terraform_remote_state.network: - id = 2016-10-29 01:57:59.780010914 +0000 UTC - addresses.# = 2 - addresses.0 = 52.207.220.222 - addresses.1 = 54.196.78.166 - backend = s3 - config.% = 3 - config.bucket = terraform-state-prod - config.key = network/terraform.tfstate - config.region = us-east-1 - elb_address = web-elb-790251200.us-east-1.elb.amazonaws.com - public_subnet_id = subnet-1e05dd33 -``` - -## Configuration variables - -The following configuration options or environment variables are supported: - - * `bucket` - (Required) The name of the S3 bucket. - * `key` - (Required) The path to the state file inside the bucket. - * `region` / `AWS_DEFAULT_REGION` - (Optional) The region of the S3 - bucket. - * `endpoint` / `AWS_S3_ENDPOINT` - (Optional) A custom endpoint for the - S3 API. - * `encrypt` - (Optional) Whether to enable [server side - encryption](https://docs.aws.amazon.com/AmazonS3/latest/dev/UsingServerSideEncryption.html) - of the state file. - * `acl` - [Canned - ACL](https://docs.aws.amazon.com/AmazonS3/latest/dev/acl-overview.html#canned-acl) - to be applied to the state file. - * `access_key` / `AWS_ACCESS_KEY_ID` - (Optional) AWS access key. - * `secret_key` / `AWS_SECRET_ACCESS_KEY` - (Optional) AWS secret access key. - * `kms_key_id` - (Optional) The ARN of a KMS Key to use for encrypting - the state. - * `lock_table` - (Optional) The name of a DynamoDB table to use for state - locking. The table must have a primary key named LockID. - * `profile` - (Optional) This is the AWS profile name as set in the - shared credentials file. - * `shared_credentials_file` - (Optional) This is the path to the - shared credentials file. If this is not set and a profile is specified, - `~/.aws/credentials` will be used. - * `token` - (Optional) Use this to set an MFA token. It can also be - sourced from the `AWS_SESSION_TOKEN` environment variable. - * `role_arn` - (Optional) The role to be assumed diff --git a/website/source/docs/state/remote/swift.html.md b/website/source/docs/state/remote/swift.html.md deleted file mode 100644 index df728a515..000000000 --- a/website/source/docs/state/remote/swift.html.md +++ /dev/null @@ -1,92 +0,0 @@ ---- -layout: "remotestate" -page_title: "Remote State Backend: swift" -sidebar_current: "docs-state-remote-swift" -description: |- - Terraform can store the state remotely, making it easier to version and work with in a team. ---- - -# swift - -Stores the state as an artifact in [Swift](http://docs.openstack.org/developer/swift/). - --> **Note:** Passing credentials directly via configuration options will -make them included in cleartext inside the persisted state. Use of -environment variables is recommended. - -## Example Usage - -``` -terraform remote config \ - -backend=swift \ - -backend-config="path=terraform_state" -``` - -## Example Referencing - -``` -data "terraform_remote_state" "foo" { - backend = "swift" - config { - path = "terraform_state" - } -} -``` - -## Configuration variables - -The following configuration options are supported: - - * `auth_url` - (Required) The Identity authentication URL. If omitted, the - `OS_AUTH_URL` environment variable is used. - - * `path` - (Required) The path where to store `terraform.tfstate`. - * `user_name` - (Optional) The Username to login with. If omitted, the - `OS_USERNAME` environment variable is used. - - * `user_id` - (Optional) The User ID to login with. If omitted, the - `OS_USER_ID` environment variable is used. - - * `password` - (Optional) The Password to login with. If omitted, the - `OS_PASSWORD` environment variable is used. - - * `token` - (Optional) Access token to login with instead of user and password. - If omitted, the `OS_AUTH_TOKEN` variable is used. - - * `region_name` (Required) - The region in which to store `terraform.tfstate`. If - omitted, the `OS_REGION_NAME` environment variable is used. - - * `tenant_id` (Optional) The ID of the Tenant (Identity v2) or Project - (Identity v3) to login with. If omitted, the `OS_TENANT_ID` or - `OS_PROJECT_ID` environment variables are used. - - * `tenant_name` - (Optional) The Name of the Tenant (Identity v2) or Project - (Identity v3) to login with. If omitted, the `OS_TENANT_NAME` or - `OS_PROJECT_NAME` environment variable are used. - - * `domain_id` - (Optional) The ID of the Domain to scope to (Identity v3). If - If omitted, the following environment variables are checked (in this order): - `OS_USER_DOMAIN_ID`, `OS_PROJECT_DOMAIN_ID`, `OS_DOMAIN_ID`. - - * `domain_name` - (Optional) The Name of the Domain to scope to (Identity v3). - If omitted, the following environment variables are checked (in this order): - `OS_USER_DOMAIN_NAME`, `OS_PROJECT_DOMAIN_NAME`, `OS_DOMAIN_NAME`, - `DEFAULT_DOMAIN`. - - * `insecure` - (Optional) Trust self-signed SSL certificates. If omitted, the - `OS_INSECURE` environment variable is used. - - * `cacert_file` - (Optional) Specify a custom CA certificate when communicating - over SSL. If omitted, the `OS_CACERT` environment variable is used. - - * `cert` - (Optional) Specify client certificate file for SSL client - authentication. If omitted the `OS_CERT` environment variable is used. - - * `key` - (Optional) Specify client private key file for SSL client - authentication. If omitted the `OS_KEY` environment variable is used. - - * `archive_path` - (Optional) The path to store archived copied of `terraform.tfstate`. - If specified, Swift object versioning is enabled on the container created at `path`. - - * `expire_after` - (Optional) How long should the `terraform.tfstate` created at `path` - be retained for? Supported durations: `m` - Minutes, `h` - Hours, `d` - Days. diff --git a/website/source/layouts/docs.erb b/website/source/layouts/docs.erb index 85f8e0038..908f67bd9 100644 --- a/website/source/layouts/docs.erb +++ b/website/source/layouts/docs.erb @@ -119,10 +119,6 @@ refresh - > - remote - - > show @@ -174,7 +170,7 @@ > - Remote State + Remote State