Helm Subcharts: Composing Applications from Dependencies

WHY IT EXISTS: To manage complex applications composed of multiple, independently developed services. Instead of copying and pasting templates for common dependencies like databases, you can treat them as modular, versioned components called subcharts, simplifying packaging and deployment.

THE MENTAL MODEL: A Helm subchart is like a function call with parameters. The parent chart "calls" the subchart and passes "arguments" by overriding its default values. The subchart itself is a black box; it's a complete, stand-alone chart that doesn't know or care that it's being used as a dependency.

HOW IT WORKS: You place a dependency chart inside the charts/ directory of your parent chart. The parent chart's values.yaml can then define a configuration block with the same name as the subchart's directory. For example, to configure a subchart in the postgresql/ directory, you add a postgresql: key to the parent's values.yaml. Helm then merges these values into the subchart's own .Values object during rendering. From the subchart's template perspective, it's just reading from its own .Values, unaware of the override.

WHEN TO USE IT: Use subcharts to bundle your application with its dependencies. A classic case is an application chart that includes a PostgreSQL or Redis chart as a subchart. This creates a single, deployable unit for the entire application stack. It's also useful for breaking a large, monolithic chart into smaller, logical components.

WHEN NOT TO USE IT: Avoid subcharts if you need the child to be aware of the parent's full configuration. The data flow is strictly one-way: parent to child. If a child chart needs to dynamically change its behavior based on a sibling chart or the parent's complete value set, this model breaks down. In such cases, you might need a different deployment strategy or use 'global' values sparingly.

ONE CANONICAL EXAMPLE: A parent chart my-app needs a database. You add the official postgresql chart into my-app/charts/. In the parent's values.yaml, you configure the database by adding a top-level key named postgresql. Inside this key, you set values like auth.username: myuser and auth.password: "secretpassword". When you install my-app, Helm passes this auth block to the postgresql subchart, overriding its defaults. The subchart's templates still just reference .Values.auth.username, unaware they are being controlled by a parent.