- Kubernetes >= 1.34
- Helm 3
The operator chart includes the CRDs as a
dependency. CRDs are
installed in a sub-chart (instead of the crds/ directory) so that
helm upgrade can update them.
Install from the OCI registry:
helm install bootc-operator oci://ghcr.io/bootc-dev/bootc-operator/charts/bootc-operator \
--create-namespace --namespace bootc-operatorTo install a specific version:
helm install bootc-operator oci://ghcr.io/bootc-dev/bootc-operator/charts/bootc-operator \
--version 0.1.0 --create-namespace --namespace bootc-operatorAlternatively, generate and install the chart from a local checkout:
make helm
helm dependency build ./chart/bootc-operator
helm install bootc-operator ./chart/bootc-operator \
--create-namespace --namespace bootc-operatorThe chart installs the configuration CRD and the operator's read permissions.
It does not create a BootcOperatorConfig instance. See
Configuring the operator to add one.
By default the chart uses the image
ghcr.io/bootc-dev/bootc-operator:<appVersion> where appVersion is
defined in Chart.yaml.
For custom settings on first startup, install the CRDs and operator as separate Helm releases. This procedure is for a fresh installation; do not use it to transfer CRDs from an existing combined release.
-
Install the CRDs. Replace
X.Y.Zwith a published chart version containingBootcOperatorConfig, and use that version for both charts:CHART_VERSION=X.Y.Z helm install bootc-operator-crds \ oci://ghcr.io/bootc-dev/bootc-operator/charts/bootc-operator-crds \ --version "$CHART_VERSION" --create-namespace --namespace bootc-operator kubectl wait --for=condition=Established \ crd/bootcoperatorconfigs.node.bootc.dev --timeout=1m
-
Check for an existing configuration. If one exists, edit it instead of creating another. Otherwise, prepare an
operator-config.yamlusing the configuration example, set the desired values, and apply it:kubectl get bootcoperatorconfigs kubectl apply -f operator-config.yaml
-
Install the operator with its CRD dependency disabled, since the separate release already owns the CRDs:
helm install bootc-operator \ oci://ghcr.io/bootc-dev/bootc-operator/charts/bootc-operator \ --version "$CHART_VERSION" --namespace bootc-operator --set crds.install=false
The controller and daemon read the configuration on their first startup. Later configuration edits still require restarting the affected workloads. If the CR allows extra pull-secret namespaces, provision their namespaced permissions before installing the operator.
Override the repository and tag to use a different image:
helm install bootc-operator ./chart/bootc-operator \
--create-namespace --namespace bootc-operator \
--set image.repository=my-registry.example.com/bootc-operator \
--set image.tag=v0.2.0The chart does not set imagePullPolicy by default, so Kubernetes uses
its own rules (Always for :latest, IfNotPresent otherwise). To
override it:
helm install bootc-operator ./chart/bootc-operator \
--create-namespace --namespace bootc-operator \
--set image.pullPolicy=AlwaysIf your registry requires authentication, create the secret first, then pass it to the chart. The secret must be in the same namespace as the release:
kubectl create namespace bootc-operator
kubectl create secret docker-registry my-pull-secret \
--namespace bootc-operator \
--docker-server=my-registry.example.com \
--docker-username=user \
--docker-password=pass
helm install bootc-operator ./chart/bootc-operator \
--namespace bootc-operator \
--set image.repository=my-registry.example.com/bootc-operator \
--set image.tag=v0.2.0 \
--set image.pullPolicy=Always \
--set-json 'imagePullSecrets=[{"name":"my-pull-secret"}]'Alternatively, create the secret from an existing pull secret file:
kubectl create secret generic my-pull-secret \
--namespace bootc-operator \
--from-file=.dockerconfigjson=$HOME/.docker/config.json \
--type=kubernetes.io/dockerconfigjsonpullSecretNamespaces configures extra namespaces for pool pullSecretRef
references. This is separate from imagePullSecrets, which authenticates pulling
the operator's own image. The release namespace is always allowed.
Configure the namespace list and its permissions as follows:
- Helm: set
pullSecretNamespacesto existing namespace names. Helm creates their Secret permissions and supplies a CLI value used when the CR field is omitted. - BootcOperatorConfig: its namespace list takes precedence over the Helm CLI value. Grant access to every namespace in that list, either through matching Helm values or the RBAC example. The CR does not create or remove permissions.
For Helm-managed access:
helm upgrade --install bootc-operator ./chart/bootc-operator \
--namespace bootc-operator \
--set-json 'pullSecretNamespaces=["team-a","team-b"]'See precedence for CR overrides and CLI fallback, including restricting access to the operator namespace.
helm upgrade bootc-operator oci://ghcr.io/bootc-dev/bootc-operator/charts/bootc-operator \
--version <version> --namespace bootc-operatorReplace <version> with the chart version (e.g. 0.2.0). The CRD
sub-chart is upgraded automatically.
If you installed CRDs separately, upgrade their release first, then upgrade the
operator with --set crds.install=false. Use the same target chart version for
both commands:
helm upgrade bootc-operator-crds oci://ghcr.io/bootc-dev/bootc-operator/charts/bootc-operator-crds \
--version <version> --namespace bootc-operator
helm upgrade bootc-operator oci://ghcr.io/bootc-dev/bootc-operator/charts/bootc-operator \
--version <version> --namespace bootc-operator --set crds.install=falsehelm uninstall bootc-operator --namespace bootc-operatorWarning: uninstalling the chart also removes the CRDs and all their instances cluster-wide, including administrator-owned
BootcOperatorConfigsettings. This applies when the CRD dependency is enabled (the default). With separate releases, uninstalling onlybootc-operatorpreserves the CRDs and configuration. Uninstallingbootc-operator-crdsdeletes the CRDs and all their instances.
The controller creates the bootc-pull-secrets Secret in the release
namespace, which Helm does not track, and helm uninstall does not
delete the namespace created by --create-namespace. Delete the namespace
to remove that Secret, along with any pull secrets created there:
kubectl delete namespace bootc-operatorMost Helm templates are generated from the kustomize manifests. After
changing CRDs, RBAC rules, deployments, or service accounts under
config/, regenerate the chart:
make helm| Key | Default | Description |
|---|---|---|
crds.install |
true |
Install the CRD sub-chart |
image.repository |
ghcr.io/bootc-dev/bootc-operator |
Operator image repository |
image.tag |
"" (uses appVersion) |
Operator image tag |
image.pullPolicy |
not set | Kubernetes image pull policy |
imagePullSecrets |
[] |
List of pull secret references |
pullSecretNamespaces |
[] |
Extra pool pull-secret namespaces; non-empty values configure a CLI fallback and namespaced RBAC |
controller.extraArgs |
[] |
Extra arguments for the controller |
daemon.extraArgs |
[] |
Extra arguments for the node daemon |