API Reference

Packages

• app.terraform.io/v1alpha2

app.terraform.io/v1alpha2

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

Resource Types

• AgentPool
• AgentToken
• Module
• Project
• RunsCollector
• Workspace

AgentAPIToken

Agent Token is a secret token that a HCP Terraform Agent is used to connect to the HCP Terraform Agent Pool. In spec only the field Name is allowed, the rest are used in status. More infromation:

• https://developer.hashicorp.com/terraform/cloud-docs/agents

Appears in:

• AgentPoolSpec
• AgentPoolStatus
• AgentTokenSpec
• AgentTokenStatus

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.

AgentDeployment

Appears in:

• AgentPoolSpec

Field	Description
replicas integer
spec PodSpec
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 allows you to configure the operator to scale the deployment for an AgentPool up and down to meet demand.

Appears in:

• 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	DEPRECATED: This field has been deprecated since 2.9.0 and will be removed in future versions. TargetWorkspaces is a list of HCP Terraform Workspaces which the agent pool should scale up to meet demand. When this field is ommited 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	CoolDownPeriod configures 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

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

Field	Description
desiredReplicas integer	Desired number of agent replicas
lastScalingEvent Time	Last time the agent pool was scaledx

AgentPool

AgentPool manages HCP Terraform Agent Pools, HCP Terraform Agent Tokens and can perform HCP Terraform Agent scaling. More infromation:

• https://developer.hashicorp.com/terraform/cloud-docs/agents/agent-pools
• https://developer.hashicorp.com/terraform/cloud-docs/users-teams-organizations/api-tokens#agent-api-tokens
• https://developer.hashicorp.com/terraform/cloud-docs/agents

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 info: 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 info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources
metadata ObjectMeta	Refer to Kubernetes API documentation for fields of metadata.
spec AgentPoolSpec

AgentPoolDeletionPolicy

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 agent pool.
• destroy: The operator will attempt to remove the managed HCP Terraform agent pool.

Appears in:

• AgentPoolSpec

AgentPoolRef

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:

• https://developer.hashicorp.com/terraform/cloud-docs/agents

Appears in:

• AgentTokenSpec
• AgentTokenStatus
• RunsCollectorSpec
• RunsCollectorStatus
• WorkspaceSpec

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

AgentPoolSpec

AgentPoolSpec defines the desired state of AgentPool.

Appears in:

• AgentPool

Field	Description
name string	Agent Pool name. More information: - https://developer.hashicorp.com/terraform/cloud-docs/agents/agent-pools
organization string	Organization name where the Workspace will be created. More information: - https://developer.hashicorp.com/terraform/cloud-docs/users-teams-organizations/organizations
token Token	API Token to be used for API calls.
agentTokens AgentAPIToken array	List of the agent tokens to generate.
agentDeployment AgentDeployment	Agent deployment settings
autoscaling AgentDeploymentAutoscaling	Agent deployment settings
deletionPolicy AgentPoolDeletionPolicy	The Deletion Policy specifies the behavior of the custom resource and its associated agent pool when the custom resource is deleted. - retain: When you delete the custom resource, the operator will remove only the custom resource. The HCP Terraform agent pool will be retained. The managed tokens will remain active on the HCP Terraform side; however, the corresponding secrets and managed agents will be removed. - destroy: The operator will attempt to remove the managed HCP Terraform agent pool. On success, the managed agents and the corresponding secret with tokens will be removed along with the custom resource. On failure, the managed agents will be scaled down to 0, and the managed tokens, along with the corresponding secret, will be removed. The operator will continue attempting to remove the agent pool until it succeeds. Default: retain.

AgentToken

AgentToken manages HCP Terraform Agent Tokens. More information:

• https://developer.hashicorp.com/terraform/cloud-docs/users-teams-organizations/api-tokens#agent-api-tokens

Field	Description
apiVersion string	app.terraform.io/v1alpha2
kind string	AgentToken
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 info: 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 info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources
metadata ObjectMeta	Refer to Kubernetes API documentation for fields of metadata.
spec AgentTokenSpec

AgentTokenDeletionPolicy

Underlying type: string

The Deletion Policy defines how managed tokens and Kubernetes Secrets should be handled when the custom resource is deleted.

