Helm Service
Overview
This service contains Terraform code to deploy an arbitrary Helm chart to Kubernetes following best practices.
This module is intended to deploy third-party applications already packaged as Helm Charts, such as those available in bitnami. If you want to deploy your own application containers to Kubernetes, see the k8s-service
module.
Kubernetes Service architecture
Features
- Deploy any Helm chart using Terraform
- Managed with Helm
Learn
This repo is a part of the Gruntwork Service Catalog, a collection of reusable, battle-tested, production ready infrastructure code. If you’ve never used the Service Catalog before, make sure to read How to use the Gruntwork Service Catalog!
Core concepts
-
Kubernetes core concepts: learn about Kubernetes architecture (control plane, worker nodes), access control (authentication, authorization, resources (pods, controllers, services, config, secrets), and more.
-
Kubernetes in Action: the best book we’ve found for getting up and running with Kubernetes.
Repo organization
- modules: the main implementation code for this repo, broken down into multiple standalone, orthogonal submodules.
- examples: This folder contains working examples of how to use the submodules.
- test: Automated tests for the modules and examples.
Deploy
Non-production deployment (quick start for learning)
If you just want to try this repo out for experimenting and learning, check out the following resources:
- examples/for-learning-and-testing folder: The
examples/for-learning-and-testing
folder contains standalone sample code optimized for learning, experimenting, and testing (but not direct production usage).
Production deployment
If you want to deploy this repo in production, check out the following resources:
- examples/for-production folder: The
examples/for-production
folder contains sample code optimized for direct usage in production. This is code from the Gruntwork Reference Architecture, and it shows you how we build an end-to-end, integrated tech stack on top of the Gruntwork Service Catalog.
Sample Usage
- Terraform
- Terragrunt
# ------------------------------------------------------------------------------------------------------
# DEPLOY GRUNTWORK'S HELM-SERVICE MODULE
# ------------------------------------------------------------------------------------------------------
module "helm_service" {
source = "git::git@github.com:gruntwork-io/terraform-aws-service-catalog.git//modules/services/helm-service?ref=v0.118.2"
# ----------------------------------------------------------------------------------------------------
# REQUIRED VARIABLES
# ----------------------------------------------------------------------------------------------------
# The name of the application (e.g. my-service-stage). Used for labeling
# Kubernetes resources.
application_name = <string>
# Chart name to be installed. The chart name can be local path, a URL to a
# chart, or the name of the chart if repository is specified. It is also
# possible to use the <repository>/<chart> format here if you are running
# Terraform on a system that the repository has been added to with helm repo
# add but this is not recommended.
helm_chart = <string>
# Repository URL where to locate the requested chart.
helm_repository = <string>
# The Kubernetes Namespace to deploy the helm chart into.
namespace = <string>
# ----------------------------------------------------------------------------------------------------
# OPTIONAL VARIABLES
# ----------------------------------------------------------------------------------------------------
# Configuration for using the IAM role with Service Accounts feature to
# provide permissions to the applications. This expects a map with two
# properties: `openid_connect_provider_arn` and `openid_connect_provider_url`.
# The `openid_connect_provider_arn` is the ARN of the OpenID Connect Provider
# for EKS to retrieve IAM credentials, while `openid_connect_provider_url` is
# the URL. Leave as an empty string if you do not wish to use IAM role with
# Service Accounts.
eks_iam_role_for_service_accounts_config = null
# Map of values to pass to the Helm chart. Leave empty to use chart default
# values.
helm_chart_values = {}
# Specify the exact chart version to install. If this is not specified, the
# latest version is installed.
helm_chart_version = null
# An object defining the policy to attach to `iam_role_name` if the IAM role
# is going to be created. Accepts a map of objects, where the map keys are
# sids for IAM policy statements, and the object fields are the resources,
# actions, and the effect ("Allow" or "Deny") of the statement. Ignored if
# `iam_role_arn` is provided. Leave as null if you do not wish to use IAM role
# with Service Accounts.
iam_policy = null
# Whether or not the IAM role passed in `iam_role_name` already exists. Set to
# true if it exists, or false if it needs to be created. Defaults to false.
iam_role_exists = false
# The name of an IAM role that will be used by the pod to access the AWS API.
# If `iam_role_exists` is set to false, this role will be created. Leave as an
# empty string if you do not wish to use IAM role with Service Accounts.
iam_role_name = ""
# The name of a service account to create for use with the Pods. This service
# account will be mapped to the IAM role defined in `var.iam_role_name` to
# give the pod permissions to access the AWS API. Must be unique in this
# namespace. Leave as an empty string if you do not wish to assign a Service
# Account to the Pods.
service_account_name = ""
# Sleep for 30 seconds to allow Kubernetes time to remove associated AWS
# resources.
sleep_for_resource_culling = false
# When true, wait until Pods are up and healthy or wait_timeout seconds before
# exiting terraform.
wait = true
# Number of seconds to wait for Pods to become healthy before marking the
# deployment as a failure.
wait_timeout = 300
}
# ------------------------------------------------------------------------------------------------------
# DEPLOY GRUNTWORK'S HELM-SERVICE MODULE
# ------------------------------------------------------------------------------------------------------
terraform {
source = "git::git@github.com:gruntwork-io/terraform-aws-service-catalog.git//modules/services/helm-service?ref=v0.118.2"
}
inputs = {
# ----------------------------------------------------------------------------------------------------
# REQUIRED VARIABLES
# ----------------------------------------------------------------------------------------------------
# The name of the application (e.g. my-service-stage). Used for labeling
# Kubernetes resources.
application_name = <string>
# Chart name to be installed. The chart name can be local path, a URL to a
# chart, or the name of the chart if repository is specified. It is also
# possible to use the <repository>/<chart> format here if you are running
# Terraform on a system that the repository has been added to with helm repo
# add but this is not recommended.
helm_chart = <string>
# Repository URL where to locate the requested chart.
helm_repository = <string>
# The Kubernetes Namespace to deploy the helm chart into.
namespace = <string>
# ----------------------------------------------------------------------------------------------------
# OPTIONAL VARIABLES
# ----------------------------------------------------------------------------------------------------
# Configuration for using the IAM role with Service Accounts feature to
# provide permissions to the applications. This expects a map with two
# properties: `openid_connect_provider_arn` and `openid_connect_provider_url`.
# The `openid_connect_provider_arn` is the ARN of the OpenID Connect Provider
# for EKS to retrieve IAM credentials, while `openid_connect_provider_url` is
# the URL. Leave as an empty string if you do not wish to use IAM role with
# Service Accounts.
eks_iam_role_for_service_accounts_config = null
# Map of values to pass to the Helm chart. Leave empty to use chart default
# values.
helm_chart_values = {}
# Specify the exact chart version to install. If this is not specified, the
# latest version is installed.
helm_chart_version = null
# An object defining the policy to attach to `iam_role_name` if the IAM role
# is going to be created. Accepts a map of objects, where the map keys are
# sids for IAM policy statements, and the object fields are the resources,
# actions, and the effect ("Allow" or "Deny") of the statement. Ignored if
# `iam_role_arn` is provided. Leave as null if you do not wish to use IAM role
# with Service Accounts.
iam_policy = null
# Whether or not the IAM role passed in `iam_role_name` already exists. Set to
# true if it exists, or false if it needs to be created. Defaults to false.
iam_role_exists = false
# The name of an IAM role that will be used by the pod to access the AWS API.
# If `iam_role_exists` is set to false, this role will be created. Leave as an
# empty string if you do not wish to use IAM role with Service Accounts.
iam_role_name = ""
# The name of a service account to create for use with the Pods. This service
# account will be mapped to the IAM role defined in `var.iam_role_name` to
# give the pod permissions to access the AWS API. Must be unique in this
# namespace. Leave as an empty string if you do not wish to assign a Service
# Account to the Pods.
service_account_name = ""
# Sleep for 30 seconds to allow Kubernetes time to remove associated AWS
# resources.
sleep_for_resource_culling = false
# When true, wait until Pods are up and healthy or wait_timeout seconds before
# exiting terraform.
wait = true
# Number of seconds to wait for Pods to become healthy before marking the
# deployment as a failure.
wait_timeout = 300
}
Reference
- Inputs
- Outputs
Required
application_name
stringThe name of the application (e.g. my-service-stage). Used for labeling Kubernetes resources.
helm_chart
stringChart name to be installed. The chart name can be local path, a URL to a chart, or the name of the chart if repository is specified. It is also possible to use the <repository>/<chart> format here if you are running Terraform on a system that the repository has been added to with helm repo add but this is not recommended.
helm_repository
stringRepository URL where to locate the requested chart.
namespace
stringThe Kubernetes Namespace to deploy the helm chart into.
Optional
Configuration for using the IAM role with Service Accounts feature to provide permissions to the applications. This expects a map with two properties: openid_connect_provider_arn
and openid_connect_provider_url
. The openid_connect_provider_arn
is the ARN of the OpenID Connect Provider for EKS to retrieve IAM credentials, while openid_connect_provider_url
is the URL. Leave as an empty string if you do not wish to use IAM role with Service Accounts.
object({
openid_connect_provider_arn = string
openid_connect_provider_url = string
})
null
Map of values to pass to the Helm chart. Leave empty to use chart default values.
Any types represent complex values of variable type. For details, please consult `variables.tf` in the source repo.
{}
helm_chart_version
stringSpecify the exact chart version to install. If this is not specified, the latest version is installed.
null
iam_policy
map(object(…))An object defining the policy to attach to iam_role_name
if the IAM role is going to be created. Accepts a map of objects, where the map keys are sids for IAM policy statements, and the object fields are the resources, actions, and the effect ('Allow' or 'Deny') of the statement. Ignored if iam_role_arn
is provided. Leave as null if you do not wish to use IAM role with Service Accounts.
map(object({
resources = list(string)
actions = list(string)
effect = string
}))
null
Example
iam_policy = {
S3Access = {
actions = ["s3:*"]
resources = ["arn:aws:s3:::mybucket"]
effect = "Allow"
},
SecretsManagerAccess = {
actions = ["secretsmanager:GetSecretValue"],
resources = ["arn:aws:secretsmanager:us-east-1:0123456789012:secret:mysecert"]
effect = "Allow"
}
}
iam_role_exists
boolWhether or not the IAM role passed in iam_role_name
already exists. Set to true if it exists, or false if it needs to be created. Defaults to false.
false
iam_role_name
stringThe name of an IAM role that will be used by the pod to access the AWS API. If iam_role_exists
is set to false, this role will be created. Leave as an empty string if you do not wish to use IAM role with Service Accounts.
""
service_account_name
stringThe name of a service account to create for use with the Pods. This service account will be mapped to the IAM role defined in <a href="#iam_role_name"><code>iam_role_name</code></a>
to give the pod permissions to access the AWS API. Must be unique in this namespace. Leave as an empty string if you do not wish to assign a Service Account to the Pods.
""
Sleep for 30 seconds to allow Kubernetes time to remove associated AWS resources.
false
wait
boolWhen true, wait until Pods are up and healthy or wait_timeout seconds before exiting terraform.
true
wait_timeout
numberNumber of seconds to wait for Pods to become healthy before marking the deployment as a failure.
300