Deploy infrastructure with the Terraform Cloud Kubernetes Operator v1
Note
This tutorial is for Terraform Cloud Kubernetes Operator v1. There is an enhanced Terraform Cloud Kubernetes Operator v2 currently in private beta. More information is available here.
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
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.
Use the package manager homebrew
to install kubectl
.
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.
Use the package manager homebrew
to install kind.
Then, create a kind Kubernetes cluster called terraform-learn
.
Verify that your cluster exists by listing your kind clusters.
Then, point kubectl
to interact with this cluster.
Clone repository
In your terminal, clone the Learn Terraform Kubernetes Operator repository.
Navigate into the repository.
This repository contains the following files.
- 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 select "Settings" -> "Teams".
If you are using a free tier, you will only find one team called "owners" that has full access to the API. Click on "owners".
Click on "Create a team token" to generate a new team token. Copy this token.
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 the contents of credentials.example
into a new file named credentials
.
Then replace TERRAFORM_CLOUD_API_TOKEN
with the Terraform Cloud Teams token you previously created.
Explore Terraform configuration
The main.tf
file has Terraform configuration that will deploy the Operator into your Kubernetes cluster. It includes:
A Kubernetes Namespace. This is where you will deploy the Operator, Secrets, and Workspace custom resource.
A
terraformrc
generic secret for your TFC Teams token. This is the default secret name the Operator uses for your Terraform Cloud credentials. The secret will contain the contents of yourcredentials
file.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 will pass them to Terraform Cloud. You will add the credential values as variables in a later step.The Operator Helm Chart. This is the configuration for the Operator, which is dependent on the
terraformrc
andworkspacesecrets
secrets.
In order to use this configuration, you need to define the variables that authenticate to the kind
cluster and AWS.
Run the following command. It will generate a terraform.tfvars
file with your kind
cluster configuration.
Open terraform.tfvars
and add your AWS credentials in aws_access_key_id
and aws_secret_access_key
respectively.
You should end up with something similar to the following.
Warning
Do not commit sensitive values into version control. The .gitignore
file found in this repository ignores all .tfvars
files. Include it in all of your future Terraform repositories.
Deploy the Operator
Now that you have defined the variables, you are ready to create the Kubernetes resources.
Initialize your configuration.
Apply your configuration. Remember to confirm your apply with a yes
.
Create an environment variable named NAMESPACE
and set it to edu
.
The Operator runs as a pod in the namespace. Verify the pod is running.
In addition to deploying the Operator, the Helm chart adds a Workspace custom resource definition to the cluster.
Explore workspace specification
Now you are ready to create infrastructure using the Operator.
First, navigate to the operator
directory.
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.
This workspace specification is equivalent to the following Terraform configuration.
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
) - 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. - The file path to secrets on the Operator. By default, the Operator helm chart mounts your
workspacesecrets
secrets to/tmp/secrets
. - A Terraform module. This Workspace specification uses the AWS SQS module.
- Input variables. For variables that must be passed to the module, the variable key in the specification must match the name of the module variable. You can set whether a variable is sensitive or an environment variable, and the variable's value using ConfigMaps. We have set reasonable defaults for these values which you will review in a later step.
- Outputs you would like to find in the Kubernetes status. The example maps
this_sqs_queue_id
to an output namedurl
.
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.
Create the message queue
Apply the ConfigMap specifications to the namespace.
Then, apply the Workspace specifications to the namespace.
Debug the Operator by accessing its logs and checking if the workspace creation ran into any errors.
View the Terraform configuration uploaded to Terraform Cloud. The Terraform configuration includes the module's source, version, and inputs.
Check the status of the workspace via kubectl or the Terraform Cloud web UI to determine the run status, outputs, and run identifiers.
The Workspace custom resource reflects that the run was applied and updates its corresponding outputs in the status.
In addition to the workspace status, the Operator creates a Kubernetes Secret containing the outputs of the Terraform Cloud workspace. The Secret is formatted <workspace_name>-outputs
.
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 Secret containing the queue url from the Terraform Cloud workspace output.
Tip
If you mount the Secret as a volume, rather than project it as an environment variable, you can update that Secret without redeploying the app.
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.
Deploy the job and examine the logs from the pod associated with the job.
View the job's logs.
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.
Changing inline, non-sensitive variables, module source, and module version in the Kubernetes Workspace custom resource will trigger a new run in the Terraform Cloud workspace. Changing sensitive variables or variables with ConfigMap references will not trigger updates or runs in Terraform Cloud.
Apply the updated workspace configuration. The Terraform Operator retrieves the configuration update, pushes it to Terraform Cloud, and executes a run.
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 workspace.
Delete workspace
Delete the Workspace custom resource.
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 and deletes the workspace in Terraform Cloud.
Once the finalizer completes, Kubernetes will delete the Workspace custom resource.
Delete resources and kind
cluster
Navigate to the root directory.
Destroy the namespace, secrets and the Operator. Remember to confirm the destroy with a yes.
Finally, delete the kind
cluster.
Next steps
Congrats! You have configured and deployed the Operator to a Kubernetes namespace, explored the Workspace specification, and created a Terraform workspace using the Operator. In doing so, you deployed a message queue from kubectl
. 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-k8s repository.
- To learn more about the Operator helm chart, check out the hashicorp/terraform-helm repository. You can also view example Workspace specifications here too.
- To watch a demo of the Operator, visit Demo: GitOps configuration using the Terraform Cloud Operator for Kubernetes or Demo: HashiCorp Terraform Operator for Kubernetes.
- To discover more about managing Kubernetes with Terraform, review the Hashicorp Kubernetes tutorials.