Deploy Infrastructure with the Terraform Cloud Kubernetes Operator v2

The Terraform Cloud Operator for Kubernetes (Operator) allows you to manage the lifecycle of cloud and on-prem infrastructure through a single Kubernetes custom resource.

You can create application-related infrastructure from a Kubernetes cluster by adding the Operator to your Kubernetes namespace. The Operator uses a Kubernetes Custom Resource Definition (CRD) to manage Terraform Cloud workspaces. These workspaces execute a Terraform Cloud run to provision Terraform modules. By using Terraform Cloud, the Operator leverages its proper state handling and locking, sequential execution of runs, and established patterns for injecting secrets and provisioning resources.

In this tutorial, you will configure and deploy the Operator to a Kubernetes cluster and use it to create a Terraform Cloud workspace. You will also use the Operator to provision a message queue that the example application needs for deployment to Kubernetes.

Prerequisites

The tutorial assumes some basic familiarity with Kubernetes and kubectl.

You should also be familiar with:

• The Terraform workflow — All Get Started tutorials
• Terraform Cloud — All Get Started with Terraform Cloud tutorials

For this tutorial, you will need:

• A Terraform Cloud account

• kubectl

• An AWS account and AWS Access Credentials

  Note

  This tutorial will provision resources that qualify under the AWS free-tier. If your account doesn't qualify under the AWS free-tier, we're not responsible for any charges that you may incur.

Install and configure kubectl

To install the kubectl (Kubernetes CLI), follow these instructions or choose a package manager based on your operating system.

$ brew install kubernetes-cli

$ choco install kubernetes-cli

You will also need a sample kubectl config. We recommend using kind to provision a local Kubernetes cluster and using that config for this tutorial.

$ brew install kind

$ choco install kind

Then, create a kind Kubernetes cluster called terraform-learn.

$ kind create cluster --name terraform-learn
Creating cluster "terraform-learn" ...
 ✓ Ensuring node image (kindest/node:v1.25.3) 🖼
 ✓ Preparing nodes 📦
 ✓ Writing configuration 📜
 ✓ Starting control-plane 🕹️
 ✓ Installing CNI 🔌
 ✓ Installing StorageClass 💾
Set kubectl context to "kind-terraform-learn"
You can now use your cluster with:

kubectl cluster-info --context kind-terraform-learn

Have a nice day! 👋

Verify that your cluster exists by listing your kind clusters.

$ kind get clusters
terraform-learn

Then, point kubectl to interact with this cluster.

$ kubectl cluster-info --context kind-terraform-learn
Kubernetes master is running at https://127.0.0.1:32769
KubeDNS is running at https://127.0.0.1:32769/api/v1/namespaces/kube-system/services/kube-dns:dns/proxy

To further debug and diagnose cluster problems, use 'kubectl cluster-info dump'.

Clone repository

In your terminal, clone the Learn Terraform Kubernetes Operator repository.

$ git clone https://github.com/hashicorp/learn-terraform-kubernetes-operator

Navigate into the repository.

$ cd learn-terraform-kubernetes-operator

Checkout the v2beta branch of the repository.

$ git checkout v2beta

This repository contains the following files.

.
├── LICENSE
├── README.md
├── aws-sqs-test
│   ├── Dockerfile
│   └── message.sh
├── main.tf
├── operator
│   ├── agentpool.yml
│   ├── application.yml
│   ├── configmap.yml
│   ├── module.yml
│   └── workspace.yml
├── terraform.tfvars.example
└── tfvars.gotemplate

• The root directory of this repository contains the Terraform configuration for a Kubernetes namespace and the Operator helm chart.
• The operator directory contains the Kubernetes .yml files that you will use to create a Terraform Cloud workspace using the Operator.
• The aws-sqs-test directory contains the files that build the Docker image that tests the message queue. This is provided as reference only. You will use an image from DockerHub to test the message queue.

Configure the Operator

The Operator must have access to Terraform Cloud and your AWS account. It also needs to run in its own Kubernetes namespace. Below you will configure the Operator and deploy it into your Kubernetes cluster using a Terraform configuration that we have provided for you.

Configure Terraform Cloud access

The Operator must authenticate to Terraform Cloud. To do this, you must create a Terraform Cloud Team API token, then add it as a secret for the Operator to access.

