Helm from Beginner to Practical Application: Starting from a Single upgrade Command

Introduction: The Story Behind a Single Command

Imagine a scenario: you are maintaining a Kubernetes cluster, and you need to ... the Web service Nginx Upgrade to the new version. You executed the following command:

helm upgrade my-nginx ./nginx-chart --set image.tag=1.25.3 -n web

This command is concise and powerful, but what exactly happens behind it?my-nginx What is it?./nginx-chart Where does this path lead?-n web What else does it represent?

This article will use this as a starting point to take you deep into the world of Helm, from basic concepts to advanced techniques, helping you become a package management expert on Kubernetes.

Part One: Getting to Know Helm — K8s's "App Store"

What is Helm?

Helm is Kubernetes's package manager. Its function is similar to that of Ubuntu's apt or Golang's module, used to simplify the deployment, upgrade, and rollback of Kubernetes applications.

In Kubernetes, deploying a complex application usually requires writing multiple YAML files (Deployment, Service, ConfigMap, Ingress...). Helm, through Package a set of YAML files into a Chart, enabling standardized distribution of applications.

Core concepts of Helm

To understand that command, you must first master the following three core concepts:

• Chart (package): A Helm package that contains all resource definitions required to run an application. For example, an Nginx Chart includes Deployment, Service, ConfigMap, and Ingress.

• Repository (repository) A place to store and share Charts, similar to Docker Hub.

• Release (Release): An instance of Chart running in a Kubernetes cluster.my-nginx It is the Release name in our command..

Key components: Where did Tiller go? (v3 changes)

If you have read the old tutorial, it will mention Tiller (the server-side component). But in Helm v3 In, Tiller has been removed!

• v2: The client (Client) interacts with Tiller in the cluster via gRPC.

• v3: The client interacts directly with the Kubernetes API Server, and release information is stored in etcd as Secrets. This greatly improves security and simplicity.

Part Two: Cracking helm upgrade The Mystery of Commands

Let us helm upgrade my-nginx ./nginx-chart --set image.tag=1.25.3 -n web Cut into eight pieces:

Parameters/Options	value	含义解释
Command	upgrade	If Release does not exist, then Install, if it already exists, then upgrade. This is the most commonly used command.
Release name	my-nginx	This is the name you gave to the deployment. Future updates, rollbacks, or deletions will rely on it for identification.
Chart path	./nginx-chart	This is Chart itself.Attention: What is used here is local path, rather than the repository name. This indicates that you are developing or using a locally modified Chart.
Configuration parameters	--set image.tag=1.25.3	Dynamically override via the command line values.yaml the image version in it, allowing the version upgrade to be completed without modifying files.
namespace	-n web	Specified Release deployed at web Under the namespace. If not specified, it defaults to default.

What did Helm do when executing this command?

• Read ./nginx-chart under the directory Chart.yaml and template files.

• According to values.yaml and --set image.tag=1.25.3 Merge render template.

• In the comparison cluster my-nginx differences between the old version and the current new version.

• Generate a Patch for a Kubernetes resource object and send it to the API Server.

• Update the Release status and save this revision record (Revision) as a Secret.

Part 3: Quick Reference for Common Helm Commands (with Scenarios)

Based on the above logic, let's summarize the most commonly used commands in daily work:

1. Add repository and search

# Add the Bitnami repository (including the Nginx Chart)
helm repo add bitnami https://charts.bitnami.com/bitnami

# Add the official Nginx repository
helm repo add nginx-stable https://helm.nginx.com/stable

# Update repository index
helm repo update

# Search Nginx-related Chart
helm search repo nginx

2. Install (Install)

# Install Nginx from the repository
helm install my-nginx bitnami/nginx -n web

# Install from local directory (commonly used for debugging)
helm install my-nginx ./nginx-chart -f custom-values.yaml

# Specify the version during installation
helm install my-nginx bitnami/nginx --version 15.0.0 -n web

3. Upgrade and Rollback (Upgrade & Rollback)

# Upgrade the Nginx image version (corresponding to the opening command)
helm upgrade my-nginx ./nginx-chart --set image.tag=1.25.3

# Use the new values file when upgrading.
helm upgrade my-nginx bitnami/nginx -f production-values.yaml

# View version history
helm history my-nginx -n web

# Roll back to version 2
helm rollback my-nginx 2

4. Uninstall (Uninstall)

# Uninstall Release
helm uninstall my-nginx

# Uninstall and keep history (for easy restoration)
helm uninstall my-nginx --keep-history

5. Debugging and Rendering (Debug)

This is the most practical debugging technique; after executing it will not actually be deployed:

# Render the template and output to the screen
helm template my-nginx ./nginx-chart --debug

# Simulate the installation process (connect to the cluster for verification)
helm install my-nginx ./nginx-chart --dry-run --debug

# View the complete rendered YAML (including the merged values)
helm template my-nginx ./nginx-chart --debug --set image.tag=1.25.3

Part Four: In-Depth Anatomy of the Chart Structure

When you see ./nginx-chart At this time, a standard Chart directory structure is as follows (using Nginx as an example):

