Helm releases

Kubermeister installs a chart from a configured repository or registry, and reads, upgrades, rolls back and uninstalls Helm releases. A revision the Helm CLI writes shows up here as soon as Helm has written it, and one written here is one the Helm CLI reads.

Both screens have a section of their own in the sidebar, Helm: Releases and Charts.

Where releases come from

Helm has no API of its own. A release is a Secret of type helm.sh/release.v1 whose release field is base64(gzip(json)), base64’d again by the API, with one Secret per revision named sh.helm.release.v1.<name>.v<n>.

Kubermeister decodes those Secrets. That is the whole mechanism, and it is why reading releases needs no Helm binary and no component in the cluster; only installing a chart and upgrading a release use Helm, to render it. A Secret that will not decode, or would decode to more than 32 MiB, is skipped rather than shown half-read. Reading releases needs permission to list Secrets in the namespaces you look at.

Releases

Releases lists one row per release, its highest revision: Name, Namespace, Chart (as name-version), Revision, Status and Updated. It covers the namespace selected in the top bar, or every namespace under All namespaces, and is re-read at the Live data refresh interval.

Status is Helm’s own word, mapped to the app’s:

Helm status	Shown as
deployed	Deployed
superseded	Superseded
failed	Failed
pending-install, pending-upgrade, pending-rollback	Progressing
uninstalling	Terminating
uninstalled, or anything else	Unknown

A release’s detail

Opening a release shows four tabs, starting on Resources.

• Resources: every object the current revision rendered, read live. See a release’s objects.
• Revisions: the Revision history of every revision the cluster still holds, newest first, with Rev, Status, Chart version, Updated and Description (Helm’s own note, such as “Install complete” or “Rollback to 2”).
• Values: the user-supplied values of the current revision, what helm get values prints. A release running on chart defaults alone says so.
• Manifest: the objects the current revision rendered, what helm get manifest prints. It is read-only, because it is history rather than a live object. A manifest longer than 256 KB is cut on a line boundary with a comment saying so; each object’s own Manifest tab has the rest.

Values and manifest are those of the current revision only. For an earlier revision the app shows only its row in the history.

All of it is decoded from the release Secrets Helm itself writes.

A release has no Events tab, because it is not an API object of its own.

A release’s objects

Resources lists the objects in the manifest Helm stored for the current revision, the one Manifest shows, with Kind, Name, Namespace and Status. An object is listed because Helm rendered it, never because its name looks like the release’s. The cluster is asked with one list per kind and namespace, at the apiVersion the manifest names, so custom resources are listed too, and the tab is re-read at the Live data refresh interval while it is open.

Status says what the cluster holds now:

• A kind with a status of its own shows that status as its own list does: a Pod’s Running or CrashLoop, a Deployment’s Healthy or Progressing, and likewise for Jobs, Services, Ingresses, persistent volumes and claims, volume snapshots, disruption budgets, webhook configurations and API services.
• Any other kind, custom resources included, shows Present.
• An object the manifest names and the cluster does not hold shows Missing, as does every object of a kind the cluster no longer serves.
• Unknown means the app was not allowed to list that kind; hovering the badge says so. It is never counted as missing.

An object’s name links to its own screen when the app has one for its kind and the object is there.

The Health card above the table judges the release from those objects rather than from the status Helm recorded, since deployed only says the install went through:

Health	When
Healthy	Every object is present and none is in a warning or failing state.
Degraded	The worst object is in a warning state, such as a Deployment still Progressing.
Failing	An object is missing or failing, such as a Pod in CrashLoop.
Unknown	Nothing is wrong that could be seen, but some objects could not be read.

When the release is not healthy, the card names the worst object as the reason, for example “ConfigMap web-config is Missing”, and how many others need attention.

Rolling back

Every revision except the current one has Roll back. The dialog, “Roll back to revision N?”, says that the objects that revision rendered are applied again and anything it never had is removed.

A rollback then does what Helm does:

