diff --git a/website/source/docs/commands/index.html.markdown b/website/source/docs/commands/index.html.markdown index aa79c29c9..d0156f212 100644 --- a/website/source/docs/commands/index.html.markdown +++ b/website/source/docs/commands/index.html.markdown @@ -31,11 +31,10 @@ Available commands are: init Initializes Terraform configuration from a module output Read an output from a state file plan Generate and show an execution plan - pull Refreshes the local state copy from the remote server - push Uploads the the local state to the remote server refresh Update local state file against real resources - remote Configures remote state management + remote Configure remote state storage show Inspect Terraform state or plan + taint Manually mark a resource for recreation version Prints the Terraform version ``` diff --git a/website/source/docs/commands/pull.html.markdown b/website/source/docs/commands/pull.html.markdown deleted file mode 100644 index 385534480..000000000 --- a/website/source/docs/commands/pull.html.markdown +++ /dev/null @@ -1,23 +0,0 @@ ---- -layout: "docs" -page_title: "Command: pull" -sidebar_current: "docs-commands-pull" -description: |- - The `terraform pull` refreshes the cached state file from the - remote server when remote state storage is enabled. ---- - -# Command: pull - -The `terraform pull` refreshes the cached state file from the -remote server when remote state storage is enabled. The [`remote` -command](/docs/commands/remote.html) should be used to enable -remote state storage. - -## Usage - -Usage: `terraform pull` - -The `pull` command is invoked without options to refresh the -cache copy of the state. - diff --git a/website/source/docs/commands/push.html.markdown b/website/source/docs/commands/push.html.markdown deleted file mode 100644 index 1a592b192..000000000 --- a/website/source/docs/commands/push.html.markdown +++ /dev/null @@ -1,27 +0,0 @@ ---- -layout: "docs" -page_title: "Command: push" -sidebar_current: "docs-commands-push" -description: |- - The `terraform push` command is used to push a cached local copy - of the state to a remote storage server. ---- - -# Command: push - -The `terraform push` uploads the cached state file to the -remote server when remote state storage is enabled. The [`remote` -command](/docs/commands/remote.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 push` - -The `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-config.html.markdown b/website/source/docs/commands/remote-config.html.markdown new file mode 100644 index 000000000..3fd6c9b17 --- /dev/null +++ b/website/source/docs/commands/remote-config.html.markdown @@ -0,0 +1,81 @@ +--- +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 use of remote +state storage. By default, Terraform persists its state only to a local +disk. 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 storaged. + +## 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, an existing local state file can 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 +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` flag. + The `-address` flag can optionally be provided. + +* Consul - Stores the state in the KV store at a given path. + Requires the `path` flag. The `-address` and `-access-token` + flag can optionally be provided. Address is assumed to be the + local agent if not provided. + +* 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` flag. + +The command-line flags are all optional. The list of available flags are: + +* `-address=url` - URL of the remote storage server. Required for HTTP backend, + optional for Atlas and Consul. + +* `-access-token=token` - Authentication token for state storage server. + Required for Atlas backend, optional for Consul. + +* `-backend=Atlas` - Specifies the type of remote backend. Must be one + of Atlas, Consul, or HTTP. Defaults to Atlas. + +* `-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. + +* `-name=name` - Name of the state file in the state storage server. + Required for Atlas backend. + +* `-path=path` - Path of the remote state in Consul. Required for the + Consul backend. + +* `-pull=true` - Controls if the remote state is pulled before disabling. + This defaults to true to ensure the latest state is cached before disabling. + +* `-state=path` - Path to read state. Defaults to "terraform.tfstate" + unless remote state is enabled. + diff --git a/website/source/docs/commands/remote-pull.html.markdown b/website/source/docs/commands/remote-pull.html.markdown new file mode 100644 index 000000000..db74689fe --- /dev/null +++ b/website/source/docs/commands/remote-pull.html.markdown @@ -0,0 +1,23 @@ +--- +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 new file mode 100644 index 000000000..fa0cc4c0c --- /dev/null +++ b/website/source/docs/commands/remote-push.html.markdown @@ -0,0 +1,27 @@ +--- +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 index cc9c4ff47..3bc96c802 100644 --- a/website/source/docs/commands/remote.html.markdown +++ b/website/source/docs/commands/remote.html.markdown @@ -10,72 +10,24 @@ description: |- # Command: remote -The `terraform remote` command is used to configure use of remote -state storage. By default, Terraform persists its state only to a local -disk. 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. +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 storaged. ## Usage -Usage: `terraform remote [options]` +Usage: `terraform remote SUBCOMMAND [options]` -The `remote` 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, an existing local state file can be migrated. -By default, `remote` 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 -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` flag. - The `-address` flag can optionally be provided. - -* Consul - Stores the state in the KV store at a given path. - Requires the `path` flag. The `-address` and `-access-token` - flag can optionally be provided. Address is assumed to be the - local agent if not provided. - -* 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` flag. - -The command-line flags are all optional. The list of available flags are: - -* `-address=url` - URL of the remote storage server. Required for HTTP backend, - optional for Atlas and Consul. - -* `-access-token=token` - Authentication token for state storage server. - Required for Atlas backend, optional for Consul. - -* `-backend=Atlas` - Specifies the type of remote backend. Must be one - of Atlas, Consul, or HTTP. Defaults to Atlas. - -* `-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. - -* `-name=name` - Name of the state file in the state storage server. - Required for Atlas backend. - -* `-path=path` - Path of the remote state in Consul. Required for the - Consul backend. - -* `-pull=true` - Controls if the remote state is pulled before disabling. - This defaults to true to ensure the latest state is cached before disabling. - -* `-state=path` - Path to read state. Defaults to "terraform.tfstate" - unless remote state is enabled. +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/layouts/docs.erb b/website/source/layouts/docs.erb index 2a313ba9a..fa8bce84a 100644 --- a/website/source/layouts/docs.erb +++ b/website/source/layouts/docs.erb @@ -79,14 +79,6 @@ plan - > - pull - - - > - push - - > refresh