> For the complete documentation index, see [llms.txt](https://dinush-chathurya.gitbook.io/kustomize-e-book/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://dinush-chathurya.gitbook.io/kustomize-e-book/advanced-kustomize-concepts/08-helm-combination.md).

# Helm Combination

Combining Helm and Kustomize lets you package complex applications with Helm’s rich templating and then layer environment-specific customizations with Kustomize. This hybrid approach is ideal for production-grade, GitOps-driven workflows.

***

## Why Combine Helm & Kustomize?

* **Helm** packages and templatizes applications (e.g., Prometheus, Grafana) into reusable charts.
* **Kustomize** applies declarative overlays and patches to raw YAML without touching underlying templates.
* Together, you can **reuse** upstream charts while **customizing** them per environment.

***

## Folder Structure

```plaintext
kustomize/
├── base/
│   ├── kustomization.yaml        # declares Helm chart
│   └── nginx-values.yaml         # base values file
└── overlays/
    ├── dev/
    │   ├── kustomization.yaml    # references base + patches
    │   └── patches/
    │       └── nginx-image.yaml
    ├── staging/
    │   ├── kustomization.yaml
    │   └── patches/
    │       └── nginx-replicas.yaml
    └── prod/
        ├── kustomization.yaml
        └── patches/
            └── nginx-resources.yaml
```

## Define Helm Chart in Base

In `base/kustomization.yaml`, use the HelmChartInflationGenerator:

```yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization

helmCharts:
  - name: nginx
    releaseName: nginx
    repo: https://charts.bitnami.com/bitnami
    version: 15.5.2
    valuesFile: nginx-values.yaml

resources:
  - service.yaml   # any additional non-Helm resources
```

Create `base/nginx-values.yaml`:

```yaml
replicaCount: 3
image:
  tag: latest
resources:
  limits:
    cpu: 100m
    memory: 128Mi
```

## Overlay Customizations

### Dev Overlay

`overlays/dev/kustomization.yaml`

```yaml
resources:
  - ../../base

patchesStrategicMerge:
  - patches/nginx-image.yaml
```

`overlays/dev/patches/nginx-image.yaml`

```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx
spec:
  template:
    spec:
      containers:
        - name: nginx
          image: nginx:dev
```

### Staging Overlay

`overlays/staging/kustomization.yaml`

```yaml
resources:
  - ../../base

patchesStrategicMerge:
  - patches/nginx-replicas.yaml
```

`overlays/staging/patches/nginx-replicas.yaml`

```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx
spec:
  replicas: 5
```

### Prod Overlay

`overlays/prod/kustomization.yaml`

```yaml
resources:
  - ../../base

patchesStrategicMerge:
  - patches/nginx-resources.yaml
```

`overlays/prod/patches/nginx-resources.yaml`

```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx
spec:
  template:
    spec:
      containers:
        - name: nginx
          resources:
            limits:
              cpu: 500m
              memory: 512Mi
            requests:
              cpu: 250m
              memory: 256Mi
```

## Best Practices

* Pin chart versions in `base/kustomization.yaml` to ensure reproducibility.
* Avoid editing Helm chart templates—always overlay via Kustomize patches.
* Keep base `values.yaml` minimal; push environment overrides into overlays for clarity.
* Name patch files descriptively (e.g., `nginx-image.yaml`, `nginx-replicas.yaml`).

## Running the Combined Flow

Deploy an environment with:

```bash
kubectl apply -k overlays/dev
```

Preview changes with:

```bash
kubectl kustomize overlays/prod | kubectl diff -f -
```

## Summary

By inflating Helm charts in your base and applying Kustomize overlays per environment, you maintain a clean separation between packaged application logic and environment-specific configurations—ideal for large teams, CI/CD pipelines, and GitOps workflows.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://dinush-chathurya.gitbook.io/kustomize-e-book/advanced-kustomize-concepts/08-helm-combination.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.