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.
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.shValue Default orcakey.apiBaseUrl — The orcakey.sh API every OrcaKeySecretuses unless it setsspec.host. Checked for a supported contract at startup.registry.existingSecret — The pull secret for the image, which is private for now. identity.audience orcakey.sh The audience of the projected token the operator presents when an OrcaKeySecretsetsidentity. Always mounted.image.tag the chart's appVersion Pinned by the chart. There is no latest.resources 50m / 96Mi, 256Mi limit Check the operator is running
kubectl -n orcakey-operator get podsA 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 lives | What it may reference | |
|---|---|---|
orcakey-operator | A token Secret and a managed Secret in any namespace | |
| Any other namespace | Only 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-pullThe 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.comThe 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.
Upgrade the chart
helm upgradeto 1.0.1 or later with--set orcakey.apiBaseUrl=..., thenkubectl apply -fthe chart'scrds/directory: Helm does not install or upgrade CRDs onhelm upgrade. Leave the old CRD in place.Apply an OrcaKeySecret per old sync
For each
OrcaKeySync, apply anOrcaKeySecretwhosemanagedSecretnames the same Secret in the same namespace, and whose token is scoped to the same environment. The tokenSecretkey is nowserviceToken, nottoken. Scoping, transforms and renames are gone: the Secret becomes the whole environment under its own key names.Wait for Ready
kubectl get orcakeysecrets -AEvery one should be
Readywith reasonSynced.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 theOrcaKeySecret. For one in another namespace it is empty. It must not name anOrcaKeySync. If it still does, the new resource has not written that Secret yet: stop here.Delete the old resources, then the old CRD
kubectl delete orcakeysyncs --all -A kubectl delete crd orcakeysyncs.connectors.orcakey.sh