Skip to content

Latest commit

 

History

History
808 lines (492 loc) · 37.2 KB

api-reference.md

File metadata and controls

808 lines (492 loc) · 37.2 KB
Raw

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

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

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

AgentPoolSpec

AgentPoolSpec defines the desired state of AgentPool.

Appears in:

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

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.

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

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:
- https://developer.hashicorp.com/terraform/language/modules/sources
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:
- 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 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`'"}}'

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

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

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

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

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.

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

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

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