@bluedynamics/cdk8s-plone 0.1.43 → 0.1.45

package/documentation/sources/how-to/deploy-with-httpcache.md

@@ -0,0 +1,224 @@
+---
+myst:
+  html_meta:
+    "description": "Deploy the PloneHttpcache Varnish cache via the mittwald kube-httpcache Helm chart and attach it to a Plone deployment."
+    "property=og:description": "Deploy the PloneHttpcache Varnish cache via the mittwald kube-httpcache Helm chart and attach it to a Plone deployment."
+    "property=og:title": "Deploy with PloneHttpcache"
+    "keywords": "Plone, cdk8s, Kubernetes, Varnish, kube-httpcache, mittwald, PloneHttpcache, caching, VCL"
+---
+
+# Deploy with PloneHttpcache
+
+This guide shows you how to deploy the `PloneHttpcache` Varnish cache and attach it to an existing Plone instance.
+
+`PloneHttpcache` deploys Varnish through the [mittwald kube-httpcache](https://github.com/mittwald/kube-httpcache) Helm chart.
+The construct renders that chart at synth time, so the cache is part of your own manifests.
+For an operator-managed alternative, see {doc}`/how-to/deploy-with-vinyl-cache`.
+
+## Prerequisites
+
+- A running Plone deployment created with `cdk8s-plone` (see {doc}`/tutorials/01-quick-start`).
+- The `helm` CLI available wherever you run `cdk8s synth`.
+- A Kubernetes `Secret` holding the Varnish admin credentials, referenced through `existingSecret`.
+- amd64 worker nodes.
+
+The construct renders the kube-httpcache Helm chart locally, so you do not pre-install a controller in the cluster.
+The pod `nodeSelector` is hard-coded to `kubernetes.io/arch=amd64` (a kube-httpcache workaround), so `PloneHttpcache` pods only schedule on amd64 nodes.
+There is no `nodeSelector` option on this construct.
+
+Create the admin credentials Secret before you deploy:
+
+```shell
+kubectl create secret generic varnish-admin \
+  --namespace <namespace> \
+  --from-literal=secret="$(head -c32 /dev/urandom | base64)"
+```
+
+## Attach a basic PloneHttpcache
+
+Construct `PloneHttpcache` with a `plone` reference, the `existingSecret`, and a `replicas` count.
+
+```typescript
+import { Plone, PloneHttpcache } from '@bluedynamics/cdk8s-plone';
+
+const plone = new Plone(chart, 'plone', {
+  backend: { image: 'plone/plone-backend:6.1.3' },
+  frontend: { image: 'plone/plone-frontend:16.0.0' },
+});
+
+new PloneHttpcache(chart, 'cache', {
+  plone: plone,
+  existingSecret: 'varnish-admin',
+  replicas: 2,
+});
+```
+
+RBAC for the rendered controller is always enabled; there is nothing to configure.
+
+## Set resources
+
+Tune the CPU and memory requests and limits to match your workload.
+
+```typescript
+new PloneHttpcache(chart, 'cache', {
+  plone: plone,
+  existingSecret: 'varnish-admin',
+  requestCpu: '200m',
+  limitCpu: '1',
+  requestMemory: '256Mi',
+  limitMemory: '1Gi',
+});
+```
+
+The defaults are `requestCpu: '100m'`, `limitCpu: '500m'`, `requestMemory: '100Mi'`, and `limitMemory: '500Mi'`.
+
+## Customize the VCL
+
+Provide an inline VCL through `varnishVcl`, which takes precedence over `varnishVclFile`.
+
+```typescript
+new PloneHttpcache(chart, 'cache', {
+  plone: plone,
+  existingSecret: 'varnish-admin',
+  varnishVcl: `
+vcl 4.1;
+backend default {
+  .host = "{{ .Env.BACKEND_SERVICE_NAME }}";
+  .port = "{{ .Env.BACKEND_SERVICE_PORT }}";
+}
+`,
+});
+```
+
+Alternatively, point `varnishVclFile` at a VCL template file on disk; the construct reads it at synth time.
+When you set neither option, the construct uses the built-in `config/varnish.tpl.vcl`.
+
+```typescript
+new PloneHttpcache(chart, 'cache', {
+  plone: plone,
+  existingSecret: 'varnish-admin',
+  varnishVclFile: './config/varnish.tpl.vcl',
+});
+```
+
+VCL templates use Go template syntax.
+The construct supplies these environment variables: `BACKEND_SERVICE_NAME`, `BACKEND_SERVICE_PORT`, `BACKEND_SITE_ID`, `FRONTEND_SERVICE_NAME`, and `FRONTEND_SERVICE_PORT`.
+Reference them as `{{ .Env.NAME }}`.
+
+Add your own variables through `extraEnvVars`, which are appended to the built-in set.
+
+```typescript
+new PloneHttpcache(chart, 'cache', {
+  plone: plone,
+  existingSecret: 'varnish-admin',
+  extraEnvVars: [
+    { name: 'THUMBOR_SERVICE_NAME', value: 'my-thumbor' },
+  ],
+});
+```
+
+Reference an extra variable in your VCL template as `{{ .Env.THUMBOR_SERVICE_NAME }}`.
+
+## Schedule the cache pods
+
+Add `tolerations` so the cache pods can run on tainted nodes.
+
+```typescript
+new PloneHttpcache(chart, 'cache', {
+  plone: plone,
+  existingSecret: 'varnish-admin',
+  tolerations: [
+    { key: 'dedicated', operator: 'Equal', value: 'cache', effect: 'NoSchedule' },
+  ],
+});
+```
+
+Omit `effect` to tolerate every taint for the given key.
+`operator` defaults to `'Equal'`.
+
+## Enable monitoring
+
+Set `servicemonitor` to emit a Prometheus `ServiceMonitor`, and keep `exporterEnabled` so the Varnish exporter sidecar is present for it to scrape.
+
+```typescript
+new PloneHttpcache(chart, 'cache', {
+  plone: plone,
+  existingSecret: 'varnish-admin',
+  servicemonitor: true,
+  exporterEnabled: true,
+});
+```
+
+`exporterEnabled` defaults to `true`, and `servicemonitor` defaults to `false`.
+Use `servicemonitor` here; there is no `monitoring` option on this construct.
+For the full monitoring setup, see {doc}`/how-to/enable-prometheus-monitoring`.
+
+## Pin the chart and image versions
+
+Set `chartVersion` to pin the kube-httpcache Helm chart, and `appVersion` to pin the image tag.
+
+```typescript
+new PloneHttpcache(chart, 'cache', {
+  plone: plone,
+  existingSecret: 'varnish-admin',
+  chartVersion: '0.13.1',
+  appVersion: '0.13.1',
+});
+```
+
+`chartVersion` defaults to the latest chart, and `appVersion` defaults to `chartVersion`.
+
+## Point your ingress at the cache
+
+Route external traffic through the cache by using the read-only `httpcacheServiceName` output as your Ingress or IngressRoute upstream instead of the Plone frontend service.
+
+```typescript
+const cache = new PloneHttpcache(chart, 'cache', {
+  plone: plone,
+  existingSecret: 'varnish-admin',
+});
+
+const upstream = cache.httpcacheServiceName;
+```
+
+For the routing and TLS details, see {doc}`/how-to/configure-ingress-tls`.
+
+## Verify the cache
+
+Generate the manifests and confirm the cache resources are present.
+
+```shell
+cdk8s synth
+grep -l 'kube-httpcache' dist/*.yaml
+```
+
+Apply the manifests and inspect the rollout on the cluster.
+
+```shell
+kubectl apply -f dist/
+kubectl get pods -n <namespace>
+kubectl get service -n <namespace>
+```
+
+Send a request through the cache service and check the Varnish response headers.
+
+```shell
+kubectl run -it --rm curl --image=curlimages/curl --restart=Never -- \
+  curl -sI http://<httpcacheServiceName>.<namespace>:80/
+```
+
+A cached response carries an `X-Varnish` header, and an `Age` header greater than zero confirms a cache hit.
+
+## PloneHttpcache compared with PloneVinylCache
+
+`PloneHttpcache` runs Varnish from the mittwald kube-httpcache chart with a Secret and a VCL template that you supply.
+`PloneVinylCache` runs Varnish through the cloud-vinyl operator, which generates VCL from structured configuration and manages credentials for you.
+For the trade-offs between the two, see {doc}`/explanation/architecture` and {doc}`/how-to/deploy-with-vinyl-cache`.
+
+## See also
+
+- {doc}`/reference/api/index` — authoritative `PloneHttpcache` and `PloneHttpcacheOptions` reference.
+- {doc}`/reference/configuration-options` — guide to `varnishVcl`, `existingSecret`, `extraEnvVars`, and `servicemonitor`.
+- {doc}`/how-to/enable-prometheus-monitoring` — scrape the Varnish cache with Prometheus.
+- {doc}`/how-to/deploy-with-vinyl-cache` — operator-managed Varnish caching alternative.
+- [mittwald kube-httpcache](https://github.com/mittwald/kube-httpcache) — upstream controller and Helm chart.

package/documentation/sources/how-to/deploy-with-vinyl-cache.md

@@ -7,11 +7,6 @@ myst:
     "keywords": "Plone, cdk8s, Kubernetes, Varnish, cloud-vinyl, VinylCache, operator, caching"
 ---
 
-```{image} ../_static/kup6s-icon-howto.svg
-:align: center
-:class: section-icon-large
-```
-
 # Deploy with cloud-vinyl cache
 
 <div class="page-metadata">

package/documentation/sources/how-to/enable-prometheus-monitoring.md

@@ -7,11 +7,6 @@ myst:
     "keywords": "Plone, cdk8s, Kubernetes, Prometheus, ServiceMonitor, monitoring, metrics"
 ---
 
-```{image} ../_static/kup6s-icon-howto.svg
-:align: center
-:class: section-icon-large
-```
-
 # Enable Prometheus monitoring
 
 <div class="page-metadata">
@@ -93,6 +88,10 @@ new PloneVinylCache(chart, 'cache', {
 });
 ```
 
+```{note}
+The option name differs by construct: backend, frontend, and `PloneHttpcache` use `servicemonitor`, while `PloneVinylCache` uses `monitoring`. Both create a Prometheus `ServiceMonitor`.
+```
+
 ## Verify the rollout
 
 ```shell

package/documentation/sources/how-to/index.md

@@ -7,11 +7,6 @@ myst:
     "keywords": "Plone, cdk8s, Kubernetes, how-to, deployment, configuration"
 ---
 
-```{image} ../_static/kup6s-icon-howto.svg
-:align: center
-:class: section-icon-large
-```
-
 # How-to guides
 
 **Goal-oriented guides showing you how to solve specific problems with cdk8s-plone.**
@@ -39,8 +34,9 @@ setup-prerequisites
 maxdepth: 1
 titlesonly: true
 ---
-deploy-production-volto
+deploy-volto
 deploy-blicca
+deploy-with-httpcache
 deploy-with-vinyl-cache
 ```
 
@@ -51,11 +47,13 @@ deploy-with-vinyl-cache
 maxdepth: 1
 titlesonly: true
 ---
+configure-env-and-secrets
 configure-security-context
 schedule-pods
+configure-ingress-tls
 ```
 
-## Operations & maintenance
+## Operations and maintenance
 
 ```{toctree}
 ---
@@ -63,11 +61,20 @@ maxdepth: 1
 titlesonly: true
 ---
 enable-prometheus-monitoring
+scale-and-high-availability
+upgrade-and-rollout
+backup-and-restore
 ```
 
 ## Troubleshooting
 
-*This section will be populated with troubleshooting guides in future releases.*
+```{toctree}
+---
+maxdepth: 1
+titlesonly: true
+---
+troubleshooting
+```
 
 ---
 

package/documentation/sources/how-to/scale-and-high-availability.md

@@ -0,0 +1,122 @@
+---
+myst:
+  html_meta:
+    "description": "Scale the Plone backend and frontend with cdk8s-plone, configure a PodDisruptionBudget, and add a HorizontalPodAutoscaler."
+    "property=og:description": "Scale the Plone backend and frontend with cdk8s-plone, configure a PodDisruptionBudget, and add a HorizontalPodAutoscaler."
+    "property=og:title": "Scale and run highly available"
+    "keywords": "Plone, cdk8s, Kubernetes, scaling, replicas, PodDisruptionBudget, HPA, high availability"
+---
+
+# Scale and run highly available
+
+This guide shows you how to run more than one replica of the Plone backend and frontend, protect them with a PodDisruptionBudget, and add a HorizontalPodAutoscaler.
+
+## Prerequisites
+
+- A working Plone deployment created with `cdk8s-plone`.
+- A PostgreSQL backend reachable by every backend replica.
+
+The backend uses RelStorage on PostgreSQL, so several backend replicas share one database and scale horizontally.
+The Volto frontend is stateless and scales horizontally as well.
+
+## Set the replica count
+
+Set `replicas` on `backend` and `frontend` independently.
+
+```typescript
+import { Plone, PloneVariant } from '@bluedynamics/cdk8s-plone';
+
+new Plone(chart, 'plone', {
+  variant: PloneVariant.VOLTO,
+  backend: {
+    image: 'plone/plone-backend:6.1.3',
+    replicas: 3,
+  },
+  frontend: {
+    image: 'plone/plone-frontend:16.0.0',
+    replicas: 2,
+  },
+});
+```
+
+Both default to `2` replicas when you omit the option.
+
+## Protect availability with a PodDisruptionBudget
+
+A PodDisruptionBudget keeps a minimum number of pods running during voluntary disruptions such as node drains.
+
+Set `minAvailable` or `maxUnavailable` on the component.
+Each accepts an absolute number or a percentage string such as `"50%"`.
+
+```typescript
+backend: {
+  image: 'plone/plone-backend:6.1.3',
+  replicas: 5,
+  minAvailable: 3,
+}
+```
+
+`cdk8s-plone` creates the PodDisruptionBudget automatically when `replicas` is `2` or more, or when you set `minAvailable` or `maxUnavailable` explicitly.
+A single replica with no explicit setting gets no PodDisruptionBudget.
+The generated PodDisruptionBudget always sets `unhealthyPodEvictionPolicy: AlwaysAllow`, so unhealthy pods never block a node drain.
+
+## Add a HorizontalPodAutoscaler
+
+`cdk8s-plone` emits plain Deployments and does not configure autoscaling.
+To scale on load, add your own HorizontalPodAutoscaler that targets the generated backend Deployment.
+
+Find the Deployment name from the synthesized manifests:
+
+```shell
+cdk8s synth
+grep -A2 'kind: Deployment' dist/*.yaml | grep 'name:'
+```
+
+Add the autoscaler as a Kubernetes manifest and apply it alongside your deployment:
+
+```yaml
+apiVersion: autoscaling/v2
+kind: HorizontalPodAutoscaler
+metadata:
+  name: plone-backend
+spec:
+  scaleTargetRef:
+    apiVersion: apps/v1
+    kind: Deployment
+    name: <backend-deployment-name>
+  minReplicas: 2
+  maxReplicas: 8
+  metrics:
+    - type: Resource
+      resource:
+        name: cpu
+        target:
+          type: Utilization
+          averageUtilization: 70
+```
+
+The HorizontalPodAutoscaler needs [metrics-server](https://github.com/kubernetes-sigs/metrics-server) in the cluster.
+Keep `minReplicas` at `2` or more so the PodDisruptionBudget stays effective.
+
+## Verify
+
+Confirm the PodDisruptionBudget is present in the synthesized manifests:
+
+```shell
+cdk8s synth
+grep -l 'kind: PodDisruptionBudget' dist/*.yaml
+```
+
+Inspect the running objects on the cluster:
+
+```shell
+kubectl get deploy -n <namespace>
+kubectl get pdb -n <namespace>
+kubectl get hpa -n <namespace>
+```
+
+## See also
+
+- {doc}`/reference/api/index` — authoritative `replicas`, `minAvailable`, and `maxUnavailable` reference.
+- {doc}`/how-to/schedule-pods` — place the extra replicas on specific nodes.
+- {doc}`/explanation/architecture` — how the backend, frontend, and database fit together.

package/documentation/sources/how-to/schedule-pods.md

@@ -7,11 +7,6 @@ myst:
     "keywords": "Plone, cdk8s, Kubernetes, nodeSelector, tolerations, scheduling, taints"
 ---
 
-```{image} ../_static/kup6s-icon-howto.svg
-:align: center
-:class: section-icon-large
-```
-
 # Schedule pods to specific nodes
 
 <div class="page-metadata">

package/documentation/sources/how-to/troubleshooting.md

@@ -0,0 +1,113 @@
+---
+myst:
+  html_meta:
+    "description": "Diagnose and fix common cdk8s-plone problems: pods not scheduling, crashes, failing probes, database connection errors, and synth failures."
+    "property=og:description": "Diagnose and fix common cdk8s-plone problems: pods not scheduling, crashes, failing probes, database connection errors, and synth failures."
+    "property=og:title": "Troubleshoot a deployment"
+    "keywords": "Plone, cdk8s, Kubernetes, troubleshooting, CrashLoopBackOff, probes, scheduling, synth"
+---
+
+# Troubleshoot a deployment
+
+This guide shows you how to diagnose and fix the problems you are most likely to hit when you deploy Plone with `cdk8s-plone`.
+
+Start by looking at the overall state, then drill into the failing object.
+
+```shell
+kubectl get pods -n <namespace>
+kubectl describe pod <pod> -n <namespace>
+kubectl logs <pod> -n <namespace>
+```
+
+## `cdk8s synth` fails
+
+If `synth` fails while rendering `PloneHttpcache`, confirm the `helm` CLI is installed and on your `PATH`.
+`PloneHttpcache` renders the kube-httpcache Helm chart at synth time and shells out to `helm`.
+
+If `synth` fails on a missing custom resource type, run the example's import step (`npm run import`) to regenerate the CRD bindings.
+
+## Pods stay `Pending`
+
+Describe the pod and read the `Events` section for the scheduler's reason.
+
+```shell
+kubectl describe pod <pod> -n <namespace>
+```
+
+Common causes:
+
+- Insufficient CPU or memory on the nodes. Lower `requestCpu` or `requestMemory`, or add capacity.
+- A `nodeSelector` or `tolerations` setting that no node satisfies. See {doc}`/how-to/schedule-pods`.
+- `PloneHttpcache` pods only schedule on amd64 nodes, because the construct hard-codes `kubernetes.io/arch=amd64`. Provide an amd64 node or use {doc}`/how-to/deploy-with-vinyl-cache` instead.
+
+## A pod is in `CrashLoopBackOff`
+
+Read the logs of the current and previous container starts.
+
+```shell
+kubectl logs <pod> -n <namespace>
+kubectl logs <pod> -n <namespace> --previous
+```
+
+A backend that exits immediately almost always cannot reach its database.
+See {ref}`backend-db-connection`.
+
+(backend-db-connection)=
+
+## The backend cannot reach the database
+
+The backend uses RelStorage on PostgreSQL, so it needs a correct connection string and credentials.
+
+- Confirm the database is running and reachable from the backend namespace.
+- Confirm the environment variable that carries the DSN resolves from its Secret. See {doc}`/how-to/configure-env-and-secrets`.
+
+```shell
+kubectl get secret -n <namespace>
+kubectl exec -n <namespace> deployment/<backend-deployment> -- env | grep -i storage
+```
+
+## Pods never become ready
+
+A pod that stays `Running` but never `Ready` is failing its readiness probe.
+
+- Increase `readinessInitialDelaySeconds` if the backend needs longer to start.
+- Increase `readinessTimeoutSeconds` or `readinessFailureThreshold` for a slow first request.
+
+```typescript
+backend: {
+  image: 'plone/plone-backend:6.1.3',
+  readinessInitialDelaySeconds: 30,
+  readinessTimeoutSeconds: 15,
+}
+```
+
+Liveness probes are disabled by default (`livenessEnabled` defaults to `false`).
+If pods restart in a loop after you enable liveness, raise `livenessInitialDelaySeconds` so the probe does not fire during startup.
+
+## The cache does not cache
+
+Check the cache pod logs, then confirm requests reach the cache service rather than the backend or frontend directly.
+
+```shell
+kubectl logs -n <namespace> -l app.kubernetes.io/part-of=plone
+kubectl run -it --rm curl --image=curlimages/curl --restart=Never -- \
+  curl -sI http://<cache-service>.<namespace>:80/
+```
+
+A missing `X-Varnish` header means traffic bypasses the cache; point your ingress at the cache service. See {doc}`/how-to/configure-ingress-tls`.
+For VCL behavior, see {doc}`/how-to/deploy-with-httpcache` and {doc}`/how-to/deploy-with-vinyl-cache`.
+
+## Prometheus does not scrape the metrics
+
+If a `ServiceMonitor` exists but no target appears in Prometheus, the selectors do not match.
+
+- Confirm the `ServiceMonitor` namespace matches the `Prometheus` resource's `serviceMonitorNamespaceSelector`.
+- Confirm its labels match the `Prometheus` resource's `serviceMonitorSelector`.
+
+See {doc}`/how-to/enable-prometheus-monitoring` for the full setup.
+
+## See also
+
+- {doc}`/how-to/deploy-volto` — a complete deployment to compare against.
+- {doc}`/reference/api/index` — authoritative option and default reference.
+- {doc}`/explanation/architecture` — how the components depend on each other.

package/documentation/sources/how-to/upgrade-and-rollout.md

@@ -0,0 +1,89 @@
+---
+myst:
+  html_meta:
+    "description": "Upgrade the Plone image and the cdk8s-plone library, roll out changes safely, and roll back a failed update."
+    "property=og:description": "Upgrade the Plone image and the cdk8s-plone library, roll out changes safely, and roll back a failed update."
+    "property=og:title": "Upgrade and roll out"
+    "keywords": "Plone, cdk8s, Kubernetes, upgrade, rollout, rolling update, rollback, migration"
+---
+
+# Upgrade and roll out
+
+This guide shows you how to upgrade the Plone images and the `cdk8s-plone` library, roll the change out safely, and roll it back if it fails.
+
+## Prerequisites
+
+- A working Plone deployment created with `cdk8s-plone`.
+- Two or more replicas if you need a zero-downtime rollout. See {doc}`/how-to/scale-and-high-availability`.
+
+## Upgrade the Plone image
+
+Change the `image` tag on `backend` and `frontend` to the new version.
+
+```typescript
+backend: {
+  image: 'plone/plone-backend:6.1.4',
+},
+frontend: {
+  image: 'plone/plone-frontend:16.1.0',
+}
+```
+
+Pin a specific tag rather than `latest`, so the rollout is reproducible and you can roll back to a known version.
+
+Regenerate the manifests and apply them:
+
+```shell
+cdk8s synth
+kubectl apply -f dist/
+```
+
+Kubernetes replaces the pods with the default RollingUpdate strategy.
+With two or more replicas and a PodDisruptionBudget, the old pods drain only as new pods become ready.
+
+```{important}
+Upgrading to a new Plone major or minor version may require a Plone site upgrade step that `cdk8s-plone` does not perform.
+After the new backend pods are ready, run the upgrade from the Plone control panel (`@@plone-upgrade`) on the maintenance or uncached route.
+```
+
+## Watch the rollout
+
+Follow the rollout and confirm it completes.
+
+```shell
+kubectl rollout status deployment/<backend-deployment> -n <namespace>
+kubectl get pods -n <namespace> -w
+```
+
+## Roll back a failed upgrade
+
+If the new version misbehaves, undo the rollout to the previous ReplicaSet:
+
+```shell
+kubectl rollout undo deployment/<backend-deployment> -n <namespace>
+```
+
+To return to a known-good definition instead, restore the previous image tag in your code, then `cdk8s synth` and `kubectl apply -f dist/` again.
+
+```{warning}
+A rollback reverts the container image, not your data.
+If the upgrade ran an irreversible Plone site migration, restore the database from a backup. See {doc}`/how-to/backup-and-restore`.
+```
+
+## Upgrade the cdk8s-plone library
+
+Bump the dependency, regenerate, and review the manifest diff before applying.
+
+```shell
+npm install @bluedynamics/cdk8s-plone@latest
+cdk8s synth
+git diff dist/
+```
+
+Read the [changelog](https://github.com/bluedynamics/cdk8s-plone/releases) for renamed or deprecated options, then apply the reviewed manifests.
+
+## See also
+
+- {doc}`/how-to/scale-and-high-availability` — replicas and PodDisruptionBudget for zero-downtime rollouts.
+- {doc}`/how-to/backup-and-restore` — back up before a risky upgrade.
+- {doc}`/reference/api/index` — authoritative option reference for each release.