Install the operator

Install a pinned 0.5.0 release and verify the rendered namespace, identities, controllers, CRDs, and admission policies. The core procedure uses Helm in the chart’s default multi-tenant mode.

Before you begin

• Confirm that the cluster meets the compatibility requirements. Kubernetes 1.33 satisfies the chart constraint, while current release gates validate Kubernetes 1.34 and 1.35.
• Use an identity that can create cluster-scoped CRDs, RBAC, and ValidatingAdmissionPolicies.
• Decide whether Helm, a release manifest, or a maintained Kustomize overlay owns future upgrades.
• Decide the tenancy model. Use the separate single-tenant procedure for one watched namespace.

Choose an installation path

Install with Helm

1. Set the release values.

   configure

   Set the 0.5.0 release values

   Copy

   export OPERATOR_RELEASE=openbao-operator
      export OPERATOR_NAMESPACE=openbao-operator-system
      export CHART_VERSION=0.5.0

2. Inspect the chart defaults when the platform needs overrides.

   inspect

   Read the pinned values

   Copy

   helm show values \
        oci://ghcr.io/dc-tec/charts/openbao-operator \
        --version "${CHART_VERSION}"

   Pin the chart and normally let its appVersion select the matching operator image. Set image.tag only for a controlled prerelease or test. The complete pinned reference is values.yaml.

3. Render the installation before applying it when you use non-default values.

   inspect

   Render the Helm release

   Copy

   helm template "${OPERATOR_RELEASE}" \
        oci://ghcr.io/dc-tec/charts/openbao-operator \
        --version "${CHART_VERSION}" \
        --namespace "${OPERATOR_NAMESPACE}"

   Check the controller and Provisioner ServiceAccounts, RoleBinding subjects, admission-policy identity variables, projected token audience, images, and namespaces.

4. Install the chart.

   apply

   Install OpenBao Operator

   Copy

   helm upgrade --install "${OPERATOR_RELEASE}" \
        oci://ghcr.io/dc-tec/charts/openbao-operator \
        --version "${CHART_VERSION}" \
        --namespace "${OPERATOR_NAMESPACE}" \
        --create-namespace \
        --wait

5. Wait for both multi-tenant Deployments.

   verify

   Verify the controller and Provisioner

   Copy

   kubectl -n "${OPERATOR_NAMESPACE}" rollout status \
        deployment/openbao-operator-controller --timeout=2m
      kubectl -n "${OPERATOR_NAMESPACE}" rollout status \
        deployment/openbao-operator-provisioner --timeout=2m

6. Verify the installed APIs and admission policies.

   verify

   Verify cluster-scoped resources

   Copy

   kubectl get crd \
        openbaoclusters.openbao.org \
        openbaotenants.openbao.org \
        openbaorestores.openbao.org
      kubectl get validatingadmissionpolicies \
        -l app.kubernetes.io/instance="${OPERATOR_RELEASE}"

7. Verify the default controller JWT contract.

   inspect

   Inspect the controller identity and audience

   Copy

   kubectl -n "${OPERATOR_NAMESPACE}" get serviceaccount \
        openbao-operator-controller
      kubectl -n "${OPERATOR_NAMESPACE}" get deployment \
        openbao-operator-controller -o yaml

   Confirm that the Deployment uses the rendered ServiceAccount, mounts the projected openbao-token, and aligns its audience with OPENBAO_JWT_AUDIENCE. Continue with operator authentication when you customize these values.

Install the published manifest

Use the release asset when the platform wants the published default resources without a Helm release:

kubectl apply -f \
  https://github.com/dc-tec/openbao-operator/releases/download/0.5.0/install.yaml

The manifest uses the repository’s default operator namespace and identity. Do not rewrite the rendered YAML by hand for a custom identity; maintain a Kustomize overlay instead.

Install with a custom raw identity

Use config/overlays/custom-identity when the platform owns a different operator namespace or namePrefix.

kubectl kustomize config/overlays/custom-identity

Before applying the overlay, confirm:

1. Controller and Provisioner ServiceAccounts have the intended names and namespace.
2. RoleBinding and ClusterRoleBinding subjects point at those ServiceAccounts.
3. Admission-policy variables use the same namespace and ServiceAccount names.
4. OPENBAO_JWT_AUDIENCE matches the projected openbao-token audience.
5. The OpenBao JWT role’s bound subject matches the rendered controller identity.

Apply only after the render is internally consistent:

kubectl apply -k config/overlays/custom-identity

Install on OpenShift

The chart defaults to platform=auto. Set platform=openshift when the installation must force OpenShift behavior:

helm upgrade --install openbao-operator \
  oci://ghcr.io/dc-tec/charts/openbao-operator \
  --version 0.5.0 \
  --namespace openbao-operator-system \
  --create-namespace \
  --set platform=openshift

OpenShift mode omits fixed runAsUser and fsGroup IDs so the Security Context Constraint can assign namespace-scoped IDs. Validate the result against the target cluster’s SCC and admission configuration.

Install from source for development

Use this path only for local development and contribution:

make install
make deploy IMG=ghcr.io/dc-tec/openbao-operator:dev

Upgrade the operator

Helm does not upgrade installed CRDs. For every release with CRD changes, apply the release CRDs before the controller:

kubectl apply -f \
  https://github.com/dc-tec/openbao-operator/releases/download/0.5.0/crds.yaml
helm upgrade openbao-operator \
  oci://ghcr.io/dc-tec/charts/openbao-operator \
  --version 0.5.0 \
  --namespace openbao-operator-system \
  --reuse-values \
  --wait

Re-render custom identities and review OpenBao-side policy changes before upgrading. Self-init does not update existing OpenBao policies.

Uninstall the operator

helm uninstall openbao-operator --namespace openbao-operator-system

Troubleshoot installation

In multi-tenant mode, continue with namespace onboarding.