@bluedynamics/cdk8s-plone 0.1.43 → 0.1.45

package/documentation/sources/how-to/configure-env-and-secrets.md

@@ -0,0 +1,184 @@
+---
+myst:
+  html_meta:
+    "description": "Configure environment variables and secrets on Plone backend and frontend pods with cdk8s-plone using the cdk8s-plus Env API."
+    "property=og:description": "Configure environment variables and secrets on Plone backend and frontend pods with cdk8s-plone using the cdk8s-plus Env API."
+    "property=og:title": "Configure environment variables and secrets"
+    "keywords": "Plone, cdk8s, Kubernetes, environment variables, secrets, ConfigMap, imagePullSecrets, Env"
+---
+
+# Configure environment variables and secrets
+
+This guide shows you how to set environment variables on Plone backend and frontend pods and how to source sensitive values from Kubernetes Secrets and ConfigMaps.
+Use it to inject a RelStorage DSN, an admin password, or any runtime configuration without baking values into the image.
+
+## Prerequisites
+
+- A working Plone deployment using `cdk8s-plone`.
+- Familiarity with the cdk8s-plus `Env` API and the `EnvValue` helpers it provides.
+- `kubectl` access to the target namespace for creating Secrets and ConfigMaps.
+
+## Set a plain environment variable on the backend
+
+Pass an `environment` object to `backend`.
+Build each value with `Env.value` for a literal string.
+
+```typescript
+import { Plone, PloneVariant } from '@bluedynamics/cdk8s-plone';
+import { Env } from 'cdk8s-plus-30';
+
+new Plone(chart, 'plone', {
+  variant: PloneVariant.VOLTO,
+  backend: {
+    image: 'plone/plone-backend:6.1.3',
+    environment: {
+      variables: {
+        PLONE_TIMEZONE: Env.value('Europe/Vienna'),
+        ZSERVER_THREADS: Env.value('4'),
+      },
+    },
+  },
+});
+```
+
+The `environment` option is typed as the cdk8s-plus `Env` construct.
+Its `variables` map takes an `EnvValue` for every entry, so always wrap raw strings in `Env.value`.
+
+## Reference a value from a Secret
+
+Store sensitive values such as a RelStorage DSN or an admin password in a Kubernetes Secret, then reference them with `Env.fromSecret`.
+
+First create the Secret in the cluster.
+
+```shell
+kubectl create secret generic plone-backend-secrets \
+  --namespace <namespace> \
+  --from-literal=relstorage-dsn='dbname=plone host=db user=plone password=s3cret' \
+  --from-literal=admin-password='change-me'
+```
+
+Reference the existing Secret by name, then read individual keys from it.
+
+```typescript
+import { Plone, PloneVariant } from '@bluedynamics/cdk8s-plone';
+import { Env, Secret } from 'cdk8s-plus-30';
+
+const backendSecret = Secret.fromSecretName(
+  chart,
+  'backend-secret',
+  'plone-backend-secrets',
+);
+
+new Plone(chart, 'plone', {
+  variant: PloneVariant.VOLTO,
+  backend: {
+    image: 'plone/plone-backend:6.1.3',
+    environment: {
+      variables: {
+        RELSTORAGE_DSN: Env.fromSecret(backendSecret, 'relstorage-dsn'),
+        ADMIN_PASSWORD: Env.fromSecret(backendSecret, 'admin-password'),
+      },
+    },
+  },
+});
+```
+
+`Env.fromSecret` renders a `secretKeyRef` in the pod template, so the value never appears in plain text in the synthesized manifest.
+
+## Reference a value from a ConfigMap
+
+For non-sensitive configuration that you manage separately from the chart, read keys from a ConfigMap with `Env.fromConfigMap`.
+
+```typescript
+import { Env, ConfigMap } from 'cdk8s-plus-30';
+
+const settings = ConfigMap.fromConfigMapName(
+  chart,
+  'settings',
+  'plone-settings',
+);
+
+// inside backend.environment.variables:
+//   LOG_LEVEL: Env.fromConfigMap(settings, 'log-level'),
+```
+
+## Set variables on the frontend
+
+The frontend accepts the same `environment` option as the backend.
+
+```typescript
+import { Plone, PloneVariant } from '@bluedynamics/cdk8s-plone';
+import { Env } from 'cdk8s-plus-30';
+
+new Plone(chart, 'plone', {
+  variant: PloneVariant.VOLTO,
+  frontend: {
+    image: 'plone/plone-frontend:16.0.0',
+    environment: {
+      variables: {
+        RAZZLE_API_PATH: Env.value('https://plone.example.com/++api++'),
+      },
+    },
+  },
+});
+```
+
+The Volto frontend automatically injects `RAZZLE_INTERNAL_API_PATH` when you do not set it.
+Override it through `environment` only when your service topology requires a non-default internal address.
+
+```typescript
+frontend: {
+  image: 'plone/plone-frontend:16.0.0',
+  environment: {
+    variables: {
+      RAZZLE_INTERNAL_API_PATH: Env.value('http://plone-backend:8080/Plone'),
+    },
+  },
+}
+```
+
+## Pull from a private registry
+
+Image registry credentials are not environment variables.
+List the names of existing pull secrets in the top-level `imagePullSecrets` option.
+
+```typescript
+new Plone(chart, 'plone', {
+  variant: PloneVariant.VOLTO,
+  imagePullSecrets: ['my-registry-credentials'],
+  backend: {
+    image: 'registry.example.com/plone-backend:6.1.3',
+  },
+  frontend: {
+    image: 'registry.example.com/plone-frontend:16.0.0',
+  },
+});
+```
+
+Create the pull secret beforehand with `kubectl create secret docker-registry <name>`.
+
+## Verify
+
+Synthesize the manifests and inspect the rendered Deployment for the expected entries.
+
+```shell
+cdk8s synth
+
+# Confirm literal values and secret references appear on the backend container
+grep -A 3 'RELSTORAGE_DSN' dist/*.yaml
+grep -B 1 -A 4 'secretKeyRef' dist/*.yaml
+```
+
+A `secretKeyRef` block in the output confirms the value resolves at runtime from the Secret rather than being stored in the manifest.
+After applying, check that the variables reach the container.
+
+```shell
+kubectl apply -f dist/
+kubectl exec -n <namespace> deployment/<plone-backend-deployment> -- env | grep RELSTORAGE_DSN
+```
+
+## See also
+
+- {doc}`/reference/api/index` — full construct and option reference.
+- {doc}`/reference/configuration-options` — guide to `environment` and `imagePullSecrets`.
+- {doc}`/how-to/configure-security-context` — harden the pods that run with these variables.