• retain: When the custom resource is deleted, the operator will remove only the resource itself. The managed HCP Terraform Agent tokens will remain active on the HCP Terraform side, and the corresponding Kubernetes Secret will not be modified.
• destroy: The operator will attempt to delete the managed HCP Terraform Agent tokens and remove the corresponding Kubernetes Secret.

Appears in:

• AgentTokenSpec

AgentTokenManagementPolicy

Underlying type: string

The Management Policy defines how the controller will manage tokens in the specified Agent Pool.

• merge — the controller will manage its tokens alongside any existing tokens in the pool, without modifying or deleting tokens it does not own.
• owner — the controller assumes full ownership of all agent tokens in the pool, managing and potentially modifying or deleting all tokens, including those not created by it.

Appears in:

• AgentTokenSpec

AgentTokenSpec

AgentTokenSpec defines the desired state of AgentToken.

Appears in:

• AgentToken

Field	Description
organization string	Organization name where the Workspace will be created. More information: - https://developer.hashicorp.com/terraform/cloud-docs/users-teams-organizations/organizations
token Token	API Token to be used for API calls.
deletionPolicy AgentTokenDeletionPolicy	The Deletion Policy defines how managed tokens and Kubernetes Secrets should be handled when the custom resource is deleted. - retain: When the custom resource is deleted, the operator will remove only the resource itself. The managed HCP Terraform Agent tokens will remain active on the HCP Terraform side, and the corresponding Kubernetes Secret will not be modified. - destroy: The operator will attempt to delete the managed HCP Terraform Agent tokens and remove the corresponding Kubernetes Secret. Default: retain.
agentPool AgentPoolRef	The Agent Pool name or ID where the tokens will be managed.
managementPolicy AgentTokenManagementPolicy	The Management Policy defines how the controller will manage tokens in the specified Agent Pool. - merge — the controller will manage its tokens alongside any existing tokens in the pool, without modifying or deleting tokens it does not own. - owner — the controller assumes full ownership of all agent tokens in the pool, managing and potentially modifying or deleting all tokens, including those not created by it. Default: merge.
agentTokens AgentAPIToken array	List of the HCP Terraform Agent tokens to manage.
secretName string	secretName specifies the name of the Kubernetes Secret where the HCP Terraform Agent tokens are stored.

ConfigurationVersionStatus

A configuration version is a resource used to reference the uploaded configuration files. More information:

• https://developer.hashicorp.com/terraform/cloud-docs/api-docs/configuration-versions
• https://developer.hashicorp.com/terraform/cloud-docs/run/api

Appears in:

• 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:

• https://developer.hashicorp.com/terraform/cloud-docs/workspaces/state#remote-state-access-controls

Appears in:

• 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:

• https://developer.hashicorp.com/terraform/cloud-docs/users-teams-organizations/permissions#custom-workspace-permissions

Appears in:

• 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:

• https://developer.hashicorp.com/terraform/cloud-docs/users-teams-organizations/permissions#custom-project-permissions
• https://developer.hashicorp.com/terraform/cloud-docs/users-teams-organizations/permissions#general-workspace-permissions

Appears in:

• ProjectTeamAccess

Field	Description
projectAccess ProjectSettingsPermissionType	Project access. Must be one of the following values: delete, read, update. Default: read.
teamManagement 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	Run access. Must be one of the following values: apply, plan, read. Default: read.
runTasks boolean	Manage Workspace Run Tasks. Default: false.
sentinelMocks WorkspaceSentinelMocksPermissionType	Download Sentinel mocks. Must be one of the following values: none, read. Default: none.
stateVersions WorkspaceStateVersionsPermissionType	State access. Must be one of the following values: none, read, read-outputs, write. Default: none.
variables 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

Module

Module implements API-driven Run Workflows. More information:

• https://developer.hashicorp.com/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 info: 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 info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources
metadata ObjectMeta	Refer to Kubernetes API documentation for fields of metadata.
spec ModuleSpec

ModuleDeletionPolicy

Underlying type: string

Deletion Policy defines the strategies for resource deletion in the Kubernetes operator. It controls how the operator should handle the deletion of resources when triggered by a user action or system event.

There is one possible value:

• retain: When the custom resource is deleted, the associated module is retained. destroyOnDeletion must be set to false. Default value.
• destroy: Executes a destroy operation. Removes all resources and the module.

Appears in:

