Helm

Defined insandbox.hcl

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

resource "helm" "name" {
  cluster = resource.k8s_cluster.main
  chart = "nginx"

  repository {
    name = "bitnami"
    url = "https://charts.bitnami.com/bitnami"
  }
}

Full Syntax

resource "helm" "name" {
  cluster = resource.k8s_cluster.production

  chart = "vault"
  version = "0.25.0"
  namespace = "vault"
  create_namespace = true

  repository {
    name = "hashicorp"
    url = "https://helm.releases.hashicorp.com"
  }

  values = "./values/vault-values.yaml"
  values_string = {
    "server.ha.enabled" = "true"
    "server.ha.replicas" = "3"
    "ui.enabled" = "true"
  }

  skip_crds = false
  retry = 3
  timeout = "300s"

  health_check {
    timeout = "120s"
    pods = [
      "app.kubernetes.io/name=vault",
      "app.kubernetes.io/instance=vault"
    ]
  }
}

Fields

Field	Type	Required	Description
cluster	referencek8s_cluster	✓	Reference to the Kubernetes cluster to deploy to
repository	block	—	Helm chart repository
chart	string	✓	Chart name within the repository or Go Getter reference
version	string	—	Semver of the chart to install
values	string	—	Path to values YAML file
values_string	map(string)	—	Inline values to pass to the chart
namespace	string	—	Kubernetes namespace to deploy to
create_namespace	bool	—	Create the namespace before installing
skip_crds	bool	—	Skip the install of any CRDs
retry	number	—	Number of times to retry the install
timeout	string	—	Maximum time a chart can run, default 300s ConstraintsMust be a valid duration (e.g. 30s, 5m)
health_check	block	—	Health check for pods deployed by the chart

Repository

helm→Repository

Helm chart repository

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

Health Check

helm→Health Check

Health check for pods deployed by the chart

Field	Type	Required	Description
timeout	string	✓	Timeout for the health check (e.g., '240s') ConstraintsMust be a valid duration (e.g. 30s, 5m)
pods	list(string)	✓	Pod label selectors to check for health

Examples

Simple Chart from Repository

resource "k8s_cluster" "dev" {
  network {
    id = resource.network.main
  }
}

resource "helm" "nginx" {
  cluster = resource.k8s_cluster.dev
  chart = "nginx"

  repository {
    name = "bitnami"
    url = "https://charts.bitnami.com/bitnami"
  }

  values_string = {
    "service.type" = "ClusterIP"
    "replicaCount" = "2"
  }
}

Chart with External Values File

resource "helm" "wordpress" {
  cluster = resource.k8s_cluster.web
  chart = "wordpress"
  version = "15.2.0"
  namespace = "wordpress"
  create_namespace = true

  repository {
    name = "bitnami"
    url = "https://charts.bitnami.com/bitnami"
  }

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

  values_string = {
    "wordpressPassword" = "secure-password"
    "mariadb.auth.rootPassword" = "root-password"
  }

  health_check {
    timeout = "300s"
    pods = ["app.kubernetes.io/name=wordpress"]
  }
}

Local Chart Directory

resource "helm" "custom_app" {
  cluster = resource.k8s_cluster.dev
  chart = "./charts/my-application"
  namespace = "apps"
  create_namespace = true

  values_string = {
    "image.tag" = "latest"
    "service.port" = "8080"
  }

  health_check {
    timeout = "120s"
    pods = ["app=my-application"]
  }
}

High Availability Setup

resource "helm" "vault" {
  cluster = resource.k8s_cluster.production
  chart = "vault"
  version = "0.25.0"
  namespace = "vault-system"
  create_namespace = true

  repository {
    name = "hashicorp"
    url = "https://helm.releases.hashicorp.com"
  }

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

  values_string = {
    "server.ha.enabled" = "true"
    "server.ha.replicas" = "3"
    "server.ha.raft.enabled" = "true"
    "ui.enabled" = "true"
    "ui.serviceType" = "LoadBalancer"
    "server.resources.requests.memory" = "256Mi"
    "server.resources.requests.cpu" = "250m"
  }

  retry = 3
  timeout = "600s"

  health_check {
    timeout = "300s"
    pods = [
      "app.kubernetes.io/name=vault",
      "component=server"
    ]
  }
}

Chart from Git Repository

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

  values_string = {
    "environment" = "dev"
    "debug" = "true"
  }

  health_check {
    timeout = "180s"
    pods = ["app=myapp"]
  }
}

Multiple Charts with Dependencies

# Database
resource "helm" "postgresql" {
  cluster = resource.k8s_cluster.app
  chart = "postgresql"
  version = "12.1.0"
  namespace = "database"
  create_namespace = true

  repository {
    name = "bitnami"
    url = "https://charts.bitnami.com/bitnami"
  }

  values_string = {
    "auth.postgresPassword" = "postgres-password"
    "auth.database" = "myapp"
  }

  health_check {
    timeout = "120s"
    pods = ["app.kubernetes.io/name=postgresql"]
  }
}

# Redis Cache
resource "helm" "redis" {
  cluster = resource.k8s_cluster.app
  chart = "redis"
  version = "17.3.0"
  namespace = "cache"
  create_namespace = true

  repository {
    name = "bitnami"
    url = "https://charts.bitnami.com/bitnami"
  }

  values_string = {
    "auth.enabled" = "false"
    "master.persistence.enabled" = "true"
  }

  health_check {
    timeout = "90s"
    pods = ["app.kubernetes.io/name=redis"]
  }
}

# Application (depends on database and cache)
resource "helm" "myapp" {
  depends_on = [
    resource.helm.postgresql,
    resource.helm.redis
  ]

  cluster = resource.k8s_cluster.app
  chart = "./charts/myapp"
  namespace = "application"
  create_namespace = true

  values_string = {
    "database.host" = "postgresql.database.svc.cluster.local"
    "database.name" = "myapp"
    "cache.host" = "redis.cache.svc.cluster.local"
    "replicas" = "3"
  }

  health_check {
    timeout = "180s"
    pods = ["app=myapp"]
  }
}

Values File Examples

Example values.yaml for production

./values/webapp-production.yaml

replicaCount: 3

image:
  repository: myapp/webapp
  tag: "1.2.0"
  pullPolicy: Always

service:
  type: LoadBalancer
  port: 80
  targetPort: 8080

resources:
  limits:
    cpu: 500m
    memory: 512Mi
  requests:
    cpu: 250m
    memory: 256Mi

autoscaling:
  enabled: true
  minReplicas: 3
  maxReplicas: 10
  targetCPUUtilizationPercentage: 70

ingress:
  enabled: true
  className: "nginx"
  annotations:
    cert-manager.io/cluster-issuer: "letsencrypt-prod"
  hosts:
    - host: webapp.example.com
      paths:
        - path: /
          pathType: Prefix
  tls:
    - secretName: webapp-tls
      hosts:
        - webapp.example.com

Integration with Other Resources

With Service Resources

resource "helm" "api" {
  cluster = resource.k8s_cluster.app
  chart = "api"
  namespace = "default"

  repository {
    name = "mycompany"
    url = "https://charts.mycompany.com"
  }
}

resource "service" "api" {
  name = "api"
  port = 8080

  target {
    resource = resource.k8s_cluster.app
    named_port = "http"
    config = {
      selector = "app=api"
    }
  }
}

With Ingress Resources

resource "ingress" "web" {
  port = 80

  target {
    resource = resource.k8s_cluster.app
    named_port = "http"
    config = {
      selector = "app.kubernetes.io/name=webapp"
    }
  }
}

Best Practices

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