ToolHive Operator CRDs Helm Chart

A Helm chart for installing the ToolHive Operator CRDs into Kubernetes.

---

ToolHive Operator CRDs

TL;DR

helm upgrade -i toolhive-operator-crds oci://ghcr.io/stacklok/toolhive/toolhive-operator-crds

Prerequisites

• Kubernetes 1.25+
• Helm 3.10+ minimum, 3.14+ recommended

Usage

Installing from the Chart

Install one of the available versions:

helm upgrade -i <release_name> oci://ghcr.io/stacklok/toolhive/toolhive-operator-crds --version=<version>

Tip: List all releases using helm list

Uninstalling the Chart

To uninstall/delete the toolhive-operator-crds deployment:

helm uninstall <release_name>

Why CRDs in templates/?

Helm does not upgrade CRDs placed in the crds/ directory during helm upgrade operations. This is a known Helm limitation to prevent accidental data loss. As a result, users running helm upgrade would silently have stale CRDs.

To ensure CRDs are upgraded alongside the chart, this chart places CRDs in templates/ with Helm conditionals. This follows the pattern used by several popular projects.

However, placing CRDs in templates/ means they would be deleted when the Helm release is uninstalled, which could result in data loss. To prevent this, CRDs are annotated with helm.sh/resource-policy: keep by default (controlled by crds.keep). This ensures CRDs persist even after uninstalling the chart.

Important: Namespace Consistency

When installing this chart, Helm stamps all CRDs with a meta.helm.sh/release-namespace annotation set to the namespace used at install time. This annotation cannot be changed by subsequent helm upgrade commands targeting a different namespace.

You are free to install this chart in any namespace, but you must use the same namespace consistently for all future upgrades. If you plan to install the operator chart in toolhive-system, install the CRD chart there too:

helm upgrade -i toolhive-operator-crds oci://ghcr.io/stacklok/toolhive/toolhive-operator-crds -n toolhive-system --create-namespace

Migrating from a Different Namespace

If you previously installed the CRD chart without specifying a namespace (defaulting to default) and now want to upgrade using a different namespace, you will see an error like:

Error: invalid ownership metadata; annotation validation error:
key "meta.helm.sh/release-namespace" must equal "toolhive-system": current value is "default"

To fix this, patch the ownership annotations on all CRDs to match your desired namespace:

for crd in $(kubectl get crd -o name | grep toolhive.stacklok.dev); do
  kubectl annotate "$crd" meta.helm.sh/release-namespace=<target-namespace> --overwrite
done

This is a one-time operation. After patching, future upgrades will work as long as the same namespace is used consistently.

Values

Key	Type	Default	Description
crds	object	{"install":true,"keep":true}	CRD installation configuration
crds.install	bool	true	Whether to install the CRDs in this chart
crds.keep	bool	true	Whether to add the "helm.sh/resource-policy: keep" annotation to CRDs When true, CRDs will not be deleted when the Helm release is uninstalled

Contributing

See CONTRIBUTING.md for guidelines on contributing to this chart.