9.5 KiB

Raw Blame History

page_title	sidebar_current	description
Provider: Helm	docs-helm-index	The Helm provider is used to deploy software packages in Kubernetes. The provider needs to be configured with the proper credentials before it can be used.

Helm Provider

The Helm provider is used to deploy software packages in Kubernetes. The provider needs to be configured with the proper credentials before it can be used.

Try the hands-on tutorial on the Helm provider on the HashiCorp Learn site.

Resources

Resource: helm_release

Data Sources

Data Source: helm_template

Example Usage

provider "helm" {
  kubernetes = {
    config_path = "~/.kube/config"
  }

  registries = [
    {
      url      = "oci://localhost:5000"
      username = "username"
      password = "password"
    },
    {
      url      = "oci://private.registry"
      username = "username"
      password = "password"
    }
  ]
}

resource "helm_release" "nginx_ingress" {
  name       = "nginx-ingress-controller"
  repository = "https://charts.bitnami.com/bitnami"
  chart      = "nginx-ingress-controller"

  set = [
    {
      name  = "service.type"
      value = "ClusterIP"
    }
  ]
}

Requirements

~> NOTE: The provider does not use the KUBECONFIG environment variable by default. See the attribute reference below for the environment variables that map to provider block attributes.

You must have a Kubernetes cluster available. We support version 1.14.0 or higher.

Authentication

The Helm provider can get its configuration in two ways:

Explicitly by supplying attributes to the provider block. This includes:
Implicitly through environment variables. This includes:
- Using the in-cluster config

For a full list of supported provider authentication arguments and their corresponding environment variables, see the argument reference below.

File config

The easiest way is to supply a path to your kubeconfig file using the config_path attribute or using the KUBE_CONFIG_PATH environment variable. A kubeconfig file may have multiple contexts. If config_context is not specified, the provider will use the default context.

provider "helm" {
  kubernetes = {
    config_path = "~/.kube/config"
  }
}

The provider also supports multiple paths in the same way that kubectl does using the config_paths attribute or KUBE_CONFIG_PATHS environment variable.

provider "helm" {
  kubernetes = {
    config_paths = [
      "/path/to/config_a.yaml",
      "/path/to/config_b.yaml"
    ]
  }
}

Credentials config

You can also configure the host, basic auth credentials, and client certificate authentication explicitly or through environment variables.

provider "helm" = {
  kubernetes {
    host     = "https://cluster_endpoint:port"

    client_certificate     = file("~/.kube/client-cert.pem")
    client_key             = file("~/.kube/client-key.pem")
    cluster_ca_certificate = file("~/.kube/cluster-ca-cert.pem")
  }
}

In-cluster Config

The provider uses the KUBERNETES_SERVICE_HOST and KUBERNETES_SERVICE_PORT environment variables to detect when it is running inside a cluster, so in this case you do not need to specify any attributes in the provider block if you want to connect to the local kubernetes cluster.

If you want to connect to a different cluster than the one terraform is running inside, configure the provider as above.

Exec plugins

Some cloud providers have short-lived authentication tokens that can expire relatively quickly. To ensure the Kubernetes provider is receiving valid credentials, an exec-based plugin can be used to fetch a new token before initializing the provider. For example, on EKS, the command eks get-token can be used:

provider "helm" {
  kubernetes = {
    host                   = var.cluster_endpoint
    cluster_ca_certificate = base64decode(var.cluster_ca_cert)
    exec = {
      api_version = "client.authentication.k8s.io/v1beta1"
      args        = ["eks", "get-token", "--cluster-name", var.cluster_name]
      command     = "aws"
    }
  }
}

For example, to authenticate with GKE, the gke-cloud-auth-plugin can be used:

provider "helm" {
    kubernetes = {
        host  = "https://${data.google_container_cluster.my_cluster.endpoint}"
        token = data.google_client_config.provider.access_token
        cluster_ca_certificate = base64decode(
        data.google_container_cluster.my_cluster.master_auth[0].cluster_ca_certificate,)
        exec = {
            api_version = "client.authentication.k8s.io/v1beta1"
            command     = "gke-gcloud-auth-plugin"
        }
    }
}