First, sign into your Terraform Cloud account, then navigate to the Settings -> Teams.

Scroll to the Team API Token section. Click on Create a team token and choose an expiration for the token. We recommend that all team tokens have a specified expiration, such as 30 days. Click Generate token to generate a new team token. Copy this token and store it somewhere secure for usage later in this tutorial.

Explore Terraform configuration

The main.tf file has Terraform configuration that will deploy the Operator into your Kubernetes cluster. It includes:

• Two Kubernetes namespaces. The Operator will be deployed in the tfc-operator-system namespace and the workspace, module, and application will be deployed in the edu namespace.

  resource "kubernetes_namespace" "tfc-operator-system" {
    metadata {
      name = "tfc-operator-system"
    }
  }
  
  resource "kubernetes_namespace" "edu" {
    metadata {
      name = "edu"
    }
  }
  

• A terraformrc generic secret for your team API token. The workspace and module that you create later in this tutorial reference this secret.

  resource "kubernetes_secret" "terraformrc" {
    metadata {
      name      = "terraformrc"
      namespace = kubernetes_namespace.edu.metadata[0].name
    }
  
    data = {
      "token" = var.tfc_token
    }
  }
  

• A generic secret named workspacesecrets containing your AWS credentials. In addition to the Terraform Cloud Teams token, Terraform Cloud needs your cloud provider credentials to create infrastructure. This configuration adds your credentials to the namespace, which is used when you create a workspace. You will add the credential values as variables and create a workspace later in this tutorial.

  resource "kubernetes_secret" "workspacesecrets" {
    metadata {
      name      = "workspacesecrets"
      namespace = kubernetes_namespace.edu.metadata[0].name
    }
  
    data = {
      "AWS_ACCESS_KEY_ID"     = var.aws_access_key_id
      "AWS_SECRET_ACCESS_KEY" = var.aws_secret_access_key
    }
  }
  

• The Operator Helm Chart. This is the configuration for the Operator. It is configured to watch the edu namespace for changes such as creating and modifying workspaces. If you use Terraform Enterprise, uncomment the final set block, which specifies the installation endpoint using an input variable.

resource "helm_release" "operator" {
  name    = "terraform-operator"
  chart   = "oci://public.ecr.aws/t8q4c9g6/terraform-cloud-operator"
  version = "0.0.7"

  namespace        = kubernetes_namespace.tfc-operator-system.metadata[0].name
  create_namespace = true

  set {
    name  = "operator.image.repository"
    value = "public.ecr.aws/t8q4c9g6/terraform-cloud-operator"
  }

  set {
    name  = "operator.image.tag"
    value = "2.0.0-beta6"
  }

  set {
    name  = "operator.watchedNamespaces"
    value = "{${kubernetes_namespace.edu.metadata[0].name}}"
  }

  /* Uncomment to deploy to Terraform Enterprise
  set {
    name  = "operator.tfeAddress"
    value = var.tfe_address
  }
  */
}

If your Terraform Enterprise installation uses a TLS certificate signed by a custom Certificate Authority, pass the custom CA bundle root certificate to the Helm chart by adding another set block to the helm_release resource. Update the value to the path of your CA bundle on your local machine.

set {
  name = "customCAcertificates"
  value = "/path/to/cert-bundle.crt"
}

In order to use this configuration, you need to define the variables that authenticate to the kind cluster, AWS, and Terraform Cloud.

Run the following command. It will generate a terraform.tfvars file with your kind cluster configuration.

$ kubectl config view --minify --flatten --context=kind-terraform-learn -o go-template-file=tfvars.gotemplate > terraform.tfvars

Open terraform.tfvars and set the aws_access_key_id, aws_secret_access_key, and tfc_token variables to your AWS and Terraform Cloud credentials. For Terraform Enterprise installations, set the tfe_address variable.

You should end up with something similar to the following.

host                   = "https://127.0.0.1:32768"
client_certificate     = "LS0tLS1CRUdJTiB..."
client_key             = "LS0tLS1CRUdJTiB..."
cluster_ca_certificate = "LS0tLS1CRUdJTiB..."
aws_access_key_id      = "REDACTED"
aws_secret_access_key  = "REDACTED"
tfc_token              = "REDACTED"
tfe_address            = "REDACTED"

