Skip to content
Tutorials Center
My learning

Topics

Lesson 37 of 38 ยท Projects and Practice

Project: An Umbrella Chart for a Shop

Compose several services and infrastructure into one umbrella chart with dependencies, conditions, globals, import-values and environment layering, with a resolver stand-in.

Microservice systems raise a question: do you install ten charts separately, or ship them together? An umbrella chart is a parent chart that contains almost no templates of its own and lists other charts as dependencies. Installing it deploys the whole stack as one release with one version. In this project you build an umbrella chart for an online shop with four services and optional infrastructure.

The system

flowchart TB
    U["shop-stack<br/>(umbrella)"] --> W["web"]
    U --> A["orders-api"]
    U --> P["payments"]
    U --> S["search-worker"]
    U -.optional.-> DB[("postgresql")]
    U -.optional.-> R[("redis")]
    A --> DB
    P --> DB
    W --> A
    S --> R

Solid lines are always deployed; dotted infrastructure is switched on only where there is no managed service.

Chart.yaml

YAML
apiVersion: v2
name: shop-stack
description: Online shop: web, orders, payments, search
type: application
version: 1.2.0
appVersion: "2026.03"
dependencies:
  - name: web
    version: "~0.5.0"
    repository: "oci://ghcr.io/my-org/charts"
  - name: orders-api
    version: "~0.7.0"
    repository: "oci://ghcr.io/my-org/charts"
  - name: payments
    version: "~0.3.0"
    repository: "oci://ghcr.io/my-org/charts"
    condition: payments.enabled
  - name: search-worker
    version: "~0.2.0"
    repository: "oci://ghcr.io/my-org/charts"
    tags: [search]
  - name: postgresql
    version: "^16.0.0"
    repository: "oci://registry-1.docker.io/bitnamicharts"
    condition: postgresql.enabled
  - name: redis
    version: "~20.1.0"
    repository: "oci://registry-1.docker.io/bitnamicharts"
    condition: redis.enabled
    tags: [search]

Run helm dependency update once and commit Chart.lock. Everyone, and CI, then uses helm dependency build as in chart dependencies. Each service is its own chart with its own repository and release cadence; the umbrella pins compatible versions together, which is exactly what you want to test and promote as a unit.

Values: global, per-service and infrastructure

YAML
# values.yaml of the umbrella
global:
  environment: dev
  imageRegistry: registry.example.com
  databaseHost: shop-stack-postgresql

tags:
  search: true

postgresql:
  enabled: true
  auth:
    database: shop
    existingSecret: shop-db-credentials
redis:
  enabled: true
  architecture: standalone

web:
  replicaCount: 2
  ingress: { enabled: true, host: shop.example.com }
orders-api:
  replicaCount: 2
payments:
  enabled: true
  replicaCount: 2
search-worker:
  replicaCount: 1

Two global values do the cross-cutting work. Each service builds its image path from .Values.global.imageRegistry and finds the database with .Values.global.databaseHost; subcharts cannot read the umbrella's other values, so anything shared must be global, as explained in subchart values.

For production the managed database replaces the in-cluster one:

YAML
# envs/values-prod.yaml
global:
  environment: prod
  databaseHost: shop-prod.cluster-abc.eu-central-1.rds.example.com
postgresql: { enabled: false }
redis: { enabled: false }
orders-api: { replicaCount: 6 }
payments: { replicaCount: 4 }
Terminal
helm upgrade --install shop ./shop-stack -n shop -f envs/values-prod.yaml --atomic --wait

Resolving what is enabled

Before you install, you want to know exactly which services a given values file will deploy. The stand-in below applies the condition and tags rules to the dependency list above, so you can compare dev and prod.

Python Stand-in: which dependencies are installed in each environment?

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.

Notice the last case: redis has both a condition and a tag. Its condition resolves to true, so it stays on even though tags.search is false, because a resolved condition wins. If you want search to take Redis with it, remove the condition or set redis.enabled=false as well.

Merging values per service

The umbrella only sets what differs from each subchart's defaults. The stand-in below layers three sources for one service the way Helm does: subchart defaults, umbrella values, then the environment file.

Python Stand-in: layered values for the orders-api subchart

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.

Release engineering for an umbrella

  • Version the umbrella (1.2.0), and bump it whenever any dependency range's resolved version changes, since the lock file changed. appVersion can carry the system's date or release train.
  • Promote the umbrella, not the pieces. What passed staging is exactly what goes to production: same Chart.lock, same version, different values file.
  • Test the whole. Install the umbrella in a kind cluster with ci/*-values.yaml, run helm test (each subchart can ship its own tests), and add one end-to-end test at the umbrella level.
  • Mind the 1 MB release limit. Ten services render a large manifest; check with helm get manifest shop | wc -c and split into several umbrellas if you approach it.
  • Upgrade ordering. Dependencies render together, so Kubernetes applies them in one pass. If orders must wait for a database migration, use hooks inside the service chart, not ordering between subcharts.
  • Blast radius. One release means one helm rollback rolls back everything. For services that deploy independently many times a day, prefer separate releases and use the umbrella only for infrastructure and the stable core.

Umbrella charts are a convenience, not a law. Teams with fast, independent services often settle on one release per service, deployed by GitOps, plus a small umbrella (or ApplicationSet) that lists them.

Exercises

  1. Add a notifications service behind notifications.enabled, off in dev and on in prod.
  2. Add import-values so the umbrella reads the PostgreSQL service port instead of hard-coding it.
  3. Write a unit test that renders the umbrella with payments.enabled=false and asserts there is no payments Deployment.
  4. Add a values.schema.json at the umbrella root that allows the subchart keys and global, and rejects environmnt typos inside global.

Check your understanding

Quick check ยท 3 questions

of 3 answered You scored / 3 ยท perfect!

  1. 1. How can a subchart learn the database host set once for the whole stack?

    Subcharts only see their own section plus global.
  2. 2. Which should you promote between environments?

    Promoting the tested artifact with its lock keeps environments identical except for values.
  3. 3. What is a downside of one umbrella release for many services?

    Release-wide operations have a big blast radius, so consider the deployment independence you need.

Summary

  • An umbrella chart lists services and infrastructure as dependencies, switched with condition and tags.
  • Shared settings travel by global; each service gets its own values section.
  • Promote the whole tested umbrella (with Chart.lock) and vary only values per environment.
  • Weigh the convenience against the blast radius of one big release.

Next: Helm Practice: Exercises, Checklists and Interview Questions