github.com/terramate-io/tf@v0.0.0-20230830114523-fce866b4dfcd/website/docs/cli/cloud/settings.mdx (about)

     1  ---
     2  page_title: Terraform Cloud Settings - Terraform CLI
     3  description: >-
     4    Configure the Terraform Cloud CLI integration.
     5  ---
     6  
     7  # Terraform Cloud Settings
     8  
     9  Terraform CLI can integrate with Terraform Cloud, acting as a client for Terraform Cloud's
    10  [CLI-driven run workflow](/terraform/cloud-docs/run/cli).
    11  
    12  > **Hands On:** Try the [Migrate State to Terraform Cloud](/terraform/tutorials/cloud/cloud-migrate) tutorial.
    13  
    14  You must configure the following settings to use Terraform Cloud for a particular working directory:
    15  
    16  - Provide credentials to access Terraform Cloud, preferably by using the
    17    [`terraform login`](/terraform/cli/commands/login) command.
    18  - Add a `cloud` block to the directory's Terraform configuration, to specify
    19    which organization and workspace(s) to use.
    20  - Optionally, use a `.terraformignore` file to specify files that shouldn't be
    21    uploaded with the Terraform configuration when running plans and applies.
    22  
    23  After adding or changing a `cloud` block, you must run `terraform init`.
    24  
    25  ## The `cloud` Block
    26  
    27  The `cloud` block is a nested block within the top-level `terraform` settings
    28  block. It specifies which Terraform Cloud workspaces to use for the current
    29  working directory.
    30  
    31  ```hcl
    32  terraform {
    33    cloud {
    34      organization = "my-org"
    35      hostname = "app.terraform.io" # Optional; defaults to app.terraform.io
    36  
    37      workspaces {
    38        project = "networking-development"
    39        tags = ["networking", "source:cli"]
    40      }
    41    }
    42  }
    43  ```
    44  
    45  The `cloud` block also has some special restrictions:
    46  
    47  - A configuration can only provide one `cloud` block.
    48  - A `cloud` block cannot be used with [state backends](/terraform/language/settings/backends/configuration).
    49    A configuration can use one or the other, but not both.
    50  - A `cloud` block cannot refer to named values (like input variables, locals, or
    51    data source attributes).
    52  
    53  The `cloud` block only affects Terraform CLI's behavior. When Terraform Cloud uses a configuration
    54  that contains a cloud block - for example, when a workspace is configured to use a VCS provider
    55  directly - it ignores the block and behaves according to its own workspace settings.
    56  
    57  ### Arguments
    58  
    59  The `cloud` block supports the following configuration arguments:
    60  
    61  - `organization` - (Required) The name of the organization containing the
    62    workspace(s) the current configuration should use.
    63  
    64  - `workspaces` - (Required) A nested block that specifies which remote Terraform Cloud workspaces to
    65    use for the current configuration. The `workspaces` block must contain **exactly one** of the
    66    following arguments, each denoting a strategy for how workspaces should be mapped:
    67  
    68    - `tags` - (Optional) A set of Terraform Cloud workspace tags. You will be able to use
    69      this working directory with any workspaces that have all of the specified tags,
    70      and can use [the `terraform workspace` commands](/terraform/cli/workspaces)
    71      to switch between them or create new workspaces. New workspaces will automatically have
    72      the specified tags. This option conflicts with `name`.
    73  
    74    - `name` - (Optional) The name of a single Terraform Cloud workspace. You will
    75      only be able to use the workspace specified in the configuration with this working
    76      directory, and cannot manage workspaces from the CLI (e.g. `terraform workspace select` or
    77      `terraform workspace new`). This option conflicts with `tags`.
    78  
    79    - `project` - (Optional) The name of a Terraform Cloud project. Workspaces that need created will
    80      will be created within this project. `terraform workspace list` will be filtered by workspaces
    81      in the supplied project.
    82  
    83  - `hostname` - (Optional) The hostname of a Terraform Enterprise installation, if using Terraform
    84    Enterprise. Defaults to Terraform Cloud (app.terraform.io).
    85  
    86  - `token` - (Optional) The token used to authenticate with Terraform Cloud.
    87    We recommend omitting the token from the configuration, and instead using
    88    [`terraform login`](/terraform/cli/commands/login) or manually configuring
    89    `credentials` in the
    90    [CLI config file](/terraform/cli/config/config-file#credentials).
    91  
    92  ### Environment Variables
    93  
    94  -> **Note:** CLI integration environment variables are supported in Terraform v1.2.0 and later.
    95  
    96  You can use environment variables to configure one or more `cloud` block attributes. This is helpful when you want to configure Terraform as part of a Continuous Integration (CI) pipeline. Terraform only reads these variables if the corresponding attribute is omitted from your configuration file. If you choose to configure the `cloud` block entirely through environment variables, you must still add an empty `cloud` block in your configuration file.
    97  
    98  ~> **Warning:** Remote execution with non-interactive workflows requires auto-approved deployments. Minimize risk of unpredictable infrastructure changes and configuration drift by making sure that no one can change your infrastructure outside of your automated build pipeline.  Refer to [Non-Interactive Workflows](/terraform/cloud-docs/run/cli#non-interactive-workflows) for details.
    99  
   100  Use the following environment variables to configure the `cloud` block:
   101  
   102  - `TF_CLOUD_ORGANIZATION` - The name of the organization. Terraform reads this variable when `organization` omitted from the `cloud` block`. If both are specified, the configuration takes precedence.
   103  
   104  - `TF_CLOUD_HOSTNAME` - The hostname of a Terraform Enterprise installation. Terraform reads this when `hostname` is omitted from the `cloud` block. If both are specified, the configuration takes precedence.
   105  
   106  - `TF_CLOUD_PROJECT` - The name of a Terraform Cloud project. Terraform reads this when `workspaces.project` is omitted from the `cloud` block. If both are specified, the cloud block configuration takes precedence.
   107  
   108  - `TF_WORKSPACE` - The name of a single Terraform Cloud workspace. Terraform reads this when `workspaces` is omitted from the `cloud` block. Terraform Cloud will not create a new workspace from this variable; the workspace must exist in the specified organization. You can set `TF_WORKSPACE` if the `cloud` block uses tags. However, the value of `TF_WORKSPACE` must be included in the set of tags. This variable also selects the workspace in your local environment. Refer to [TF_WORKSPACE](/terraform/cli/config/environment-variables#tf_workspace) for details.
   109  
   110  ## Excluding Files from Upload with .terraformignore
   111  
   112  When executing a remote `plan` or `apply` in a [CLI-driven run](/terraform/cloud-docs/run/cli),
   113  a copy of your configuration directory is uploaded to Terraform Cloud. You can define
   114  paths to exclude from upload by adding a `.terraformignore` file at the root of your
   115  configuration directory. If this file is not present, the upload will exclude
   116  the following by default:
   117  
   118  - `.git/` directories
   119  - `.terraform/` directories (exclusive of `.terraform/modules`)
   120  
   121  The rules in `.terraformignore` file resemble the rules allowed in a
   122  [.gitignore file](https://git-scm.com/book/en/v2/Git-Basics-Recording-Changes-to-the-Repository#_ignoring):
   123  
   124  - Comments (starting with `#`) or blank lines are ignored.
   125  - End a pattern with a forward slash `/` to specify a directory.
   126  - Negate a pattern by starting it with an exclamation point `!`.
   127  
   128  -> **Note:** Unlike `.gitignore`, only the `.terraformignore` at the root of the configuration directory is considered.