• ModuleSpec

ModuleOutput

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

Appears in:

• 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

Field	Description
source string	Non local Terraform module source. More information: - https://developer.hashicorp.com/terraform/language/modules/sources
version string	Terraform module version.

ModuleSpec

ModuleSpec defines the desired state of Module.

Appears in:

• Module

Field	Description
organization string	Organization name where the Workspace will be created. More information: - https://developer.hashicorp.com/terraform/cloud-docs/users-teams-organizations/organizations
token Token	API Token to be used for API calls.
module ModuleSource	Module source and version to execute.
workspace ModuleWorkspace	Workspace to execute the module.
name string	Name of the module that will be uploaded and executed. Default: this.
variables ModuleVariable array	Variables to pass to the module, they must exist in the Workspace.
outputs ModuleOutput array	Module outputs to store in ConfigMap(non-sensitive) or Secret(sensitive).
destroyOnDeletion boolean	DEPRECATED: 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 --type=merge --patch '{"spec": {"restartedAt": "'`date -u -Iseconds`'"}}'
deletionPolicy ModuleDeletionPolicy	Deletion Policy defines the strategies for resource deletion in the Kubernetes operator. It controls how the operator should handle the deletion of resources when triggered by a user action or system event. There is one possible value: - retain: When the custom resource is deleted, the associated module is retained. destroyOnDeletion must be set to false. - destroy: Executes a destroy operation. Removes all resources and the module. Default: retain.

ModuleVariable

Variables to pass to the module.

Appears in:

• 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

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:

• https://developer.hashicorp.com/terraform/cloud-docs/workspaces/settings/notifications

Appears in:

• WorkspaceSpec

Field	Description
name string	Notification name.
type 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 array	The list of run events that will trigger notifications. Trigger represents the different TFC notifications that can be sent as a run's progress transitions between different states. There are two categories of triggers: - Health Events: assessment:check_failure, assessment:drifted, assessment:failed. - 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 different TFC notifications that can be sent as a run's progress transitions between different states. This must be aligned with go-tfe type NotificationTriggerType. Must be 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

OutputStatus

Outputs status.

Appears in:

• ModuleStatus

Field	Description
runID string	Run ID of the latest run that updated the outputs.

PlanStatus

Appears in:

• 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 manages HCP Terraform Projects. More information:

• https://developer.hashicorp.com/terraform/cloud-docs/projects/manage

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 info: 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 info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources
metadata ObjectMeta	Refer to Kubernetes API documentation for fields of metadata.
spec ProjectSpec

ProjectDeletionPolicy

Underlying type: string

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

You must use one of the following values:

• retain: When the custom resource is deleted, the operator will not delete the associated project.
• soft: Attempts to remove the project. The project must be empty.

Appears in:

• ProjectSpec

ProjectSpec

ProjectSpec defines the desired state of Project. More information:

• https://developer.hashicorp.com/terraform/cloud-docs/workspaces/organize-workspaces-with-projects

Appears in:

• Project

Field	Description
organization string	Organization name where the Workspace will be created. More information: - https://developer.hashicorp.com/terraform/cloud-docs/users-teams-organizations/organizations
token Token	API Token to be used for API calls.
name string	Name of the Project.
teamAccess 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: - https://developer.hashicorp.com/terraform/cloud-docs/workspaces/organize-workspaces-with-projects#permissions - https://developer.hashicorp.com/terraform/cloud-docs/users-teams-organizations/permissions#project-permissions
deletionPolicy ProjectDeletionPolicy	DeletionPolicy defines the strategy the Kubernetes operator uses when you delete a project, either manually or by a system event. You must use one of the following values: - retain: When the custom resource is deleted, the operator will not delete the associated project. - soft: Attempts to remove the project. The project must be empty. Default: retain.

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:

• https://developer.hashicorp.com/terraform/cloud-docs/workspaces/organize-workspaces-with-projects#permissions
• https://developer.hashicorp.com/terraform/cloud-docs/users-teams-organizations/permissions#project-permissions

Appears in:

• ProjectSpec

