Operator installation

The operator ships as a Helm chart at tools/k8s-operator/charts/orbitalreg-operator.

This page summarises the four supported install paths. The full canonical install guide lives at docs/operator/installation.md.

Prerequisites

• Kubernetes ≥ 1.24
• Helm ≥ 3.10 (for the templated chart) or 4.x
• An OrbitalReg deployment reachable from the cluster
• An admin-scoped API token (mint under Profile → API tokens in the OrbitalReg UI)
• RBAC sufficient to install cluster-scoped CRDs and a ClusterRole

Quickstart (development)

helm install orbitalreg-operator \
    ./tools/k8s-operator/charts/orbitalreg-operator \
    --namespace orbitalreg-operator --create-namespace \
    --set credentials.create=true \
    --set credentials.endpoint=https://registry.example.com \
    --set credentials.token=$ORBITALREG_TOKEN

Verify:

kubectl -n orbitalreg-operator rollout status deploy/orbitalreg-operator
kubectl -n orbitalreg-operator logs -l app.kubernetes.io/name=orbitalreg-operator -f

The first reconcile pass picks up any pre-existing CRs in the cluster.

Production install

For production, store the API token in an externally-managed Secret (ExternalSecrets, Sealed Secrets, etc.) and reference it via credentials.existingSecret:

credentials:
  create: false
  existingSecret: orbitalreg-operator-creds
  # The Secret must contain `endpoint` and `token` keys.

helm install orbitalreg-operator \
  ./tools/k8s-operator/charts/orbitalreg-operator \
  --namespace orbitalreg-operator --create-namespace \
  --values values-prod.yaml

Air-gapped install

The chart values cover the air-gap case directly:

image:
  repository: registry.internal.example.com/orbitalreg/operator
  tag: v1.2.3
credentials:
  existingSecret: orbitalreg-operator-creds

webhooks:
  enabled: true
  certManager:
    enabled: true

Then mirror the operator image into the private registry using skopeo:

skopeo copy --all \
  docker://ghcr.io/orbitalreg/orbital-operator:v1.2.3 \
  docker://registry.internal.example.com/orbitalreg/operator:v1.2.3

The chart's CRDs are templated rather than served from crds/ so they roll forward with helm upgrade — no manual kubectl apply -f crds/ step needed in the air-gap loop.

Manual install (no Helm)

For non-Helm clusters, render the chart and apply:

helm template orbitalreg-operator \
  ./tools/k8s-operator/charts/orbitalreg-operator \
  --namespace orbitalreg-operator \
  --values values-prod.yaml > orbitalreg-operator.yaml
kubectl create namespace orbitalreg-operator
kubectl apply -f orbitalreg-operator.yaml

The rendered output is vanilla Kubernetes resources — Deployment, ServiceAccount, ClusterRole, ClusterRoleBinding, ConfigMap, Service, optional Webhooks, plus Secrets you provision yourself.

Validation webhooks

Validating-admission webhooks for all seven CRDs are gated by --enable-webhooks, default off so the zero-config single-binary deployment stays unchanged.

To enable:

webhooks:
  enabled: true
  certManager:
    enabled: true
    issuerRef:
      name: letsencrypt-internal
      kind: ClusterIssuer

The chart provisions a Certificate, a Service for the webhook endpoint, and a ValidatingWebhookConfiguration annotated with cert-manager.io/inject-ca-from so cert-manager injects the CA bundle automatically.

Verify

kubectl get crds | grep orbitalreg
kubectl -n orbitalreg-operator get pods
kubectl -n orbitalreg-operator logs deploy/orbitalreg-operator | head

Apply a sample CR:

kubectl apply -f tools/k8s-operator/examples/quickstart/project.yaml
kubectl wait --for=condition=Ready orbitalregproject sample --timeout=120s

Uninstall

helm uninstall orbitalreg-operator -n orbitalreg-operator

Each CRD ships with helm.sh/resource-policy: keep, so the uninstall does not cascade-delete CRs or the Secrets they materialise. To fully remove:

kubectl delete orbitalregproject --all
kubectl delete crd \
  orbitalregprojects.orbitalreg.io \
  orbitalregrepositories.orbitalreg.io \
  orbitalregserviceaccounts.orbitalreg.io \
  orbitalregserviceaccounttokens.orbitalreg.io \
  orbitalregretentionpolicies.orbitalreg.io \
  orbitalregsecurityblocks.orbitalreg.io \
  orbitalregwebhooksubscriptions.orbitalreg.io
kubectl delete namespace orbitalreg-operator