HCP Terraform Operator for Kubernetes

The HCP Terraform Operator allows you to manage HCP Terraform (formerly Terraform Enterprise) resources using Kubernetes Custom Resources (CRs). The operator manages the following resource types:

• AgentPool: Manages HCP Terraform Agent Pools and Agent Tokens, and can perform TFC agent scaling.
• AgentToken: Manages HCP Terraform Agent Tokens.
• Module: Implements API-driven Run Workflows.
• Project: Manages HCP Terraform Projects.
• Runs Collector: Scrapes HCP Terraform run statuses from a specific Agent Pool and exposes them as Prometheus-compatible metrics.
• Workspace: Manages HCP Terraform Workspaces.

The RunsCollector controller is a component of the HCP Terraform Operator that retrieves HCP Terraform run statuses from a specific Agent Pool and exposes that data as Prometheus metrics. This allows you to monitor the status of Terraform runs within your Kubernetes environment using standard Prometheus scraping.

apiVersion: app.terraform.io/v1alpha2
kind: RunsCollector
metadata:
  name: this
spec:
  organization: kubernetes-operator
  token:
    secretKeyRef:
      name: hcp-terraform-operator
      key: token
  agentPool:
    name: multik

HCP Terraform workspaces use TeamAccess to manage permissions on a per-team basis.

Permissions: You can choose between fixed permission sets or custom permissions. Fixed permission values are:

• admin
• custom
• plan
• read
• write

Team Identification: When defining a Team, you must provide either an id or a name, but not both. The id must match the pattern ^team-[a-zA-Z0-9]+$.

The AgentToken controller manages tokens within an HCP Terraform agent pool using one of two managementPolicy modes. Choosing the correct policy is critical for determining how the operator interacts with existing tokens in a pool:

• merge: The controller manages its specific tokens alongside any existing tokens in the pool. It will not modify or delete tokens that it does not own. This is recommended for multicluster environments where multiple operator instances manage different tokens within the same pool.
• owner: The controller assumes full ownership of all tokens in the pool. It may modify or delete any token in the pool, including those it did not create.

Set this via the spec.managementPolicy field in your AgentToken Custom Resource.

The Operator's performance is influenced by the number of API calls made to the HCP Terraform API. When configuring features like Run Triggers in a Workspace resource, you can refer to target workspaces by either name or id.

Using name requires the Operator to perform an additional API call during every reconciliation to resolve the name to an ID. To improve performance and reduce API consumption, use the workspace id directly. This allows the Operator to use the identifier immediately without resolution steps.

apiVersion: app.terraform.io/v1alpha2
kind: Workspace
metadata:
  name: this
spec:
  runTriggers:
    - id: ws-NUVHA9feCXzAmPHx
    - name: target-workspace

The Project controller allows you to manage HCP Terraform Projects using Kubernetes Custom Resources (CRs). By applying a Project resource to your Kubernetes cluster, the operator will automatically create or manage the corresponding project within your specified HCP Terraform organization.

To use this, you must provide:

1. The target HCP Terraform organization.
2. An HCP Terraform token via a Kubernetes Secret.
3. The desired name for the project.

Refer to the API Reference for the full list of available configuration options.

apiVersion: app.terraform.io/v1alpha2
kind: Project
metadata:
  name: this
spec:
  organization: kubernetes-operator
  token:
    secretKeyRef:
      name: tfc-operator
      key: token
  name: project-demo

If the agentDeployment attribute is specified, the operator deploys agents as Pods in the same namespace as the AgentPool object.

• Minimal configuration: Setting agentDeployment: {} deploys a single agent Pod using the hashicorp/tfc-agent:latest image.
• Custom configuration: The agentDeployment.spec accepts a standard PodSpec (identical to a Deployment's spec.template.spec). This allows you to customize containers, images, and other pod settings.
• Environment Variables: The operator automatically injects TFC-specific environment variables into the containers to provide agent tokens and the API endpoint.
• Cleanup: Deleting the AgentPool resource will automatically delete the associated agent Deployment.

The following annotations allow you to configure the parameters of a Terraform run, but note that changing these annotations does not start a new run; they must be used in conjunction with the workspace.app.terraform.io/run-new annotation to take effect.

• workspace.app.terraform.io/run-type: Specifies the run type. Possible values are plan, apply, or refresh. Defaults to "plan".
• workspace.app.terraform.io/run-terraform-version: Specifies the Terraform version to use. This is only valid when workspace.app.terraform.io/run-type is set to plan. If not specified, it defaults to the Workspace version.

The Operator monitors specific workspaces and automatically scales the number of agents based on pending runs.

• Scaling Up: The agent count increases when pending runs are detected, up to the limit defined in autoscaling.maxReplicas or your HCP Terraform license limit.
• Scaling Down: If no pending runs are detected, the Operator reduces the agent count to the value specified in autoscaling.minReplicas after the duration defined in autoscaling.cooldownPeriodSeconds has passed.

To prevent the operator from reconciling a specific custom resource, set the app.terraform.io/paused annotation to "true".

While paused, the operator will skip reconciliation even if the resource changes. However, deletion logic will still be executed if the resource is deleted. To resume reconciliation, set the annotation to "false".

kubectl annotate workspace <WORKSPACE-NAME> app.terraform.io/paused="true"