1. Applies every object the target revision rendered, creating it if it is missing. Each one carries the label and annotations Helm marks its own objects with, so a later helm uninstall removes it rather than leaving it behind as not owned by the release.
2. Deletes the objects the current revision has and the target never had, except those the chart marked to be kept.
3. Writes a new revision, numbered one above the current, marked deployed and described “Rollback to N”, and marks the old current revision superseded.

A rollback writes each object by server-side apply, as Helm 4 does and as an upgrade does, so it keeps the same things: a field another manager owns and the target revision leaves out stays, such as replicas an autoscaler or kubectl scale set, and a field only Helm set that the target revision does not render is removed. Every object is checked with a server-side dry run first, so a field the target revision would take from another manager refuses the whole rollback, naming the field and its manager, before anything is written.

Helm numbers forward and never rewinds, so a rollback from revision 5 to revision 3 produces revision 6. The toast says which revision is now current and how many objects the chart kept. The point of using Helm’s own Secret names, labels and status words is that a release this app rolls back is still one the Helm CLI can read and act on.

Uninstalling

Uninstall in the release’s header asks “Uninstall release?” and deletes every object the current revision rendered, except those the chart marked to be kept. What happens to the history depends on Keep the release history, which is off by default:

• Off: every revision Secret is deleted, like helm uninstall.
• On: the revisions stay, with the current one marked uninstalled, like helm uninstall --keep-history.

The toast counts the objects removed and kept, and you land back on Releases.

Objects Helm is told to keep

An object annotated helm.sh/resource-policy: keep is never deleted by a rollback or an uninstall, and the app counts them back to you so you know what was left behind.

Installing a chart

Installing takes one version of a chart from a repository or registry added under Settings › Charts and installs it as a new release in the namespace selected in the top bar.

Where to start

There are three ways in:

• Install on a chart’s row under Helm › Charts, which opens the chart’s latest version.
• The Install a chart button (a download arrow) on a repository’s row under Settings › Charts.
• Install a chart… in the command palette (⌘K or Ctrl+K).

The last two open the Install a chart dialog. From the palette it first asks for the Repository; from a repository’s row it already knows it. For a classic repository you pick the chart from the list its index holds, searching by name, and the install screen opens on its latest version. An OCI registry publishes no list of its charts, so you type the Chart name and the Chart version, as helm pull oci://… takes them. Continue opens the install screen. With no repository configured, the dialog says so and links to Settings › Charts.

Helm is required

The chart is rendered by the helm installed on your machine, Helm 3 or later, found on your login shell’s PATH. Kubermeister runs it for helm template and nothing else, with an empty kubeconfig and a Helm home of its own, so it never reaches your cluster, your repositories or your plugins. Every object is then written by Kubermeister itself, under the context you are on, as any other write is. Without Helm, every way in says Helm is required to install a chart, with a link to Helm’s install page, instead of opening a screen that could not render the chart. The dialog’s Check again looks for Helm again, so a Helm installed while Kubermeister runs is found without a restart. Nothing else in the app needs Helm.

The values

The screen, Install chart, asks for three things:

• Release name, which starts as the chart’s name: lowercase letters, digits and dashes, starting and ending with a letter or digit, at most 53 characters.
• Version, from the versions a classic repository’s index lists. An OCI registry lists none, so the version is the one the screen was opened on. Switching the version after editing the values keeps what you changed and takes the new version’s defaults for everything else.
• The values, in an editor that starts from the chart’s own values.yaml. When the chart ships a values.schema.json, the editor marks what it refuses as you type and completes keys and values from it.

The namespace is the one selected in the top bar. Under All namespaces the screen says a chart installs into one namespace and Review stays off until you choose it.

The values start from the chart's own values.yaml.

Helm is handed only what you changed, as helm install -f would take a file of your own values, and reads the chart’s values.yaml itself for the rest. A value you leave as the chart wrote it is therefore read by Helm exactly as helm install reads it: a default written yes is true. A value taken out of the editor keeps the chart’s default; set it to null to remove the default, as Helm does. What you change is read the way the editor checks it, as YAML 1.2, so yes, no, on and off you type are strings; write true and false for booleans. Those changes are what the release records, and what helm get values shows.

