HCP Terraform Operator for Kubernetes overview

The HCP Terraform Operator for Kubernetes allows you to manage HCP Terraform resources with Kubernetes custom resources. You can provision infrastructure internal or external to your Kubernetes cluster directly from the Kubernetes control plane.

The operator's CustomResourceDefinitions (CRD) let you dynamically create HCP Terraform workspaces with Terraform modules, populate workspace variables, and provision infrastructure with Terraform runs.

Key benefits

The HCP Terraform Operator for Kubernetes v2 offers several improvements over v1:

• Flexible resource management: The operator now features multiple custom resources, each with separate controllers for different HCP Terraform resources. This provides additional flexibility and the ability to manage more custom resources concurrently, significantly improving performance for large-scale deployments.

• Namespace management: The --namespace option allows you to tailor the operator's watch scope to specific namespaces, which enables more fine-grained resource management.

• Configurable synchronization: The --sync-period option allows you to configure the synchronization frequency between custom resources and HCP Terraform, ensuring timely updates and smoother operations.

Supported HCP Terraform features

The HCP Terraform Operator for Kubernetes allows you to create agent pools, deploy modules, and manage workspaces through Kubernetes controllers. These controllers enable you to automate and manage HCP Terraform resources using custom resources in Kubernetes.

Agent pools

Agent pools in HCP Terraform manage the execution environment for Terraform runs. The HCP Terraform Operator for Kubernetes allows you to create and manage agent pools as part of your Kubernetes infrastructure.

The following example creates a new agent pool with the name agent-pool-development and generates an agent token with the name token-red.

---
apiVersion: app.terraform.io/v1alpha2
kind: AgentPool
metadata:
  name: my-agent-pool
spec:
  organization: kubernetes-operator
  token:
    secretKeyRef:
      name: tfc-operator
      key: token
  name: agent-pool-development
  agentTokens:
    - name: token-red

The operator stores the token-red agent token in a Kubernetes secret named my-agent-pool-token-red.

You can also enable agent autoscaling by providing a .spec.autoscaling configuration in your AgentPool specification.

---
apiVersion: app.terraform.io/v1alpha2
kind: AgentPool
metadata:
  name: this
spec:
  organization: kubernetes-operator
  token:
    secretKeyRef:
      name: tfc-operator
      key: token
  name: agent-pool-development
  agentTokens:
  - name: token-red
  agentDeployment:
   replicas: 1
  autoscaling:
    targetWorkspaces:
    - name: us-west-development
    - id: ws-NUVHA9feCXzAmPHx
    - wildcardName: eu-development-*
    minReplicas: 1
    maxReplicas: 3
    cooldownPeriod:
      scaleUpSeconds: 30
      scaleDownSeconds: 30

In the above example, the operator ensures that at least one agent pod is continuously running and dynamically scales the number of pods up to a maximum of three based on the workload or resource demand. The operator then monitors resource demands by observing the load of the designated workspaces specified by the name, id, or wildcardName patterns. When the workload decreases, the operator downscales the number of agent pods.

Refer to the agent pool API reference for the complete AgentPool specification.

Module

The Module controller enforces an API-driven Run workflow and lets you deploy Terraform modules within workspaces.

The following example deploys version 1.0.0 of the hashicorp/module/random module in the workspace-name workspace.

---
apiVersion: app.terraform.io/v1alpha2
kind: Module
metadata:
  name: my-module
spec:
  organization: kubernetes-operator
  token:
    secretKeyRef:
      name: tfc-operator
      key: token
  module:
    source: hashicorp/module/random
    version: 1.0.0
  workspace:
    name: workspace-name
  variables:
  - name: string_length
  outputs:
  - name: random_string

The operator passes the workspace's string_length variable to the module and stores the random_string outputs as either a Kubernetes secret or a ConfigMap. If the workspace marks the output as sensitive, the operator stores the random_string as a Kubernetes secret; otherwise, the operator stores it as a ConfigMap. The variables must be accessible within the workspace as a workspace variable, workspace variable set, or project variable set.

Refer to the module API reference for the complete Module specification.

Project

Projects let you organize your workspaces and scope access to workspace resources. The Project controller allows you to create, configure, and manage projects directly from Kubernetes.

The following example creates a new project named testing.

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

The Project controller allows you to manage team access permissions.

The following example creates a project named testing and grants the qa team admin access to the project.

---
apiVersion: app.terraform.io/v1alpha2
kind: Project
metadata:
  name: testing
spec:
  organization: kubernetes-operator
  token:
    secretKeyRef:
      name: tfc-operator
      key: token
  name: project-demo
  teamAccess:
  - team:
      name: qa
    access: admin

Refer to the project API reference for the complete Project specification.

Workspace

HCP Terraform workspaces organize and manage Terraform configurations. The HCP Terraform Operator for Kubernetes allows you to create, configure, and manage workspaces directly from Kubernetes.

The following example creates a new workspace named us-west-development, configured to use Terraform version 1.6.2. This workspace has two variables, nodes and rds-secret. The variable rds-secret is treated as sensitive, and the operator reads the value for the variable from a Kubernetes secret named us-west-development-secrets.

---
apiVersion: app.terraform.io/v1alpha2
kind: Workspace
metadata:
  name: us-west-development
spec:
  organization: kubernetes-operator
  token:
    secretKeyRef:
      name: tfc-operator
      key: token
  name: us-west-development
  description: US West development workspace
  terraformVersion: 1.6.2
  applyMethod: auto
  agentPool:
    name: ap-us-west-development
  terraformVariables:
    - name: nodes
      value: 2
    - name: rds-secret
      sensitive: true
      valueFrom:
        secretKeyRef:
          name: us-west-development-secrets
          key: rds-secret
  runTasks:
    - name: rt-us-west-development
      stage: pre_plan

In the above example, the applyMethod has the value of auto, so HCP Terraform automatically applies any changes to this workspace. The specification also configures the workspace to use the ap-us-west-development agent pool and run the rt-us-west-development run task at the pre_plan stage.

The operator stores the value of the workspace outputs as Kubernetes secrets or ConfigMaps. If the outputs are marked as sensitive, they are stored as Kubernetes secrets, otherwise they are stored as ConfigMaps.

Refer to the workspace API reference for the complete Workspace specification.