Skip to content

docs: add example of patching a helm chart #4840

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
bburky wants to merge 2 commits into
base: main
Choose a base branch
from
Open

docs: add example of patching a helm chart #4840

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
3f3f0cf
Add example of patching a helm chart
bburky Apr 20, 2026
a0a50a3
Apply suggestion from @bburky
bburky Apr 20, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions examples/helm-charts/.gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
podinfo/
25 changes: 25 additions & 0 deletions examples/helm-charts/0001-example-patch.patch
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
From 6a7f74a9717d63033810d0ca3fa96fb8c41f5323 Mon Sep 17 00:00:00 2001
From: Blake Burkhart <blake@defenseunicorns.com>
Date: Mon, 20 Apr 2026 12:13:53 -0500
Subject: [PATCH] example patch

---
charts/podinfo/templates/deployment.yaml | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/charts/podinfo/templates/deployment.yaml b/charts/podinfo/templates/deployment.yaml
index 87ed373..4385fb8 100644
--- a/charts/podinfo/templates/deployment.yaml
+++ b/charts/podinfo/templates/deployment.yaml
@@ -31,7 +31,7 @@ spec:
serviceAccountName: {{ template "podinfo.serviceAccountName" . }}
{{- end }}
containers:
- - name: {{ .Chart.Name }}
+ - name: {{ .Chart.Name }}-patched
image: "{{ .Values.image.repository }}:{{ .Values.image.tag }}"
imagePullPolicy: {{ .Values.image.pullPolicy }}
{{- if .Values.securityContext }}
--
2.50.1 (Apple Git-155)

6 changes: 5 additions & 1 deletion examples/helm-charts/readme.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1 +1,5 @@
This example shows the many ways you can deploy Helm Charts with Zarf. To learn more about how `charts` work in Zarf, see the [Helm Charts section](/ref/components/#helm-charts) of the package components documentation.
This example shows the many ways you can deploy Helm Charts with Zarf. To learn more about how `charts` work in Zarf, see the [Helm Charts section](/ref/components/#helm-charts) of the package components documentation.

To customize Helm charts you should utilize Helm value overrides or consider upstreaming any required modifications to Helm charts. But if these options are insufficient, you may need to make custom modifications to a Helm chart. Typically, you might fork the upstream Helm chart's git repository and periodically rebase or merge in new upstream changes.

The `demo-patched-helm-chart` component an alternative method using a [Zarf `onCreate` action](/ref/actions/), which performs a `git clone` of the upstream git repository and applies patch files with `git am`. This is conceptually equivalent to rebasing a set of changes onto the upstream repository, and is a useful technique to apply some minor changes to an upstream repository. If more complexity is required, or if you need to make changes to the patches frequently, maintaining a fork of the upstream repository may be more appropriate. To create patches, clone the upstream repository, commit your changes locally and use [`git format-patch`](https://git-scm.com/docs/git-format-patch) to generate patches.
28 changes: 28 additions & 0 deletions examples/helm-charts/zarf.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -55,10 +55,38 @@ components:
releaseName: cool-release-name
valuesFiles:
- values.yaml

images:
- ghcr.io/stefanprodan/podinfo:6.4.0
# This is the cosign signature for the podinfo image for image signature verification
- ghcr.io/stefanprodan/podinfo:sha256-57a654ace69ec02ba8973093b6a786faa15640575fbf0dbb603db55aca2ccec8.sig

- name: demo-patched-helm-chart

@brandtkeller brandtkeller Apr 22, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Existing tests that attempt to run zarf dev find-images on this package will now fail because the localPath doesn't exist until the action runs.

We'll need to make a decision here around this being solely documentation or looking at the behaviors/testing for updates.

required: true
images:
- ghcr.io/stefanprodan/podinfo:6.4.0
- ghcr.io/stefanprodan/podinfo:sha256-57a654ace69ec02ba8973093b6a786faa15640575fbf0dbb603db55aca2ccec8.sig
charts:
- name: podinfo-patched
version: 6.4.0
namespace: podinfo-from-git-patched
# In this case `localPath` will load the local podinfo chart which is created by the `onCreate` action
localPath: podinfo/charts/podinfo
valuesFiles:
- values.yaml
# git clone podinfo/ for podinfo-patched chart and apply patches (typically created with `git format-patch`)
# This is a simple method to apply modifications to a Helm chart that is not under your control, if value overrides are not sufficient
actions:
onCreate:
before:

@brandtkeller brandtkeller Apr 20, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What are your thoughts on cleaning up the cloned repository? Could we have an after action for cleaning up? It removes some of the step-by-step subtlety but I also don't want an (even an ignored) directory remaining behind if possible.

@bburky bburky Apr 20, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If you get an error during the onCreate before action, I think the after action would be skipped. This action is expected to fail if the patches fail to apply cleanly (which may happen when bumping the git tag and the user would need to examine the repo and see what has changed).

uds-k3d does an rm in their onDeploy after, I've seen it litter my current directory with files when deploy fails. This rm never gets run on error.

For onCreate, a gitignore is pretty easy and should work well. But I can add an rm in to after if you'd like.

Because the after can be skipped, it is not possible to remove the first rm command currently present in the before

@brandtkeller brandtkeller Apr 21, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

agree with the semantics around errors. I was thinking merely for testing that we have cleanup as that example is used in our testing.

We are seeing the side-effect of that in the tests though - where we can't run a find images on the manifest as Zarf hasn't performed the clone yet and as such the local path doesn't exist for templating the chart....

- cmd: |
# Clone and apply patches to git repo
rm -rf podinfo
git clone -b 6.4.0 --depth 1 -c advice.detachedHead=false https://github.com/stefanprodan/podinfo.git
cd podinfo
export GIT_COMMITTER_NAME="zarf"
export GIT_COMMITTER_EMAIL="zarf@invalid"
git am --3way ../*.patch # will error if the patch does not apply cleanly

@bburky bburky Apr 21, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Anyways, if you'd like an rm in after, you can apply this GitHub suggestion

Suggested change
after:
- cmd: rm -rf podinfo

I tested locally.

documentation:
readme: readme.md
Loading