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

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 configures 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	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	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

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

Appears in:

AgentPoolStatus

Field	Description
`desiredReplicas` integer	Desired number of agent replicas
`lastScalingEvent` Time	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
`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
`metadata` ObjectMeta	Refer to Kubernetes API documentation for fields of `metadata`.
`spec` AgentPoolSpec

AgentPoolSpec

AgentPoolSpec defines the desired state of AgentPool.

Appears in:

AgentPool

Field	Description
`name` string	Agent Pool name. More information.
`organization` string	Organization name where the Workspace will be created. More information.
`token` Token	API Token to be used for API calls.
`agentTokens` AgentToken array	List of the agent tokens to generate.
`agentDeployment` AgentDeployment	Agent deployment settings
`autoscaling` 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.

Appears in:

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:

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.

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.

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:

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 is the Schema for the modules API Module implements the API-driven Run Workflow. More information.

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
`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
`metadata` ObjectMeta	Refer to Kubernetes API documentation for fields of `metadata`.
`spec` 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.
`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.
`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	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

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.

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

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 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
`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
`metadata` ObjectMeta	Refer to Kubernetes API documentation for fields of `metadata`.
`spec` ProjectSpec

ProjectSpec

ProjectSpec defines the desired state of Project. More information.

Appears in:

Project

Field	Description
`organization` string	Organization name where the Workspace will be created. More information.
`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: Project permissions - Team 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:

Appears in:

ProjectSpec

Field	Description
`team` Team	Team to grant access. More information.
`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: - Project 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.

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.

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:

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.

Appears in:

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.

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.

Appears in:

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.

Appears in:

WorkspaceSpec

Field	Description
`team` Team	Team to grant access. More information.
`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.
`custom` CustomPermissions	Custom permissions let you assign specific, finer-grained permissions to a team than the broader fixed permission sets provide. More information.

Token

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

Appears in:

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.

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.

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

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: - Speculative plans on pull requests - 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
`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
`metadata` ObjectMeta	Refer to Kubernetes API documentation for fields of `metadata`.
`spec` 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.

Appears in:

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.

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.

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.
`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.
`allowDestroyPlan` boolean	Allows a destroy plan to be created and applied. Default: `true`. More information.
`description` string	Workspace description.
`agentPool` WorkspaceAgentPool	HCP Terraform Agents allow HCP Terraform to communicate with isolated, private, or on-premises infrastructure. More information.
`executionMode` string	Define where the Terraform code will be executed. Must be one of the following values: `agent`, `local`, `remote`. Default: `remote`. More information.
`runTasks` WorkspaceRunTask array	Run tasks allow HCP Terraform to interact with external systems at specific points in the HCP Terraform run lifecycle. More information.
`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.
`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 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 - 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: - Workspace 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.
`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.
`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	SSH key used to clone Terraform modules. More information.
`notifications` Notification array	Notifications allow you to send messages to other applications based on run and workspace events. More information.
`project` WorkspaceProject	Projects let you organize your workspaces into groups. Default: default organization project. More information.
`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`.