Terraform
HCP Terraform Operator for Kubernetes API reference
Packages
app.terraform.io/v1alpha2
Package v1alpha2 contains API Schema definitions for the app v1alpha2 API group.
Resource Types
AgentDeployment
Appears in:
| 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:
| 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 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:
| 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:
| Field | Description |
|---|---|
desiredReplicas integer | Desired number of agent replicas |
lastScalingEvent Time | Last time the agent pool was scaled |
AgentPool
AgentPool manages HCP Terraform Agent Pools, HCP Terraform Agent Tokens and can perform HCP Terraform Agent scaling.
More information:
| 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:
| 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
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 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:
| 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:
| 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:
| 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:
| 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:
Module
Module implements API-driven Run Workflows.
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:
| 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:
| 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:
| 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:
| 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:
| 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:
| 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:
OutputStatus
Outputs status.
Appears in:
| Field | Description |
|---|---|
runID string | Run ID of the latest run that updated the outputs. |
PlanStatus
Appears in:
| 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:
| 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:
| 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: Manage projects and 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:
| 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 and 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:
| 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:
| 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:
| 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:
TargetWorkspace
TargetWorkspace is the name or ID of the workspace you want autoscale against.
Appears in:
| 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:
| 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:
| 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:
| 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:
| Field | Description |
|---|---|
id string | |
name string |
VariableStatus
Appears in:
| 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:
Appears in:
| 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 and Speculative plans. |
Workspace
Workspace manages HCP Terraform Workspaces.
More information:
| 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:
| 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:
| 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:
| 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:
| 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 |
workingDirectory string | The directory where Terraform will execute, specified as a relative path from the root of the configuration directory. More information |
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 and 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 and 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: UI and VCS-driven run workflow and Connect to VCS providers |
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. |
variableSets WorkspaceVariableSet array | HCP Terraform variable sets let you reuse variables in an efficient and centralized way. More information |
WorkspaceVariableSet
Appears in:
| Field | Description |
|---|---|
id string | ID of the variable set. Must match pattern: varset-[a-zA-Z0-9]+$ More information. |
name string | Name of the variable set. More information. |