Argument Reference

The following arguments are supported:

debug - (Optional) - Debug indicates whether or not Helm is running in Debug mode. Defaults to false.
plugins_path - (Optional) The path to the plugins directory. Defaults to HELM_PLUGINS env if it is set, otherwise uses the default path set by helm.
registry_config_path - (Optional) The path to the registry config file. Defaults to HELM_REGISTRY_CONFIG env if it is set, otherwise uses the default path set by helm.
repository_config_path - (Optional) The path to the file containing repository names and URLs. Defaults to HELM_REPOSITORY_CONFIG env if it is set, otherwise uses the default path set by helm.
repository_cache - (Optional) The path to the file containing cached repository indexes. Defaults to HELM_REPOSITORY_CACHE env if it is set, otherwise uses the default path set by helm.
helm_driver - (Optional) "The backend storage driver. Valid values are: configmap, secret, memory, sql. Defaults to secret. Note: Regarding the sql driver, as of helm v3.2.0 SQL support exists only for the postgres dialect. The connection string can be configured by setting the HELM_DRIVER_SQL_CONNECTION_STRING environment variable e.g. HELM_DRIVER_SQL_CONNECTION_STRING=postgres://username:password@host/dbname more info here.
burst_limit - (Optional) The helm burst limit to use. Set this value higher if your cluster has many CRDs. Default: 100
kubernetes - Kubernetes configuration block.
registries - Private OCI registry configuration block. Can be specified multiple times.

The kubernetes block supports:

config_path - (Optional) Path to the kube config file. Can be sourced from KUBE_CONFIG_PATH.
config_paths - (Optional) A list of paths to the kube config files. Can be sourced from KUBE_CONFIG_PATHS.
host - (Optional) The hostname (in form of URI) of the Kubernetes API. Can be sourced from KUBE_HOST.
username - (Optional) The username to use for HTTP basic authentication when accessing the Kubernetes API. Can be sourced from KUBE_USER.
password - (Optional) The password to use for HTTP basic authentication when accessing the Kubernetes API. Can be sourced from KUBE_PASSWORD.
token - (Optional) The bearer token to use for authentication when accessing the Kubernetes API. Can be sourced from KUBE_TOKEN.
insecure - (Optional) Whether server should be accessed without verifying the TLS certificate. Can be sourced from KUBE_INSECURE.
tls_server_name - (Optional) Server name passed to the server for SNI and is used in the client to check server certificates against. Can be sourced from KUBE_TLS_SERVER_NAME.
client_certificate - (Optional) PEM-encoded client certificate for TLS authentication. Can be sourced from KUBE_CLIENT_CERT_DATA.
client_key - (Optional) PEM-encoded client certificate key for TLS authentication. Can be sourced from KUBE_CLIENT_KEY_DATA.
cluster_ca_certificate - (Optional) PEM-encoded root certificates bundle for TLS authentication. Can be sourced from KUBE_CLUSTER_CA_CERT_DATA.
config_context - (Optional) Context to choose from the config file. Can be sourced from KUBE_CTX.
proxy_url - (Optional) URL to the proxy to be used for all API requests. URLs with "http", "https", and "socks5" schemes are supported. Can be sourced from KUBE_PROXY_URL.
exec - (Optional) Configuration block to use an exec-based credential plugin, e.g. call an external command to receive user credentials.
api_version - (Required) API version to use when decoding the ExecCredentials resource, e.g. client.authentication.k8s.io/v1beta1.
command - (Required) Command to execute.
args - (Optional) List of arguments to pass when executing the plugin.
env - (Optional) Map of environment variables to set when executing the plugin.

The registries block has options:

url - (Required) url to the registry in format oci://host:port
username - (Required) username to registry
password - (Required) password to registry

Experiments

The provider takes an experiments block that allows you enable experimental features by setting them to true.

manifest - Enable storing of the rendered manifest for helm_release so the full diff of what is changing can been seen in the plan.

provider "helm" {
  experiments = {
    manifest = true
  }
}

9.5 KiB Raw Blame History