github.com/hugorut/terraform@v1.1.3/website/docs/cli/cloud/settings.mdx (about)

     1  ---
     2  page_title: Terraform Cloud Settings - Terraform CLI
     3  ---
     4  
     5  # Terraform Cloud Settings
     6  
     7  Terraform CLI can integrate with Terraform Cloud, acting as a client for Terraform Cloud's
     8  [CLI-driven run workflow](/cloud-docs/run/cli).
     9  
    10  > **Hands On:** Try the [Migrate State to Terraform Cloud](https://learn.hashicorp.com/tutorials/terraform/cloud-migrate) tutorial on HashiCorp Learn.
    11  
    12  You must configure the following settings to use Terraform Cloud for a particular working directory:
    13  
    14  - Provide credentials to access Terraform Cloud, preferably by using the
    15    [`terraform login`](/cli/commands/login) command.
    16  - Add a `cloud` block to the directory's Terraform configuration, to specify
    17    which organization and workspace(s) to use.
    18  - Optionally, use a `.terraformignore` file to specify files that shouldn't be
    19    uploaded with the Terraform configuration when running plans and applies.
    20  
    21  After adding or changing a `cloud` block, you must run `terraform init`.
    22  
    23  ## The `cloud` Block
    24  
    25  The `cloud` block is a nested block within the top-level `terraform` settings
    26  block. It specifies which Terraform Cloud workspaces to use for the current
    27  working directory.
    28  
    29  ```hcl
    30  terraform {
    31    cloud {
    32      organization = "my-org"
    33      hostname = "app.terraform.io" # Optional; defaults to app.terraform.io
    34  
    35      workspaces {
    36        tags = ["networking", "source:cli"]
    37      }
    38    }
    39  }
    40  ```
    41  
    42  The `cloud` block also has some special restrictions:
    43  
    44  - A configuration can only provide one `cloud` block.
    45  - A `cloud` block cannot be used with [state backends](/language/settings/backends).
    46    A configuration can use one or the other, but not both.
    47  - A `cloud` block cannot refer to named values (like input variables, locals, or
    48    data source attributes).
    49  
    50  The `cloud` block only affects Terraform CLI's behavior. When Terraform Cloud uses a configuration
    51  that contains a cloud block - for example, when a workspace is configured to use a VCS provider
    52  directly - it ignores the block and behaves according to its own workspace settings.
    53  
    54  ### Arguments
    55  
    56  The `cloud` block supports the following configuration arguments:
    57  
    58  - `organization` - (Required) The name of the organization containing the
    59    workspace(s) the current configuration should use.
    60  
    61  - `workspaces` - (Required) A nested block that specifies which remote Terraform Cloud workspaces to
    62    use for the current configuration. The `workspaces` block must contain **exactly one** of the
    63    following arguments, each denoting a strategy for how workspaces should be mapped:
    64  
    65    - `tags` - (Optional) A set of Terraform Cloud workspace tags. You will be able to use
    66      this working directory with any workspaces that have all of the specified tags,
    67      and can use [the `terraform workspace` commands](/cli/workspaces)
    68      to switch between them or create new workspaces. New workspaces will automatically have
    69      the specified tags. This option conflicts with `name`.
    70  
    71    - `name` - (Optional) The name of a single Terraform Cloud workspace. You will
    72      only be able to use the workspace specified in the configuration with this working
    73      directory, and cannot manage workspaces from the CLI (e.g. `terraform workspace select` or
    74      `terraform workspace new`). This option conflicts with `tags`.
    75  
    76  - `hostname` - (Optional) The hostname of a Terraform Enterprise installation, if using Terraform
    77    Enterprise. Defaults to Terraform Cloud (app.terraform.io).
    78  
    79  - `token` - (Optional) The token used to authenticate with Terraform Cloud.
    80    We recommend omitting the token from the configuration, and instead using
    81    [`terraform login`](/cli/commands/login) or manually configuring
    82    `credentials` in the
    83    [CLI config file](/cli/config/config-file#credentials).
    84  
    85  ## Excluding Files from Upload with .terraformignore
    86  
    87  When executing a remote `plan` or `apply` in a [CLI-driven run](/cloud-docs/run/cli),
    88  a copy of your configuration directory is uploaded to Terraform Cloud. You can define
    89  paths to exclude from upload by adding a `.terraformignore` file at the root of your
    90  configuration directory. If this file is not present, the upload will exclude
    91  the following by default:
    92  
    93  - `.git/` directories
    94  - `.terraform/` directories (exclusive of `.terraform/modules`)
    95  
    96  The rules in `.terraformignore` file resemble the rules allowed in a
    97  [.gitignore file](https://git-scm.com/book/en/v2/Git-Basics-Recording-Changes-to-the-Repository#_ignoring):
    98  
    99  - Comments (starting with `#`) or blank lines are ignored.
   100  - End a pattern with a forward slash `/` to specify a directory.
   101  - Negate a pattern by starting it with an exclamation point `!`.
   102  
   103  -> **Note:** Unlike `.gitignore`, only the `.terraformignore` at the root of the configuration directory is considered.