Manage Agent Pools with the Terraform Cloud Kubernetes Operator v2
Note
The Terraform Cloud Kubernetes Operator v2 is currently in private beta. Please contact your HashiCorp account team for more information on how to join. Terraform Cloud Free Edition includes one self-hosted agent. Refer to Terraform Cloud pricing for details.
The Terraform Cloud Kubernetes Operator lets you create and manage Terraform Cloud agents, agent pools, and tokens through a single Kubernetes custom resource.
Terraform Cloud Agents let Terraform Cloud communicate with isolated, private, or on-premises infrastructure. By deploying agents within a specific network segment, you can connect your environment and Terraform Cloud, which lets Terraform provision and manage private infrastructure.
In this tutorial you will use the Terraform Cloud Kubernetes Operator to create and manage a Terraform Cloud Agent. The operator manages the lifecycle of agents, making it easier to scale them quickly and securely.
Prerequisites
This tutorial assumes that you are familiar with the standard Terraform workflow, Terraform Cloud, and basic Kubernetes usage.
For this tutorial, you will need:
- A Terraform Cloud organization owner account
- kubectl
- A running Kubernetes cluster v1.16+ with the Terraform Cloud Kubernetes Operator installed
If you do not have the Terraform Cloud Kubernetes Operator installed already, follow the Deploy Infrastructure with the Terraform Cloud Operator for Kubernetes tutorial through the Deploy the operator step and do not delete the Kind cluster or any of the resources created.
Clone repository
In your terminal, clone the Learn Terraform Kubernetes Operator repository.
Review Configuration
Navigate into the repository directory.
Checkout the v2beta
branch of the repository.
Navigate into the operator
directory, which contains configuration files for the operator.
Open the agentpool.yml
file. This file defines a Terraform Cloud agent pool with one agent. Replace ORGANIZATION-NAME
with your own Terraform Cloud organization and save the file.
Configure Terraform Cloud access
The operator requires owner privileges in your Terraform Cloud organization to manage your agents. To do so, create an API token for your owners team, then add it to your cluster as a Kubernetes secret.
First, sign into your Terraform Cloud account, then select Settings -> Teams.
Click on the owners team then click Create a team token to generate a new team API token. If you already have an active token for your owners team, retrieve it or regenerate it if necessary.
Warning
The Team token has global privileges. Ensure that the Kubernetes cluster using this token has proper role-based access control to limit access to the secret, or store it in a secret manager with access control policies.
Copy this token and store it somewhere safe.
Create the agent pool
Create an environment variable to configure the Kubernetes namespace to deploy to named NAMESPACE
and set it to edu
.
Create a secret containing your Terraform Cloud Team API token. Replace APITOKEN
with the token that you created earlier.
Apply the AgentPool specification to the namespace.
Review the operator logs to confirm you launched the agent and agent pool.
Verify the agent pool
Navigate to your Terraform Cloud organization settings. Go to the Agents page and verify that you created a new agent pool named agent-pool-demo
with one agent.
Clean up resources
First, destroy the agent pool and agent by removing the resource definition from your cluster.
Next, delete the Kubernetes resources. Navigate to the root directory.
Destroy the namespace, secrets, and the operator. Confirm the deletion by typing yes
when prompted.
Finally, if you are running on Kind, delete the cluster.
Next steps
In this tutorial, you used the Terraform Cloud Kubernetes operator to create a Terraform Cloud agent pool. You can modify and extend the example configuration to deploy multiple agent pools, and scale the number of agents in each agent pool.
Visit the following resources to learn more about the Terraform Cloud Kubernetes Operator.
- Read the Deploy infrastructure with the Terraform Cloud Kubernetes Operator v2 tutorial.
- To learn more about the Operator and its design, check out the hashicorp/terraform-cloud-operator repository.
- To discover more about managing Kubernetes with Terraform, review the HashiCorp Kubernetes tutorials.