Helm is a package management tool for deploying applications to Kubernetes clusters. Helm charts help you define, install, and upgrade Kubernetes applications. Helm charts expose dozens of useful configurations and automatically set up complex resources.
The Terraform Helm provider allows you to deploy and manage your Kubernetes applications dynamically and securely. Using Terraform, you can provision clusters and deploy applications in the same apply operation. When you pass cluster authentication parameters to the Helm provider, Terraform's built-in dependency graph ensures proper ordering in resource creation.
In this tutorial, you will deploy the kubewatch Helm chart to a pre-provisioned Kubernetes cluster with Terraform. Kubewatch authenticates to your Slack organization and sends alerts regarding your cluster.
»Prerequisites
To run this tutorial locally, you will need:
- Terraform 0.14
- A Slack account with Admin permissions or permissions to create a workspace
- The helm CLI
- A running Kubernetes cluster. Follow the quick-start below, or for more in-depth instructions follow the Provision an EKS Cluster tutorial and do not destroy your cluster.
»Create your EKS cluster
Create a new directory for your project.
Change into your project directory.
Clone the EKS cluster tutorial repo.
Change directories into the cloned repo.
Run terraform init
.
Apply the EKS cluster configuration. Enter yes
when prompted to deploy your EKS configuration.
It may take up to 10 minutes to deploy your EKS cluster.
»Clone the example repository
After deploying your EKS cluster, change into your terraform_project
directory.
Clone the Learn Helm Provider repository for this tutorial.
Your terraform_project
directory should have a subdirectory containing your EKS configuration, and a subdirectory containing your Helm provider configuration.
Change into the Helm configuration repository.
This configuration relies on data from the state file for your EKS cluster. Confirm the state file's path in your kubernetes.tf
file. If you deployed the EKS cluster in the quickstart above your state data source path is "../learn-terraform-provision-eks-cluster/terraform.tfstate"
.
The path
may be different on your machine, so verify the full path to the state file.
Tip: We recommend using provider-specific data sources when convenient. terraform_remote_state
is more flexible, but requires access to the whole Terraform state.
»Review the Helm configuration
In your cloned repository, open the helm_release.tf
file.
The helm
provider block establishes your identity to your Kubernetes cluster. The host
and the cluster_ca_certificate
use your aws_eks_cluster
state data source to construct a method for logging in to your cluster. The exec
argument gets a short-lived token to authenticate to your EKS cluster.
The Terraform Helm provider contains the helm_release
resource that deploys a Helm chart to a Kubernetes cluster. The helm_release
resource specifies the chart name and the configuration variables for your deployment.
Review the helm_release
resource block.
This helm_release
resource installs the kubewatch
chart from the Bitnami repository, then deploys it to your Kubernetes cluster with the custom values specified in kubewatch-values.yaml
and the set_sensitive
block.
Without a custom values file, this resource deploys the default values of your Helm chart to your default Kubernetes cluster. In the next section, you will change this resource to set custom values and point to a custom values file.
»Review the Helm chart
Helm charts are composed of two primary files: a Chart.yaml
file and a values file.
The Chart.yaml
file includes core information about the application you are deploying. The required values are the chart API version, the chart's name, and SemVer 2 version (chart version). For more information on chart configuration files, visit the Helm chart yaml
file documentation.
Open the kubewatch-values.yaml
file in your cloned repository. This file contains the custom values you will configure with your Slack app information. The file
function merges these values with the default Helm chart in the helm_release
resource. Later in this tutorial, you will change the slack.channel
value from #YOUR-CHANNEL
to a test channel in your Slack account.
For more information about Helm values files, visit the Helm documentation.
»Authenticate your application in Helm
Some Helm deployments require API authentication. In this section, you will create a Slack token and update your Terraform configuration so kubewatch
can successfully authenticate to your Slack organization.
»Create a Slack token
First, navigate to your Slack bot services and choose your intended workspace.
Name your app kubewatch-bot
.
Copy the API token and save it somewhere secure.
Invite the bot to your channel with the /invite @kubewatch-bot
command in your intended Slack channel.
You must invite the bot to your channel or else you will not receive your cluster alerts.
Tip: For more information on creating a Slack bot, refer to the Slack bot user documentation.
»Add the Slack token to your configuration
In your terminal, add the Slack token as a TF_VAR
environment variable so Terraform can use it later. Replace <YOUR_SLACK_TOKEN>
with the API token you created in Slack.
Open the kubewatch-values.yaml
file. Change the slack.channel
value from #YOUR-CHANNEL
to the channel you invited the Kubewatch bot to.
Next, open the helm_release.tf
file.
Review the set_sensitive
argument to helm_release.kubewatch
to authenticate to Slack. The value resolves to the TF_VAR_slack_app_token
environment variable you created earlier.
Warning: Never place sensitive credentials in your Terraform configuration if you check in to version control.
»Deploy Kubewatch
Now that you have customized your helm_release
resource, deploy your configuration with Terraform.
Initialize your directory.
Run terraform apply
. Type yes
when prompted to accept your changes.
»Verify kubewatch
To verify that your kubewatch deployment is working, update your kubernetes_deployment
to trigger the alerts.
Open the kubernetes.tf
file, edit the number of replicas to deploy, and save this file.
Apply this configuration. Respond to the confirmation prompt with yes
.
This change causes an update to your deployment to add a new replica and triggers an event in Kubewatch.
After you run your apply, review the Slack channel to ensure you receive your alerts as configured.
»Clean up your infrastructure
Remember to remove the Slack bot you created from your workspace.
Destroy the infrastructure you created in this tutorial. Enter yes
when prompted to confirm your changes.
Change into your EKS cluster directory.
Destroy your EKS cluster. Enter yes
when prompted to confirm your changes.
»Next steps:
In this tutorial, you used Terraform to deploy a Kubernetes monitor to your EKS cluster with a Helm chart.
To learn more about Kubernetes and Helm, refer to the following resources:
- Deploy Consul with Helm tutorial
- Manage Kubernetes Resources via Terraform
- Review the
templatefile()
function to create templatized Helm values files