From f2ffff33eb34a109609bb8ae28fa833e2ac8b4e6 Mon Sep 17 00:00:00 2001 From: Radek Simko Date: Sun, 17 Jan 2016 22:27:13 +0000 Subject: [PATCH] docs: Create new section for remote state backends --- website/source/assets/stylesheets/_docs.scss | 1 + .../docs/commands/remote-config.html.markdown | 62 ++----------------- .../docs/state/remote/artifactory.html.md | 54 ++++++++++++++++ .../source/docs/state/remote/atlas.html.md | 43 +++++++++++++ .../source/docs/state/remote/consul.html.md | 48 ++++++++++++++ website/source/docs/state/remote/etcd.html.md | 41 ++++++++++++ website/source/docs/state/remote/http.html.md | 40 ++++++++++++ .../{remote.html.md => remote/index.html.md} | 4 +- website/source/docs/state/remote/s3.html.md | 53 ++++++++++++++++ .../source/docs/state/remote/swift.html.md | 44 +++++++++++++ website/source/layouts/docs.erb | 2 +- website/source/layouts/remotestate.erb | 44 +++++++++++++ 12 files changed, 375 insertions(+), 61 deletions(-) create mode 100644 website/source/docs/state/remote/artifactory.html.md create mode 100644 website/source/docs/state/remote/atlas.html.md create mode 100644 website/source/docs/state/remote/consul.html.md create mode 100644 website/source/docs/state/remote/etcd.html.md create mode 100644 website/source/docs/state/remote/http.html.md rename website/source/docs/state/{remote.html.md => remote/index.html.md} (97%) create mode 100644 website/source/docs/state/remote/s3.html.md create mode 100644 website/source/docs/state/remote/swift.html.md create mode 100644 website/source/layouts/remotestate.erb diff --git a/website/source/assets/stylesheets/_docs.scss b/website/source/assets/stylesheets/_docs.scss index 9a2a5052e6..348f84273a 100755 --- a/website/source/assets/stylesheets/_docs.scss +++ b/website/source/assets/stylesheets/_docs.scss @@ -35,6 +35,7 @@ body.layout-vsphere, body.layout-docs, body.layout-downloads, body.layout-inner, +body.layout-remotestate, body.layout-terraform, body.layout-intro{ background: $light-black image-url('sidebar-wire.png') left 62px no-repeat; diff --git a/website/source/docs/commands/remote-config.html.markdown b/website/source/docs/commands/remote-config.html.markdown index 22cdc9333a..8f2e55c7ab 100644 --- a/website/source/docs/commands/remote-config.html.markdown +++ b/website/source/docs/commands/remote-config.html.markdown @@ -40,70 +40,16 @@ below this section for more details. When remote storage is disabled, the existing remote state is migrated to a local file. This defaults to the `-state` path during restore. -The following backends are supported: - -* Atlas - Stores the state in Atlas. Requires the `name` and `access_token` - variables. The `address` variable can optionally be provided. - -* Consul - Stores the state in the KV store at a given path. Requires the - `path` variable. Supports the `CONSUL_HTTP_TOKEN` environment variable - for specifying access credentials, or the `access_token` variable may - be provided, but this is not recommended since it would be included in - cleartext inside the persisted, shard state. Other supported parameters - include: - * `address` - DNS name and port of your Consul endpoint specified in the - format `dnsname:port`. Defaults to the local agent HTTP listener. This - may also be specified using the `CONSUL_HTTP_ADDR` environment variable. - * `scheme` - 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`. - * `http_auth` - HTTP Basic Authentication credentials to be used when - communicating with Consul, in the format of either `user` or `user:pass`. - This may also be specified using the `CONSUL_HTTP_AUTH` environment - variable. - -* Etcd - Stores the state in etcd at a given path. - Requires the `path` and `endpoints` variables. The `username` and `password` - variables can optionally be provided. `endpoints` is assumed to be a - space-separated list of etcd endpoints. - -* S3 - Stores the state as a given key in a given bucket on Amazon S3. - Requires the `bucket` and `key` variables. Supports and honors the standard - AWS environment variables `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, - `AWS_S3_ENDPOINT` and `AWS_DEFAULT_REGION`. These can optionally be provided - as parameters in the `access_key`, `secret_key`, `endpoint` and `region` - variables respectively, but passing credentials this way is not recommended - since they will be included in cleartext inside the persisted state. - Other supported parameters include: - * `bucket` - the name of the S3 bucket - * `key` - path where to place/look for state file inside the bucket - * `encrypt` - 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. - -* Artifactory - Stores the state as an artifact in a given repository in - Artifactory. Requires the `url`, `username`, `password`, `repo` and `subpath` - variables. Generic HTTP repositories are supported, and state from different - configurations may be kept at different subpaths within the repository. The URL - must include the path to the Artifactory installation - it will likely end in - `/artifactory`. Alternately the following environment variables can be used in - place of hard-coded values: - * `ARTIFACTORY_USERNAME` - * `ARTIFACTORY_PASSWORD` - * `ARTIFACTORY_URL` (note that this is the base url to artifactory not the full repo and subpath) - - -* HTTP - Stores the state using a simple REST client. State will be fetched - via GET, updated via POST, and purged with DELETE. Requires the `address` variable. +Supported storage backends and supported features of those +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 above +* `-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 the required variables for the backends above. + This is how you set the required variables for the backend. * `-backup=path` - Path to backup the existing state file before modifying. Defaults to the "-state" path with ".backup" extension. diff --git a/website/source/docs/state/remote/artifactory.html.md b/website/source/docs/state/remote/artifactory.html.md new file mode 100644 index 0000000000..295e7c0ab3 --- /dev/null +++ b/website/source/docs/state/remote/artifactory.html.md @@ -0,0 +1,54 @@ +--- +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 + +``` +resource "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 new file mode 100644 index 0000000000..df458d4da4 --- /dev/null +++ b/website/source/docs/state/remote/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 + +``` +resource "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/consul.html.md b/website/source/docs/state/remote/consul.html.md new file mode 100644 index 0000000000..1e4422d3ba --- /dev/null +++ b/website/source/docs/state/remote/consul.html.md @@ -0,0 +1,48 @@ +--- +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 + +``` +resource "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`. + * `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 new file mode 100644 index 0000000000..d58179a869 --- /dev/null +++ b/website/source/docs/state/remote/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 + +``` +resource "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/http.html.md b/website/source/docs/state/remote/http.html.md new file mode 100644 index 0000000000..7e354a4fd5 --- /dev/null +++ b/website/source/docs/state/remote/http.html.md @@ -0,0 +1,40 @@ +--- +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 + +``` +resource "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 + * `skip_cert_verification` - (Optional) Whether to skip TLS verification. + Defaults to `false`. diff --git a/website/source/docs/state/remote.html.md b/website/source/docs/state/remote/index.html.md similarity index 97% rename from website/source/docs/state/remote.html.md rename to website/source/docs/state/remote/index.html.md index 40f4e32be4..39af76a8ba 100644 --- a/website/source/docs/state/remote.html.md +++ b/website/source/docs/state/remote/index.html.md @@ -1,7 +1,7 @@ --- -layout: "docs" +layout: "remotestate" page_title: "Remote State" -sidebar_current: "docs-state-remote" +sidebar_current: "docs-state-remote_index" description: |- Terraform can store the state remotely, making it easier to version and work with in a team. --- diff --git a/website/source/docs/state/remote/s3.html.md b/website/source/docs/state/remote/s3.html.md new file mode 100644 index 0000000000..4f0f51b18f --- /dev/null +++ b/website/source/docs/state/remote/s3.html.md @@ -0,0 +1,53 @@ +--- +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/). + +-> **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=s3 \ + -backend-config="bucket=terraform-state-prod" \ + -backend-config="key=network/terraform.tfstate" \ + -backend-config="region=us-east-1" +``` + +## Example Referencing + +``` +resource "terraform_remote_state" "foo" { + backend = "s3" + config { + bucket = "terraform-state-prod" + key = "network/terraform.tfstate" + region = "us-east-1" + } +} +``` + +## Configuration variables + +The following configuration options / environment variables are supported: + + * `bucket` - (Required) The name of the S3 bucket + * `key` - (Required) The path where to place/look for 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 key diff --git a/website/source/docs/state/remote/swift.html.md b/website/source/docs/state/remote/swift.html.md new file mode 100644 index 0000000000..a2ee56cd61 --- /dev/null +++ b/website/source/docs/state/remote/swift.html.md @@ -0,0 +1,44 @@ +--- +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/). + +## Example Usage + +``` +terraform remote config \ + -backend=swift \ + -backend-config="path=random/path" +``` + +## Example Referencing + +``` +resource "terraform_remote_state" "foo" { + backend = "swift" + config { + path = "random/path" + } +} +``` + +## Configuration variables + +The following configuration option is supported: + + * `path` - (Required) The path where to store `terraform.tfstate` + +The following environment variables are supported: + + * `OS_AUTH_URL` - (Required) The identity endpoint + * `OS_USERNAME` - (Required) The username + * `OS_PASSWORD` - (Required) The password + * `OS_REGION_NAME` - (Required) The region + * `OS_TENANT_NAME` - (Required) The name of the tenant diff --git a/website/source/layouts/docs.erb b/website/source/layouts/docs.erb index 5e7ec4c3a0..7a386d90af 100644 --- a/website/source/layouts/docs.erb +++ b/website/source/layouts/docs.erb @@ -113,7 +113,7 @@ State diff --git a/website/source/layouts/remotestate.erb b/website/source/layouts/remotestate.erb new file mode 100644 index 0000000000..7a4c57af28 --- /dev/null +++ b/website/source/layouts/remotestate.erb @@ -0,0 +1,44 @@ +<% wrap_layout :inner do %> + <% content_for :sidebar do %> + + <% end %> + + <%= yield %> +<% end %>