terraform API Reference app terraform io v1alpha2 appterraformiov1alpha2 page title HCP Terraform Operator for Kubernetes API reference Packages API reference for the HCP Terraform Operator for Kubernetes

Answer:
---
page_title: HCP Terraform Operator for Kubernetes API reference
description: >-
  API reference for the HCP Terraform Operator for Kubernetes.
---

# API Reference

## Packages
- [app.terraform.io/v1alpha2](#appterraformiov1alpha2)

## app.terraform.io/v1alpha2

Package v1alpha2 contains API Schema definitions for the app v1alpha2 API group

### Resource Types
- [AgentPool](#agentpool)
- [Module](#module)
- [Project](#project)
- [Workspace](#workspace)

#### AgentDeployment

_Appears in:_
- [AgentPoolSpec](#agentpoolspec)

| Field | Description |
| --- | --- |
| `replicas` _integer_ |  |
| `spec` _[PodSpec](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.27/#podspec-v1-core)_ |  |
| `annotations` _object (keys:string, values:string)_ | The annotations that the operator will apply to the pod template in the deployment. |
| `labels` _object (keys:string, values:string)_ | The labels that the operator will apply to the pod template in the deployment. |

#### AgentDeploymentAutoscaling

AgentDeploymentAutoscaling configures the operator to scale the deployment for an AgentPool up and down to meet demand.

_Appears in:_
- [AgentPoolSpec](#agentpoolspec)

| Field | Description |
| --- | --- |
| `maxReplicas` _integer_ | MaxReplicas is the maximum number of replicas for the Agent deployment. |
| `minReplicas` _integer_ | MinReplicas is the minimum number of replicas for the Agent deployment. |
| `targetWorkspaces` _[TargetWorkspace](#targetworkspace)_ | TargetWorkspaces is a list of HCP Terraform Workspaces which the agent pool should scale up to meet demand. When this field is omitted the autoscaler will target all workspaces that are associated with the AgentPool. |
| `cooldownPeriodSeconds` _integer_ | CooldownPeriodSeconds is the time to wait between scaling events. Defaults to 300. |
| `cooldownPeriod` _[AgentDeploymentAutoscalingCooldownPeriod](#agentdeploymentautoscalingcooldownperiod)_ | CoolDownPeriod is the period to wait between scaling up and scaling down |

#### AgentDeploymentAutoscalingCooldownPeriod

AgentDeploymentAutoscalingCooldownPeriod configures the period to wait between scaling up and scaling down.

_Appears in:_
- [AgentDeploymentAutoscaling](#agentdeploymentautoscaling)

| Field | Description |
| --- | --- |
| `scaleUpSeconds` _integer_ | ScaleUpSeconds is the time to wait before scaling up. |
| `scaleDownSeconds` _integer_ | ScaleDownSeconds is the time to wait before scaling down. |

#### AgentDeploymentAutoscalingStatus

AgentDeploymentAutoscalingStatus

_Appears in:_
- [AgentPoolStatus](#agentpoolstatus)

| Field | Description |
| --- | --- |
| `desiredReplicas` _integer_ | Desired number of agent replicas |
| `lastScalingEvent` _[Time](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.27/#time-v1-meta)_ | Last time the agent pool was scaledx |

#### AgentPool

AgentPool is the Schema for the agentpools API.

| Field | Description |
| --- | --- |
| `apiVersion` _string_ | `app.terraform.io/v1alpha2`
| `kind` _string_ | `AgentPool`
| `kind` _string_ | Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. [More information](https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds) |
| `apiVersion` _string_ | APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. [More information](https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources) |
| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.27/#objectmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. |
| `spec` _[AgentPoolSpec](#agentpoolspec)_ |  |

#### AgentPoolSpec

AgentPoolSpec defines the desired state of AgentPool.

_Appears in:_
- [AgentPool](#agentpool)

| Field | Description |
| --- | --- |
| `name` _string_ | Agent Pool name. [More information](/terraform/cloud-docs/agents/agent-pools). |
| `organization` _string_ | Organization name where the Workspace will be created. [More information](/terraform/cloud-docs/users-teams-organizations/organizations). |
| `token` _[Token](#token)_ | API Token to be used for API calls. |
| `agentTokens` _[AgentToken](#agenttoken) array_ | List of the agent tokens to generate. |
| `agentDeployment` _[AgentDeployment](#agentdeployment)_ | Agent deployment settings |
| `autoscaling` _[AgentDeploymentAutoscaling](#agentdeploymentautoscaling)_ | Agent deployment settings |

#### AgentToken

Terraform uses `AgentTokens` to connect to the Terraform agent pool. Only the field `Name` is allowed in the `spec` list. Use the other fields in the `status` list. [More information](/terraform/cloud-docs/agents).

_Appears in:_
- [AgentPoolSpec](#agentpoolspec)
- [AgentPoolStatus](#agentpoolstatus)

| Field | Description |
| --- | --- |
| `name` _string_ | Agent Token name. |
| `id` _string_ | Agent Token ID. |
| `createdAt` _integer_ | Timestamp of when the agent token was created. |
| `lastUsedAt` _integer_ | Timestamp of when the agent token was last used. |

#### ConfigurationVersionStatus

A configuration version is a resource used to reference the uploaded configuration files.
More information:
  - [Configuration versions API](/terraform/cloud-docs/api-docs/configuration-versions)
  - [The API-driven run workflow](/terraform/cloud-docs/run/api)

_Appears in:_
- [ModuleStatus](#modulestatus)

| Field | Description |
| --- | --- |
| `id` _string_ | Configuration Version ID. |

#### ConsumerWorkspace

ConsumerWorkspace allows access to the state for specific workspaces within the same organization. Only one of the fields `ID` or `Name` is allowed. At least one of the fields `ID` or `Name` is mandatory. [More information](/terraform/cloud-docs/workspaces/state#remote-state-access-controls).

_Appears in:_
- [RemoteStateSharing](#remotestatesharing)

| Field | Description |
| --- | --- |
| `id` _string_ | Consumer Workspace ID. Must match pattern: `^ws-[a-zA-Z0-9]+$` |
| `name` _string_ | Consumer Workspace name. |

#### CustomPermissions

Custom permissions let you assign specific, finer-grained permissions to a team than the broader fixed permission sets provide. [More information](/terraform/cloud-docs/users-teams-organizations/permissions#custom-workspace-permissions).

_Appears in:_
- [TeamAccess](#teamaccess)

| Field | Description |
| --- | --- |
| `runs` _string_ | Run access. Must be one of the following values: `apply`, `plan`, `read`. Default: `read`. |
| `runTasks` _boolean_ | Manage Workspace Run Tasks. Default: `false`. |
| `sentinel` _string_ | Download Sentinel mocks. Must be one of the following values: `none`, `read`. Default: `none`. |
| `stateVersions` _string_ | State access. Must be one of the following values: `none`, `read`, `read-outputs`, `write`. Default: `none`. |
| `variables` _string_ | Variable access. Must be one of the following values: `none`, `read`, `write`. Default: `none`. |
| `workspaceLocking` _boolean_ | Lock/unlock workspace. Default: `false`. |

#### CustomProjectPermissions

Custom permissions let you assign specific, finer-grained permissions to a team than the broader fixed permission sets provide.
More information:
  - [Custom project permissions](/terraform/cloud-docs/users-teams-organizations/permissions#custom-project-permissions)
  - [General workspace permissions](/terraform/cloud-docs/users-teams-organizations/permissions#general-workspace-permissions)

_Appears in:_
- [ProjectTeamAccess](#projectteamaccess)

| Field | Description |
| --- | --- |
| `projectAccess` _[ProjectSettingsPermissionType](#projectsettingspermissiontype)_ | Project access. Must be one of the following values: `delete`, `read`, `update`. Default: `read`. |
| `teamManagement` _[ProjectTeamsPermissionType](#projectteamspermissiontype)_ | Team management. Must be one of the following values: `manage`, `none`, `read`. Default: `none`. |
| `createWorkspace` _boolean_ | Allow users to create workspaces in the project. This grants read access to all workspaces in the project. Default: `false`. |
| `deleteWorkspace` _boolean_ | Allows users to delete workspaces in the project. Default: `false`. |
| `moveWorkspace` _boolean_ | Allows users to move workspaces out of the project. A user must have this permission on both the source and destination project to successfully move a workspace from one project to another. Default: `false`. |
| `lockWorkspace` _boolean_ | Allows users to manually lock the workspace to temporarily prevent runs. When a workspace's execution mode is set to "local", users must have this permission to perform local CLI runs using the workspace's state. Default: `false`. |
| `runs` _[WorkspaceRunsPermissionType](#workspacerunspermissiontype)_ | Run access. Must be one of the following values: `apply`, `plan`, `read`. Default: `read`. |
| `runTasks` _boolean_ | Manage Workspace Run Tasks. Default: `false`. |
| `sentinelMocks` _[WorkspaceSentinelMocksPermissionType](#workspacesentinelmockspermissiontype)_ | Download Sentinel mocks. Must be one of the following values: `none`, `read`. Default: `none`. |
| `stateVersions` _[WorkspaceStateVersionsPermissionType](#workspacestateversionspermissiontype)_ | State access. Must be one of the following values: `none`, `read`, `read-outputs`, `write`. Default: `none`. |
| `variables` _[WorkspaceVariablesPermissionType](#workspacevariablespermissiontype)_ | Variable access. Must be one of the following values: `none`, `read`, `write`. Default: `none`. |

#### DeletionPolicy

_Underlying type:_ _string_

DeletionPolicy defines the strategy the Kubernetes operator uses when you delete a resource, either manually or by a system event.

You must use one of the following values:
- `retain`: When you delete the custom resource, the operator does not delete the workspace.
- `soft`: Attempts to delete the associated workspace only if it does not contain any managed resources.
- `destroy`: Executes a destroy operation to remove all resources managed by the associated workspace. Once the destruction of these resources is successful, the operator deletes the workspace, and then deletes the custom resource.
- `force`: Forcefully and immediately deletes the workspace and the custom resource.

_Appears in:_
- [WorkspaceSpec](#workspacespec)

#### Module

Module is the Schema for the modules API Module implements the API-driven Run Workflow. [More information](/terraform/cloud-docs/run/api).

| Field | Description |
| --- | --- |
| `apiVersion` _string_ | `app.terraform.io/v1alpha2`
| `kind` _string_ | `Module`
| `kind` _string_ | Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. [More information](https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds) |
| `apiVersion` _string_ | APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. [More information](https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources) |
| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.27/#objectmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. |
| `spec` _[ModuleSpec](#modulespec)_ |  |

#### ModuleOutput

Module outputs to store in ConfigMap(non-sensitive) or Secret(sensitive).

_Appears in:_
- [ModuleSpec](#modulespec)

| Field | Description |
| --- | --- |
| `name` _string_ | Output name must match with the module output. |
| `sensitive` _boolean_ | Specify whether or not the output is sensitive. Default: `false`. |

#### ModuleSource

Module source and version to execute.

_Appears in:_
- [ModuleSpec](#modulespec)

| Field | Description |
| --- | --- |
| `source` _string_ | Non local Terraform module source. [More information](/terraform/language/modules/sources). |
| `version` _string_ | Terraform module version. |

#### ModuleSpec

ModuleSpec defines the desired state of Module.

_Appears in:_
- [Module](#module)

| Field | Description |
| --- | --- |
| `organization` _string_ | Organization name where the Workspace will be created. [More information](/terraform/cloud-docs/users-teams-organizations/organizations). |
| `token` _[Token](#token)_ | API Token to be used for API calls. |
| `module` _[ModuleSource](#modulesource)_ | Module source and version to execute. |
| `workspace` _[ModuleWorkspace](#moduleworkspace)_ | Workspace to execute the module. |
| `name` _string_ | Name of the module that will be uploaded and executed. Default: `this`. |
| `variables` _[ModuleVariable](#modulevariable) array_ | Variables to pass to the module, they must exist in the Workspace. |
| `outputs` _[ModuleOutput](#moduleoutput) array_ | Module outputs to store in ConfigMap(non-sensitive) or Secret(sensitive). |
| `destroyOnDeletion` _boolean_ | Specify whether or not to execute a Destroy run when the object is deleted from the Kubernetes. Default: `false`. |
| `restartedAt` _string_ | Allows executing a new Run without changing any Workspace or Module attributes. Example: ``kubectl patch KIND NAME --type=merge --patch '{"spec": {"restartedAt": "'\`date -u -Iseconds\`'"}}'`` |

#### ModuleVariable

Variables to pass to the module.

_Appears in:_
- [ModuleSpec](#modulespec)

| Field | Description |
| --- | --- |
| `name` _string_ | Variable name must exist in the Workspace. |

#### ModuleWorkspace

Workspace to execute the module. Only one of the fields `ID` or `Name` is allowed. At least one of the fields `ID` or `Name` is mandatory.

_Appears in:_
- [ModuleSpec](#modulespec)

| Field | Description |
| --- | --- |
| `id` _string_ | Module Workspace ID. Must match pattern: `^ws-[a-zA-Z0-9]+$` |
| `name` _string_ | Module Workspace Name. |

#### Notification

Notifications allow you to send messages to other applications based on run and workspace events. [More information](/terraform/cloud-docs/workspaces/settings/notifications).

_Appears in:_
- [WorkspaceSpec](#workspacespec)

| Field | Description |
| --- | --- |
| `name` _string_ | Notification name. |
| `type` _[NotificationDestinationType](#notificationdestinationtype)_ | The type of the notification. Must be one of the following values: `email`, `generic`, `microsoft-teams`, `slack`. |
| `enabled` _boolean_ | Whether the notification configuration should be enabled or not. Default: `true`. |
| `token` _string_ | The token of the notification. |
| `triggers` _[NotificationTrigger](#notificationtrigger) array_ | The list of run events that trigger notifications. Triggers are notifications that Terraform sends when a run transitions to a different state.

The following triggers notify you about health events: `assessment:check_failure`, `assessment:drifted`, `assessment:failed`.

The following triggers notify you about run events: `run:applying`, `run:completed`, `run:created`, `run:errored`, `run:needs_attention`, `run:planning`. |
| `url` _string_ | The URL of the notification. Must match pattern: `^https?://.*` |
| `emailAddresses` _string array_ | The list of email addresses that will receive notification emails. It is only available for Terraform Enterprise users. It is not available in HCP Terraform. |
| `emailUsers` _string array_ | The list of users belonging to the organization that will receive notification emails. |

#### NotificationTrigger

_Underlying type:_ _string_

NotificationTrigger represents the notifications Terraform sends when a run transitions to a different state. This resource must align with `go-tfe` type `NotificationTriggerType`. You must use one of the following values:  `run:applying`, `assessment:check_failure`, `run:completed`, `run:created`, `assessment:drifted`, `run:errored`, `assessment:failed`, `run:needs_attention`, `run:planning`.

_Appears in:_
- [Notification](#notification)

#### OutputStatus

Outputs status.

_Appears in:_
- [ModuleStatus](#modulestatus)

| Field | Description |
| --- | --- |
| `runID` _string_ | Run ID of the latest run that updated the outputs. |

#### PlanStatus

_Appears in:_
- [WorkspaceStatus](#workspacestatus)

| Field | Description |
| --- | --- |
| `id` _string_ | Latest plan-only/speculative plan HCP Terraform run ID. |
| `terraformVersion` _string_ | The version of Terraform to use for this run. |

#### Project

Project is the Schema for the projects API

| Field | Description |
| --- | --- |
| `apiVersion` _string_ | `app.terraform.io/v1alpha2`
| `kind` _string_ | `Project`
| `kind` _string_ | Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. [More information](https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds) |
| `apiVersion` _string_ | APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. [More information](https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources) |
| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.27/#objectmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. |
| `spec` _[ProjectSpec](#projectspec)_ |  |

#### ProjectSpec

ProjectSpec defines the desired state of Project. [More information](/terraform/cloud-docs/workspaces/organize-workspaces-with-projects).

_Appears in:_
- [Project](#project)

| Field | Description |
| --- | --- |
| `organization` _string_ | Organization name where the Workspace will be created. [More information](/terraform/cloud-docs/users-teams-organizations/organizations). |
| `token` _[Token](#token)_ | API Token to be used for API calls. |
| `name` _string_ | Name of the Project. |
| `teamAccess` _[ProjectTeamAccess](#projectteamaccess) array_ | HCP Terraform's access model is team-based. In order to perform an action within a HCP Terraform organization, users must belong to a team that has been granted the appropriate permissions. You can assign project-specific permissions to teams. More information:
 [Project permissions](/terraform/cloud-docs/workspaces/organize-workspaces-with-projects#permissions) - [Team project permissions](/terraform/cloud-docs/users-teams-organizations/permissions#project-permissions) |

#### ProjectTeamAccess

HCP Terraform's access model is team-based. In order to perform an action within a HCP Terraform organization, users must belong to a team that has been granted the appropriate permissions. You can assign project-specific permissions to teams. More information:

  - [Project permissions API](/terraform/cloud-docs/workspaces/organize-workspaces-with-projects#permissions)
  - [Project permissions](/terraform/cloud-docs/users-teams-organizations/permissions#project-permissions)

_Appears in:_
- [ProjectSpec](#projectspec)

| Field | Description |
| --- | --- |
| `team` _[Team](#team)_ | Team to grant access. [More information](/terraform/cloud-docs/users-teams-organizations/teams). |
| `access` _[TeamProjectAccessType](#teamprojectaccesstype)_ | There are two ways to choose which permissions a given team has on a project: fixed permission sets, and custom permissions. Must be one of the following values: `admin`, `custom`, `maintain`, `read`, `write`. More information:
 - [Project permissions](/terraform/cloud-docs/users-teams-organizations/permissions#project-permissions)
- [General project permissions](/terraform/cloud-docs/users-teams-organizations/permissions#general-project-permissions) |
| `custom` _[CustomProjectPermissions](#customprojectpermissions)_ | Custom permissions let you assign specific, finer-grained permissions to a team than the broader fixed permission sets provide. [More information](/terraform/cloud-docs/users-teams-organizations/permissions#custom-project-permissions). |

#### RemoteStateSharing

RemoteStateSharing allows remote state access between workspaces.
By default, new workspaces in HCP Terraform do not allow other workspaces to access their state. [More information](/terraform/cloud-docs/workspaces/state#accessing-state-from-other-workspaces).

_Appears in:_
- [WorkspaceSpec](#workspacespec)

| Field | Description |
| --- | --- |
| `allWorkspaces` _boolean_ | Allow access to the state for all workspaces within the same organization. Default: `false`. |
| `workspaces` _[ConsumerWorkspace](#consumerworkspace) array_ | Allow access to the state for specific workspaces within the same organization. |

#### RunStatus

_Appears in:_
- [ModuleStatus](#modulestatus)
- [WorkspaceStatus](#workspacestatus)

| Field | Description |
| --- | --- |
| `id` _string_ | Current(both active and finished) HCP Terraform run ID. |
| `configurationVersion` _string_ | The configuration version of this run. |
| `outputRunID` _string_ | Run ID of the latest run that could update the outputs. |

#### RunTrigger

RunTrigger allows you to connect this workspace to one or more source workspaces.
These connections allow runs to queue automatically in this workspace on successful apply of runs in any of the source workspaces.
Only one of the fields `ID` or `Name` is allowed.
At least one of the fields `ID` or `Name` is mandatory. [More information](/terraform/cloud-docs/workspaces/settings/run-triggers).

_Appears in:_
- [WorkspaceSpec](#workspacespec)

| Field | Description |
| --- | --- |
| `id` _string_ | Source Workspace ID. Must match pattern: `^ws-[a-zA-Z0-9]+$` |
| `name` _string_ | Source Workspace Name. |

#### SSHKey

SSH key used to clone Terraform modules. Only one of the fields `ID` or `Name` is allowed. At least one of the fields `ID` or `Name` is mandatory. [More information](/terraform/cloud-docs/workspaces/settings/ssh-keys).

_Appears in:_
- [WorkspaceSpec](#workspacespec)

| Field | Description |
| --- | --- |
| `id` _string_ | SSH key ID. Must match pattern: `^sshkey-[a-zA-Z0-9]+$` |
| `name` _string_ | SSH key name. |

#### Tag

_Underlying type:_ _string_

Tags allows you to correlate, organize, and even filter workspaces based on the assigned tags. Tags must be one or more characters; can include letters, numbers, colons, hyphens, and underscores; and must begin and end with a letter or number. Must match pattern: `^[A-Za-z0-9][A-Za-z0-9:_-]*$`

_Appears in:_
- [WorkspaceSpec](#workspacespec)

#### TargetWorkspace

TargetWorkspace is the name or ID of the workspace you want autoscale against.

_Appears in:_
- [AgentDeploymentAutoscaling](#agentdeploymentautoscaling)

| Field | Description |
| --- | --- |
| `id` _string_ | Workspace ID |
| `name` _string_ | Workspace Name |
| `wildcardName` _string_ | Wildcard Name to match match workspace names using `*` on name suffix, prefix, or both. |

#### Team

Teams are groups of HCP Terraform users within an organization. If a user belongs to at least one team in an organization, they are considered a member of that organization. Only one of the fields `ID` or `Name` is allowed. At least one of the fields `ID` or `Name` is mandatory. [More information](/terraform/cloud-docs/users-teams-organizations/teams).

_Appears in:_
- [ProjectTeamAccess](#projectteamaccess)
- [TeamAccess](#teamaccess)

| Field | Description |
| --- | --- |
| `id` _string_ | Team ID. Must match pattern: `^team-[a-zA-Z0-9]+$` |
| `name` _string_ | Team name. |

#### TeamAccess

HCP Terraform workspaces can only be accessed by users with the correct permissions. You can manage permissions for a workspace on a per-team basis. When a workspace is created, only the owners team and teams with the "manage workspaces" permission can access it, with full admin permissions. These teams' access can't be removed from a workspace.[More information](/terraform/cloud-docs/workspaces/settings/access).

_Appears in:_
- [WorkspaceSpec](#workspacespec)

| Field | Description |
| --- | --- |
| `team` _[Team](#team)_ | Team to grant access. [More information](/terraform/cloud-docs/users-teams-organizations/teams). |
| `access` _string_ | There are two ways to choose which permissions a given team has on a workspace: fixed permission sets, and custom permissions. Must be one of the following values: `admin`, `custom`, `plan`, `read`, `write`. [More information](/terraform/cloud-docs/users-teams-organizations/permissions#workspace-permissions). |
| `custom` _[CustomPermissions](#custompermissions)_ | Custom permissions let you assign specific, finer-grained permissions to a team than the broader fixed permission sets provide. [More information](/terraform/cloud-docs/users-teams-organizations/permissions#custom-workspace-permissions). |

#### Token

Token refers to a Kubernetes Secret object within the same namespace as the Workspace object

_Appears in:_
- [AgentPoolSpec](#agentpoolspec)
- [ModuleSpec](#modulespec)
- [ProjectSpec](#projectspec)
- [WorkspaceSpec](#workspacespec)

| Field | Description |
| --- | --- |
| `secretKeyRef` _[SecretKeySelector](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.27/#secretkeyselector-v1-core)_ | Selects a key of a secret in the workspace's namespace |

#### ValueFrom

ValueFrom source for the variable's value. Cannot be used if value is not empty.

_Appears in:_
- [Variable](#variable)

| Field | Description |
| --- | --- |
| `configMapKeyRef` _[ConfigMapKeySelector](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.27/#configmapkeyselector-v1-core)_ | Selects a key of a ConfigMap. |
| `secretKeyRef` _[SecretKeySelector](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.27/#secretkeyselector-v1-core)_ | Selects a key of a Secret. |

#### Variable

Variables let you customize configurations, modify Terraform's behavior, and store information like provider credentials. [More information](/terraform/cloud-docs/workspaces/variables).

_Appears in:_
- [WorkspaceSpec](#workspacespec)

| Field | Description |
| --- | --- |
| `name` _string_ | Name of the variable. |
| `description` _string_ | Description of the variable. |
| `hcl` _boolean_ | Parse this field as HashiCorp Configuration Language (HCL). This allows you to interpolate values at runtime. Default: `false`. |
| `sensitive` _boolean_ | Sensitive variables are never shown in the UI or API. They may appear in Terraform logs if your configuration is designed to output them. Default: `false`. |
| `value` _string_ | Value of the variable. |
| `valueFrom` _[ValueFrom](#valuefrom)_ | Source for the variable's value. Cannot be used if value is not empty. |

#### VariableStatus

_Appears in:_
- [WorkspaceStatus](#workspacestatus)

| Field | Description |
| --- | --- |
| `name` _string_ | Name of the variable. |
| `id` _string_ | ID of the variable. |
| `versionID` _string_ | VersionID is a hash of the variable on the HCP Terraform end. |
| `valueID` _string_ | ValueID is a hash of the variable on the CRD end. |
| `category` _string_ | Category of the variable. |

#### VersionControl

VersionControl settings for the workspace's VCS repository, enabling the UI/VCS-driven run workflow. Omit this argument to utilize the CLI-driven and API-driven workflows, where runs are not driven by webhooks on your VCS provider. More information:

  - [The UI- and VCS-driven run workflow](/terraform/cloud-docs/run/ui)
  - [Connecting VCS providers to HCP Terraform](/terraform/cloud-docs/vcs)

_Appears in:_
- [WorkspaceSpec](#workspacespec)

| Field | Description |
| --- | --- |
| `oAuthTokenID` _string_ | The VCS Connection (OAuth Connection + Token) to use. Must match pattern: `^ot-[a-zA-Z0-9]+$` |
| `repository` _string_ | A reference to your VCS repository in the format `<organization>/<repository>` where `<organization>` and `<repository>` refer to the organization and repository in your VCS provider. |
| `branch` _string_ | The repository branch that Run will execute from. This defaults to the repository's default branch (e.g. main). |
| `speculativePlans` _boolean_ | Whether this workspace allows automatic speculative plans on PR. Default: `true`. More information:
- [Speculative plans on pull requests](/terraform/cloud-docs/run/ui#speculative-plans-on-pull-requests)
- [Speculative plans](/terraform/cloud-docs/run/remote-operations#speculative-plans) |

#### Workspace

Workspace is the Schema for the workspaces API

| Field | Description |
| --- | --- |
| `apiVersion` _string_ | `app.terraform.io/v1alpha2`
| `kind` _string_ | `Workspace`
| `kind` _string_ | Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. [More information](https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds) |
| `apiVersion` _string_ | APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. [More information](https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources) |
| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.27/#objectmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. |
| `spec` _[WorkspaceSpec](#workspacespec)_ |  |

#### WorkspaceAgentPool

AgentPool allows HCP Terraform to communicate with isolated, private, or on-premises infrastructure. Only one of the fields `ID` or `Name` is allowed. At least one of the fields `ID` or `Name` is mandatory. [More information](/terraform/cloud-docs/agents).

_Appears in:_
- [WorkspaceSpec](#workspacespec)

| Field | Description |
| --- | --- |
| `id` _string_ | Agent Pool ID. Must match pattern: `^apool-[a-zA-Z0-9]+$` |
| `name` _string_ | Agent Pool name. |

#### WorkspaceProject

Projects let you organize your workspaces into groups. Only one of the fields `ID` or `Name` is allowed. At least one of the fields `ID` or `Name` is mandatory. [More information](/terraform/tutorials/cloud/projects).

_Appears in:_
- [WorkspaceSpec](#workspacespec)

| Field | Description |
| --- | --- |
| `id` _string_ | Project ID. Must match pattern: `^prj-[a-zA-Z0-9]+$` |
| `name` _string_ | Project name. |

#### WorkspaceRunTask

Run tasks allow HCP Terraform to interact with external systems at specific points in the HCP Terraform run lifecycle. Only one of the fields `ID` or `Name` is allowed. At least one of the fields `ID` or `Name` is mandatory. [More information](/terraform/cloud-docs/workspaces/settings/run-tasks).

_Appears in:_
- [WorkspaceSpec](#workspacespec)

| Field | Description |
| --- | --- |
| `id` _string_ | Run Task ID. Must match pattern: `^task-[a-zA-Z0-9]+$` |
| `name` _string_ | Run Task Name. |
| `enforcementLevel` _string_ | Run Task Enforcement Level. Can be one of `advisory` or `mandatory`. Default: `advisory`. Must be one of the following values: `advisory`, `mandatory` Default: `advisory`. |
| `stage` _string_ | Run Task Stage. Must be one of the following values: `pre_apply`, `pre_plan`, `post_plan`. Default: `post_plan`. |

#### WorkspaceSpec

WorkspaceSpec defines the desired state of Workspace.

_Appears in:_
- [Workspace](#workspace)

| Field | Description |
| --- | --- |
| `name` _string_ | Workspace name. |
| `organization` _string_ | Organization name where the Workspace will be created. [More information](/terraform/cloud-docs/users-teams-organizations/organizations). |
| `token` _[Token](#token)_ | API Token to be used for API calls. |
| `applyMethod` _string_ | Define either change will be applied automatically(auto) or require an operator to confirm(manual). Must be one of the following values: `auto`, `manual`. Default: `manual`. [More information](/terraform/cloud-docs/workspaces/settings#auto-apply-and-manual-apply). |
| `allowDestroyPlan` _boolean_ | Allows a destroy plan to be created and applied. Default: `true`. [More information](/terraform/cloud-docs/workspaces/settings#destruction-and-deletion). |
| `description` _string_ | Workspace description. |
| `agentPool` _[WorkspaceAgentPool](#workspaceagentpool)_ | HCP Terraform Agents allow HCP Terraform to communicate with isolated, private, or on-premises infrastructure. [More information](/terraform/cloud-docs/agents). |
| `executionMode` _string_ | Define where the Terraform code will be executed. Must be one of the following values: `agent`, `local`, `remote`. Default: `remote`. [More information](/terraform/cloud-docs/workspaces/settings#execution-mode). |
| `runTasks` _[WorkspaceRunTask](#workspaceruntask) array_ | Run tasks allow HCP Terraform to interact with external systems at specific points in the HCP Terraform run lifecycle. [More information](/terraform/cloud-docs/workspaces/settings/run-tasks). |
| `tags` _[Tag](#tag) array_ | Workspace tags are used to help identify and group together workspaces. Tags must be one or more characters; can include letters, numbers, colons, hyphens, and underscores; and must begin and end with a letter or number. |
| `teamAccess` _[TeamAccess](#teamaccess) array_ | HCP Terraform workspaces can only be accessed by users with the correct permissions. You can manage permissions for a workspace on a per-team basis. When a workspace is created, only the owners team and teams with the "manage workspaces" permission can access it, with full admin permissions. These teams' access can't be removed from a workspace. [More information](/terraform/cloud-docs/workspaces/settings/access). |
| `terraformVersion` _string_ | The version of Terraform to use for this workspace. If not specified, the latest available version will be used. Must match pattern: `^\\d{1}\\.\\d{1,2}\\.\\d{1,2}$` More information:   - /cloud-docs/workspaces/settings#terraform-version |
| `workingDirectory` _string_ | The directory where Terraform will execute, specified as a relative path from the root of the configuration directory. More information:   - /cloud-docs/workspaces/settings#terraform-working-directory |
| `environmentVariables` _[Variable](#variable) array_ | Terraform Environment variables for all plans and applies in this workspace. Variables defined within a workspace always overwrite variables from variable sets that have the same type and the same key. More information:
 - [Workspace variables](/terraform/cloud-docs/workspaces/variables)
 - [Environment variables](/terraform/cloud-docs/workspaces/variables#environment-variables) |
| `terraformVariables` _[Variable](#variable) array_ | Terraform variables for all plans and applies in this workspace. Variables defined within a workspace always overwrite variables from variable sets that have the same type and the same key. [More information:
 - [Workspace variables](/terraform/cloud-docs/workspaces/variables)
- [Terraform variables](/terraform/cloud-docs/workspaces/variables#terraform-variables) |
| `remoteStateSharing` _[RemoteStateSharing](#remotestatesharing)_ | Remote state access between workspaces. By default, new workspaces in HCP Terraform do not allow other workspaces to access their state. [More information](/terraform/cloud-docs/workspaces/state#accessing-state-from-other-workspaces). |
| `runTriggers` _[RunTrigger](#runtrigger) array_ | Run triggers allow you to connect this workspace to one or more source workspaces. These connections allow runs to queue automatically in this workspace on successful apply of runs in any of the source workspaces. [More information](/terraform/cloud-docs/workspaces/settings/run-triggers). |
| `versionControl` _[VersionControl](#versioncontrol)_ | Settings for the workspace's VCS repository, enabling the UI/VCS-driven run workflow. Omit this argument to utilize the CLI-driven and API-driven workflows, where runs are not driven by webhooks on your VCS provider. More information:   - /cloud-docs/run/ui   - /cloud-docs/vcs |
| `sshKey` _[SSHKey](#sshkey)_ | SSH key used to clone Terraform modules. [More information](/terraform/cloud-docs/workspaces/settings/ssh-keys). |
| `notifications` _[Notification](#notification) array_ | Notifications allow you to send messages to other applications based on run and workspace events. [More information](/terraform/cloud-docs/workspaces/settings/notifications). |
| `project` _[WorkspaceProject](#workspaceproject)_ | Projects let you organize your workspaces into groups. Default: default organization project. [More information](/terraform/tutorials/cloud/projects). |
| `deletionPolicy` _[DeletionPolicy](#deletionpolicy)_ | The Deletion Policy specifies the behavior of the custom resource and its associated workspace when the custom resource is deleted.
- `retain`: When you delete the custom resource, the operator does not delete the workspace.
- `soft`: Attempts to delete the associated workspace only if it does not contain any managed resources.
- `destroy`: Executes a destroy operation to remove all resources managed by the associated workspace. Once the destruction of these resources is successful, the operator deletes the workspace, and then deletes the custom resource.
- `force`: Forcefully and immediately deletes the workspace and the custom resource.
Default: `retain`. |

page title  HCP Terraform Operator for Kubernetes API reference description       API reference for the HCP Terraform Operator for Kubernetes         API Reference     Packages    app terraform io v1alpha2   appterraformiov1alpha2      app terraform io v1alpha2  Package v1alpha2 contains API Schema definitions for the app v1alpha2 API group      Resource Types    AgentPool   agentpool     Module   module     Project   project     Workspace   workspace        AgentDeployment   Appears in      AgentPoolSpec   agentpoolspec     Field   Description                    replicas   integer          spec    PodSpec  https   kubernetes io docs reference generated kubernetes api v1 27  podspec v1 core           annotations   object  keys string  values string     The annotations that the operator will apply to the pod template in the deployment       labels   object  keys string  values string     The labels that the operator will apply to the pod template in the deployment          AgentDeploymentAutoscaling  AgentDeploymentAutoscaling configures the operator to scale the deployment for an AgentPool up and down to meet demand    Appears in      AgentPoolSpec   agentpoolspec     Field   Description                    maxReplicas   integer    MaxReplicas is the maximum number of replicas for the Agent deployment       minReplicas   integer    MinReplicas is the minimum number of replicas for the Agent deployment       targetWorkspaces    TargetWorkspace   targetworkspace     TargetWorkspaces is a list of HCP Terraform Workspaces which the agent pool should scale up to meet demand  When this field is omitted the autoscaler will target all workspaces that are associated with the AgentPool       cooldownPeriodSeconds   integer    CooldownPeriodSeconds is the time to wait between scaling events  Defaults to 300       cooldownPeriod    AgentDeploymentAutoscalingCooldownPeriod   agentdeploymentautoscalingcooldownperiod     CoolDownPeriod is the period to wait between scaling up and scaling down         AgentDeploymentAutoscalingCooldownPeriod  AgentDeploymentAutoscalingCooldownPeriod configures the period to wait between scaling up and scaling down    Appears in      AgentDeploymentAutoscaling   agentdeploymentautoscaling     Field   Description                    scaleUpSeconds   integer    ScaleUpSeconds is the time to wait before scaling up       scaleDownSeconds   integer    ScaleDownSeconds is the time to wait before scaling down          AgentDeploymentAutoscalingStatus  AgentDeploymentAutoscalingStatus   Appears in      AgentPoolStatus   agentpoolstatus     Field   Description                    desiredReplicas   integer    Desired number of agent replicas      lastScalingEvent    Time  https   kubernetes io docs reference generated kubernetes api v1 27  time v1 meta     Last time the agent pool was scaledx         AgentPool  AgentPool is the Schema for the agentpools API     Field   Description                    apiVersion   string     app terraform io v1alpha2     kind   string     AgentPool     kind   string    Kind is a string value representing the REST resource this object represents  Servers may infer this from the endpoint the client submits requests to  Cannot be updated  In CamelCase   More information  https   git k8s io community contributors devel sig architecture api conventions md types kinds       apiVersion   string    APIVersion defines the versioned schema of this representation of an object  Servers should convert recognized schemas to the latest internal value  and may reject unrecognized values   More information  https   git k8s io community contributors devel sig architecture api conventions md resources       metadata    ObjectMeta  https   kubernetes io docs reference generated kubernetes api v1 27  objectmeta v1 meta     Refer to Kubernetes API documentation for fields of  metadata        spec    AgentPoolSpec   agentpoolspec              AgentPoolSpec  AgentPoolSpec defines the desired state of AgentPool    Appears in      AgentPool   agentpool     Field   Description                    name   string    Agent Pool name   More information   terraform cloud docs agents agent pools        organization   string    Organization name where the Workspace will be created   More information   terraform cloud docs users teams organizations organizations        token    Token   token     API Token to be used for API calls       agentTokens    AgentToken   agenttoken  array    List of the agent tokens to generate       agentDeployment    AgentDeployment   agentdeployment     Agent deployment settings      autoscaling    AgentDeploymentAutoscaling   agentdeploymentautoscaling     Agent deployment settings         AgentToken  Terraform uses  AgentTokens  to connect to the Terraform agent pool  Only the field  Name  is allowed in the  spec  list  Use the other fields in the  status  list   More information   terraform cloud docs agents     Appears in      AgentPoolSpec   agentpoolspec     AgentPoolStatus   agentpoolstatus     Field   Description                    name   string    Agent Token name       id   string    Agent Token ID       createdAt   integer    Timestamp of when the agent token was created       lastUsedAt   integer    Timestamp of when the agent token was last used          ConfigurationVersionStatus  A configuration version is a resource used to reference the uploaded configuration files  More information       Configuration versions API   terraform cloud docs api docs configuration versions       The API driven run workflow   terraform cloud docs run api    Appears in      ModuleStatus   modulestatus     Field   Description                    id   string    Configuration Version ID          ConsumerWorkspace  ConsumerWorkspace allows access to the state for specific workspaces within the same organization  Only one of the fields  ID  or  Name  is allowed  At least one of the fields  ID  or  Name  is mandatory   More information   terraform cloud docs workspaces state remote state access controls     Appears in      RemoteStateSharing   remotestatesharing     Field   Description                    id   string    Consumer Workspace ID  Must match pattern    ws  a zA Z0 9          name   string    Consumer Workspace name          CustomPermissions  Custom permissions let you assign specific  finer grained permissions to a team than the broader fixed permission sets provide   More information   terraform cloud docs users teams organizations permissions custom workspace permissions     Appears in      TeamAccess   teamaccess     Field   Description                    runs   string    Run access  Must be one of the following values   apply    plan    read   Default   read        runTasks   boolean    Manage Workspace Run Tasks  Default   false        sentinel   string    Download Sentinel mocks  Must be one of the following values   none    read   Default   none        stateVersions   string    State access  Must be one of the following values   none    read    read outputs    write   Default   none        variables   string    Variable access  Must be one of the following values   none    read    write   Default   none        workspaceLocking   boolean    Lock unlock workspace  Default   false           CustomProjectPermissions  Custom permissions let you assign specific  finer grained permissions to a team than the broader fixed permission sets provide  More information       Custom project permissions   terraform cloud docs users teams organizations permissions custom project permissions       General workspace permissions   terraform cloud docs users teams organizations permissions general workspace permissions    Appears in      ProjectTeamAccess   projectteamaccess     Field   Description                    projectAccess    ProjectSettingsPermissionType   projectsettingspermissiontype     Project access  Must be one of the following values   delete    read    update   Default   read        teamManagement    ProjectTeamsPermissionType   projectteamspermissiontype     Team management  Must be one of the following values   manage    none    read   Default   none        createWorkspace   boolean    Allow users to create workspaces in the project  This grants read access to all workspaces in the project  Default   false        deleteWorkspace   boolean    Allows users to delete workspaces in the project  Default   false        moveWorkspace   boolean    Allows users to move workspaces out of the project  A user must have this permission on both the source and destination project to successfully move a workspace from one project to another  Default   false        lockWorkspace   boolean    Allows users to manually lock the workspace to temporarily prevent runs  When a workspace s execution mode is set to  local   users must have this permission to perform local CLI runs using the workspace s state  Default   false        runs    WorkspaceRunsPermissionType   workspacerunspermissiontype     Run access  Must be one of the following values   apply    plan    read   Default   read        runTasks   boolean    Manage Workspace Run Tasks  Default   false        sentinelMocks    WorkspaceSentinelMocksPermissionType   workspacesentinelmockspermissiontype     Download Sentinel mocks  Must be one of the following values   none    read   Default   none        stateVersions    WorkspaceStateVersionsPermissionType   workspacestateversionspermissiontype     State access  Must be one of the following values   none    read    read outputs    write   Default   none        variables    WorkspaceVariablesPermissionType   workspacevariablespermissiontype     Variable access  Must be one of the following values   none    read    write   Default   none           DeletionPolicy   Underlying type    string   DeletionPolicy defines the strategy the Kubernetes operator uses when you delete a resource  either manually or by a system event    You must use one of the following values     retain   When you delete the custom resource  the operator does not delete the workspace     soft   Attempts to delete the associated workspace only if it does not contain any managed resources     destroy   Executes a destroy operation to remove all resources managed by the associated workspace  Once the destruction of these resources is successful  the operator deletes the workspace  and then deletes the custom resource     force   Forcefully and immediately deletes the workspace and the custom resource    Appears in      WorkspaceSpec   workspacespec         Module  Module is the Schema for the modules API Module implements the API driven Run Workflow   More information   terraform cloud docs run api      Field   Description                    apiVersion   string     app terraform io v1alpha2     kind   string     Module     kind   string    Kind is a string value representing the REST resource this object represents  Servers may infer this from the endpoint the client submits requests to  Cannot be updated  In CamelCase   More information  https   git k8s io community contributors devel sig architecture api conventions md types kinds       apiVersion   string    APIVersion defines the versioned schema of this representation of an object  Servers should convert recognized schemas to the latest internal value  and may reject unrecognized values   More information  https   git k8s io community contributors devel sig architecture api conventions md resources       metadata    ObjectMeta  https   kubernetes io docs reference generated kubernetes api v1 27  objectmeta v1 meta     Refer to Kubernetes API documentation for fields of  metadata        spec    ModuleSpec   modulespec              ModuleOutput  Module outputs to store in ConfigMap non sensitive  or Secret sensitive     Appears in      ModuleSpec   modulespec     Field   Description                    name   string    Output name must match with the module output       sensitive   boolean    Specify whether or not the output is sensitive  Default   false           ModuleSource  Module source and version to execute    Appears in      ModuleSpec   modulespec     Field   Description                    source   string    Non local Terraform module source   More information   terraform language modules sources        version   string    Terraform module version          ModuleSpec  ModuleSpec defines the desired state of Module    Appears in      Module   module     Field   Description                    organization   string    Organization name where the Workspace will be created   More information   terraform cloud docs users teams organizations organizations        token    Token   token     API Token to be used for API calls       module    ModuleSource   modulesource     Module source and version to execute       workspace    ModuleWorkspace   moduleworkspace     Workspace to execute the module       name   string    Name of the module that will be uploaded and executed  Default   this        variables    ModuleVariable   modulevariable  array    Variables to pass to the module  they must exist in the Workspace       outputs    ModuleOutput   moduleoutput  array    Module outputs to store in ConfigMap non sensitive  or Secret sensitive        destroyOnDeletion   boolean    Specify whether or not to execute a Destroy run when the object is deleted from the Kubernetes  Default   false        restartedAt   string    Allows executing a new Run without changing any Workspace or Module attributes  Example    kubectl patch KIND NAME   type merge   patch    spec     restartedAt       date  u  Iseconds                  ModuleVariable  Variables to pass to the module    Appears in      ModuleSpec   modulespec     Field   Description                    name   string    Variable name must exist in the Workspace          ModuleWorkspace  Workspace to execute the module  Only one of the fields  ID  or  Name  is allowed  At least one of the fields  ID  or  Name  is mandatory    Appears in      ModuleSpec   modulespec     Field   Description                    id   string    Module Workspace ID  Must match pattern    ws  a zA Z0 9          name   string    Module Workspace Name           Notification  Notifications allow you to send messages to other applications based on run and workspace events   More information   terraform cloud docs workspaces settings notifications     Appears in      WorkspaceSpec   workspacespec     Field   Description                    name   string    Notification name       type    NotificationDestinationType   notificationdestinationtype     The type of the notification  Must be one of the following values   email    generic    microsoft teams    slack        enabled   boolean    Whether the notification configuration should be enabled or not  Default   true        token   string    The token of the notification       triggers    NotificationTrigger   notificationtrigger  array    The list of run events that trigger notifications  Triggers are notifications that Terraform sends when a run transitions to a different state   br   br  The following triggers notify you about health events   assessment check failure    assessment drifted    assessment failed    br   br  The following triggers notify you about run events   run applying    run completed    run created    run errored    run needs attention    run planning        url   string    The URL of the notification  Must match pattern    https             emailAddresses   string array    The list of email addresses that will receive notification emails  It is only available for Terraform Enterprise users  It is not available in HCP Terraform       emailUsers   string array    The list of users belonging to the organization that will receive notification emails           NotificationTrigger   Underlying type    string   NotificationTrigger represents the notifications Terraform sends when a run transitions to a different state  This resource must align with  go tfe  type  NotificationTriggerType   You must use one of the following values    run applying    assessment check failure    run completed    run created    assessment drifted    run errored    assessment failed    run needs attention    run planning     Appears in      Notification   notification        OutputStatus  Outputs status    Appears in      ModuleStatus   modulestatus     Field   Description                    runID   string    Run ID of the latest run that updated the outputs          PlanStatus   Appears in      WorkspaceStatus   workspacestatus     Field   Description                    id   string    Latest plan only speculative plan HCP Terraform run ID       terraformVersion   string    The version of Terraform to use for this run          Project  Project is the Schema for the projects API    Field   Description                    apiVersion   string     app terraform io v1alpha2     kind   string     Project     kind   string    Kind is a string value representing the REST resource this object represents  Servers may infer this from the endpoint the client submits requests to  Cannot be updated  In CamelCase   More information  https   git k8s io community contributors devel sig architecture api conventions md types kinds       apiVersion   string    APIVersion defines the versioned schema of this representation of an object  Servers should convert recognized schemas to the latest internal value  and may reject unrecognized values   More information  https   git k8s io community contributors devel sig architecture api conventions md resources       metadata    ObjectMeta  https   kubernetes io docs reference generated kubernetes api v1 27  objectmeta v1 meta     Refer to Kubernetes API documentation for fields of  metadata        spec    ProjectSpec   projectspec              ProjectSpec  ProjectSpec defines the desired state of Project   More information   terraform cloud docs workspaces organize workspaces with projects     Appears in      Project   project     Field   Description                    organization   string    Organization name where the Workspace will be created   More information   terraform cloud docs users teams organizations organizations        token    Token   token     API Token to be used for API calls       name   string    Name of the Project       teamAccess    ProjectTeamAccess   projectteamaccess  array    HCP Terraform s access model is team based  In order to perform an action within a HCP Terraform organization  users must belong to a team that has been granted the appropriate permissions  You can assign project specific permissions to teams  More information   br     Project permissions   terraform cloud docs workspaces organize workspaces with projects permissions     Team project permissions   terraform cloud docs users teams organizations permissions project permissions          ProjectTeamAccess  HCP Terraform s access model is team based  In order to perform an action within a HCP Terraform organization  users must belong to a team that has been granted the appropriate permissions  You can assign project specific permissions to teams  More information        Project permissions API   terraform cloud docs workspaces organize workspaces with projects permissions       Project permissions   terraform cloud docs users teams organizations permissions project permissions    Appears in      ProjectSpec   projectspec     Field   Description                    team    Team   team     Team to grant access   More information   terraform cloud docs users teams organizations teams        access    TeamProjectAccessType   teamprojectaccesstype     There are two ways to choose which permissions a given team has on a project  fixed permission sets  and custom permissions  Must be one of the following values   admin    custom    maintain    read    write   More information   br       Project permissions   terraform cloud docs users teams organizations permissions project permissions   br      General project permissions   terraform cloud docs users teams organizations permissions general project permissions       custom    CustomProjectPermissions   customprojectpermissions     Custom permissions let you assign specific  finer grained permissions to a team than the broader fixed permission sets provide   More information   terraform cloud docs users teams organizations permissions custom project permissions           RemoteStateSharing  RemoteStateSharing allows remote state access between workspaces  By default  new workspaces in HCP Terraform do not allow other workspaces to access their state   More information   terraform cloud docs workspaces state accessing state from other workspaces     Appears in      WorkspaceSpec   workspacespec     Field   Description                    allWorkspaces   boolean    Allow access to the state for all workspaces within the same organization  Default   false        workspaces    ConsumerWorkspace   consumerworkspace  array    Allow access to the state for specific workspaces within the same organization          RunStatus   Appears in      ModuleStatus   modulestatus     WorkspaceStatus   workspacestatus     Field   Description                    id   string    Current both active and finished  HCP Terraform run ID       configurationVersion   string    The configuration version of this run       outputRunID   string    Run ID of the latest run that could update the outputs          RunTrigger  RunTrigger allows you to connect this workspace to one or more source workspaces  These connections allow runs to queue automatically in this workspace on successful apply of runs in any of the source workspaces  Only one of the fields  ID  or  Name  is allowed  At least one of the fields  ID  or  Name  is mandatory   More information   terraform cloud docs workspaces settings run triggers     Appears in      WorkspaceSpec   workspacespec     Field   Description                    id   string    Source Workspace ID  Must match pattern    ws  a zA Z0 9          name   string    Source Workspace Name          SSHKey  SSH key used to clone Terraform modules  Only one of the fields  ID  or  Name  is allowed  At least one of the fields  ID  or  Name  is mandatory   More information   terraform cloud docs workspaces settings ssh keys     Appears in      WorkspaceSpec   workspacespec     Field   Description                    id   string    SSH key ID  Must match pattern    sshkey  a zA Z0 9          name   string    SSH key name          Tag   Underlying type    string   Tags allows you to correlate  organize  and even filter workspaces based on the assigned tags  Tags must be one or more characters  can include letters  numbers  colons  hyphens  and underscores  and must begin and end with a letter or number  Must match pattern     A Za z0 9  A Za z0 9          Appears in      WorkspaceSpec   workspacespec        TargetWorkspace  TargetWorkspace is the name or ID of the workspace you want autoscale against    Appears in      AgentDeploymentAutoscaling   agentdeploymentautoscaling     Field   Description                    id   string    Workspace ID      name   string    Workspace Name      wildcardName   string    Wildcard Name to match match workspace names using     on name suffix  prefix  or both          Team  Teams are groups of HCP Terraform users within an organization  If a user belongs to at least one team in an organization  they are considered a member of that organization  Only one of the fields  ID  or  Name  is allowed  At least one of the fields  ID  or  Name  is mandatory   More information   terraform cloud docs users teams organizations teams     Appears in      ProjectTeamAccess   projectteamaccess     TeamAccess   teamaccess     Field   Description                    id   string    Team ID  Must match pattern    team  a zA Z0 9          name   string    Team name          TeamAccess  HCP Terraform workspaces can only be accessed by users with the correct permissions  You can manage permissions for a workspace on a per team basis  When a workspace is created  only the owners team and teams with the  manage workspaces  permission can access it  with full admin permissions  These teams  access can t be removed from a workspace  More information   terraform cloud docs workspaces settings access     Appears in      WorkspaceSpec   workspacespec     Field   Description                    team    Team   team     Team to grant access   More information   terraform cloud docs users teams organizations teams        access   string    There are two ways to choose which permissions a given team has on a workspace  fixed permission sets  and custom permissions  Must be one of the following values   admin    custom    plan    read    write    More information   terraform cloud docs users teams organizations permissions workspace permissions        custom    CustomPermissions   custompermissions     Custom permissions let you assign specific  finer grained permissions to a team than the broader fixed permission sets provide   More information   terraform cloud docs users teams organizations permissions custom workspace permissions           Token  Token refers to a Kubernetes Secret object within the same namespace as the Workspace object   Appears in      AgentPoolSpec   agentpoolspec     ModuleSpec   modulespec     ProjectSpec   projectspec     WorkspaceSpec   workspacespec     Field   Description                    secretKeyRef    SecretKeySelector  https   kubernetes io docs reference generated kubernetes api v1 27  secretkeyselector v1 core     Selects a key of a secret in the workspace s namespace         ValueFrom  ValueFrom source for the variable s value  Cannot be used if value is not empty    Appears in      Variable   variable     Field   Description                    configMapKeyRef    ConfigMapKeySelector  https   kubernetes io docs reference generated kubernetes api v1 27  configmapkeyselector v1 core     Selects a key of a ConfigMap       secretKeyRef    SecretKeySelector  https   kubernetes io docs reference generated kubernetes api v1 27  secretkeyselector v1 core     Selects a key of a Secret          Variable  Variables let you customize configurations  modify Terraform s behavior  and store information like provider credentials   More information   terraform cloud docs workspaces variables     Appears in      WorkspaceSpec   workspacespec     Field   Description                    name   string    Name of the variable       description   string    Description of the variable       hcl   boolean    Parse this field as HashiCorp Configuration Language  HCL   This allows you to interpolate values at runtime  Default   false        sensitive   boolean    Sensitive variables are never shown in the UI or API  They may appear in Terraform logs if your configuration is designed to output them  Default   false        value   string    Value of the variable       valueFrom    ValueFrom   valuefrom     Source for the variable s value  Cannot be used if value is not empty          VariableStatus   Appears in      WorkspaceStatus   workspacestatus     Field   Description                    name   string    Name of the variable       id   string    ID of the variable       versionID   string    VersionID is a hash of the variable on the HCP Terraform end       valueID   string    ValueID is a hash of the variable on the CRD end       category   string    Category of the variable          VersionControl  VersionControl settings for the workspace s VCS repository  enabling the UI VCS driven run workflow  Omit this argument to utilize the CLI driven and API driven workflows  where runs are not driven by webhooks on your VCS provider  More information        The UI  and VCS driven run workflow   terraform cloud docs run ui       Connecting VCS providers to HCP Terraform   terraform cloud docs vcs    Appears in      WorkspaceSpec   workspacespec     Field   Description                    oAuthTokenID   string    The VCS Connection  OAuth Connection   Token  to use  Must match pattern    ot  a zA Z0 9          repository   string    A reference to your VCS repository in the format   organization   repository   where   organization   and   repository   refer to the organization and repository in your VCS provider       branch   string    The repository branch that Run will execute from  This defaults to the repository s default branch  e g  main        speculativePlans   boolean    Whether this workspace allows automatic speculative plans on PR  Default   true   More information   br      Speculative plans on pull requests   terraform cloud docs run ui speculative plans on pull requests   br      Speculative plans   terraform cloud docs run remote operations speculative plans          Workspace  Workspace is the Schema for the workspaces API    Field   Description                    apiVersion   string     app terraform io v1alpha2     kind   string     Workspace     kind   string    Kind is a string value representing the REST resource this object represents  Servers may infer this from the endpoint the client submits requests to  Cannot be updated  In CamelCase   More information  https   git k8s io community contributors devel sig architecture api conventions md types kinds       apiVersion   string    APIVersion defines the versioned schema of this representation of an object  Servers should convert recognized schemas to the latest internal value  and may reject unrecognized values   More information  https   git k8s io community contributors devel sig architecture api conventions md resources       metadata    ObjectMeta  https   kubernetes io docs reference generated kubernetes api v1 27  objectmeta v1 meta     Refer to Kubernetes API documentation for fields of  metadata        spec    WorkspaceSpec   workspacespec              WorkspaceAgentPool  AgentPool allows HCP Terraform to communicate with isolated  private  or on premises infrastructure  Only one of the fields  ID  or  Name  is allowed  At least one of the fields  ID  or  Name  is mandatory   More information   terraform cloud docs agents     Appears in      WorkspaceSpec   workspacespec     Field   Description                    id   string    Agent Pool ID  Must match pattern    apool  a zA Z0 9          name   string    Agent Pool name          WorkspaceProject  Projects let you organize your workspaces into groups  Only one of the fields  ID  or  Name  is allowed  At least one of the fields  ID  or  Name  is mandatory   More information   terraform tutorials cloud projects     Appears in      WorkspaceSpec   workspacespec     Field   Description                    id   string    Project ID  Must match pattern    prj  a zA Z0 9          name   string    Project name          WorkspaceRunTask  Run tasks allow HCP Terraform to interact with external systems at specific points in the HCP Terraform run lifecycle  Only one of the fields  ID  or  Name  is allowed  At least one of the fields  ID  or  Name  is mandatory   More information   terraform cloud docs workspaces settings run tasks     Appears in      WorkspaceSpec   workspacespec     Field   Description                    id   string    Run Task ID  Must match pattern    task  a zA Z0 9          name   string    Run Task Name       enforcementLevel   string    Run Task Enforcement Level  Can be one of  advisory  or  mandatory   Default   advisory   Must be one of the following values   advisory    mandatory  Default   advisory        stage   string    Run Task Stage  Must be one of the following values   pre apply    pre plan    post plan   Default   post plan           WorkspaceSpec  WorkspaceSpec defines the desired state of Workspace    Appears in      Workspace   workspace     Field   Description                    name   string    Workspace name       organization   string    Organization name where the Workspace will be created   More information   terraform cloud docs users teams organizations organizations        token    Token   token     API Token to be used for API calls       applyMethod   string    Define either change will be applied automatically auto  or require an operator to confirm manual   Must be one of the following values   auto    manual   Default   manual    More information   terraform cloud docs workspaces settings auto apply and manual apply        allowDestroyPlan   boolean    Allows a destroy plan to be created and applied  Default   true    More information   terraform cloud docs workspaces settings destruction and deletion        description   string    Workspace description       agentPool    WorkspaceAgentPool   workspaceagentpool     HCP Terraform Agents allow HCP Terraform to communicate with isolated  private  or on premises infrastructure   More information   terraform cloud docs agents        executionMode   string    Define where the Terraform code will be executed  Must be one of the following values   agent    local    remote   Default   remote    More information   terraform cloud docs workspaces settings execution mode        runTasks    WorkspaceRunTask   workspaceruntask  array    Run tasks allow HCP Terraform to interact with external systems at specific points in the HCP Terraform run lifecycle   More information   terraform cloud docs workspaces settings run tasks        tags    Tag   tag  array    Workspace tags are used to help identify and group together workspaces  Tags must be one or more characters  can include letters  numbers  colons  hyphens  and underscores  and must begin and end with a letter or number       teamAccess    TeamAccess   teamaccess  array    HCP Terraform workspaces can only be accessed by users with the correct permissions  You can manage permissions for a workspace on a per team basis  When a workspace is created  only the owners team and teams with the  manage workspaces  permission can access it  with full admin permissions  These teams  access can t be removed from a workspace   More information   terraform cloud docs workspaces settings access        terraformVersion   string    The version of Terraform to use for this workspace  If not specified  the latest available version will be used  Must match pattern      d 1      d 1 2      d 1 2    More information       cloud docs workspaces settings terraform version      workingDirectory   string    The directory where Terraform will execute  specified as a relative path from the root of the configuration directory  More information       cloud docs workspaces settings terraform working directory      environmentVariables    Variable   variable  array    Terraform Environment variables for all plans and applies in this workspace  Variables defined within a workspace always overwrite variables from variable sets that have the same type and the same key  More information   br       Workspace variables   terraform cloud docs workspaces variables   br       Environment variables   terraform cloud docs workspaces variables environment variables       terraformVariables    Variable   variable  array    Terraform variables for all plans and applies in this workspace  Variables defined within a workspace always overwrite variables from variable sets that have the same type and the same key   More information   br       Workspace variables   terraform cloud docs workspaces variables   br      Terraform variables   terraform cloud docs workspaces variables terraform variables       remoteStateSharing    RemoteStateSharing   remotestatesharing     Remote state access between workspaces  By default  new workspaces in HCP Terraform do not allow other workspaces to access their state   More information   terraform cloud docs workspaces state accessing state from other workspaces        runTriggers    RunTrigger   runtrigger  array    Run triggers allow you to connect this workspace to one or more source workspaces  These connections allow runs to queue automatically in this workspace on successful apply of runs in any of the source workspaces   More information   terraform cloud docs workspaces settings run triggers        versionControl    VersionControl   versioncontrol     Settings for the workspace s VCS repository  enabling the UI VCS driven run workflow  Omit this argument to utilize the CLI driven and API driven workflows  where runs are not driven by webhooks on your VCS provider  More information       cloud docs run ui      cloud docs vcs      sshKey    SSHKey   sshkey     SSH key used to clone Terraform modules   More information   terraform cloud docs workspaces settings ssh keys        notifications    Notification   notification  array    Notifications allow you to send messages to other applications based on run and workspace events   More information   terraform cloud docs workspaces settings notifications        project    WorkspaceProject   workspaceproject     Projects let you organize your workspaces into groups  Default  default organization project   More information   terraform tutorials cloud projects        deletionPolicy    DeletionPolicy   deletionpolicy     The Deletion Policy specifies the behavior of the custom resource and its associated workspace when the custom resource is deleted  br      retain   When you delete the custom resource  the operator does not delete the workspace  br      soft   Attempts to delete the associated workspace only if it does not contain any managed resources  br      destroy   Executes a destroy operation to remove all resources managed by the associated workspace  Once the destruction of these resources is successful  the operator deletes the workspace  and then deletes the custom resource  br      force   Forcefully and immediately deletes the workspace and the custom resource  br   Default   retain


terraform Learn how to automatically migrate state to HCP Terraform or Terraform Enterprise using the Terraform migrate CLI tool page title Terraform migrate HCP Terraform Terraform migrate Terraform migrate automatically migrates your Terraform Community Edition state to HCP Terraform or Terraform Enterprise It also updates your local configuration with any necessary changes and optionally creates a pull request to update your code repository

Answer:
---
page_title: Terraform migrate - HCP Terraform
description: >-
  Learn how to automatically migrate state to HCP Terraform or Terraform Enterprise using the Terraform migrate CLI tool
---

# Terraform migrate

Terraform migrate automatically migrates your Terraform Community Edition state to HCP Terraform or Terraform Enterprise. It also updates your local configuration with any necessary changes and optionally creates a pull request to update your code repository.

## Overview

Complete the following steps to migrate Terraform state using the CLI:

1. Download and install `tf-migrate`: You can manually download and install or use Homebrew if you are on macOS.
1. `tf-migrate prepare`: This step scans the current working directory and generates Terraform configuration to migrate your state. The generated migration plan depends on the structure of your configuration. For more information, refer to [tf-migrate prepare](/terraform/cloud-docs/migrate/tf-migrate/reference/prepare).

1. `tf-migrate execute`: This step directs Terraform to run the `init`, `plan`, and `apply` commands to perform the migration to HCP Terraform or Terraform Enterprise. At the end of the migration, `tf-migrate` displays a summary of what it migrated, links to the workspaces it created, and, if configured, a link to the pull request it created. For more information, refer to [tf-migrate execute](/terraform/cloud-docs/migrate/tf-migrate/reference/execute).

## Install

<Tabs>

<Tab heading="Manual installation">

HashiCorp distributes Terraform migrate as a binary package. To install Terraform migrate, find the [appropriate binary](https://releases.hashicorp.com/tf-migrate/) for your operating system and download it as a zip archive.

After you download Terraform migrate, unzip the archive. Terraform migrate runs as a single binary named `tf-migrate`.

Finally, make sure that the `tf-migrate` binary is available in a directory that is in your system's `PATH`.

### Verify the installation

Every build of Terraform migrate includes a `SHA256SUMS` and a `SHA256SUMS.sig` file to validate your downloaded binary. Refer to the [verify HashiCorp binary downloads tutorial](https://developer.hashicorp.com/well-architected-framework/operational-excellence/verify-hashicorp-binary) for more information.

</Tab>

<Tab heading="Homebrew of macOS">

[Homebrew](https://brew.sh/) is a free and open-source package management system for macOS. You can install the official [Terraform migrate](https://github.com/hashicorp/homebrew-tap) formula from the terminal.

First, install the HashiCorp tap, a repository of all our Homebrew packages.

```
$ brew tap hashicorp/tap
```

Now, install Terraform migrate with the `hashicorp/tap/tf-migrate` formula.

```
$ brew install hashicorp/tap/tf-migrate
```

</Tab>

</Tabs>

## Authentication

Terraform migrate uses your locally configured Terraform CLI API token. If you have not authenticated your local Terraform installation with HCP Terraform, use the `terraform login` command to create an authentication token.

```
$ terraform login

Terraform will request an API token for app.terraform.io using your browser.

If login is successful, Terraform will store the token in plain text in
the following file for use by subsequent commands:
   /Users/redacted/.terraform.d/credentials.tfrc.json

Do you want to proceed?
 Only 'yes' will be accepted to confirm.

 Enter a value: yes
```

Terraform opens a browser to the HCP Terraform login screen. Enter a token name in the web UI, or leave the default name. Click **Create API token** to generate the authentication token.

HCP Terraform only displays your token once. Copy this token, then when the Terraform CLI prompts you, paste the user token exactly once into your terminal. Press **Enter** to complete the authentication process.

Terraform migrate uses the GitHub API to create a pull request to update your configuration. Set the `GITHUB_TOKEN` environment variable to provide your GitHub API token. Your token must have the `repo` scope.

```
$ export GITHUB_TOKEN=<TOKEN>
```

## Logging

You can enable detailed logging by setting the `TF_MIGRATE_ENABLE_LOG` environment variable to `true`. When you enable this setting, Terraform migrate writes the logs to the following locations, depending on your operating system:

| Platform | Location |
| -------- | -------- |
| macOS/Linux | `/Users/<username>/.tf-migrate/logs/<commandName>/<date>.log` |
| Windows | `C:\Users\<username>\.tf-migrate\logs\<commandName>\<date>.log` |

You can set the `TF_MIGRATE_LOG_LEVEL` environment variable to one of the following values to change the verbosity of the logs (in order of decreasing verbosity):

- `TRACE`
- `DEBUG`
- `INFO`
- `WARN`
- `ERROR

page title  Terraform migrate   HCP Terraform description       Learn how to automatically migrate state to HCP Terraform or Terraform Enterprise using the Terraform migrate CLI tool         Terraform migrate  Terraform migrate automatically migrates your Terraform Community Edition state to HCP Terraform or Terraform Enterprise  It also updates your local configuration with any necessary changes and optionally creates a pull request to update your code repository       Overview  Complete the following steps to migrate Terraform state using the CLI   1  Download and install  tf migrate   You can manually download and install or use Homebrew if you are on macOS   1   tf migrate prepare   This step scans the current working directory and generates Terraform configuration to migrate your state  The generated migration plan depends on the structure of your configuration  For more information  refer to  tf migrate prepare   terraform cloud docs migrate tf migrate reference prepare    1   tf migrate execute   This step directs Terraform to run the  init    plan   and  apply  commands to perform the migration to HCP Terraform or Terraform Enterprise  At the end of the migration   tf migrate  displays a summary of what it migrated  links to the workspaces it created  and  if configured  a link to the pull request it created  For more information  refer to  tf migrate execute   terraform cloud docs migrate tf migrate reference execute       Install   Tabs    Tab heading  Manual installation    HashiCorp distributes Terraform migrate as a binary package  To install Terraform migrate  find the  appropriate binary  https   releases hashicorp com tf migrate   for your operating system and download it as a zip archive   After you download Terraform migrate  unzip the archive  Terraform migrate runs as a single binary named  tf migrate    Finally  make sure that the  tf migrate  binary is available in a directory that is in your system s  PATH         Verify the installation  Every build of Terraform migrate includes a  SHA256SUMS  and a  SHA256SUMS sig  file to validate your downloaded binary  Refer to the  verify HashiCorp binary downloads tutorial  https   developer hashicorp com well architected framework operational excellence verify hashicorp binary  for more information     Tab    Tab heading  Homebrew of macOS     Homebrew  https   brew sh   is a free and open source package management system for macOS  You can install the official  Terraform migrate  https   github com hashicorp homebrew tap  formula from the terminal   First  install the HashiCorp tap  a repository of all our Homebrew packages         brew tap hashicorp tap      Now  install Terraform migrate with the  hashicorp tap tf migrate  formula         brew install hashicorp tap tf migrate        Tab     Tabs      Authentication  Terraform migrate uses your locally configured Terraform CLI API token  If you have not authenticated your local Terraform installation with HCP Terraform  use the  terraform login  command to create an authentication token         terraform login  Terraform will request an API token for app terraform io using your browser   If login is successful  Terraform will store the token in plain text in the following file for use by subsequent commands      Users redacted  terraform d credentials tfrc json  Do you want to proceed   Only  yes  will be accepted to confirm    Enter a value  yes      Terraform opens a browser to the HCP Terraform login screen  Enter a token name in the web UI  or leave the default name  Click   Create API token   to generate the authentication token   HCP Terraform only displays your token once  Copy this token  then when the Terraform CLI prompts you  paste the user token exactly once into your terminal  Press   Enter   to complete the authentication process   Terraform migrate uses the GitHub API to create a pull request to update your configuration  Set the  GITHUB TOKEN  environment variable to provide your GitHub API token  Your token must have the  repo  scope         export GITHUB TOKEN  TOKEN          Logging  You can enable detailed logging by setting the  TF MIGRATE ENABLE LOG  environment variable to  true   When you enable this setting  Terraform migrate writes the logs to the following locations  depending on your operating system     Platform   Location                             macOS Linux     Users  username   tf migrate logs  commandName   date  log      Windows    C  Users  username   tf migrate logs  commandName   date  log     You can set the  TF MIGRATE LOG LEVEL  environment variable to one of the following values to change the verbosity of the logs  in order of decreasing verbosity        TRACE     DEBUG      INFO      WARN     ERROR


terraform tf migrate prepare page title tf migrate prepare Terraform migrate HCP Terraform Gather information and create a plan to migrate your Terraform Community Edition state The tf migrate prepare command recursively scans the current directory for Terraform state files then generates new Terraform configuration to migrate the state to HCP Terraform or Terraform Enterprise

Answer:
---
page_title: tf-migrate prepare - Terraform migrate - HCP Terraform
description: >-
  Gather information and create a plan to migrate your Terraform Community Edition state.
---

# tf-migrate prepare

The `tf-migrate prepare` command recursively scans the current directory for Terraform state files, then generates new Terraform configuration to migrate the state to HCP Terraform or Terraform Enterprise.

## Usage

```
$ tf-migrate prepare [options]
```

## Description

The `tf-migrate prepare` command prompts you for the following information:

- The HCP Terraform or Terraform Enterprise organization to migrate your state to.
- If you would like to create a new branch named `hcp-migrate-main`.
- If you would like it to automatically create a pull request with the updated code change when the migration is complete.

After you run the `prepare` command, Terraform migrate generates a new Terraform configuration in the `hcp-migrate-config` directory to perform the migration. This configuration creates the following resources:

- One workspace per state file
- One project to store all workspaces
- A new local git branch if you responded to the prompt to create a new branch with `yes`.
- A new pull request in the remote git repository if you responded to the prompt to create a pull request with `yes`.

The `tf-migrate` CLI tool adds the generated configuration to the `.gitignore` file so that the configuration is not committed to source control.

Terraform migrate creates the following structure in HCP Terraform or Terraform Enterprise depending on your local configuration:

| Source | Result |
| :---- | :---- |
| Single configuration, single state | Single HCP workspace |
| Single configuration, multiple states for each Community Edition workspace | One HCP workspace per state |
| Multiple configurations, one state per configuration | One HCP workspace per configuration |
| Multiple configurations, multiple states per configuration | One HCP workspace per combination of configuration and state |

## Example

The following configuration uses the AWS S3 backend and has a single state file.

<CodeBlockConfig hideClipboard>

```
.
├── LICENSE
├── README.md
└── main.tf
```

</CodeBlockConfig>

The `tf-migrate prepare` command generates the configuration to migrate this state to a single HCP Terraform workspace.

<CodeBlockConfig hideClipboard>

```
$ tf-migrate prepare
✓ Current working directory: /tmp/backend-test/learn-terraform-migrate
✓ Environment readiness checks completed
✓ Found 3 HCP Terraform organizations
┌────────────────────────────┐
│ Available Orgs             │
├────────────────────────────┤
│ my-org-1                   │
│ my-org-2                   │
│ my-org-3                   │
└────────────────────────────┘
Enter the name of the HCP Terraform organization to migrate to:  my-org-1
✓ You have selected organization my-org-1 for migration
✓ Found 1 directories with Terraform files
┌────────────────────────────────┐
│   Terraform File Directories   │
├────────────────────────────────┤
│ learn-terraform-migrate        │
└────────────────────────────────┘
Create a local branch named hcp-migrate-main from the current branch main: ... ?

  Only 'yes or no' will be accepted as input.
  Type 'yes' to approve the step
  Type 'no' to to skip

Enter a value:  yes

✓ Successfully created branch hcp-migrate-main
Do you want to open a pull request from hcp-migrate-main ... ?

  Only 'yes or no' will be accepted as input.
  Type 'yes' to approve the step
  Type 'no' to to skip

Enter a value:  yes

✓ Migration config generation completed
```

</CodeBlockConfig>

## Available options

You can include the following flags when you run the `tf-migrate prepare` command:

| Option | Description | Default | Required |
| ------ | ----------- | ------- | -------- |
| `-hostname` | The hostname of your Terraform Enterprise server. If you do not provide a hostname, Terraform migrate defaults to HCP Terraform. | `app.terraform.io` | No

page title  tf migrate prepare   Terraform migrate   HCP Terraform description       Gather information and create a plan to migrate your Terraform Community Edition state         tf migrate prepare  The  tf migrate prepare  command recursively scans the current directory for Terraform state files  then generates new Terraform configuration to migrate the state to HCP Terraform or Terraform Enterprise       Usage        tf migrate prepare  options          Description  The  tf migrate prepare  command prompts you for the following information     The HCP Terraform or Terraform Enterprise organization to migrate your state to    If you would like to create a new branch named  hcp migrate main       If you would like it to automatically create a pull request with the updated code change when the migration is complete   After you run the  prepare  command  Terraform migrate generates a new Terraform configuration in the  hcp migrate config  directory to perform the migration  This configuration creates the following resources     One workspace per state file     One project to store all workspaces     A new local git branch if you responded to the prompt to create a new branch with  yes       A new pull request in the remote git repository if you responded to the prompt to create a pull request with  yes    The  tf migrate  CLI tool adds the generated configuration to the   gitignore  file so that the configuration is not committed to source control   Terraform migrate creates the following structure in HCP Terraform or Terraform Enterprise depending on your local configuration     Source   Result                       Single configuration  single state   Single HCP workspace     Single configuration  multiple states for each Community Edition workspace   One HCP workspace per state     Multiple configurations  one state per configuration   One HCP workspace per configuration     Multiple configurations  multiple states per configuration   One HCP workspace per combination of configuration and state       Example  The following configuration uses the AWS S3 backend and has a single state file    CodeBlockConfig hideClipboard             LICENSE     README md     main tf        CodeBlockConfig   The  tf migrate prepare  command generates the configuration to migrate this state to a single HCP Terraform workspace    CodeBlockConfig hideClipboard         tf migrate prepare   Current working directory   tmp backend test learn terraform migrate   Environment readiness checks completed   Found 3 HCP Terraform organizations                                  Available Orgs                                                my org 1                       my org 2                       my org 3                                                    Enter the name of the HCP Terraform organization to migrate to   my org 1   You have selected organization my org 1 for migration   Found 1 directories with Terraform files                                        Terraform File Directories                                          learn terraform migrate                                             Create a local branch named hcp migrate main from the current branch main            Only  yes or no  will be accepted as input    Type  yes  to approve the step   Type  no  to to skip   Enter a value   yes    Successfully created branch hcp migrate main Do you want to open a pull request from hcp migrate main           Only  yes or no  will be accepted as input    Type  yes  to approve the step   Type  no  to to skip   Enter a value   yes    Migration config generation completed        CodeBlockConfig      Available options  You can include the following flags when you run the  tf migrate prepare  command     Option   Description   Default   Required                                                     hostname    The hostname of your Terraform Enterprise server  If you do not provide a hostname  Terraform migrate defaults to HCP Terraform     app terraform io    No