Deploy applications with the Helm provider

8min
|
Terraform

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 Nginx Helm chart to a Kubernetes cluster with Terraform. Nginx is a widely used webserver and it serves a static HTML file by default so you can verify the deployment.

Prerequisites

To run this tutorial, you will need:

Terraform installed locally
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.

$ mkdir terraform_project

Change into your project directory.

$ cd terraform_project

Clone the EKS cluster tutorial repo.

$ git clone https://github.com/hashicorp/learn-terraform-provision-eks-cluster

Change into the repository directory.

$ cd learn-terraform-provision-eks-cluster

In your editor, open terraform.tf and comment out the cloud block.

terraform.tf

terraform {
  /*
  cloud {
    workspaces {
      name = "learn-terraform-eks"
    }
  }
  */

## ...

Run terraform init.

$ terraform init
Initializing modules...
Downloading registry.terraform.io/terraform-aws-modules/eks/aws 19.5.1 for eks...
- eks in .terraform/modules/eks
- eks.eks_managed_node_group in .terraform/modules/eks/modules/eks-managed-node-group
- eks.eks_managed_node_group.user_data in .terraform/modules/eks/modules/_user_data
- eks.fargate_profile in .terraform/modules/eks/modules/fargate-profile
Downloading registry.terraform.io/terraform-aws-modules/kms/aws 1.1.0 for eks.kms...
- eks.kms in .terraform/modules/eks.kms
- eks.self_managed_node_group in .terraform/modules/eks/modules/self-managed-node-group
- eks.self_managed_node_group.user_data in .terraform/modules/eks/modules/_user_data
Downloading registry.terraform.io/terraform-aws-modules/vpc/aws 3.19.0 for vpc...
- vpc in .terraform/modules/vpc

Initializing the backend...

Initializing provider plugins...
##...
Terraform has been successfully initialized!
##...

Apply the EKS cluster configuration. Respond yes at the prompt to confirm the operation.

$ terraform apply
Terraform used the selected providers to generate the following execution
plan. Resource actions are indicated with the following symbols:
  + create
 <= read (data resources)

Terraform will perform the following actions:

## ...

Plan: 55 to add, 0 to change, 0 to destroy.

Changes to Outputs:
  + cluster_endpoint          = (known after apply)
  + cluster_name              = (known after apply)
  + cluster_security_group_id = (known after apply)
  + region                    = "us-east-2"

Do you want to perform these actions in workspace "learn-terraform-eks"?
  Terraform will perform the actions described above.
  Only 'yes' will be accepted to approve.

  Enter a value: yes

## ...

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

Outputs:

cluster_endpoint = "https://XXXXX.gr7.us-east-2.eks.amazonaws.com"
cluster_name = "education-eks-XXXX"
cluster_security_group_id = "sg-XXXX"
region = "us-east-2"

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.

$ cd ..

Clone the example repository for this tutorial.

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

Change into the repository directory.

$ cd learn-terraform-helm

This configuration uses 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".

learn-terraform-helm/kubernetes.tf

## ...
data "terraform_remote_state" "eks" {
  backend = "local"
  config = {
    path = "../learn-terraform-provision-eks-cluster/terraform.tfstate"
  }
}

The path may be different on your machine, so modify the path to the state file if necessary.

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 editor, open learn-terraform-helm/helm_release.tf.

learn-terraform-helm/helm_release.tf

provider "helm" {
  kubernetes {
    host                   = data.aws_eks_cluster.cluster.endpoint
    cluster_ca_certificate = base64decode(data.aws_eks_cluster.cluster.certificate_authority.0.data)
    exec {
      api_version = "client.authentication.k8s.io/v1beta1"
      args        = ["eks", "get-token", "--cluster-name", data.aws_eks_cluster.cluster.name]
      command     = "aws"
    }
  }
}

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.

Now, review the helm_release resource block.

learn-terraform-helm/helm_release.tf

## ...
resource "helm_release" "nginx" {
  name       = "nginx"
  repository = "https://charts.bitnami.com/bitnami"
  chart      = "nginx"

  values = [
    file("${path.module}/nginx-values.yaml")
  ]
}

The helm_release resource deploys the nginx Helm chart from the Bitnami chart repository to your Kubernetes cluster. The values parameter overrides the chart's default values. The file function merges custom values from the nginx-values.yaml file with the chart's default values.

Next, open the nginx-values.yaml file.

learn-terraform-helm/nginx-values.yaml

replicaCount: 1

The configuration uses the custom values in this file to override the chart's default values during deployment. You will modify these values later in this tutorial.

For more information about Helm values files, visit the Helm documentation.

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 the chart's SemVer 2 version. For more information on chart configuration files, visit the Helm chart yaml file documentation.

annotations:
  category: Infrastructure
  licenses: Apache-2.0
apiVersion: v2
appVersion: 1.23.3
## ...
name: nginx
sources:
  - https://github.com/bitnami/containers/tree/main/bitnami/nginx
  - https://www.nginx.org
version: 13.2.23

Deploy Nginx

Now initialize your configuration that deploys the helm chart.

$ terraform init
Initializing the backend...

Initializing provider plugins...
- terraform.io/builtin/terraform is built in to Terraform
- Reusing previous version of hashicorp/kubernetes from the dependency lock file
- Reusing previous version of hashicorp/aws from the dependency lock file
- Reusing previous version of hashicorp/helm from the dependency lock file
- Using previously-installed hashicorp/aws v4.52.0
- Using previously-installed hashicorp/helm v2.8.0
- Using previously-installed hashicorp/kubernetes v2.17.0

Terraform has been successfully initialized!

##...

Run terraform apply. Respond yes at the prompt to confirm the operation.

$ terraform apply
data.terraform_remote_state.eks: Reading...
## ...

Terraform will perform the following actions:
## ...

Plan: 1 to add, 0 to change, 0 to destroy.

Changes to Outputs:
  + nginx_endpoint = (known after apply)

Do you want to perform these actions?
  Terraform will perform the actions described above.
  Only 'yes' will be accepted to approve.

  Enter a value: yes

helm_release.nginx: Creating...
## ...

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

Outputs:

nginx_endpoint = "http://adfc43040b9cb4ce19e0bba76947fe77-986443180.us-east-2.elb.amazonaws.com"

Verify Nginx

To verify that your Nginx deployment is working, visit the URL from the nginx_endpoint output. It may take up to five minutes for Nginx to become available.

$ curl $(terraform output -raw nginx_endpoint)
<!DOCTYPE html>
<html>
<head>
<title>Welcome to nginx!</title>
<style>
html { color-scheme: light dark; }
body { width: 35em; margin: 0 auto;
font-family: Tahoma, Verdana, Arial, sans-serif; }
</style>
</head>
<body>
<h1>Welcome to nginx!</h1>
<p>If you see this page, the nginx web server is successfully installed and
working. Further configuration is required.</p>

<p>For online documentation and support please refer to
<a href="http://nginx.org/">nginx.org</a>.<br/>
Commercial support is available at
<a href="http://nginx.com/">nginx.com</a>.</p>

<p><em>Thank you for using nginx.</em></p>
</body>
</html>

Modify Nginx

Now open learn-terraform-helm/nginx-values.yaml.

Add the following to the bottom of the file, and save the file.

learn-terraform-helm/nginx-values.yaml

serverBlock: |-
  server {
    listen 0.0.0.0:8080;
    location / {
      default_type text/html;
      return 200 "hello!\n";
    }
  }

This serverBlock custom value configures Nginx to return a custom HTTP response.

Now, redeploy nginx with the updated values. Respond yes at the prompt to confirm the operation.

$ terraform apply
## ...

Plan: 0 to add, 1 to change, 0 to destroy.

Changes to Outputs:
  ~ nginx_endpoint = "http://adfc43040b9cb4ce19e0bba76947fe77-986443180.us-east-2.elb.amazonaws.com" -> (known after apply)

Do you want to perform these actions?
  Terraform will perform the actions described above.
  Only 'yes' will be accepted to approve.

  Enter a value: yes

helm_release.nginx: Modifying... [id=nginx]
## ...

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

Outputs:

nginx_endpoint = "http://adfc43040b9cb4ce19e0bba76947fe77-986443180.us-east-2.elb.amazonaws.com"

Finally, verify the change.

$ curl $(terraform output -raw nginx_endpoint)
hello!

Clean up your infrastructure

Destroy the infrastructure you created in this tutorial. Respond yes at the prompt to confirm the operation.

$ terraform destroy
##...
Plan: 0 to add, 0 to change, 1 to destroy.

Do you want to perform these actions?
  Terraform will perform the actions described above.
  Only 'yes' will be accepted to approve.

  Enter a value: yes

helm_release.nginx: Destroying... [id=nginx]
helm_release.nginx: Still destroying... [id=nginx, 10s elapsed]
helm_release.nginx: Still destroying... [id=nginx, 20s elapsed]
helm_release.nginx: Destruction complete after 28s

Destroy complete! Resources: 1 destroyed.

Change into your EKS cluster configuration directory.

$ cd ../learn-terraform-provision-eks-cluster

Destroy your EKS cluster. Respond yes at the prompt to confirm the operation.

$ terraform destroy
##...
Plan: 0 to add, 0 to change, 55 to destroy.

Changes to Outputs:
  - cluster_endpoint          = "https://XXXX.gr7.us-east-2.eks.amazonaws.com" -> null
  - cluster_name              = "education-eks-Lh9k4i0u" -> null
  - cluster_security_group_id = "sg-0b89a05da52641c12" -> null
  - region                    = "us-east-2" -> null

Do you really want to destroy all resources?
  Terraform will destroy all your managed infrastructure, as shown above.
  There is no undo. Only 'yes' will be accepted to confirm.

  Enter a value: yes
##...
Destroy complete! Resources: 55 destroyed.

Next steps:

In this tutorial, you used Terraform to deploy Nginx 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

Kubernetes Operator v2 agent pools

Kubernetes custom resources

This tutorial also appears in:

13 tutorials

Use Cases for Terraform
Use Terraform to perform common operations with other technologies, including Consul, Vault, Packer, and Kubernetes.
- Terraform