HCP Terraform Operator for Kubernetes

Kubernetes Operator allows managing HCP Terraform / Terraform Enterprise resources via Kubernetes Custom Resources.

Note

From this point forward, the terms HCP Terraform can be used interchangeably with Terraform Enterprise in all documents, provided that the contrary is indicated.

The Operator can manage the following types of resources:

• AgentPool manages HCP Terraform Agent Pools, HCP Terraform 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 Runs scrapes HCP Terraform run statuses from a given Agent Pool and exposes them as Prometheus-compatible metrics. Learn more about Runs.
• Workspace manages HCP Terraform Workspaces

Getting started

To get started see our tutorials on the HashiCorp Developer Portal:

• HCP Terraform Operator for Kubernetes overview
• Deploy infrastructure with the HCP Terraform Operator for Kubernetes
• Manage agent pools with the HCP Terraform Operator for Kubernetes
• HCP Terraform Operator for Kubernetes Migration Guide

Documentation

Supported Features

The full list of supported HCP Terraform Operator features can be found on our Developer portal.

Installation

The Operator provides Helm chart as a first-class method of installation on Kubernetes.

Three simple commands to install the Operator:

$ helm repo add hashicorp https://helm.releases.hashicorp.com
$ helm repo update
$ helm install demo hashicorp/hcp-terraform-operator --wait --version 2.11.3

More detailed information about the installation and available values can be found here.

Usage

General usage documentation can be found here.

Controllers usage guides:

• AgentPool
• AgentToken
• Module
• Project
• RunsCollector
• Workspace

Annotations and Labels

Annotations and Labels used by HCP Terraform Operator can be found here.

Metrics

The Operator exposes metrics in the Prometheus format for each controller. More information can be found here.

API reference

API reference documentation can be found here.

Frequently Asked Questions

FAQ can be found here.

Examples

YAML manifests examples live here.

Community Contribution

If you come across articles, videos, how-tos, or any other resources that could assist individuals in adopting and utilizing the operator with greater efficiency, kindly inform us by initiating a pull request and placing a link within this designated section.

Your participation matters. Thank you for being a part of our community! 🙌

Troubleshooting

If you encounter any issues with the Operator there are a number of ways how to troubleshoot it:

• check the Operator logs:

  $ kubectl logs -f <POD_NAME>
  

  Logs for a specific CR can be identified with the following pattern:

  {"<KIND>": "<NAMESPACE>/<METADATA.NAME>", "msg": "..."}
  

  For example:

  2023-01-05T12:11:31Z INFO Agent Pool Controller	{"agentpool": "default/this", "msg": "successfully reconcilied agent pool"}
  

• check the CR:

  $ kubectl get agentpool <NAME>
  $ kubectl get agenttoken <NAME>
  $ kubectl get module <NAME>
  $ kubectl get project <NAME>
  $ kubectl get runscollector <NAME>
  $ kubectl get workspace <NAME>
  

• check the CR events:

  $ kubectl describe agentpool <NAME>
  $ kubectl describe agenttoken <NAME>
  $ kubectl describe module <NAME>
  $ kubectl describe project <NAME>
  $ kubectl describe runscollector <NAME>
  $ kubectl describe workspace <NAME>
  

If you believe you've found a bug and cannot find an existing issue, feel free to open a new issue! Be sure to include as much information as you can about your environment.

Contributing to the Operator

We appreciate your enthusiasm for participating in the development of the HCP Terraform Operator. To contribute, please read the contribution guidelines.

Security Reporting

If you think you've found a security vulnerability, we'd love to hear from you.

Follow the instructions in SECURITY.md to make a report.