A Kopf-based Python operator for managing Plone 6 CMS deployments on Kubernetes. It manages the full lifecycle of a PloneSite custom resource — provisioning, site initialisation, ingress, and scheduled database maintenance — without Helm.
- Two deployment types: Volto (React frontend + REST API backend) and Classic (backend only)
- Two database backends: ZODB via ZEO (in-cluster StatefulSet) and PostgreSQL via RelStorage (external or CloudNativePG)
- Traefik ingress: single Ingress with correct path routing for both deployment types
- Virtual Host Monster: both deployment types use a Traefik
replacePathRegexMiddleware so Plone generates correct public URLs; Classic rewrites all paths, Volto scopes the rewrite to/++api++/*only - Automatic site initialisation: polls the REST API after deploy and creates the Plone site if it does not exist
- Automatic database migration: after every reconcile the operator calls
GET /@upgrade; if pending steps are detected it callsPOST /@upgradeto run the migration — idempotent and safe on a clean install - Scheduled database packing: configurable interval (default weekly); skippable via
packIntervalDays: 0 - Server-side apply: all child resources are managed via Kubernetes SSA — no drift, no ownership conflicts
- Status tracking:
phase,siteUrl,deploymentType,ingressConfigured,lastPackTime,lastUpgradeTimesurfaced on the CR
PloneSite CR
│
▼
plone_operator.py (Kopf, asyncio)
│
├── ZEO StatefulSet + Service (database.type: zodb)
├── CNPG Cluster CR (database.type: postgresql, cnpg: true)
│
├── Backend Deployment + Service (always)
├── Frontend Deployment + Service (deploymentType: volto)
│
├── Traefik Middleware (<name>-rewrite) (publicUrl set)
├── Ingress (ingress.enabled: true)
│
└── db-pack Job (one-off, weekly) (kopf.timer, batch/v1 Job)
All child resources carry ownerReferences pointing to the PloneSite — Kubernetes garbage-collects them automatically when the CR is deleted.
- Kubernetes 1.25+
- Traefik ingress controller
- CloudNativePG operator (only if
database.cnpg: true) kubectlconfigured against your cluster- uv (for local development)
# Creates plone-operator-system and plone namespaces, applies CRDs, RBAC, operator Deployment
make deployThe operator always reads admin credentials from a Secret named <cr-name>-admin
with keys username and password. The Secret must be in the same namespace as the CR:
kubectl create secret generic my-plone-admin -n plone \
--from-literal=username=admin \
--from-literal=password=changemekubectl apply -f config/samples/simple_plonesite.yamlkubectl get plonesites -n plone
kubectl describe plonesite my-plone -n ploneThe operator uses two namespaces:
| Namespace | Purpose |
|---|---|
plone-operator-system |
Operator Deployment, ServiceAccount, RBAC |
plone |
PloneSite CRs and all their child resources |
make deploy creates both namespaces. Admin secrets and the PloneSite CRs themselves must be created in the plone namespace (or whichever namespace you choose — the operator watches all namespaces).
apiVersion: plone.org/v1alpha1
kind: PloneSite
metadata:
name: my-plone
namespace: plone
spec: {}Create the required Secret first:
kubectl create secret generic my-plone-admin -n plone \
--from-literal=username=admin --from-literal=password=changemeapiVersion: plone.org/v1alpha1
kind: PloneSite
metadata:
name: production-plone
namespace: plone
spec:
siteId: "Plone"
deploymentType: "volto"
backendImage: "plone/plone-backend:6.0"
frontendImage: "plone/plone-frontend:18"
replicas: 3
publicUrl: "https://www.example.com"
ingress:
enabled: true
className: "traefik"
tls: true
database:
type: "postgresql"
cnpg: true
packIntervalDays: 7
persistence:
enabled: true
storageClass: "fast-ssd"
size: "50Gi"
resources:
limits:
cpu: "4000m"
memory: "4Gi"
requests:
cpu: "1000m"
memory: "1Gi"
environment:
TZ: "America/New_York"Only the admin Secret is required — CNPG auto-generates the database credentials:
kubectl create secret generic production-plone-admin -n plone \
--from-literal=username=admin --from-literal=password=changemeapiVersion: plone.org/v1alpha1
kind: PloneSite
metadata:
name: classic-plone
namespace: plone
spec:
siteId: "Plone"
deploymentType: "classic"
publicUrl: "https://classic.example.com"
ingress:
enabled: true
className: "traefik"
tls: true
database:
type: "zodb"
persistence:
enabled: true
size: "20Gi"| Field | Type | Default | Description |
|---|---|---|---|
siteId |
string | "plone" |
URL path component (e.g. /Plone) |
deploymentType |
string | "volto" |
volto or classic |
backendImage |
string | plone/plone-backend:latest |
Backend container image |
frontendImage |
string | plone/plone-frontend:latest |
Volto frontend container image (only used when deploymentType: volto) |
replicas |
integer | 1 |
Backend replica count |
publicUrl |
string | — | Public URL of the site (e.g. https://example.com). Enables Ingress and VHM rewriting. |
sitePath |
string | siteId |
Zope traversal path to the site object; used for Classic UI path rewriting. |
addons |
array | [] |
Plone add-ons to activate |
environment |
object | {} |
Extra environment variables injected into the backend |
Admin credentials are always read from a Secret named <cr-name>-admin
(keys: username, password). There is no field for this — the name is derived
from the CR name to avoid collisions.
| Field | Type | Default | Description |
|---|---|---|---|
enabled |
boolean | false |
Create a Traefik Ingress |
className |
string | "traefik" |
Ingress class |
tls |
boolean | false |
Enable TLS on the Ingress |
| Field | Type | Default | Description |
|---|---|---|---|
type |
string | "zodb" |
zodb or postgresql |
cnpg |
boolean | false |
Use CloudNativePG for in-cluster PostgreSQL |
credentialsSecret |
string | — | Required for external PostgreSQL (cnpg: false) only — see below |
packIntervalDays |
integer | 7 |
Days between db-pack jobs; 0 disables packing |
credentialsSecret usage:
| Scenario | Behaviour |
|---|---|
External PostgreSQL (cnpg: false) |
Required. Secret must contain: host, port, dbname, username, password |
CNPG in-cluster (cnpg: true) |
Not used. CNPG auto-generates credentials and writes <name>-db-app Secret |
| Field | Type | Default | Description |
|---|---|---|---|
enabled |
boolean | false |
Create PVCs |
size |
string | "10Gi" |
PVC capacity |
storageClass |
string | "" |
Storage class (empty = cluster default) |
Standard Kubernetes resources block (limits / requests with cpu and memory).
When publicUrl is set the operator creates a Traefik replacePathRegex Middleware
named <name>-rewrite that rewrites request paths to include the Zope Virtual Host
Monster (VHM) traversal prefix, so Plone generates correct absolute @id URLs.
The operator:
- Sets
RAZZLE_API_PATH=<publicUrl>on the Volto frontend (browser-side API base URL). - Sets
RAZZLE_INTERNAL_API_PATH=http://<name>-backend.<ns>.svc.cluster.local:8080/<siteId>(Node.js SSR). - Sets
CORS_ALLOW_ORIGIN=<publicUrl>on the backend. - Creates a Traefik Middleware that rewrites only
/++api++/*paths:/++api++/<rest> → /VirtualHostBase/<scheme>/<host>/<siteId>/VirtualHostRoot/++api++<rest> - Creates an Ingress with two rules, the
/++api++rule annotated with the middleware:/++api++→<name>-backend:8080(REST API, rewritten via VHM)/→<name>-frontend:3000(Volto frontend, no rewrite)
The operator:
- Creates a Traefik Middleware that rewrites all paths:
/<rest> → /VirtualHostBase/<scheme>/<host>/<siteId>/VirtualHostRoot/<rest> - Creates an Ingress with a single
/→<name>-backend:8080rule, annotated with the middleware.
| Field | Description |
|---|---|
phase |
Pending, Running, or Failed |
siteUrl |
Public URL of the running site |
deploymentType |
Reflects the active deploymentType |
ingressConfigured |
true if a publicUrl was provided |
lastPackTime |
ISO-8601 timestamp of the last db-pack job |
lastUpgradeTime |
ISO-8601 timestamp of the last automatic Plone DB upgrade |
conditions |
Standard Kubernetes condition array (Ready) |
After every successful reconcile the operator runs a two-step upgrade check
against the live backend's REST API using the admin credentials from the
<name>-admin Secret:
GET /{siteId}/@upgrade— reads the current filesystem generation (versions.fs) and the instance generation (versions.instance).- If they differ,
POST /{siteId}/@upgrade— executes all pending migration steps (timeout: 300 s).
The check is idempotent: on a fresh install or when the site is already
up to date it logs "already up to date" and returns immediately. When
migration runs, the operator sets status.lastUpgradeTime.
Patch the backend (and optionally frontend) image:
kubectl patch plonesite <name> -n plone --type=merge \
-p '{"spec":{"backendImage":"plone/plone-backend:6.1","frontendImage":"plone/plone-frontend:18"}}'The operator will:
- Apply the new image to the backend Deployment (rolling update).
- Wait for the backend to become healthy.
- Detect pending upgrade steps via
GET /@upgrade. - Run
POST /@upgradeto migrate the ZODB or PostgreSQL schema. - Set
status.lastUpgradeTimeand mark the siteRunning.
Watch progress in the operator logs:
kubectl logs -n plone-operator-system \
deployment/plone-operator-controller-manager -fExpected output:
Plone site plone/Plone needs upgrading (18 step(s)), running migration...
Plone DB upgrade complete for plone/Plone: done
Warning: Do not downgrade the backend image after running a migration. ZODB and RelStorage schemas are not backward-compatible.
# Was an upgrade performed, and when?
kubectl get plonesite <name> -n plone \
-o jsonpath='{.status.lastUpgradeTime}'
# Confirm the site is up to date (fs == instance, no pending steps)
kubectl exec -n plone deployment/<name>-backend -- \
python3 -c "
import urllib.request, base64, json
url = 'http://localhost:8080/<siteId>/@upgrade'
req = urllib.request.Request(url)
req.add_header('Accept', 'application/json')
req.add_header('Authorization', 'Basic ' + base64.b64encode(b'admin:password').decode())
print(json.dumps(json.loads(urllib.request.urlopen(req).read()).get('versions'), indent=2))
"packIntervalDays days have elapsed since status.lastPackTime.
- ZEO: runs
zeopackfromplone/plone-zeo:6 - PostgreSQL: runs a RelStorage
pack(days=0)call via the backend image
Set packIntervalDays: 0 to disable packing entirely.
Jobs are auto-deleted 24 hours after completion (ttlSecondsAfterFinished: 86400).
plone-operator/
├── plone_operator.py # Kopf operator (single file)
├── pyproject.toml # uv project / dependencies
├── uv.lock
├── Dockerfile
├── Makefile
└── config/
├── crd/bases/ # PloneSite CRD
├── rbac/ # ServiceAccount, Role, RoleBinding
├── manager/ # Operator Deployment + Namespaces
└── samples/ # Example PloneSite CRs
# Install dependencies
uv sync
# Install CRDs into your current cluster context
make install
# Run operator locally (uses ~/.kube/config)
uv run kopf run plone_operator.py --verbosemake lint # ruff
make typecheck # ty# Build image inside minikube's Docker daemon and restart the operator
make minikube-load
# Or: build + deploy everything from scratch
make minikube-deploy
# Create admin secrets for all sample CRs in the plone namespace
make create-secrets
# Deploy the three minikube sample CRs
make deploy-sample| Target | Description |
|---|---|
make deploy |
Create namespaces, apply CRDs, RBAC, and operator Deployment |
make undeploy |
Remove operator Deployment and RBAC |
make install |
Apply CRDs only |
make uninstall |
Remove CRDs |
make create-secrets |
Create sample admin secrets in PLONE_NS (default: plone) |
make deploy-sample |
Apply the three minikube sample PloneSite CRs |
make undeploy-sample |
Delete the sample CRs |
make minikube-load |
Build image in minikube daemon + kubectl set image (updates a running operator) |
make minikube-deploy |
Build image in minikube daemon + make deploy (use for fresh clusters) |
make lint |
ruff check plone_operator.py |
make typecheck |
ty check plone_operator.py |
kubectl logs -n plone-operator-system deployment/plone-operator-controller-manager -fkubectl get plonesites -n plone
kubectl describe plonesite <name> -n plone# Check that the admin Secret exists in the correct namespace
kubectl get secret <cr-name>-admin -n plone -o yaml
# For CNPG PostgreSQL: check the auto-generated runtime Secret
kubectl get secret <cr-name>-db-app -n plone -o yaml
# For external PostgreSQL: check credentialsSecret
kubectl get secret <credentialsSecret> -n plone -o yamlkubectl get ingress <cr-name> -n plone -o yaml
# Verify the Traefik Middleware exists
kubectl get middleware <cr-name>-rewrite -n plone -o yaml# Check status.lastPackTime and packIntervalDays
kubectl get plonesite <name> -n plone -o jsonpath='{.status.lastPackTime}'
# List completed pack jobs
kubectl get jobs -n plone -l app.kubernetes.io/component=db-packApache License 2.0