The objects the chart renders are read the way Helm and kubectl read them, as YAML 1.1, so a file mode a template writes as 0644 is octal, as in helm install.

The review

Review renders the chart and checks what it rendered, before anything is written:

• A render Helm refuses, such as a required value or one the chart’s schema rejects, is marked on the values it names, in Helm’s own words, and the screen stays on the values.
• A release of the same name already recorded in the namespace is refused, as helm install refuses one.

Otherwise the review lists every object in the order it will be written — Custom resource definitions, Hooks and Objects — each with its YAML one click away and what a server-side dry run said about it:

Check	Meaning
Checked	The API server accepted it.
After its CRD	Its kind comes from a CRD in this chart, so it can only be checked once that CRD is installed.
Already there	A CRD the cluster already has. Helm leaves it as it is, and so does the install.
Refused	The API server refused it, or it already exists. Install stays off.

Charts that call lookup

A template’s lookup finds nothing while a chart is rendered for review, exactly as in helm template, so whatever it would have read from the cluster is missing from the objects. The review says so when a chart calls it.

The install

Install release writes the render you reviewed, not a new one, in the order Helm follows:

1. The CRDs from the chart’s crds/, skipping any already there, each waited on until it is served.
2. The release, recorded as pending-install in the Secret sh.helm.release.v1.<name>.v1.
3. The pre-install hooks, by weight, each waited on: a Job until it completes, a Pod until it succeeds, anything else once it exists.
4. The objects, applied server-side as the field manager helm, as Helm 4 installs them.
5. The post-install hooks, the same way.
6. The release marked deployed.

A hook with no delete policy is deleted before it is created, and the hook-succeeded and hook-failed policies are applied as Helm applies them. Hooks for other events, such as test, are recorded with the release and not run. Each hook may take five minutes, Helm’s own default. The new release then opens on Resources, which shows whether everything came up; the install does not wait for workloads to become ready.

A review is good for one install and for 30 minutes. An install refused before anything is written, because the review expired or a release of the same name was recorded in the meantime, says why and takes you back to the values to review again.

If a step fails once the release is recorded, the release is marked failed, as Helm marks it, and owns what was written before the failure. The screen says why and offers Uninstall and Open release. CRDs are never removed by an uninstall, by Kubermeister or by Helm.

A release installed here is one the Helm CLI reads and acts on: helm list, helm get values, helm get hooks and helm uninstall all work on it.

Upgrading a release

Upgrade in a release’s header opens Upgrade release, which moves the release to a chart version from a repository or registry added under Settings › Charts, in the release’s own namespace. It needs Helm on your machine, as installing does; without it the screen says Helm is required to upgrade a release, and without a configured source it says No chart repository to upgrade from.

The chart and the values

A release does not record where its chart came from, so the screen chooses:

• Source starts as the first classic repository whose index lists a chart of the release’s chart name, or else the first registry. Any configured source can be chosen instead.
• Chart starts as the release’s chart name, and can be changed to upgrade to another chart, as helm upgrade allows.
• Version starts as the newest version the repository lists, with the one the release runs marked (current). An OCI registry lists no versions, so the field starts as the version the release runs and takes the one you type.

The values start from the current revision’s own user-supplied values, what the Values tab shows, and are checked against the chosen version’s schema as you type. What the editor holds is the whole of what the new revision is given, over that version’s defaults: a value taken out of the editor goes back to the chart’s default, as it would with helm upgrade -f and not --reuse-values. A yes you type is a string here too, while the chart’s own values.yaml is read by Helm, where a default written yes is true.

The review

Review renders the chosen version as an upgrade of the release (.Release.IsUpgrade is true) and shows what the upgrade changes before anything is written. A render Helm refuses is marked on the values, as for an install, and a release another operation holds pending (pending-install, pending-upgrade or pending-rollback) or one that was uninstalled is refused. A release uninstalled with its history kept cannot be installed again either, since that history still holds the name: Uninstall it once more with Keep the release history off, then install it.