Field	Description
team Team	Team to grant access. More information: - https://developer.hashicorp.com/terraform/cloud-docs/users-teams-organizations/teams
access 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: - https://developer.hashicorp.com/terraform/cloud-docs/users-teams-organizations/permissions#project-permissions - https://developer.hashicorp.com/terraform/cloud-docs/users-teams-organizations/permissions#general-project-permissions
custom CustomProjectPermissions	Custom permissions let you assign specific, finer-grained permissions to a team than the broader fixed permission sets provide. More information: - https://developer.hashicorp.com/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:

• https://developer.hashicorp.com/terraform/cloud-docs/workspaces/state#accessing-state-from-other-workspaces

Appears in:

• WorkspaceSpec

Field	Description
allWorkspaces boolean	Allow access to the state for all workspaces within the same organization. Default: false.
workspaces ConsumerWorkspace array	Allow access to the state for specific workspaces within the same organization.

RunStatus

Appears in:

• ModuleStatus
• 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:

• https://developer.hashicorp.com/terraform/cloud-docs/workspaces/settings/run-triggers

Appears in:

• WorkspaceSpec

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

RunsCollector

RunsCollector scraptes HCP Terraform Run statuses from a given Agent Pool and exposes them as Prometheus-compatible metrics. More information:

• https://developer.hashicorp.com/terraform/cloud-docs/run/remote-operations

Field	Description
apiVersion string	app.terraform.io/v1alpha2
kind string	RunsCollector
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 info: 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 info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources
metadata ObjectMeta	Refer to Kubernetes API documentation for fields of metadata.
spec RunsCollectorSpec

RunsCollectorSpec

Appears in:

• RunsCollector

Field	Description
organization string	Organization name where the Workspace will be created. More information: - https://developer.hashicorp.com/terraform/cloud-docs/users-teams-organizations/organizations
token Token	API Token to be used for API calls.
agentPool AgentPoolRef	The Agent Pool name or ID from which the controller will collect runs. More information: - https://developer.hashicorp.com/terraform/cloud-docs/run/states

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:

• https://developer.hashicorp.com/terraform/cloud-docs/workspaces/settings/ssh-keys

Appears in:

• 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

TargetWorkspace

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

Appears in:

• 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:

• https://developer.hashicorp.com/terraform/cloud-docs/users-teams-organizations/teams

Appears in:

• ProjectTeamAccess
• 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:

• https://developer.hashicorp.com/terraform/cloud-docs/workspaces/settings/access

Appears in:

• WorkspaceSpec

Field	Description
team Team	Team to grant access. More information: - https://developer.hashicorp.com/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: - https://developer.hashicorp.com/terraform/cloud-docs/users-teams-organizations/permissions#workspace-permissions
custom CustomPermissions	Custom permissions let you assign specific, finer-grained permissions to a team than the broader fixed permission sets provide. More information: - https://developer.hashicorp.com/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
• AgentTokenSpec
• ModuleSpec
• ProjectSpec
• RunsCollectorSpec
• WorkspaceSpec

Field	Description
secretKeyRef SecretKeySelector	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

Field	Description
configMapKeyRef ConfigMapKeySelector	Selects a key of a ConfigMap.
secretKeyRef SecretKeySelector	Selects a key of a Secret.

Variable

Variables let you customize configurations, modify Terraform's behavior, and store information like provider credentials. More information:

• https://developer.hashicorp.com/terraform/cloud-docs/workspaces/variables

Appears in:

• 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	Source for the variable's value. Cannot be used if value is not empty.

VariableSetStatus

Appears in:

• WorkspaceStatus

Field	Description
id string
name string

VariableStatus

Appears in:

• 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 TFC 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:

• https://developer.hashicorp.com/terraform/cloud-docs/run/ui
• https://developer.hashicorp.com/terraform/cloud-docs/vcs

Appears in:

• 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: - https://developer.hashicorp.com/terraform/cloud-docs/run/ui#speculative-plans-on-pull-requests - https://developer.hashicorp.com/terraform/cloud-docs/run/remote-operations#speculative-plans
enableFileTriggers boolean	File triggers allow you to queue runs in HCP Terraform when files in your VCS repository change. Default: false. More informarion: - https://developer.hashicorp.com/terraform/cloud-docs/workspaces/settings/vcs#automatic-run-triggering
triggerPatterns string array	The list of pattern triggers that will queue runs in HCP Terraform when files in your VCS repository change. spec.versionControl.fileTriggersEnabled must be set to true. More informarion: - https://developer.hashicorp.com/terraform/cloud-docs/workspaces/settings/vcs#automatic-run-triggering
triggerPrefixes string array	The list of pattern prefixes that will queue runs in HCP Terraform when files in your VCS repository change. spec.versionControl.fileTriggersEnabled must be set to true. More informarion: - https://developer.hashicorp.com/terraform/cloud-docs/workspaces/settings/vcs#automatic-run-triggering