nginx-chart/
├── Chart.yaml          # Required: Chart metadata (name, version, description)
│                       # Example: name: nginx, version: 15.0.0, appVersion: 1.25.3
├── values.yaml         # Required: default configuration value
│                       # Includes: image.tag, service.type, ingress.enabled, etc.
├── charts/             # Optional: Subchart (dependencies)
├── templates/          # Required: K8s YAML template
│   ├── deployment.yaml
│   ├── service.yaml
│   ├── ingress.yaml
│   ├── configmap.yaml
│   ├── _helpers.tpl   # Template function definition (starts with an underscore)
│   └── NOTES.txt      # Prompt message displayed after installation
└── crds/               # Optional: Custom Resource Definition

values.yaml and --set priority of:

• Default values.yaml(minimum)

• Father Chart's values.yaml

• command line --set or --set-file

• command line -f The specified file (maximum)

Best practices: For complex projects, it is recommended to use -f production.yaml Differentiate environments and use sparingly.--set Stacking parameters. For example, in Nginx production environments, it is recommended to use -f production.yaml Covers replica count, resource limits, and Ingress configuration.

Part Five: Advanced Practice — Take Your Helm Skills to the Next Level

1. Lifecycle Hooks (Hooks)

Helm allows you to execute Jobs or Pods at specific moments during Release installation/upgrade/deletion. It is commonly used for scenarios such as configuration warm-up and cache cleanup.

The following example runs a configuration validation Job before upgrading Nginx:

apiVersion: batch/v1
kind: Job
metadata:
  name: nginx-config-test
  annotations:
    "helm.sh/hook": pre-upgrade          # Execute before upgrading
    "helm.sh/hook-weight": "5"           # The smaller the weight, the earlier it executes.
    "helm.sh/hook-delete-policy": hook-succeeded # Delete the Job after success
spec:
  template:
    spec:
      containers:
      - name: config-test
        image: nginx:1.25.3
        command: ["nginx", "-t"]
        volumeMounts:
        - name: config
          mountPath: /etc/nginx/nginx.conf
          subPath: nginx.conf
      volumes:
      - name: config
        configMap:
          name: nginx-config
      restartPolicy: Never

2. Dependency Management (Dependencies)

At Chart.yaml declare dependencies in ..., similar to requirements.txt. For example, Nginx relies on Redis as a cache backend:

dependencies:
  - name: redis
    version: "18.x.x"
    repository: "https://charts.bitnami.com/bitnami"
    condition: redis.enabled  # Can be toggled via values
    alias: cache              # Alias, avoid conflicts

Automatically handle dependencies during installation:

helm dependency update ./nginx-chart

3. Use the Lookup function to implement idempotency

Helm v3 introduced lookup function, allowing templates to query existing resources in the cluster. This solves a pain point:Avoid conflicts caused by duplicate resource creation.

{{ if not (lookup "v1" "ConfigMap" .Release.Namespace "nginx-config") }}
# If the ConfigMap does not exist, create it.
apiVersion: v1
kind: ConfigMap
metadata:
  name: nginx-config
data:
  nginx.conf: |
    {{ .Values.nginxConfig | indent 4 }}
{{ end }}

4. Validate using Values (Schema)

Helm v3 supports via values.schema.json Validate values against JSON Schema to intercept invalid configurations before installation:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "image": {
      "type": "object",
      "properties": {
        "tag": { "type": "string", "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+$" }
      }
    },
    "replicaCount": {
      "type": "integer",
      "minimum": 1,
      "maximum": 10
    }
  },
  "required": ["image", "replicaCount"]
}

Part 6: Pitfall Avoidance Guide and Best Practices

• Do not hardcode Namespace in the template: Use .Release.Namespace Variable, in conjunction with -n Dynamic parameter specification.

• Manage CRDs with caution: Helm will not upgrade CRDs (unless in crds/ catalog). Changes to CRDs usually require manual handling or use helm upgrade --force(Use with caution).

• Storage space considerations: Each upgrade generates a new Secret (recording the Revision). By default, 10 are retained, and this can be modified.--history-max.

• Use an OCI repository Modern Helm supports pushing Charts to Harbor or Docker Registry (OCI format):

helm package ./nginx-chart
helm push nginx-chart-15.0.0.tgz oci://registry.company.com/charts

• Sensitive Information Management: Avoid storing passwords in plaintext in values; prefer using Kubernetes Secret or external key management tools (such as Vault).

• Version locking: For production environments, it is recommended to lock the Chart version and App version to avoid accidental upgrades breaking compatibility:

helm install my-nginx bitnami/nginx --version 15.0.0 --set image.tag=1.25.3

Conclusion: From Commands to Productivity

Back to the command at the beginning:

helm upgrade my-nginx ./nginx-chart --set image.tag=1.25.3 -n web

Now you already know: this is in web namespace Below, use the local directory../nginx-chart The Chart in , will be named my-nginx Nginx Release Upgrade to 1.25.3 Version.

Helm's strength lies in abstracting complex YAML orchestration into simple commands and version management. Once you master it, you have a powerful tool for managing large-scale delivery of cloud-native applications.

Recommended related resources:

• Helm official documentation

• Helm Template Function Manual

• Artifact Hub—— Massive Helm Chart Hub

• Bitnami Nginx Helm Chart

• Helm plugin: helm-unittest—— A Go-style unit testing framework, suitable for Chart developers