• Values: the current revision’s values against the new ones, line by line.
• Objects: every object the new revision renders, marked Created, Changed or Unchanged. Opening one shows the object the cluster holds against what it will hold, both as the API server stores them: each is a server-side dry run of the very apply the upgrade sends, so a field the server fills in, or another manager owns, is not a change, and a field only Helm set that the render drops is. An object that is already in the cluster but was neither rendered by the current revision nor marked as belonging to this release is Refused, as Helm refuses to take it over, and so is one where the render would change a field another manager owns: the row names the field and the manager, such as .spec.replicas is managed by "kubectl".
• Removed: what the current revision rendered and the new one does not. Each is Deleted, Already gone, or Kept when the chart annotated it helm.sh/resource-policy: keep.
• Hooks: every hook the new revision renders, with its dry run; the pre-upgrade and post-upgrade ones run.

The chart’s crds/ definitions are left alone, and the review says how many: Helm installs them on install only and never upgrades them. The review flags a chart that calls lookup, as for an install.

The upgrade

Upgrade to revision N writes the render you reviewed, in the order Helm follows:

1. The new revision, numbered one above the newest, recorded as pending-upgrade.
2. The pre-upgrade hooks, by weight, each waited on and deleted as its policy says, as an install’s hooks are.
3. The objects, each applied server-side as the field manager helm, the one the Helm CLI applies as, carrying the label and annotations Helm marks its own objects with. See what an upgrade keeps.
4. The removed objects deleted, except those the chart marked to be kept.
5. The post-upgrade hooks, the same way.
6. The previous revision marked superseded and the new one deployed, described “Upgrade complete”.

The release then opens on Resources; the upgrade does not wait for workloads to become ready. The diff is the cluster as it was when you reviewed; a field another manager takes after the review is a conflict when the upgrade applies, and fails it as below.

A review is good for one upgrade and for 30 minutes, and one made before another revision was recorded is refused, so you review again. If a step fails once the new revision is recorded, it is marked failed with Helm’s description, and the revision before it stays deployed. The screen says why and offers Open release, from whose Revisions tab the release can be rolled back.

What an upgrade keeps

An upgrade writes each object by server-side apply, as Helm 4 does, so the API server decides field by field:

• A field another manager owns and the render leaves out stays as it is: replicas an autoscaler or kubectl scale set when the chart sets none, an annotation a tool added.
• A field only Helm set, which the previous revision rendered and the new one does not, is removed.
• A field the render would change while another manager owns it is a conflict, and Helm’s default is to refuse it rather than take it over. The review marks the object Refused, naming the field and its manager; give the field back, for example by setting it to the value the chart renders, or leave it out of the values.

A release written client-side before, by Helm 3 or by Helm 4 with --server-side=false, has Helm’s ownership moved to server-side apply on each object first, as helm upgrade --server-side does, so Helm’s own earlier writes are never a conflict. The new revision records that it was applied server-side, so a later helm upgrade applies it the same way. A release installed here is applied server-side from the start.

The Helm CLI reads the upgraded release like any other: helm history shows the new revision and the superseded one, and helm get values, helm get hooks and helm uninstall work on it.

Helm charts

Helm › Charts lists the charts you can install: every chart in the index of each classic repository configured under Settings › Charts, one row per repository and chart, with Name, Repository, Latest version, App version and Description, all as the repository’s index gives them. Install on a row opens the install screen on that chart’s latest version.

The list is read from the copy of each index Kubermeister keeps, which is fetched when a repository is added or refreshed, so it does not follow the namespace or the context and makes no request while you browse it. A repository whose index has never been read, such as one written into the settings file by hand, is read the first time the list is opened; if it does not answer, its charts are left out, and its row under Settings › Charts says it was never read.

An OCI registry publishes no index, so its charts are not listed here; install one from its row under Settings › Charts or from the command palette. When there is nothing to list, the screen says why: no repository is configured, only OCI registries are, or the repositories’ indexes hold no charts. Each case points at Settings › Charts.

Chart repositories

Chart repositories can be added, refreshed and removed under Settings › Charts, and they live in app settings rather than in the cluster, so they survive a context switch. The charts of a classic repository are listed under Helm › Charts, and a chart from any of them can be installed, or a release upgraded to one. See settings.