Workspace

Workspace manages HCP Terraform Workspaces. More information:

• https://developer.hashicorp.com/terraform/cloud-docs/workspaces

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 info: 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 info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources
metadata ObjectMeta	Refer to Kubernetes API documentation for fields of metadata.
spec WorkspaceSpec

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:

• https://developer.hashicorp.com/terraform/tutorials/cloud/projects

Appears in:

• 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:

• https://developer.hashicorp.com/terraform/cloud-docs/workspaces/settings/run-tasks

Appears in:

• 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

Field	Description
name string	Workspace name.
organization string	Organization name where the Workspace will be created. More information: - https://developer.hashicorp.com/terraform/cloud-docs/users-teams-organizations/organizations
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: - https://developer.hashicorp.com/terraform/cloud-docs/workspaces/settings#auto-apply-and-manual-apply
applyRunTrigger string	Specifies the type of apply, whether manual or auto Must be of value auto or manual Default: manual More information: - https://developer.hashicorp.com/terraform/cloud-docs/workspaces/settings#auto-apply
allowDestroyPlan boolean	Allows a destroy plan to be created and applied. Default: true. More information: - https://developer.hashicorp.com/terraform/cloud-docs/workspaces/settings#destruction-and-deletion
description string	Workspace description.
agentPool AgentPoolRef	HCP Terraform Agents allow HCP Terraform to communicate with isolated, private, or on-premises infrastructure. More information: - https://developer.hashicorp.com/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: - https://developer.hashicorp.com/terraform/cloud-docs/workspaces/settings#execution-mode
runTasks WorkspaceRunTask array	Run tasks allow HCP Terraform to interact with external systems at specific points in the HCP Terraform run lifecycle. More information: - https://developer.hashicorp.com/terraform/cloud-docs/workspaces/settings/run-tasks
tags 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 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: - https://developer.hashicorp.com/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: - https://www.terraform.io/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: - https://www.terraform.io/cloud-docs/workspaces/settings#terraform-working-directory
environmentVariables 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: - https://developer.hashicorp.com/terraform/cloud-docs/workspaces/variables - https://developer.hashicorp.com/terraform/cloud-docs/workspaces/variables#environment-variables
terraformVariables 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: - https://developer.hashicorp.com/terraform/cloud-docs/workspaces/variables - https://developer.hashicorp.com/terraform/cloud-docs/workspaces/variables#terraform-variables
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: - https://developer.hashicorp.com/terraform/cloud-docs/workspaces/state#accessing-state-from-other-workspaces
runTriggers 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: - https://developer.hashicorp.com/terraform/cloud-docs/workspaces/settings/run-triggers
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: - https://www.terraform.io/cloud-docs/run/ui - https://www.terraform.io/cloud-docs/vcs
sshKey SSHKey	SSH key used to clone Terraform modules. More information: - https://developer.hashicorp.com/terraform/cloud-docs/workspaces/settings/ssh-keys
notifications Notification array	Notifications allow you to send messages to other applications based on run and workspace events. More information: - https://developer.hashicorp.com/terraform/cloud-docs/workspaces/settings/notifications
project WorkspaceProject	Projects let you organize your workspaces into groups. Default: default organization project. More information: - https://developer.hashicorp.com/terraform/tutorials/cloud/projects
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.
variableSets WorkspaceVariableSet array	HCP Terraform variable sets let you reuse variables in an efficient and centralized way. More information - https://developer.hashicorp.com/terraform/tutorials/cloud/cloud-multiple-variable-sets

WorkspaceVariableSet

Appears in:

• WorkspaceSpec

Field	Description
id string	ID of the variable set. Must match pattern: varset-[a-zA-Z0-9]+$ More information: - https://developer.hashicorp.com/terraform/tutorials/cloud/cloud-multiple-variable-sets
name string	Name of the variable set. More information: - https://developer.hashicorp.com/terraform/tutorials/cloud/cloud-multiple-variable-sets