Deploy Applications with the Helm Provider | 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 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.

$ mkdir terraform_project

$ mkdir terraform_project

Change into your project directory.

$ cd terraform_project

$ cd terraform_project

Clone the EKS cluster tutorial repo.

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

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

Change directories into the cloned repo.

$ cd learn-terraform-provision-eks-cluster

$ cd learn-terraform-provision-eks-cluster

Run terraform init.

$ terraform init
Initializing modules...
Downloading terraform-aws-modules/eks/aws 14.0.0 for eks...
- eks in .terraform/modules/eks
- eks.fargate in .terraform/modules/eks/modules/fargate
- eks.node_groups in .terraform/modules/eks/modules/node_groups
Downloading terraform-aws-modules/vpc/aws 2.66.0 for vpc...
- vpc in .terraform/modules/vpc

Initializing the backend...

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

$ terraform init
Initializing modules...
Downloading terraform-aws-modules/eks/aws 14.0.0 for eks...
- eks in .terraform/modules/eks
- eks.fargate in .terraform/modules/eks/modules/fargate
- eks.node_groups in .terraform/modules/eks/modules/node_groups
Downloading terraform-aws-modules/vpc/aws 2.66.0 for vpc...
- vpc in .terraform/modules/vpc

Initializing the backend...

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

Apply the EKS cluster configuration. Enter yes when prompted to deploy your EKS configuration.

$ terraform apply
An execution plan has been generated and is shown below.
Resource actions are indicated with the following symbols:
   + create
  <= read (data resources)

 Terraform will perform the following actions:
##...
Plan: 54 to add, 0 to change, 0 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

random_string.suffix: Creating...
random_string.suffix: Creation complete after 0s [id=9U9GXhLe]
module.vpc.aws_vpc.this[0]: Creating...
module.vpc.aws_eip.nat[0]: Creating...
##...

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

$ terraform apply
An execution plan has been generated and is shown below.
Resource actions are indicated with the following symbols:
   + create
  <= read (data resources)

 Terraform will perform the following actions:
##...
Plan: 54 to add, 0 to change, 0 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

random_string.suffix: Creating...
random_string.suffix: Creation complete after 0s [id=9U9GXhLe]
module.vpc.aws_vpc.this[0]: Creating...
module.vpc.aws_eip.nat[0]: Creating...
##...

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

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 ..

$ cd ..

Clone the Learn Helm Provider repository for this tutorial.

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

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

Your terraform_project directory should have a subdirectory containing your EKS configuration, and a subdirectory containing your Helm provider configuration.

$ tree .
.
├── learn-terraform-helm
│   ├── README.md
│   ├── helm_release.tf
│   ├── kubernetes.tf
│   ├── kubewatch-values.yaml
│   ├── variables.tf
│   └── versions.tf
└── learn-terraform-provision-eks-cluster
    ├── README.md
    ├── eks-cluster.tf
    ├── kubernetes-dashboard-admin.rbac.yaml
    ├── kubernetes.tf
    ├── outputs.tf
    ├── security-groups.tf
    ├── terraform.tfstate
    ├── versions.tf
    └── vpc.tf

$ tree .
.
├── learn-terraform-helm
│   ├── README.md
│   ├── helm_release.tf
│   ├── kubernetes.tf
│   ├── kubewatch-values.yaml
│   ├── variables.tf
│   └── versions.tf
└── learn-terraform-provision-eks-cluster
    ├── README.md
    ├── eks-cluster.tf
    ├── kubernetes-dashboard-admin.rbac.yaml
    ├── kubernetes.tf
    ├── outputs.tf
    ├── security-groups.tf
    ├── terraform.tfstate
    ├── versions.tf
    └── vpc.tf

Change into the Helm configuration repository.

$ cd learn-terraform-helm

$ cd learn-terraform-helm

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".

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

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 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.

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/v1alpha1"
      args        = ["eks", "get-token", "--cluster-name", data.aws_eks_cluster.cluster.name]
      command     = "aws"
    }
  }
}

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/v1alpha1"
      args        = ["eks", "get-token", "--cluster-name", data.aws_eks_cluster.cluster.name]
      command     = "aws"
    }
  }
}

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.

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

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

  set_sensitive {
    name  = "slack.token"
    value = var.slack_app_token
  }
}

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

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

  set_sensitive {
    name  = "slack.token"
    value = var.slack_app_token
  }
}

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.

