104 lines
4.6 KiB
Plaintext
104 lines
4.6 KiB
Plaintext
---
|
|
page_title: Terraform Cloud Settings - Terraform CLI
|
|
---
|
|
|
|
# Terraform Cloud Settings
|
|
|
|
Terraform CLI can integrate with Terraform Cloud, acting as a client for Terraform Cloud's
|
|
[CLI-driven run workflow](/cloud-docs/run/cli).
|
|
|
|
> **Hands On:** Try the [Migrate State to Terraform Cloud](https://learn.hashicorp.com/tutorials/terraform/cloud-migrate) tutorial on HashiCorp Learn.
|
|
|
|
You must configure the following settings to use Terraform Cloud for a particular working directory:
|
|
|
|
- Provide credentials to access Terraform Cloud, preferably by using the
|
|
[`terraform login`](/cli/commands/login) command.
|
|
- Add a `cloud` block to the directory's Terraform configuration, to specify
|
|
which organization and workspace(s) to use.
|
|
- Optionally, use a `.terraformignore` file to specify files that shouldn't be
|
|
uploaded with the Terraform configuration when running plans and applies.
|
|
|
|
After adding or changing a `cloud` block, you must run `terraform init`.
|
|
|
|
## The `cloud` Block
|
|
|
|
The `cloud` block is a nested block within the top-level `terraform` settings
|
|
block. It specifies which Terraform Cloud workspaces to use for the current
|
|
working directory.
|
|
|
|
```hcl
|
|
terraform {
|
|
cloud {
|
|
organization = "my-org"
|
|
hostname = "app.terraform.io" # Optional; defaults to app.terraform.io
|
|
|
|
workspaces {
|
|
tags = ["networking", "source:cli"]
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
The `cloud` block also has some special restrictions:
|
|
|
|
- A configuration can only provide one `cloud` block.
|
|
- A `cloud` block cannot be used with [state backends](/language/settings/backends).
|
|
A configuration can use one or the other, but not both.
|
|
- A `cloud` block cannot refer to named values (like input variables, locals, or
|
|
data source attributes).
|
|
|
|
The `cloud` block only affects Terraform CLI's behavior. When Terraform Cloud uses a configuration
|
|
that contains a cloud block - for example, when a workspace is configured to use a VCS provider
|
|
directly - it ignores the block and behaves according to its own workspace settings.
|
|
|
|
### Arguments
|
|
|
|
The `cloud` block supports the following configuration arguments:
|
|
|
|
- `organization` - (Required) The name of the organization containing the
|
|
workspace(s) the current configuration should use.
|
|
|
|
- `workspaces` - (Required) A nested block that specifies which remote Terraform Cloud workspaces to
|
|
use for the current configuration. The `workspaces` block must contain **exactly one** of the
|
|
following arguments, each denoting a strategy for how workspaces should be mapped:
|
|
|
|
- `tags` - (Optional) A set of Terraform Cloud workspace tags. You will be able to use
|
|
this working directory with any workspaces that have all of the specified tags,
|
|
and can use [the `terraform workspace` commands](/cli/workspaces)
|
|
to switch between them or create new workspaces. New workspaces will automatically have
|
|
the specified tags. This option conflicts with `name`.
|
|
|
|
- `name` - (Optional) The name of a single Terraform Cloud workspace. You will
|
|
only be able to use the workspace specified in the configuration with this working
|
|
directory, and cannot manage workspaces from the CLI (e.g. `terraform workspace select` or
|
|
`terraform workspace new`). This option conflicts with `tags`.
|
|
|
|
- `hostname` - (Optional) The hostname of a Terraform Enterprise installation, if using Terraform
|
|
Enterprise. Defaults to Terraform Cloud (app.terraform.io).
|
|
|
|
- `token` - (Optional) The token used to authenticate with Terraform Cloud.
|
|
We recommend omitting the token from the configuration, and instead using
|
|
[`terraform login`](/cli/commands/login) or manually configuring
|
|
`credentials` in the
|
|
[CLI config file](/cli/config/config-file#credentials).
|
|
|
|
## Excluding Files from Upload with .terraformignore
|
|
|
|
When executing a remote `plan` or `apply` in a [CLI-driven run](/cloud-docs/run/cli),
|
|
a copy of your configuration directory is uploaded to Terraform Cloud. You can define
|
|
paths to exclude from upload by adding a `.terraformignore` file at the root of your
|
|
configuration directory. If this file is not present, the upload will exclude
|
|
the following by default:
|
|
|
|
- `.git/` directories
|
|
- `.terraform/` directories (exclusive of `.terraform/modules`)
|
|
|
|
The rules in `.terraformignore` file resemble the rules allowed in a
|
|
[.gitignore file](https://git-scm.com/book/en/v2/Git-Basics-Recording-Changes-to-the-Repository#_ignoring):
|
|
|
|
- Comments (starting with `#`) or blank lines are ignored.
|
|
- End a pattern with a forward slash `/` to specify a directory.
|
|
- Negate a pattern by starting it with an exclamation point `!`.
|
|
|
|
-> **Note:** Unlike `.gitignore`, only the `.terraformignore` at the root of the configuration directory is considered.
|