The Terraform operator concept bridges Kubernetes control planes and Infrastructure as Code workflows. Terraform Operator is a Kubernetes CRD and Controller to handle Terraform operations by generating k8s jobs catered to perform Terraform workflows. The HCP Terraform Operator for Kubernetes is a Kubernetes extension that enables declarative management of HashiCorp Cloud Platform Terraform resources through Kubernetes Custom Resource Definitions. This operator bridges the gap between Kubernetes and HashiCorp's Infrastructure as Code ecosystem, allowing teams to manage their Terraform Cloud workspaces, modules, projects, and agent pools directly from their Kubernetes cluster.
The overview page introduces the core concepts, architecture, and components of the HCP Terraform Operator. 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 let you dynamically create HCP Terraform workspaces with Terraform modules, populate workspace variables, and provision infrastructure with Terraform runs.
HCP Terraform Operator Architecture
The HCP Terraform Operator implements the Kubernetes operator pattern, extending the Kubernetes API with custom resources that represent HCP Terraform entities. The operator watches for changes to these custom resources and reconciles the desired state with the actual state in HCP Terraform.
The operator consists of a set of controllers that watch for changes to custom resources and reconcile them with the corresponding resources in HCP Terraform. The operator uses the go-tfe client to communicate with the HCP Terraform API and the Kubernetes client to interact with the Kubernetes API.
Key components:
The operator runs as a Deployment within a Kubernetes cluster and can be configured to watch resources in a single namespace, multiple namespaces, or across all namespaces.
The operator defines four custom resource definitions and implements controllers to manage them:
- Manages HCP Terraform Workspaces, which are environments for Terraform runs. It synchronizes workspace configuration, variables, SSH keys, and notifications. It also captures outputs from Terraform runs into ConfigMaps and Secrets.
- Manages HCP Terraform Agent Pools and Agent Tokens. It can deploy agent pods in the Kubernetes cluster and scale them based on pending runs in HCP Terraform workspaces.
- Implements API-driven Run Workflows for executing Terraform modules
The operator supports four main resource types.
Custom Resources and Controllers
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.
The HCP Terraform Operator for Kubernetes allows you to create agent pools, deploy modules, and manage workspaces through Kubernetes controllers.
The operator supports a wide range of HCP Terraform features, including workspaces, modules, projects, and agent pools, with advanced capabilities like autoscaling, VCS integration, and output management.
Workspace Resource
Workspace resources support variable management, allowing users to define Terraform variables, environment variables, and sensitive values that are passed to Terraform runs.
Workspace resources can be configured to connect to a Version Control System VCS repository, allowing Terraform runs to be triggered by changes to the code.
Workspace resources capture outputs from Terraform runs into ConfigMaps and Secrets for consumption by other Kubernetes workloads.
Agent Pool Resource
The autoscaling feature allows the operator to automatically adjust the number of agent pods based on the workload, ensuring efficient resource utilization.
Manages HCP Terraform Agent Pools and Agent Tokens. It can deploy agent pods in the Kubernetes cluster and scale them based on pending runs in HCP Terraform workspaces.
Module and Project Resources
The operator supports declarative management of Terraform modules and projects through custom resources.
By leveraging custom resources and controllers, it allows teams to manage their HCP Terraform resources declaratively through the familiar Kubernetes API.
The HCP Terraform Operator for Kubernetes provides a powerful integration between Kubernetes and HCP Terraform, enabling infrastructure-as-code workflows directly from Kubernetes.
Operational Configuration
The operator exposes metrics in Prometheus format for each controller, allowing monitoring of:
Metrics can be collected by Prometheus and visualized using tools like Grafana.
The operator's performance depends on several factors:
For optimal performance, consider:
The operator runs as a Deployment within a Kubernetes cluster and can be configured to watch resources in a single namespace, multiple namespaces, or across all namespaces.
Note: HCP Terraform and Terraform Enterprise can be used interchangeably in this documentation unless specified otherwise.
Configuration options include:
- --namespace to tailor the operator's watch scope
- --sync-period to configure synchronization frequency
Terraform Operator for Job Generation
Terraform Operator is a Kubernetes CRD and Controller to handle Terraform operations by generating k8s jobs catered to perform Terraform workflows.
Documentation covers fundamentals of Terraform Operator, troubleshooting and guides to get started quickly.
Blog posts demonstrate using Terraform Operator.
This pattern differs from the HCP Terraform Operator. The job-generation operator creates Kubernetes Jobs to run Terraform locally, while the HCP Terraform Operator manages HCP Terraform resources declaratively.
Terraform Ternary Operator in Configurations
In this article, we’ll show you how to use the Terraform ternary operator in real configurations.
What is the Terraform ternary operator?
The Terraform ternary operator is a conditional expression that returns one of two values based on a boolean condition. It follows the format:
Terraform evaluates the condition first. If it is true the expression resolves to the first value. If it is false it resolves to the second. Both values must be of the same or a compatible type so Terraform can understand the expression during planning.
This operator is typically used to set resource arguments, variable defaults, module inputs, or meta arguments such as count or for_each that depend on feature flags or environment settings.
How does the Terraform ternary operator compare to if/else in programming languages?
In most programming languages, an if / else block controls the flow of execution. It can wrap multiple lines, declare variables, and run different logic. The Terraform ternary operator is always an expression. It produces a single value that you can plug into an argument.
Terraform does not have an if / else statement for resources
Example usage pattern:
hcl
resource "aws_instance" "example" {
instance_type = var.is_prod ? "t3.large" : "t3.micro"
}
The expression evaluates the condition first. If true the expression resolves to the first value. If false it resolves to the second.
Comparison of Operator Types
| Feature | HCP Terraform Operator for Kubernetes | Terraform Operator for Jobs |
|---|---|---|
| Purpose | Declarative management of HCP Terraform resources via CRDs | Generate Kubernetes Jobs to execute Terraform workflows |
| Integration | HCP Terraform API via go-tfe client | Runs Terraform in cluster pods |
| Core Resources | Workspaces, Agent Pools, Modules, Projects | Jobs created per Terraform run |
| Reconciliation | Watches CRDs and reconciles with HCP Terraform state | Creates Jobs for plan/apply |
| Metrics | Prometheus format per controller | Depends on implementation |
Resource Specifications
| Custom Resource | Managed HCP Terraform Entity | Controller Function |
|---|---|---|
| Workspace | HCP Terraform Workspaces | Synchronizes config, variables, SSH keys, notifications |
| Agent Pool | HCP Terraform Agent Pools and Agent Tokens | Deploys and scales agent pods |
| Module | Terraform Modules | API-driven Run Workflows |
| Project | HCP Terraform Projects | Declarative project management |
Conclusion
The HCP Terraform Operator for Kubernetes delivers declarative control of HCP Terraform resources from within a Kubernetes cluster. Through four custom resource definitions and dedicated controllers, it synchronizes workspaces, agent pools, modules, and projects between the Kubernetes API and HCP Terraform API. Features such as variable management, VCS integration, output capture to ConfigMaps and Secrets, autoscaling of agent pods, and Prometheus metrics enable production-grade infrastructure as code workflows.
The operator runs as a Deployment, supports namespace-scoped or cluster-wide watches via --namespace, and allows tuning of reconciliation frequency via --sync-period. Version 2 improves flexibility and performance through separate controllers per resource type and concurrent management of large-scale deployments.
Separate from this, the Terraform Operator pattern for job generation provides a Kubernetes CRD and controller that creates Kubernetes Jobs to perform Terraform workflows, offering an alternative execution model.
Within Terraform configurations themselves, the ternary operator remains a core expression for conditional values. It returns one of two values based on a boolean condition, and is used for resource arguments, variable defaults, module inputs, and meta arguments like count or for_each. Unlike procedural if/else blocks, Terraform's ternary is an expression that produces a single value for planning and apply.
Together these approaches extend Terraform usage into Kubernetes-native operations, enabling teams to manage infrastructure declaratively through familiar Kubernetes APIs while preserving Terraform's expression language for configuration logic.