annotations:
  category: Infrastructure
apiVersion: v2
## ..
name: kubewatch
sources:
  - https://github.com/bitnami/bitnami-docker-kubewatch
  - https://github.com/bitnami-labs/kubewatch
version: 3.1.0

annotations:
  category: Infrastructure
apiVersion: v2
## ..
name: kubewatch
sources:
  - https://github.com/bitnami/bitnami-docker-kubewatch
  - https://github.com/bitnami-labs/kubewatch
version: 3.1.0

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.

rbac:
  create: true
slack:
  enabled: true
  channel: '#YOUR-CHANNEL'
resourcesToWatch:
  pod: true
  daemonset: true
  services: true
  deployment: true

rbac:
  create: true
slack:
  enabled: true
  channel: '#YOUR-CHANNEL'
resourcesToWatch:
  pod: true
  daemonset: true
  services: true
  deployment: true

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.

$ export TF_VAR_slack_app_token="<YOUR_SLACK_TOKEN>"

$ export TF_VAR_slack_app_token="<YOUR_SLACK_TOKEN>"

Open the kubewatch-values.yaml file. Change the slack.channel value from #YOUR-CHANNEL to the channel you invited the Kubewatch bot to.

rbac:
  create: true
slack:
  enabled: true
  channel: '#YOUR-CHANNEL'
resourcesToWatch:
  pod: true
  daemonset: true
  services: true
  deployment: true

rbac:
  create: true
slack:
  enabled: true
  channel: '#YOUR-CHANNEL'
resourcesToWatch:
  pod: true
  daemonset: true
  services: true
  deployment: true

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.

resource "helm_release" "kubewatch" {
  ##...
  set_sensitive {
    name  = "slack.token"
    value = var.slack_app_token
  }
}
##...


resource "helm_release" "kubewatch" {
  ##...
  set_sensitive {
    name  = "slack.token"
    value = var.slack_app_token
  }
}
##...

»Deploy Kubewatch

Now that you have customized your helm_release resource, deploy your configuration with Terraform.

Initialize your directory.

$ terraform init
Initializing the backend...

Initializing provider plugins...

##...

Terraform has been successfully initialized!

##...

$ terraform init
Initializing the backend...

Initializing provider plugins...

##...

Terraform has been successfully initialized!

##...

Run terraform apply. Type yes when prompted to accept your changes.

$ terraform apply
An execution plan has been generated and is shown below.
Resource actions are indicated with the following symbols:
  + create

