Handover Checklist
Deploying OLIVE needs two people, and the manual splits their work across two guides for good reason: the cluster operator installs the infrastructure, the platform administrator specifies what it has to deliver. That split is correct, but it means neither of them can see the whole handover on one page.
This page is that page. It is the list the two of them work through together before the first install, and the one to re-run after any change to the ingress, the mesh, the CNI, the StorageClass or the Keycloak host.
Nothing here is new material. Every row points at the page that explains it. What this page adds is that it is one list, in the order the handover actually happens, so neither side discovers a missing value during a failed sync.
Most of the values exchanged below fail silently when they are wrong. A NetworkPolicy peer selector that matches no pods is not an error — it is zero peers, and default-deny then closes every route into the namespace. A serviceMesh.mode that disagrees with the cluster renders policies for the wrong traffic shape and produces timeouts. A Kyverno enrolment label with a typo leaves a namespace that looks protected and is not.
None of those produce a message. Getting the handover right on paper is cheaper than diagnosing any of them later.
1. What the cluster operator provides
The platform administrator cannot install any of this and generally does not hold the rights to. Confirm each row exists before the first OLIVE sync.
| Provide | Detail | Where it is specified |
|---|---|---|
| A Kubernetes cluster 1.31 or later | RKE2 and Amazon EKS are the tested distributions; any CNCF-conformant cluster meeting the requirements on this page should work, unvalidated. Note that the AppArmor profile in the pod security context needs 1.31 — it can be switched off with global.appArmor: false on hosts that cannot enforce it, such as SELinux hosts, though we do not recommend doing so where the host supports it | Platform Technology Overview |
A CNI that enforces NetworkPolicy | Cilium and Calico do. On EKS the VPC CNI only enforces with enableNetworkPolicy=true | Networking |
| Traefik as the ingress controller | The only supported controller from 1.3. Entry points web and websecure, providers kubernetesIngress and kubernetesCRD | Ingress Requirements |
The redirectErrors Traefik plugin | Not built in. Without it users meet an error page instead of a login page | Ingress Requirements |
A StorageClass with allowVolumeExpansion: true | RWO is sufficient; no OLIVE component needs RWX | Storage Requirements |
A ClusterIssuer for TLS | OLIVE creates the Certificate; the issuer, its ACME account or CA key material, and the solver are yours | Ingress Requirements |
DNS for *.<cluster>.<domain> | A wildcard record covers all five hostnames of every tenant | Ingress Requirements |
cert-manager, plus a ClusterIssuer | Required. OLIVE renders the Certificate objects and never creates the issuer — the issuer, its ACME account or CA key material, and the solver configuration are yours. Not needed only if you issue certificates by other means and create the TLS Secret yourself | Ingress Requirements |
| The CloudNativePG operator | Required. Provides the workflow engine's PostgreSQL, and Keycloak's | Dependencies |
| HashiCorp Vault, initialised and unsealed | Required. OLIVE does not start without one | HashiCorp Vault |
| Vault Secrets Operator — exactly one per cluster | It has no watch-namespace option, so a second instance reconciles the same resources | HashiCorp Vault |
| Keycloak with a publicly trusted certificate | Required for authenticated deployments. Reached over its public HTTPS address, never in-cluster DNS | Keycloak |
Argo CD, and an AppProject that permits what OLIVE creates | An empty clusterResourceWhitelist permits nothing cluster-scoped, which stops the first sync at the Namespace | Kubernetes Resources |
| Istio ambient — optional | Only if serviceMesh.mode will be ambient. Also the mesh exemptions below | Service Mesh |
| Kyverno — optional | Only if admission policies will be enforced | Kyverno |
Network egress the cluster must permit
| Destination | Needed by | Notes |
|---|---|---|
registry.gitlab.com over HTTPS | Every node pulling images, and Argo CD pulling charts | Two OCI endpoints on one host: the charts and OLIVE's own images |
quay.io, gcr.io and docker.io (also index.docker.io) over HTTPS | Every node | OLIVE does not re-host its third-party images. Keycloak, OAuth2 Proxy, Vault, CouchDB, Redis, SeaweedFS, Temporal, the distroless bases, Alpine and BusyBox are pulled from these. Allow-listing only the row above produces ImagePullBackOff on Keycloak and CouchDB. The exact prefixes are the registry allow-list policy's — see Kyverno |
The Sigstore services — fulcio.sigstore.dev, rekor.sigstore.dev and tuf-repo-cdn.sigstore.dev — over HTTPS | The Kyverno pods only, and only if image signature verification will be enabled | Keyless cosign verification happens inside the admission call. Without this route, enforce blocks every pod creation and audit verifies nothing — see Admission Control |
| The Keycloak host on 443 | Every OLIVE service, for JWKS | Tell the platform administrator whether the host resolves to a public or a private address, from inside the cluster. Public → the default covers it. Private (internal LB, private hosted zone) → the default blocks it and they need the VPC CIDR in global.keycloakIpBlocks. If a public address is pinned, tell them when it changes |
| The OTLP collector ports | Every pod's telemetry exporter | Confirm the ports against your collector's Service — 4317 and 4318 by default, and Grafana Alloy commonly also 12345 |
The first two rows are a hard prerequisite — there is no offline installation path. The third applies only if image signature verification will be enabled. See Network requirements.
The required CRDs
A missing CRD fails as no matches for kind, which reads like a chart bug rather than a missing prerequisite:
# Hard requirements
kubectl get crd | grep -E 'secrets.hashicorp.com|cnpg.io|cert-manager.io|traefik.io'
# Optional components
kubectl get crd | grep -E 'istio.io|kyverno.io|wgpolicyk8s.io'
2. Values the platform administrator needs back from the cluster operator
This is the heart of the handover. Each of these goes into the OLIVE deployment values, and each one, wrong, fails without an error message.
| Value needed | How the cluster operator reads it off their installation | Goes into | Consequence if wrong |
|---|---|---|---|
| The Traefik namespace and pod labels | kubectl get pods -n <traefik-ns> --show-labels | global.networkPolicy.ingressController | A selector matching nothing closes every route into the namespace the moment default-deny lands |
The IngressClass name | kubectl get ingressclass | global.ingress.className | No ingress serves the OLIVE routes |
The StorageClass name, or confirmation that one is marked (default) | kubectl get storageclass | global.storageClassName | Claims stay Pending, pods with them |
| Whether that class allows volume expansion | kubectl get sc -o custom-columns='NAME:.metadata.name,EXPANSION:.allowVolumeExpansion' | — | Growing a tenant's storage later becomes a data migration instead of a patch |
The ClusterIssuer name | kubectl get clusterissuer | global.clusterIssuer | No certificate is issued; the Ingress serves nothing or an invalid chain |
| The Vault namespace and Service name | kubectl get svc -n <vault-ns> | global.vault.namespace, .serviceName | A renamed Vault Helm release fails as a connection timeout, not a name error |
| Whether the Vault namespace is mesh-enrolled | kubectl get ns <vault-ns> -o jsonpath='{.metadata.labels}' | global.serviceMesh.vaultMeshed | Over-declaring is tolerated silently, and tenant-to-Vault traffic runs as plaintext carrying Vault tokens |
| Which mesh mode is actually installed | kubectl get ns -L istio.io/dataplane-mode; kubectl -n istio-system get ds | global.serviceMesh.mode | sidecar and ambient need opposite policy changes. The symptom is a timeout |
Whether the CNI enforces NetworkPolicy | Their own installation; on EKS, the VPC CNI add-on configuration | — | Policies are accepted and enforce nothing, which is worse than having none, because you will believe you have one |
| The scrape agent's namespace and pod labels | kubectl get pods -n <monitoring-ns> --show-labels | global.metrics.scrape | The scrape is dropped at the network; the target reports down in an agent the administrator cannot see |
| The observability collector's OTLP ports | Their collector's Service — Grafana Alloy commonly also listens on 12345 | telemetry egress | Telemetry stops with no other symptom, and the retry noise can rotate away the evidence |
| The backup tool's volume selector label | Their backup tool's configuration | global.volumeLabels | Decide before the first install — the labels are part of volumeClaimTemplates and cannot be changed afterwards |
| Whether hosts have AppArmor | SELinux hosts (RHEL, Rocky, OpenShift) and some managed clouds do not | global.appArmor | The kubelet rejects every pod with "Cannot enforce AppArmor" |
global.volumeLabels and the volume sizes (couchdbPvcSize, seaweed.pvcSize) are read when the claim is created and live in the StatefulSet's volumeClaimTemplates, which is immutable. Settle both in this handover rather than after the first install. See Storage Requirements.
3. Values the cluster operator needs from the platform administrator
The traffic goes both ways. None of these mean anything to a cluster operator who has not been told them.
| Value | Why the cluster operator needs it |
|---|---|
| The namespaces OLIVE will use | The AppProject destinations, and the namespaces the scrape agent's selector has to cover |
| The Keycloak public hostname | DNS and a publicly trusted certificate for it. An internally signed certificate fails the onboarding Job's TLS verification |
The tenant hostname pattern *.<cluster>.<domain> | The wildcard DNS record and the certificate |
| The Vault bootstrap policy and role | Section 5 below. This is the part that cannot be improvised |
That the KV mount must be named secret and be KV v2 | Tenant onboarding writes every policy against secret/data/.... A renamed mount produces policies that are syntactically valid and match no path |
That disable_iss_validation=true is required on the Kubernetes auth config | Otherwise onboarding fails to authenticate |
| The Kyverno enrolment label keys, if Kyverno is used | olive/image-verification, olive/image-registry, olive/pod-privileges — and the cosign keyless subject and issuer |
| The mesh exemptions OLIVE depends on | Section 4 below |
That olive-regcred must exist in Vault at secret/shared-secrets/olive-regcred | No chart creates it — it is a credential OLIVE has no business holding on your behalf |
The shared values block
These describe the cluster, not a tenant, and are read by several charts. Agree them here and keep them in one shared values file that every deployment includes — a cluster where two charts disagree about where Vault lives, or which mesh mode is installed, fails in ways that look like something else entirely.
global:
vault:
namespace: 'oli-hashicorp-vault'
serviceName: 'oli-vault'
port: 8200
scheme: 'http'
serviceMesh:
mode: ambient # none | sidecar | ambient — must match what is installed
vaultMeshed: true
ingress:
className: traefik
storageClassName: longhorn # or 'default' for the cluster's default class
networkPolicy:
enabled: true
ingressController:
namespace: kube-system # 'traefik' for a separate install
podLabels:
app.kubernetes.io/name: rke2-traefik # 'traefik' upstream — no rke2- prefix
appArmor: true
seccomp: true
imageVerification:
labelKey: 'olive/image-verification'
imageRegistry:
labelKey: 'olive/image-registry'
podPrivileges:
labelKey: 'olive/pod-privileges'
4. If a service mesh is used
Each of these exists because some unmeshed component legitimately needs to reach a meshed pod. They are the cluster operator's to apply, and OLIVE depends on all of them.
| Exemption | What happens without it |
|---|---|
The mesh starts PERMISSIVE; STRICT is phased in | STRICT rejects plaintext from anything unmeshed |
PERMISSIVE for the vault-agent-injector webhook, applied before strict peer authentication | The kube-apiserver has no mesh identity, so pod creation fails in every tenant namespace that runs CouchDB or SeaweedFS — which is every tenant |
PERMISSIVE for Kyverno's webhook callers | Same failure, via a different webhook |
| An exemption for the ingress controller, unless it is itself enrolled | The platform goes dark from outside while looking healthy inside |
L4 AuthorizationPolicy for couchdb and seaweedfs, enabled with enrollment | Under ambient the real destination port travels inside the HBONE tunnel where the CNI cannot see it, so the NetworkPolicy port restrictions stop binding |
Kubelet health probes allowed from 169.254.7.127/32 (and the IPv6 equivalent on dual-stack) | Every liveness and readiness probe fails. This is the most common ambient rollout failure |
5. The Vault bootstrap policy
This is the piece that has to be right to the character, and the one a cluster operator cannot derive from Vault's own documentation. Tenant onboarding authenticates against this policy and creates the per-tenant policies, Kubernetes auth roles and JWT auth mounts through it.
The full policy, the bootstrap role, and the three things about it that are easy to get wrong — sudo on sys/auth/jwt-*, * being a wildcard only as the final character, and why the name prefixes are load-bearing — are in Infrastructure Prerequisites → The bootstrap policy. Apply it from there rather than from memory.
sys/policies/acl/* and auth/kubernetes/role/*An earlier version of this policy did exactly that, and it made the role a standing Vault administrator — able to write the default policy, mint roles binding any service account, and read any tenant's secrets. The name prefixes are what reduce it to the objects onboarding actually manages.
6. Cluster-scoped checks only the cluster operator can run
Most verification of the security controls is a cluster-scoped read, and a platform administrator usually cannot run it. These are the questions that come back to you, with the commands that answer them.
# Are the Kyverno policies present AND active?
# A policy whose CEL failed to compile is listed and completely inert — read the status.
kubectl get validatingpolicy,imagevalidatingpolicy
# Which namespaces are enrolled, per control, and in which mode?
kubectl get ns -L olive/image-verification,olive/image-registry,olive/pod-privileges
# Does the ClusterRole the VSO binding references exist?
kubectl get clusterrole | grep vault-secrets-operator
# Is the mesh enrolment where the values say it is?
kubectl get ns -L istio.io/dataplane-mode
The matching check the platform administrator runs themselves is kubectl get polr -n <namespace>. A namespace that carries an enrolment label but has no rows there is enrolled and not being evaluated — which is the state a values file reads as "protected".
7. Controls that are split between the two roles
Most rows in Shared Responsibility fall clearly to one role. These do not — each is divided, which is what makes them the ones most easily left undone by both sides:
| Control | Cluster operator's part | Platform administrator's part |
|---|---|---|
| Backup and restore | The infrastructure and the execution | Verifying that an OLIVE-level restore is correct |
| Alerting and triage | The tooling, and alerts on the cluster itself | OLIVE-level alert rules and first-line triage |
| Secret rotation | Cluster-level secrets | OLIVE-level secrets |
| Encryption at rest | Owns it — volumes, backups, object storage, etcd | Needs to know whether it is in place, and for what |
ServiceMonitor / PodMonitor objects | The agent's selector label and its namespace coverage | The namespace they are created in |
Worth reading together rather than separately.
8. Verify the result, not the configuration
A values file that says a control is on is not evidence that it is. Verify the Deployment covers the workloads, the sign-in path, the five-minute liveness check and whether the security controls are actually in effect; Production Readiness Checklist is the longer list, for an environment about to carry real data.
Related
- Infrastructure Prerequisites — what each component must provide, in full
- Infrastructure Charts — one way of making it true, provided as-is
- Shared Responsibility — who owns which control
- Kubernetes Resources — what OLIVE creates, and the
AppProjectallow-list