Installing it

Getting the operator running, once, per cluster.

The operator is installed once per cluster. Each environment you then want in the cluster is one token and one small resource — see Projecting an environment.

Before you start

You need a cluster you can install into and Helm. Integrations → Kubernetes generates everything below filled in for you.

  1. Install the operator

    The image and the chart are private for now:

    kubectl create namespace orcakey-operator --dry-run=client -o yaml | kubectl apply -f -
    kubectl -n orcakey-operator create secret docker-registry ghcr-pull \
      --docker-server=ghcr.io \
      --docker-username=YOUR_GITHUB_USERNAME \
      --docker-password=YOUR_READ_PACKAGES_TOKEN \
      --dry-run=client -o yaml | kubectl apply -f -
    helm registry login ghcr.io --username YOUR_GITHUB_USERNAME
    helm install orcakey-connector oci://ghcr.io/bluepawlabs/charts/orcakey-connector \
      --version 1.1.0 \
      --namespace orcakey-operator \
      --set registry.existingSecret=ghcr-pull \
      --set orcakey.apiBaseUrl=https://api.orcakey.sh
    ValueDefault
    orcakey.apiBaseUrl—The orcakey.sh API every OrcaKeySecret uses unless it sets spec.host. Checked for a supported contract at startup.
    registry.existingSecret—The pull secret for the image, which is private for now.
    identity.audienceorcakey.shThe audience of the projected token the operator presents when an OrcaKeySecret sets identity. Always mounted.
    image.tagthe chart's appVersionPinned by the chart. There is no latest.
    resources50m / 96Mi, 256Mi limit
  2. Check the operator is running

    kubectl -n orcakey-operator get pods

    A running pod means the operator started and understood the orcakey.sh API it was pointed at. If it refuses to start it names the API version it expected and the one it found, rather than syncing against an API it does not understand.

What it may do

The chart grants the operator a ClusterRole: read and write on secrets, read and patch on deployments (for restarts), and full control of its own OrcaKeySecret resources. Nothing else.

That is cluster-wide Secret write, and one rule limits it:

Where the OrcaKeySecret livesWhat it may reference
orcakey-operatorA token Secret and a managed Secret in any namespace
Any other namespaceOnly its own namespace, and never identity

A resource outside orcakey-operator that names another namespace is not processed and reports NamespaceNotAllowed. So who may write a secret into any namespace is whoever may create an OrcaKeySecret in orcakey-operator. Keep that namespace to cluster administrators.

The same goes for reading: a resource in orcakey-operator may authenticate as the cluster and read any environment assigned to it.

Registry credentials

The image and the chart are private on GHCR for now, so an install needs a GitHub token with read:packages: helm registry login ghcr.io for the chart, and a pull secret for the image. Create the pull secret yourself and name it:

kubectl create namespace orcakey-operator --dry-run=client -o yaml | kubectl apply -f -
kubectl -n orcakey-operator create secret docker-registry ghcr-pull \
  --docker-server=ghcr.io \
  --docker-username=YOUR_GITHUB_USERNAME \
  --docker-password=YOUR_READ_PACKAGES_TOKEN \
  --dry-run=client -o yaml | kubectl apply -f -
helm install ... --set registry.existingSecret=ghcr-pull

The chart accepts no registry credentials and builds no pull secret. Naming one you already own keeps it under whatever rotation you already apply.

Verifying what you installed

Every image and chart is signed, and the signature needs no key from us:

cosign verify ghcr.io/bluepawlabs/orcakey-connector:1.0.3 \
  --certificate-identity-regexp '^https://github.com/bluepawlabs/orcakey.sh/' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com

The same command works for ghcr.io/bluepawlabs/charts/orcakey-connector.

There is no latest tag. A tag that moves under a running cluster is a version nobody can name during an incident, so every install names one.

Migrating from OrcaKeySync (0.x)

Chart 1.0.0 replaces OrcaKeySync (connectors.orcakey.sh/v1alpha1) with OrcaKeySecret (secrets.orcakey.sh/v1beta1). The 1.0.0 operator does not read the old resource, and there is no automatic conversion.

  1. Upgrade the chart

    helm upgrade to 1.0.1 or later with --set orcakey.apiBaseUrl=..., then kubectl apply -f the chart's crds/ directory: Helm does not install or upgrade CRDs on helm upgrade. Leave the old CRD in place.

  2. Apply an OrcaKeySecret per old sync

    For each OrcaKeySync, apply an OrcaKeySecret whose managedSecret names the same Secret in the same namespace, and whose token is scoped to the same environment. The token Secret key is now serviceToken, not token. Scoping, transforms and renames are gone: the Secret becomes the whole environment under its own key names.

  3. Wait for Ready

    kubectl get orcakeysecrets -A

    Every one should be Ready with reason Synced.

  4. Check each Secret's owner

    kubectl -n <namespace> get secret <name> \
      -o jsonpath='{.metadata.ownerReferences}'

    For a Secret in the same namespace as its OrcaKeySecret, this names the OrcaKeySecret. For one in another namespace it is empty. It must not name an OrcaKeySync. If it still does, the new resource has not written that Secret yet: stop here.

  5. Delete the old resources, then the old CRD

    kubectl delete orcakeysyncs --all -A
    kubectl delete crd orcakeysyncs.connectors.orcakey.sh