Helm

The helm resource deploys Helm charts to Kubernetes clusters. It supports charts from remote repositories, local directories, or Git references, with comprehensive configuration options for values, namespaces, and health checks.

Use Cases

As a lab author, you can use helm resources to:

Application Deployment: Deploy microservices, web applications, and API services using production-ready Helm charts
Chart Customization: Override Helm chart values to customize deployments for specific lab requirements and configurations

Helm resources enable rapid deployment of complex Kubernetes applications with industry-standard configurations and best practices.

HCL Syntax

Basic Syntax

1
resource "helm" "name" {
2
  cluster = resource.k8s_cluster.main
3
  chart = "nginx"
4

5
  repository {
6
    name = "bitnami"
7
    url = "https://charts.bitnami.com/bitnami"
8
  }
9
}

Full Syntax

1
resource "helm" "name" {
2
  cluster = resource.k8s_cluster.production
3

4
  chart = "vault"
5
  version = "0.25.0"
6
  namespace = "vault"
7
  create_namespace = true
8

9
  repository {
10
    name = "hashicorp"
11
    url = "https://helm.releases.hashicorp.com"
12
  }
13

14
  values = "./values/vault-values.yaml"
15
  values_string = {
16
    "server.ha.enabled" = "true"
17
    "server.ha.replicas" = "3"
18
    "ui.enabled" = "true"
19
  }
20

21
  skip_crds = false
22
  retry = 3
23
  timeout = "300s"
24

25
  health_check {
26
    timeout = "120s"
27
    pods = [
28
      "app.kubernetes.io/name=vault",
29
      "app.kubernetes.io/instance=vault"
30
    ]
31
  }
32
}

Fields

Field	Required	Type	Description
`cluster`	✓	reference to `kubernetes_cluster`	Reference to a Kubernetes cluster resource
`chart`	✓	string	Chart name or path (repository chart, local path, or Git URL)
`version`		string	Semver version of the chart (repository charts only). Defaults to latest.
`namespace`		string	Kubernetes namespace for deployment. Defaults to “default”.
`create_namespace`		bool	Create namespace if it doesn’t exist. Defaults to false.
`repository`		block	Remote repository configuration
`values`		string	Path to YAML values file
`values_string`		map(string)	Inline values as key-value pairs. Defaults to empty map.
`skip_crds`		bool	Skip installation of Custom Resource Definitions. Defaults to false.
`retry`		number	Number of retry attempts on failure. Defaults to 0.
`timeout`		string	Maximum time for chart installation. Defaults to “300s”.
`health_check`		block	Kubernetes health check configuration

Repository Block

helm → repository

Configures remote Helm chart repositories for downloading charts.

Field	Required	Type	Description
`name`	✓	string	Repository name
`url`	✓	string	Repository URL

Health Check Block

helm → health_check

Post-deployment health verification configuration.

Field	Required	Type	Description
`timeout`	✓	string	Health check timeout duration
`pods`	✓	list(string)	Kubernetes selectors for pods to monitor

Validation Rules

Chart paths are made absolute relative to the config file location
Values file paths are made absolute relative to the config file location
Referenced cluster must exist and be healthy
Repository URL must be valid if specified
Timeout values must be valid Go duration strings
Health check selectors must use valid Kubernetes label syntax

Examples

Simple Chart from Repository

1
resource "k8s_cluster" "dev" {
2
  network {
3
    id = resource.network.main
4
  }
5
}
6

7
resource "helm" "nginx" {
8
  cluster = resource.k8s_cluster.dev
9
  chart = "nginx"
10

11
  repository {
12
    name = "bitnami"
13
    url = "https://charts.bitnami.com/bitnami"
14
  }
15

16
  values_string = {
17
    "service.type" = "ClusterIP"
18
    "replicaCount" = "2"
19
  }
20
}

Chart with External Values File

1
resource "helm" "wordpress" {
2
  cluster = resource.k8s_cluster.web
3
  chart = "wordpress"
4
  version = "15.2.0"
5
  namespace = "wordpress"
6
  create_namespace = true
7

8
  repository {
9
    name = "bitnami"
10
    url = "https://charts.bitnami.com/bitnami"
11
  }
12

13
  values = "./values/wordpress-production.yaml"
14

15
  values_string = {
16
    "wordpressPassword" = "secure-password"
17
    "mariadb.auth.rootPassword" = "root-password"
18
  }
19

20
  health_check {
21
    timeout = "300s"
22
    pods = ["app.kubernetes.io/name=wordpress"]
23
  }
24
}

Local Chart Directory

1
resource "helm" "custom_app" {
2
  cluster = resource.k8s_cluster.dev
3
  chart = "./charts/my-application"
4
  namespace = "apps"
5
  create_namespace = true
6

7
  values_string = {
8
    "image.tag" = "latest"
9
    "service.port" = "8080"
10
  }
11

12
  health_check {
13
    timeout = "120s"
14
    pods = ["app=my-application"]
15
  }
16
}

High Availability Setup

