Skip to content
Tutorials Center
My learning

Topics

Lesson 6 of 38 ยท Charts and Releases

Creating a Chart with helm create

Generate a starter chart with helm create, read every generated file, learn the fullname and labels helpers, and trim the scaffold down to what you need.

You rarely write a chart from an empty folder. helm create generates a working starter chart with a Deployment, Service, optional Ingress, autoscaler and service account, plus a _helpers.tpl full of conventions. Reading that scaffold is also the fastest way to learn what a well-formed chart looks like.

Generate and render

Terminal
helm create webapp

This creates the folder webapp/ with the layout from Chart Structure. The generated chart deploys nginx by default, so it works immediately. You can render it without a cluster at all:

Terminal
helm template demo ./webapp
helm lint ./webapp

helm template renders locally and prints YAML. It does not contact the cluster, which makes it safe for experiments and for CI. Use --show-only templates/service.yaml to print a single file.

What the scaffold contains

TEXT
webapp/
โ”œโ”€โ”€ Chart.yaml
โ”œโ”€โ”€ values.yaml
โ”œโ”€โ”€ .helmignore
โ”œโ”€โ”€ charts/
โ””โ”€โ”€ templates/
    โ”œโ”€โ”€ NOTES.txt
    โ”œโ”€โ”€ _helpers.tpl
    โ”œโ”€โ”€ deployment.yaml
    โ”œโ”€โ”€ hpa.yaml
    โ”œโ”€โ”€ ingress.yaml
    โ”œโ”€โ”€ service.yaml
    โ”œโ”€โ”€ serviceaccount.yaml
    โ””โ”€โ”€ tests/test-connection.yaml

The generated values.yaml shows the conventions most charts follow:

YAML
replicaCount: 1

image:
  repository: nginx
  pullPolicy: IfNotPresent
  tag: ""          # defaults to the chart's appVersion

nameOverride: ""
fullnameOverride: ""

serviceAccount:
  create: true
  automount: true
  annotations: {}
  name: ""

service:
  type: ClusterIP
  port: 80

ingress:
  enabled: false
  className: ""
  hosts:
    - host: chart-example.local
      paths:
        - path: /
          pathType: ImplementationSpecific

resources: {}
autoscaling:
  enabled: false
  minReplicas: 1
  maxReplicas: 100
  targetCPUUtilizationPercentage: 80

Notice the patterns: a feature is switched on with an enabled boolean, free-form maps default to {}, and an empty tag falls back to the appVersion. These are habits to copy.

Reading the Deployment template

The core of templates/deployment.yaml looks like this (trimmed):

YAML
apiVersion: apps/v1
kind: Deployment
metadata:
  name: {{ include "webapp.fullname" . }}
  labels:
    {{- include "webapp.labels" . | nindent 4 }}
spec:
  {{- if not .Values.autoscaling.enabled }}
  replicas: {{ .Values.replicaCount }}
  {{- end }}
  selector:
    matchLabels:
      {{- include "webapp.selectorLabels" . | nindent 6 }}
  template:
    metadata:
      labels:
        {{- include "webapp.selectorLabels" . | nindent 8 }}
    spec:
      containers:
        - name: {{ .Chart.Name }}
          image: "{{ .Values.image.repository }}:{{ .Values.image.tag | default .Chart.AppVersion }}"
          ports:
            - name: http
              containerPort: 80

Do not worry about every symbol yet. The Templates and Values chapter explains include, nindent, default and if. What matters now is the idea: names, labels and the image tag come from helpers and values, never hard-coded, so the same template works for any release.

The helpers file

_helpers.tpl defines named templates that every other template reuses. Its most important job is naming. A release called blog with chart webapp should make objects called blog-webapp, so that two releases never collide:

TEXT
fullname = release name + "-" + chart name     (blog-webapp)
           unless the release name already contains the chart name  (webapp-prod -> webapp-prod)
           or fullnameOverride is set
           truncated to 63 characters, no trailing dash

63 characters is the Kubernetes DNS label limit. The next stand-in reimplements this logic so you can try names. The real one is written in Go templates ({{- if contains $name .Release.Name }}...).

Python Stand-in: the fullname helper

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Besides fullname, the scaffold defines webapp.name, webapp.chart (name-version, used in a label), webapp.labels, webapp.selectorLabels and webapp.serviceAccountName. The standard labels follow Kubernetes' recommended set:

YAML
helm.sh/chart: webapp-0.1.0
app.kubernetes.io/name: webapp
app.kubernetes.io/instance: blog
app.kubernetes.io/version: "1.16.0"
app.kubernetes.io/managed-by: Helm

Only name and instance go into the selector. The selector of a Deployment is immutable, so putting a changing label such as the chart version there would make every upgrade fail. The following program builds both label sets and shows why.

Python Stand-in: labels versus selector labels

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Make the scaffold yours

The starter chart is a teaching aid. Real charts usually remove what they do not need:

  1. Delete templates you do not use (hpa.yaml, ingress.yaml) together with their values.
  2. Change the image repository and the containerPort.
  3. Replace the generated test-connection.yaml with a meaningful test (see the Testing chapter).
  4. Edit Chart.yaml: description, appVersion, maintainers.
  5. Run helm lint and helm template after each change.

You can also scaffold from your own starter with helm create mychart --starter my-company-starter; the starter is a chart kept in $HELM_DATA_HOME/starters that applies your company's labels and policies to every new chart.

Keep a ci/ folder of values files (ci/prod-values.yaml, ci/minimal-values.yaml) and render the chart with each one in CI. Many chart bugs only appear for a specific combination of values.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which command renders a chart to YAML locally without contacting the cluster?

    helm template renders client-side only; helm install talks to the cluster.
  2. 2. Why are only name and instance labels used in the selector?

    A changing label such as the chart version in the selector would make upgrades fail.
  3. 3. What does an empty image.tag mean in the generated chart?

    The template uses the default function with .Chart.AppVersion.
  4. 4. Why is the fullname truncated to 63 characters?

    Many Kubernetes names must be valid DNS labels, at most 63 characters.

Summary

  • helm create NAME scaffolds a working nginx chart; helm template and helm lint check it without a cluster.
  • Charts use helpers for names and labels, values for everything configurable, and enabled switches for optional features.
  • Selector labels must stay stable; full labels may include versions.
  • Trim the scaffold to your needs and keep CI values files.

Next: Install, Upgrade and Rollback