diff --git a/website/source/assets/stylesheets/_docs.scss b/website/source/assets/stylesheets/_docs.scss index e5af033ff..9bb966a9c 100755 --- a/website/source/assets/stylesheets/_docs.scss +++ b/website/source/assets/stylesheets/_docs.scss @@ -6,6 +6,7 @@ body.page-sub{ background-color: $light-black; } +body.layout-backend-types, body.layout-commands-state, body.layout-alicloud, body.layout-archive, diff --git a/website/source/docs/backends/types/artifactory.html.md b/website/source/docs/backends/types/artifactory.html.md new file mode 100644 index 000000000..00c9ce57d --- /dev/null +++ b/website/source/docs/backends/types/artifactory.html.md @@ -0,0 +1,56 @@ +--- +layout: "backend-types" +page_title: "Remote State Backend: artifactory" +sidebar_current: "docs-backends-types-standard-artifactory" +description: |- + Terraform can store the state remotely, making it easier to version and work with in a team. +--- + +# artifactory + +**Kind: Standard (with no locking)** + +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/backends/types/atlas.html.md b/website/source/docs/backends/types/atlas.html.md new file mode 100644 index 000000000..0cefaf933 --- /dev/null +++ b/website/source/docs/backends/types/atlas.html.md @@ -0,0 +1,43 @@ +--- +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/backends/types/azure.html.md b/website/source/docs/backends/types/azure.html.md new file mode 100644 index 000000000..0decbe1ad --- /dev/null +++ b/website/source/docs/backends/types/azure.html.md @@ -0,0 +1,51 @@ +--- +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/backends/types/consul.html.md b/website/source/docs/backends/types/consul.html.md new file mode 100644 index 000000000..d5c30878a --- /dev/null +++ b/website/source/docs/backends/types/consul.html.md @@ -0,0 +1,49 @@ +--- +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/backends/types/etcd.html.md b/website/source/docs/backends/types/etcd.html.md new file mode 100644 index 000000000..797a3f7cb --- /dev/null +++ b/website/source/docs/backends/types/etcd.html.md @@ -0,0 +1,41 @@ +--- +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/backends/types/gcs.html.md b/website/source/docs/backends/types/gcs.html.md new file mode 100644 index 000000000..868db31da --- /dev/null +++ b/website/source/docs/backends/types/gcs.html.md @@ -0,0 +1,56 @@ +--- +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/backends/types/http.html.md b/website/source/docs/backends/types/http.html.md new file mode 100644 index 000000000..9c03185b9 --- /dev/null +++ b/website/source/docs/backends/types/http.html.md @@ -0,0 +1,42 @@ +--- +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/backends/types/index.html.md b/website/source/docs/backends/types/index.html.md new file mode 100644 index 000000000..4034a0ae6 --- /dev/null +++ b/website/source/docs/backends/types/index.html.md @@ -0,0 +1,25 @@ +--- +layout: "backend-types" +page_title: "Backend: Supported Backend Types" +sidebar_current: "docs-backends-types-index" +description: |- + Terraform can store the state remotely, making it easier to version and work with in a team. +--- + +# Backend Types + +This section documents the various backend types supported by Terraform. +If you're not familiar with backends, please +[read the sections about backends](/docs/backends/index.html) first. + +Backends may support differing levels of features in Terraform. We differentiate +these by calling a backend either **standard** or **enhanced**. All backends +must implement **standard** functionality. These are defined below: + + * **Standard**: State management, functionality covered in + [State Storage & Locking](/docs/backends/state.html) + + * **Enhanced**: Everything in standard plus + [remote operations](/docs/backends/operations.html). + +The backends are separated in the left by standard and enhanced. diff --git a/website/source/docs/backends/types/local.html.md b/website/source/docs/backends/types/local.html.md new file mode 100644 index 000000000..b8495a2f5 --- /dev/null +++ b/website/source/docs/backends/types/local.html.md @@ -0,0 +1,36 @@ +--- +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/backends/types/manta.html.md b/website/source/docs/backends/types/manta.html.md new file mode 100644 index 000000000..05ca012bb --- /dev/null +++ b/website/source/docs/backends/types/manta.html.md @@ -0,0 +1,46 @@ +--- +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/backends/types/s3.html.md b/website/source/docs/backends/types/s3.html.md new file mode 100644 index 000000000..6abb430f1 --- /dev/null +++ b/website/source/docs/backends/types/s3.html.md @@ -0,0 +1,103 @@ +--- +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/backends/types/swift.html.md b/website/source/docs/backends/types/swift.html.md new file mode 100644 index 000000000..df728a515 --- /dev/null +++ b/website/source/docs/backends/types/swift.html.md @@ -0,0 +1,92 @@ +--- +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/backend-types.erb b/website/source/layouts/backend-types.erb new file mode 100644 index 000000000..623c9b547 --- /dev/null +++ b/website/source/layouts/backend-types.erb @@ -0,0 +1,65 @@ +<% wrap_layout :inner do %> + <% content_for :sidebar do %> + + <% end %> + + <%= yield %> +<% end %> diff --git a/website/source/layouts/docs.erb b/website/source/layouts/docs.erb index dd6303475..85f8e0038 100644 --- a/website/source/layouts/docs.erb +++ b/website/source/layouts/docs.erb @@ -477,6 +477,10 @@ State Storage & Locking + > + Backend Types + +