Deploy the Operator

Now that you have defined the variables, you are ready to create the Kubernetes resources.

Initialize your configuration.

$ terraform init

Apply your configuration. Remember to confirm your apply with a yes.

$ terraform apply
## ...
kubernetes_namespace.edu: Creating...
kubernetes_namespace.tfc-operator-system: Creating...
kubernetes_namespace.tfc-operator-system: Creation complete after 0s [id=tfc-operator-system]
kubernetes_namespace.edu: Creation complete after 0s [id=edu]
kubernetes_secret.terraformrc: Creating...
kubernetes_secret.workspacesecrets: Creating...
kubernetes_secret.terraformrc: Creation complete after 0s [id=edu/terraformrc]
kubernetes_secret.workspacesecrets: Creation complete after 0s [id=edu/workspacesecrets]
helm_release.operator: Creating...
helm_release.operator: Still creating... [10s elapsed]
helm_release.operator: Creation complete after 13s [id=terraform-operator]

Apply complete! Resources: 5 added, 0 changed, 0 destroyed.

Verify the Operator pods are running.

$ kubectl get -n tfc-operator-system pods
NAME                                                           READY   STATUS    RESTARTS   AGE
terraform-operator-terraform-cloud-operator-6549bb49cd-lq7h4   2/2     Running   0          72s
terraform-operator-terraform-cloud-operator-6549bb49cd-m8n6p   2/2     Running   0          72s

In addition to deploying the Operator, the Helm chart adds custom resource definitions for Workspaces, Modules, and Agent Pools.

$ kubectl get crds
NAME                          CREATED AT
agentpools.app.terraform.io   2023-01-26T18:32:42Z
modules.app.terraform.io      2023-01-26T18:32:42Z
workspaces.app.terraform.io   2023-01-26T18:32:42Z

Explore the specifications

Now you are ready to create infrastructure using the Operator.

First, navigate to the operator directory.

$ cd operator

Open workspace.yml, the workspace specification, and customize it with your Terraform Cloud organization name. The workspace specification both creates a Terraform Cloud workspace, and uses it to deploy your application's required infrastructure.

You can find the following items in workspace.yml, which you use to apply the Workspace custom resource to a Kubernetes cluster.

• The workspace name suffix. The workspace name is a combination of your namespace and metadata.name (in this case: edu-greetings)

  metadata:
    name: greetings
  

• The Terraform Cloud organization. This organization must match the one you generate the Teams token for. Replace ORGANIZATION_NAME with your Terraform Cloud organization name.

  spec:
    organization: ORGANIZATION_NAME
  

• The Terraform Cloud token. The Workspace spec expects a token value, which can be accessed in the terraformrc secret at the key token

  token:
    secretKeyRef:
      name: terraformrc
      key: token
  

• Terraform and Environment variables. For variables that must be passed to the module, the terraformVariables key in the specification must match the name of the module variable. Environment variables can be set using the environmentVariables key. You can indicate that a variable is sensitive by setting sensitive to true. The value can either be set directly with the value or by using ConfigMaps or with a Secret with the valueFrom key. We have set reasonable defaults for these values which you will review in a later step.

  terraformVariables:
    - name: name
      value: greetings.fifo
    - name: fifo_queue
      value: "true"
  environmentVariables:
    - name: AWS_DEFAULT_REGION
      sensitive: false
      valueFrom:
        configMapKeyRef:
          name: aws-configuration
          key: region
    - name: AWS_ACCESS_KEY_ID
      sensitive: false
      valueFrom:
        secretKeyRef:
          name: workspacesecrets
          key: AWS_ACCESS_KEY_ID
    - name: AWS_SECRET_ACCESS_KEY
      sensitive: true
      valueFrom:
        secretKeyRef:
          name: workspacesecrets
          key: AWS_SECRET_ACCESS_KEY
    - name: CONFIRM_DESTROY
      sensitive: false
      value: "1"
  

Explore configmap.yml

In workspace.yml, the AWS_DEFAULT_REGION variable is defined by a ConfigMap named aws-configuration.

Open configmap.yml. Here you will find the specifications for the aws-configuration ConfigMap.

apiVersion: v1
kind: ConfigMap
metadata:
  name: aws-configuration
data:
  region: us-east-2

Explore module.yml

