terraform/website/docs/cli/cloud/settings.html.md

105 lines
4.7 KiB
Markdown
Raw Normal View History

2021-12-07 22:29:11 +01:00
---
layout: "docs"
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](https://www.terraform.io/docs/cloud/run/cli.html).
2021-12-08 19:45:14 +01:00
> **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:
2021-12-07 22:29:11 +01:00
- Provide credentials to access Terraform Cloud, preferably by using the
[`terraform login`](/docs/cli/commands/login.html) 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"]
}
}
}
```
2021-12-08 19:45:14 +01:00
The `cloud` block also has some special restrictions:
2021-12-07 22:29:11 +01:00
- A configuration can only provide one `cloud` block.
- A `cloud` block cannot be used with [state backends](/docs/language/settings/backends/index.html).
A configuration can use one or the other, but not both.
- A `cloud` block cannot refer to named values (like input variables, locals, or
2021-12-07 22:29:11 +01:00
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
2021-12-07 22:29:11 +01:00
workspace(s) the current configuration should use.
- `workspaces` - (Required) A nested block that specifies which remote Terraform Cloud workspaces to
2021-12-07 22:29:11 +01:00
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
2021-12-07 22:29:11 +01:00
this working directory with any workspaces that have all of the specified tags,
and can use [the `terraform workspace` commands](/docs/cli/workspaces/index.html)
to switch between them or create new workspaces. New workspaces will automatically have
2021-12-07 22:29:11 +01:00
the specified tags. This option conflicts with `name`.
- `name` - (Optional) The name of a single Terraform Cloud workspace. You will
2021-12-07 22:29:11 +01:00
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
2021-12-07 22:29:11 +01:00
Enterprise. Defaults to Terraform Cloud (app.terraform.io).
- `token` - (Optional) The token used to authenticate with Terraform Cloud.
2021-12-07 22:29:11 +01:00
We recommend omitting the token from the configuration, and instead using
[`terraform login`](/docs/cli/commands/login.html) or manually configuring
`credentials` in the
[CLI config file](/docs/cli/config/config-file.html#credentials).
## Excluding Files from Upload with .terraformignore
When executing a remote `plan` or `apply` in a [CLI-driven run](/docs/cloud/run/cli.html),
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`)
2021-12-07 22:29:11 +01:00
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 `!`.
2021-12-07 22:29:11 +01:00
-> **Note:** Unlike `.gitignore`, only the `.terraformignore` at the root of the configuration directory is considered.