1
resource "helm" "vault" {
2
  cluster = resource.k8s_cluster.production
3
  chart = "vault"
4
  version = "0.25.0"
5
  namespace = "vault-system"
6
  create_namespace = true
7

8
  repository {
9
    name = "hashicorp"
10
    url = "https://helm.releases.hashicorp.com"
11
  }
12

13
  values = "./config/vault-ha.yaml"
14

15
  values_string = {
16
    "server.ha.enabled" = "true"
17
    "server.ha.replicas" = "3"
18
    "server.ha.raft.enabled" = "true"
19
    "ui.enabled" = "true"
20
    "ui.serviceType" = "LoadBalancer"
21
    "server.resources.requests.memory" = "256Mi"
22
    "server.resources.requests.cpu" = "250m"
23
  }
24

25
  retry = 3
26
  timeout = "600s"
27

28
  health_check {
29
    timeout = "300s"
30
    pods = [
31
      "app.kubernetes.io/name=vault",
32
      "component=server"
33
    ]
34
  }
35
}

Chart from Git Repository

1
resource "helm" "git_chart" {
2
  cluster = resource.k8s_cluster.dev
3
  chart = "git+https://github.com/my-org/helm-charts.git//charts/myapp?ref=v1.0.0"
4
  namespace = "development"
5
  create_namespace = true
6

7
  values_string = {
8
    "environment" = "dev"
9
    "debug" = "true"
10
  }
11

12
  health_check {
13
    timeout = "180s"
14
    pods = ["app=myapp"]
15
  }
16
}

Multiple Charts with Dependencies

1
# Database
2
resource "helm" "postgresql" {
3
  cluster = resource.k8s_cluster.app
4
  chart = "postgresql"
5
  version = "12.1.0"
6
  namespace = "database"
7
  create_namespace = true
8

9
  repository {
10
    name = "bitnami"
11
    url = "https://charts.bitnami.com/bitnami"
12
  }
13

14
  values_string = {
15
    "auth.postgresPassword" = "postgres-password"
16
    "auth.database" = "myapp"
17
  }
18

19
  health_check {
20
    timeout = "120s"
21
    pods = ["app.kubernetes.io/name=postgresql"]
22
  }
23
}
24

25
# Redis Cache
26
resource "helm" "redis" {
27
  cluster = resource.k8s_cluster.app
28
  chart = "redis"
29
  version = "17.3.0"
30
  namespace = "cache"
31
  create_namespace = true
32

33
  repository {
34
    name = "bitnami"
35
    url = "https://charts.bitnami.com/bitnami"
36
  }
37

38
  values_string = {
39
    "auth.enabled" = "false"
40
    "master.persistence.enabled" = "true"
41
  }
42

43
  health_check {
44
    timeout = "90s"
45
    pods = ["app.kubernetes.io/name=redis"]
46
  }
47
}
48

49
# Application (depends on database and cache)
50
resource "helm" "myapp" {
51
  depends_on = [
52
    resource.helm.postgresql,
53
    resource.helm.redis
54
  ]
55

56
  cluster = resource.k8s_cluster.app
57
  chart = "./charts/myapp"
58
  namespace = "application"
59
  create_namespace = true
60

61
  values_string = {
62
    "database.host" = "postgresql.database.svc.cluster.local"
63
    "database.name" = "myapp"
64
    "cache.host" = "redis.cache.svc.cluster.local"
65
    "replicas" = "3"
66
  }
67

68
  health_check {
69
    timeout = "180s"
70
    pods = ["app=myapp"]
71
  }
72
}

Values File Examples

Example values.yaml for production

1
replicaCount: 3
2

3
image:
4
  repository: myapp/webapp
5
  tag: "1.2.0"
6
  pullPolicy: Always
7

8
service:
9
  type: LoadBalancer
10
  port: 80
11
  targetPort: 8080
12

13
resources:
14
  limits:
15
    cpu: 500m
16
    memory: 512Mi
17
  requests:
18
    cpu: 250m
19
    memory: 256Mi
20

21
autoscaling:
22
  enabled: true
23
  minReplicas: 3
24
  maxReplicas: 10
25
  targetCPUUtilizationPercentage: 70
26

27
ingress:
28
  enabled: true
29
  className: "nginx"
30
  annotations:
31
    cert-manager.io/cluster-issuer: "letsencrypt-prod"
32
  hosts:
33
    - host: webapp.example.com
34
      paths:
35
        - path: /
36
          pathType: Prefix
37
  tls:
38
    - secretName: webapp-tls
39
      hosts:
40
        - webapp.example.com

Integration with Other Resources

With Service Resources

1
resource "helm" "api" {
2
  cluster = resource.k8s_cluster.app
3
  chart = "api"
4
  namespace = "default"
5

6
  repository {
7
    name = "mycompany"
8
    url = "https://charts.mycompany.com"
9
  }
10
}
11

12
resource "service" "api" {
13
  name = "api"
14
  port = 8080
15

16
  target {
17
    resource = resource.k8s_cluster.app
18
    named_port = "http"
19
    config = {
20
      selector = "app=api"
21
    }
22
  }
23
}

With Ingress Resources

1
resource "ingress" "web" {
2
  port = 80
3

4
  target {
5
    resource = resource.k8s_cluster.app
6
    named_port = "http"
7
    config = {
8
      selector = "app.kubernetes.io/name=webapp"
9
    }
10
  }
11
}

Best Practices

Version Pinning: Always specify chart versions in production environments
Namespace Isolation: Use dedicated namespaces for different applications
Values Management: Store complex values in external YAML files
Health Checks: Configure appropriate health checks for critical applications
Resource Limits: Set CPU and memory limits in chart values
Secrets Management: Use Kubernetes secrets or external secret management
Retry Logic: Enable retries for network-dependent installations
Timeout Configuration: Set appropriate timeouts for complex charts