Open module.yml. This specification is equivalent to the following Terraform configuration:

module "queue" {
  source = "terraform-aws-modules/sqs/aws"
  version = "4.0.1"
  name = var.name
  fifo_queue = var.fifo_queue
}

You can also find the following items in module.yml, which you use to apply the Module custom resource to a Kubernetes cluster.

• The Terraform Cloud organization. This organization must match the one you generate the Teams token for. Replace ORGANIZATION_NAME with your Terraform Cloud organization name.

  spec:
    organization: ORGANIZATION_NAME
  

• Outputs you would like to find in the Kubernetes status. The example stores the queue_id which you will use in a later step.

  outputs:
      - name: queue_id
  

Create the message queue

Create an environment variable named NAMESPACE and set it to edu.

$ export NAMESPACE=edu

Apply the ConfigMap specifications to the namespace.

$ kubectl apply -n $NAMESPACE -f configmap.yml
configmap/aws-configuration created

Then, apply the Workspace specifications to the namespace.

$ kubectl apply -n $NAMESPACE -f workspace.yml
workspace.app.terraform.io/greetings created

Next, apply the Module specifications to the namespace.

$ kubectl apply -n $NAMESPACE -f module.yml
module.app.terraform.io/greetings created

Debug the Operator by accessing its logs and checking if the workspace creation ran into any errors.

$ kubectl logs deployment/terraform-operator-terraform-cloud-operator -n tfc-operator-system -f
## ...
{"level":"info","ts":1613124305.9530287,"logger":"terraform-k8s","msg":"Run incomplete","Organization":"hashicorp-training","RunID":"run-xxxxxxxxxxxxxxxx","RunStatus":"applying"}
{"level":"info","ts":1613124306.7574627,"logger":"terraform-k8s","msg":"Checking outputs","Organization":"hashicorp-training","WorkspaceID":"ws-xxxxxxxxxxxxxxxx","RunID":"run-xxxxxxxxxxxxxxxx"}
{"level":"info","ts":1613124307.0337532,"logger":"terraform-k8s","msg":"Updated outputs","Organization":"hashicorp-training","WorkspaceID":"ws-xxxxxxxxxxxxxxxx"}
{"level":"info","ts":1613124307.0339234,"logger":"terraform-k8s","msg":"Updating secrets","name":"greetings-outputs"}

Check the status of the workspace via kubectl or the Terraform Cloud web UI to determine the run status, outputs, and run identifiers.

$ kubectl describe -n $NAMESPACE workspace greetings
Name:         greetings
Namespace:    edu
## ...
Status:
  Observed Generation:  1
  Run Status:
    Configuration Version:
    Id:                     run-xxxxxxxxxxxxxxxx
    Output Run ID:          run-xxxxxxxxxxxxxxxx
    Status:                 applied
  Update At:                1674761640
  Workspace ID:             ws-xxxxxxxxxxxxxxxx

$ kubectl get -n $NAMESPACE module greetings --subresource=status
NAME        CV STATUS   RUN STATUS
greetings   uploaded    applied

In addition to the workspace status, the Operator creates a Kubernetes ConfigMap containing the outputs of the Terraform Cloud workspace. The ConfigMap is formatted <workspace_name>-outputs.

$ kubectl describe -n $NAMESPACE configmap greetings-outputs
Name:         greetings-outputs
Namespace:    edu
Labels:       workspaceID=ws-xxxxxxxxxxxxxxxx
              workspaceName=greetings
Annotations:  <none>

Data
====
queue_id:
----
https://sqs.us-east-2.amazonaws.com/REDACTED/greetings.fifo

Verify message queue

Now that you have deployed the queue, you will now send and receive messages on the queue.

The application.yml contains a spec that runs a containerized application in your kind cluster. That app calls a script called message.sh, which sends and receives messages from the queue, using the same AWS credentials that the Operator used.

To give the script access to the queue's location, the application.yml spec creates a new environment variable named QUEUE_URL, and sets it to the Kubernetes ConfigMap containing the queue url from the Terraform Cloud workspace output.

- name: QUEUE_URL
  valueFrom:
    secretKeyRef:
      name: greetings-outputs
      key: queue_id