Terraform will perform the following actions:

  # helm_release.kubewatch will be created
  + resource "helm_release" "kubewatch" {
##...
Plan: 4 to add, 0 to change, 0 to destroy.

Changes to Outputs:
  + k8s_terramino = (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

kubernetes_namespace.terramino: Creating...
kubernetes_namespace.terramino: Creation complete after 2s [id=terramino]
kubernetes_deployment.terramino: Creating...
helm_release.kubewatch: Creating...
##...
Apply complete! Resources: 4 added, 0 changed, 0 destroyed.

Outputs:

k8s_terramino = "http://<DEPLOYMENT_IP>:8080"

$ terraform apply
An execution plan has been generated and is shown below.
Resource actions are indicated with the following symbols:
  + create

Terraform will perform the following actions:

  # helm_release.kubewatch will be created
  + resource "helm_release" "kubewatch" {
##...
Plan: 4 to add, 0 to change, 0 to destroy.

Changes to Outputs:
  + k8s_terramino = (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

kubernetes_namespace.terramino: Creating...
kubernetes_namespace.terramino: Creation complete after 2s [id=terramino]
kubernetes_deployment.terramino: Creating...
helm_release.kubewatch: Creating...
##...
Apply complete! Resources: 4 added, 0 changed, 0 destroyed.

Outputs:

k8s_terramino = "http://<DEPLOYMENT_IP>:8080"

»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.

resource "kubernetes_deployment" "terramino" {
  ## ...

  spec {
-   replicas = 3
+   replicas = 4
    selector {
      match_labels = {
        app = var.application_name
      }
    }
    ## ...
  }
}

resource "kubernetes_deployment" "terramino" {
  ## ...

  spec {
-   replicas = 3
+   replicas = 4
    selector {
      match_labels = {
        app = var.application_name
      }
    }
    ## ...
  }
}

Apply this configuration. Respond to the confirmation prompt with yes.

$ terraform apply
helm_release.kubewatch: Refreshing state... [id=kubewatch]
kubernetes_namespace.terramino: Refreshing state... [id=terramino]
kubernetes_deployment.terramino: Refreshing state... [id=terramino/terramino]
kubernetes_service.terramino: Refreshing state... [id=terramino/terramino]

An execution plan has been generated and is shown below.
Resource actions are indicated with the following symbols:
  ~ update in-place

Terraform will perform the following actions:

  # kubernetes_deployment.terramino will be updated in-place
  ~ resource "kubernetes_deployment" "terramino" {
        id               = "terramino/terramino"
        # (1 unchanged attribute hidden)

      ~ spec {
          ~ replicas                  = "3" -> "4"
            # (4 unchanged attributes hidden)
            # (3 unchanged blocks hidden)
        }
        # (1 unchanged block hidden)
    }

Plan: 0 to add, 1 to change, 0 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

kubernetes_deployment.terramino: Modifying... [id=terramino/terramino]
kubernetes_deployment.terramino: Modifications complete after 5s [id=terramino/terramino]

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

$ terraform apply
helm_release.kubewatch: Refreshing state... [id=kubewatch]
kubernetes_namespace.terramino: Refreshing state... [id=terramino]
kubernetes_deployment.terramino: Refreshing state... [id=terramino/terramino]
kubernetes_service.terramino: Refreshing state... [id=terramino/terramino]

An execution plan has been generated and is shown below.
Resource actions are indicated with the following symbols:
  ~ update in-place

Terraform will perform the following actions:

  # kubernetes_deployment.terramino will be updated in-place
  ~ resource "kubernetes_deployment" "terramino" {
        id               = "terramino/terramino"
        # (1 unchanged attribute hidden)

      ~ spec {
          ~ replicas                  = "3" -> "4"
            # (4 unchanged attributes hidden)
            # (3 unchanged blocks hidden)
        }
        # (1 unchanged block hidden)
    }

Plan: 0 to add, 1 to change, 0 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

kubernetes_deployment.terramino: Modifying... [id=terramino/terramino]
kubernetes_deployment.terramino: Modifications complete after 5s [id=terramino/terramino]

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

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.

$ terraform destroy
An execution plan has been generated and is shown below.
##...
Plan: 0 to add, 0 to change, 4 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

kubernetes_namespace.terramino: Still destroying... [id=terramino, 10s elapsed]
kubernetes_namespace.terramino: Still destroying... [id=terramino, 20s elapsed]
kubernetes_namespace.terramino: Destruction complete after 23s

Destroy complete! Resources: 4 destroyed.

$ terraform destroy
An execution plan has been generated and is shown below.
##...
Plan: 0 to add, 0 to change, 4 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

kubernetes_namespace.terramino: Still destroying... [id=terramino, 10s elapsed]
kubernetes_namespace.terramino: Still destroying... [id=terramino, 20s elapsed]
kubernetes_namespace.terramino: Destruction complete after 23s

Destroy complete! Resources: 4 destroyed.

Change into your EKS cluster directory.

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

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

Destroy your EKS cluster. Enter yes when prompted to confirm your changes.

$ terraform destroy

An execution plan has been generated and is shown below.
##...
Plan: 0 to add, 0 to change, 54 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
##...
Destroy complete! Resources: 54 destroyed.

$ terraform destroy

An execution plan has been generated and is shown below.
##...
Plan: 0 to add, 0 to change, 54 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
##...
Destroy complete! Resources: 54 destroyed.

»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

Infrastructure

Security

Applications

Networking

cloud