package/documentation/sources/how-to/configure-ingress-tls.md

@@ -0,0 +1,108 @@
+---
+myst:
+  html_meta:
+    "description": "Expose a cdk8s-plone deployment with a Kubernetes Ingress and TLS certificates from cert-manager."
+    "property=og:description": "Expose a cdk8s-plone deployment with a Kubernetes Ingress and TLS certificates from cert-manager."
+    "property=og:title": "Configure ingress and TLS"
+    "keywords": "Plone, cdk8s, Kubernetes, ingress, TLS, cert-manager, Traefik, Volto"
+---
+
+# Configure ingress and TLS
+
+This guide shows you how to expose a Plone deployment to the internet with a Kubernetes Ingress and TLS certificates from cert-manager.
+
+`cdk8s-plone` does not create ingress resources.
+It creates the Services you route to, and you add the ingress yourself.
+
+## Prerequisites
+
+- A working Plone deployment created with `cdk8s-plone`.
+- An ingress controller in the cluster, such as [Traefik](https://doc.traefik.io/traefik/) or [ingress-nginx](https://kubernetes.github.io/ingress-nginx/).
+- [cert-manager](https://cert-manager.io/) installed, with a `ClusterIssuer` for your certificate authority.
+- DNS records for your domains pointing at the ingress controller.
+
+## Identify the services to route to
+
+The constructs expose the Service names you need as read-only members:
+
+```typescript
+const plone = new Plone(chart, 'plone', {
+  backend: { image: 'plone/plone-backend:6.1.3' },
+  frontend: { image: 'plone/plone-frontend:16.0.0' },
+});
+
+const backendService = plone.backendServiceName;   // backend REST API, port 8080
+const frontendService = plone.frontendServiceName; // Volto frontend, port 3000 (Volto only)
+```
+
+Both Services name their port `http`, so reference them by that name in an Ingress.
+For the Blicca variant there is no frontend Service; route public traffic to the backend instead.
+When you run a cache, route public traffic to the cache Service from {doc}`/how-to/deploy-with-httpcache` or {doc}`/how-to/deploy-with-vinyl-cache`.
+
+## Add an Ingress with TLS
+
+Apply an Ingress that routes your domain to the frontend Service and requests a certificate through cert-manager.
+
+```yaml
+apiVersion: networking.k8s.io/v1
+kind: Ingress
+metadata:
+  name: plone
+  annotations:
+    cert-manager.io/cluster-issuer: letsencrypt-prod
+spec:
+  tls:
+    - hosts:
+        - plone.example.com
+      secretName: plone-tls
+  rules:
+    - host: plone.example.com
+      http:
+        paths:
+          - path: /
+            pathType: Prefix
+            backend:
+              service:
+                name: <frontendServiceName>
+                port:
+                  name: http
+```
+
+cert-manager watches the `tls` block and the `cluster-issuer` annotation, issues the certificate, and stores it in the `plone-tls` Secret.
+
+## Route a cache, an API, and a maintenance domain
+
+A production setup commonly uses three domains:
+
+- a public domain that points at the Varnish cache Service,
+- an uncached domain that points at the frontend Service for testing,
+- a maintenance domain that points at the backend Service for the Plone control panel.
+
+Add one `host` rule per domain, each with its own `tls` entry, pointing at the matching Service.
+
+```{tip}
+The [volto example](https://github.com/bluedynamics/cdk8s-plone/tree/main/examples/volto) implements this three-domain pattern with Traefik `IngressRoute` resources in `ingress.ts`.
+Use it as a complete, tested reference, including the Kong and Traefik variants.
+```
+
+## Verify
+
+Confirm the ingress and certificate exist and resolve:
+
+```shell
+kubectl get ingress -n <namespace>
+kubectl get certificate -n <namespace>
+kubectl describe certificate plone-tls -n <namespace>
+```
+
+Once the certificate is `Ready`, request the site over HTTPS:
+
+```shell
+curl -sI https://plone.example.com/
+```
+
+## See also
+
+- {doc}`/how-to/deploy-with-httpcache` — route public traffic through Varnish.
+- {doc}`/how-to/deploy-volto` — a full deployment that includes ingress and TLS.
+- {doc}`/reference/api/index` — `backendServiceName` and `frontendServiceName` reference.

package/documentation/sources/how-to/configure-security-context.md

@@ -7,11 +7,6 @@ myst:
     "keywords": "Plone, cdk8s, Kubernetes, security context, Pod Security Standards, hardening"
 ---
 
-```{image} ../_static/kup6s-icon-howto.svg
-:align: center
-:class: section-icon-large
-```
-
 # Configure security context
 
 <div class="page-metadata">

package/documentation/sources/how-to/deploy-blicca.md

@@ -18,7 +18,7 @@ Blicca is the new name for what Plone formerly called "Classic UI".
 The [Blicca example](https://github.com/bluedynamics/cdk8s-plone/tree/main/examples/blicca) provides Plone with server-side rendering:
 
 - **Plone 6.1 Blicca** (backend renders the UI, no separate frontend)
-- **PostgreSQL** with RelStorage (CloudNativePG or Bitnami)
+- **PostgreSQL** with RelStorage (plain PostgreSQL or CloudNativePG)
 - **Varnish HTTP caching** with kube-httpcache
 - **Ingress** with TLS (Traefik or Kong)
 - **Simpler architecture** (single backend service)
@@ -34,17 +34,17 @@ The [Blicca example](https://github.com/bluedynamics/cdk8s-plone/tree/main/examp
 
 :::{tip}
 Choose Blicca if you want a single backend service without a separate frontend, or if you need Blicca-specific add-ons.
-For the React single-page frontend approach, consider [Volto](deploy-production-volto.md).
+For the React single-page frontend approach, consider [Volto](deploy-volto.md).
 :::
 
 ## Prerequisites
 
-Same as the {ref}`production-volto-prerequisites` in the Production Volto guide, you need:
+Same as the {ref}`volto-prerequisites` in the Volto guide, you need:
 
 - Ingress controller (Traefik or Kong)
 - cert-manager
 - kube-httpcache operator
-- PostgreSQL operator (CloudNativePG or Bitnami)
+- PostgreSQL: plain single-instance (default, no operator) or the CloudNativePG operator
 
 See [Setup Prerequisites](setup-prerequisites.md) for detailed instructions.
 
@@ -89,7 +89,7 @@ CLUSTER_ISSUER=letsencrypt-prod
 # Optional: Custom backend image
 #PLONE_BACKEND_IMAGE=plone/plone-backend:6.1.3
 
-# Database: 'bitnami' or 'cloudnativepg'
+# Database: 'plain' or 'cloudnativepg'
 DATABASE=cloudnativepg
 ```
 
@@ -258,11 +258,11 @@ Some add-ons are Volto-specific. For Blicca:
 If you want to migrate from Blicca to Volto later:
 
 1. Keep your backend deployment (same configuration)
-2. Add Volto frontend from the [Volto example](deploy-production-volto.md)
+2. Add Volto frontend from the [Volto example](deploy-volto.md)
 3. Update ingress to route to frontend
 4. Both UIs can run simultaneously during migration
 
-See the [Production Volto deployment guide](deploy-production-volto.md) for details.
+See the [Volto deployment guide](deploy-volto.md) for details.
 
 ## Customization
 
@@ -328,7 +328,7 @@ kubectl delete -f dist/plone-blicca.k8s.yaml
 
 ## See also
 
-- {doc}`deploy-production-volto` — For the React single-page frontend.
+- {doc}`deploy-volto` — For the React single-page frontend.
 - {doc}`setup-prerequisites` — Cluster requirements.
 - {doc}`/reference/configuration-options` — API reference.
 - [Plone 6 Classic UI documentation](https://6.docs.plone.org/classic-ui/)

package/documentation/sources/how-to/{deploy-production-volto.md → deploy-volto.md}

@@ -3,25 +3,25 @@ myst:
   html_meta:
     "description": "Deploy the production-ready Volto example: React frontend, Plone REST API backend, PostgreSQL, Varnish caching, and ingress with TLS."
     "property=og:description": "Deploy the production-ready Volto example: React frontend, Plone REST API backend, PostgreSQL, Varnish caching, and ingress with TLS."
-    "property=og:title": "Deploy production Volto example"
+    "property=og:title": "Deploy the Volto example"
     "keywords": "Plone, cdk8s, Kubernetes, Volto, production, PostgreSQL, Varnish, ingress, TLS"
 ---
 
-# Deploy production Volto example
+# Deploy the Volto example
 
 This guide shows you how to deploy the production-ready Volto example to your Kubernetes cluster.
 
 ## What you'll deploy
 
-The [Production Volto example](https://github.com/bluedynamics/cdk8s-plone/tree/main/examples/production-volto) includes:
+The [Volto example](https://github.com/bluedynamics/cdk8s-plone/tree/main/examples/volto) includes:
 
 - **Plone 6.1 with Volto** (React frontend + REST API backend)
-- **PostgreSQL** with RelStorage (CloudNativePG or Bitnami)
+- **PostgreSQL** with RelStorage (plain PostgreSQL or CloudNativePG)
 - **Varnish HTTP caching** with kube-httpcache
 - **Ingress** with TLS (Traefik or Kong)
 - **Three access domains** (cached, uncached, maintenance)
 
-(production-volto-prerequisites)=
+(volto-prerequisites)=
 
 ## Prerequisites
 
@@ -43,16 +43,13 @@ Ensure you have these installed on your cluster:
    kubectl apply -f https://github.com/mittwald/kube-httpcache/releases/latest/download/kube-httpcache.yaml
    ```
 
-4. **PostgreSQL Operator** - Choose one:
+4. **PostgreSQL** - The example provisions the database itself; choose the backend with the `DATABASE` variable in Step 4. Prepare the cluster for your choice:
 
-   **Option A: CloudNativePG** (recommended for production):
-   ```shell
-   kubectl apply -f https://raw.githubusercontent.com/cloudnative-pg/cloudnative-pg/release-1.24/releases/cnpg-1.24.0.yaml
-   ```
+   **Option A: plain** (default; no operator needed) - the example deploys a single-instance PostgreSQL StatefulSet using the official `postgres` image, so there is nothing to install.
 
-   **Option B: Bitnami** (simpler for testing):
+   **Option B: CloudNativePG** (recommended for production HA) - install the operator:
    ```shell
-   kubectl create namespace plone
+   kubectl apply -f https://raw.githubusercontent.com/cloudnative-pg/cloudnative-pg/release-1.24/releases/cnpg-1.24.0.yaml
    ```
 
 ### Local tools
@@ -67,7 +64,7 @@ Clone the repository and navigate to the example:
 
 ```shell
 git clone https://github.com/bluedynamics/cdk8s-plone.git
-cd cdk8s-plone/examples/production-volto
+cd cdk8s-plone/examples/volto
 ```
 
 ## Step 2: Install dependencies
@@ -110,14 +107,14 @@ CLUSTER_ISSUER=letsencrypt-prod
 
 # Optional: Custom images
 #PLONE_BACKEND_IMAGE=plone/plone-backend:6.1.3
-#PLONE_FRONTEND_IMAGE=plone/plone-frontend:latest
+#PLONE_FRONTEND_IMAGE=plone/plone-frontend:16.0.0
 
-# Database: 'bitnami' or 'cloudnativepg'
-DATABASE=cloudnativepg
+# Database: 'plain' or 'cloudnativepg'
+DATABASE=plain
 ```
 
 :::{tip}
-For production, use `cloudnativepg` for high availability. For testing, `bitnami` is simpler.
+For production high availability, use `cloudnativepg`. For development and small setups, `plain` is simpler and needs no operator.
 :::
 
 ## Step 5: Generate manifests
@@ -188,7 +185,7 @@ You should see:
 - `plone-backend` (backend service)
 - `plone-frontend` (frontend service)
 - `plone-httpcache` (Varnish cache)
-- Database service (Bitnami or CloudNativePG)
+- Database service (plain PostgreSQL or CloudNativePG)
 
 ## Step 10: Check ingress
 
@@ -253,14 +250,12 @@ kubectl get cluster
 kubectl get secret -l cnpg.io/cluster
 ```
 
-**Bitnami:**
+**Plain PostgreSQL:**
 
 ```shell
-# Check service
-kubectl get svc -l app.kubernetes.io/name=postgresql
-
-# Check secret
-kubectl describe secret <postgresql-secret-name>
+# Check the StatefulSet and pod
+kubectl get statefulset -l app.kubernetes.io/name=plone-postgresql
+kubectl get pods -l app.kubernetes.io/name=plone-postgresql
 ```
 
 ### TLS certificate issues
@@ -319,7 +314,7 @@ kubectl delete -f dist/plone-example.k8s.yaml
 ## Next steps
 
 - Configure monitoring and metrics through {doc}`enable-prometheus-monitoring`.
-- Customize [Varnish caching rules](https://github.com/bluedynamics/cdk8s-plone/blob/main/examples/production-volto/config/varnish.tpl.vcl).
+- Customize [Varnish caching rules](https://github.com/bluedynamics/cdk8s-plone/blob/main/examples/volto/config/varnish.tpl.vcl).
 - Harden pods with {doc}`configure-security-context`.
 
 ## See also