Open aws-sqs-test/message.sh. This bash script tests the message queue. To access the queue, it creates environment variables with your AWS credentials and the queue URL. Since Terraform Cloud outputs from the Kubernetes Secret contain double quotes, the script strips the double quotes from the output (QUEUE_URL) to ensure the script works as expected.

## ...
export SQS_URL=$(eval echo $QUEUE_URL | sed 's/"//g')
## ...

Deploy the job and examine the logs from the pod associated with the job.

$ kubectl apply -n $NAMESPACE -f application.yml
job.batch/greetings created

View the job's logs.

$ kubectl logs -n $NAMESPACE $(kubectl get pods -n $NAMESPACE --selector "app=greetings" -o jsonpath="{.items[0].metadata.name}")
https://sqs.us-east-1.amazonaws.com/REDACTED/greetings.fifo
sending a sdfgsdf message to queue https://sqs.us-east-1.amazonaws.com/REDACTED/greetings.fifo
{
    "MD5OfMessageBody": "fc3ff98e8c6a0d3087d515c0473f8677",
    "SequenceNumber": "xxxxxxxxxxxxxxxx",
    "MessageId": "xxxxxxxxxxxxxxxx"
}
reading a message from queue https://sqs.us-east-1.amazonaws.com/REDACTED/greetings.fifo
{
    "Messages": [
        {
            "Body": "hello world!",
            "ReceiptHandle": "xxxxxxxxxxxxxxxx",
            "MD5OfBody": "fc3ff98e8c6a0d3087d515c0473f8677",
            "MessageId": "xxxxxxxxxxxxxxxx"
        }
    ]
}

Change the queue name

Once your infrastructure is running, you can use the Operator to modify it. Update the workspace.yml file to change the queue's name, and the type of the queue from FIFO to standard.

apiVersion: app.terraform.io/v1alpha2
kind: Workspace
metadata:
  name: greetings
spec:
  ## ...
  terraformVariables:
    - name: name
-      value: greetings.fifo
+      value: greetings
    - name: fifo_queue
-      value: "true"
+      value: "false"
  ## ...

Apply the updated workspace configuration. The Terraform Operator retrieves the configuration update and updates the variables in the workspace.

$ kubectl apply -n $NAMESPACE -f workspace.yml
workspace.app.terraform.io/greetings configured

A new run won't be ran unless there is a change to the Module resource. To trigger a new one, make a small change by updating the restartedAt value of the specification.

$ kubectl -n $NAMESPACE patch module greetings --type merge --patch '{"spec": {"restartedAt": "'`date -u -Iseconds`'"}}'
module.app.terraform.io/greetings patched

Examine the run for the workspace in the Terraform Cloud UI. The plan indicates that Terraform Cloud replaced the queue.

You can audit updates to the workspace from the Operator through Terraform Cloud, which maintains a history of runs and the current state.

Clean up resources

Now that you have created and modified a Terraform Cloud workspace using the Operator, delete the module and workspace.

Delete the application

Delete the job used to test the SQS queue.

$ kubectl delete -n $NAMESPACE job greetings
job.app.terraform.io "greetings" deleted

Delete the module

Delete the Module custom resource.

$ kubectl delete -n $NAMESPACE module greetings
module.app.terraform.io "greetings" deleted

You may notice that the command hangs for a few minutes. This is because the Operator executes a finalizer, a pre-delete hook. It executes a terraform destroy on workspace resources.

Once the finalizer completes, Kubernetes will delete the Module custom resource.

Delete the workspace

Delete the Workspace custom resource.

$ kubectl delete -n $NAMESPACE workspace greetings
workspace.app.terraform.io "greetings" deleted

Delete resources and kind cluster

Navigate to the root directory.

$ cd ..

Destroy the namespace, secrets and the Operator. Remember to confirm the destroy with a yes.

$ terraform destroy

Finally, delete the kind cluster.

$ kind delete cluster --name terraform-learn
Deleting cluster "terraform-learn" ...

Next steps

Congrats! You have configured and deployed the Operator to a Kubernetes namespace, created a Terraform workspace, and deployed a message queue using the Operator. This pattern can extend to other application infrastructure, such as DNS servers, databases, and identity and access management rules.

Visit the following resources to learn more about the Terraform Cloud Operator for Kubernetes.

• 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.
• Learn how to Manage Agent Pools with the Terraform Cloud Kubernetes Operator v2.