@bluedynamics/cdk8s-plone 0.1.42 → 0.1.44

package/documentation/sources/reference/configuration-options.md

@@ -1,142 +1,84 @@
 ---
 myst:
   html_meta:
-    "description": "Complete reference for cdk8s-plone constructs and configuration options: Plone, PloneHttpcache, PloneVinylCache."
-    "property=og:description": "Complete reference for cdk8s-plone constructs and configuration options: Plone, PloneHttpcache, PloneVinylCache."
-    "property=og:title": "Configuration options"
-    "keywords": "Plone, cdk8s, Kubernetes, configuration, reference, Volto, Varnish"
+    "description": "Task-oriented configuration guide for cdk8s-plone with copy-pasteable examples, linking to the generated API reference."
+    "property=og:description": "Task-oriented configuration guide for cdk8s-plone with copy-pasteable examples, linking to the generated API reference."
+    "property=og:title": "Configuration guide"
+    "keywords": "Plone, cdk8s, Kubernetes, configuration, Volto, Blicca, Varnish"
 ---
 
-# Configuration options
+# Configuration guide
 
-Complete reference for all configuration options in cdk8s-plone.
+This guide shows the most common ways to configure cdk8s-plone, grouped by task, with copy-pasteable examples.
 
-## Key constructs
-
-### `Plone`
-
-Main construct for deploying Plone CMS. Supports two variants:
-- **VOLTO**: React single-page frontend talking to the REST API backend (default)
-- **BLICCA**: the Plone backend renders the UI server-side and serves HTML directly
+```{important}
+For the complete and authoritative list of every construct, option, type, default value, and whether it is required, see the {doc}`API reference <api/index>`.
+That reference is generated from the TypeScript source, so it never drifts.
+This guide is hand-written orientation and deliberately does **not** repeat the full option tables.
+```
 
-**Properties:**
-- `backendServiceName` - Name of the backend Kubernetes service
-- `frontendServiceName` - Name of the frontend service (VOLTO only)
-- `variant` - Deployment variant (VOLTO or BLICCA)
-- `siteId` - Plone site ID in ZODB (default: 'Plone')
+## Constructs at a glance
 
-**Example:**
-```typescript
-import { Plone, PloneVariant } from '@bluedynamics/cdk8s-plone';
+`Plone`
+:   Deploys the Plone backend and, for the Volto variant, the React frontend, plus their services and (optionally) a `PodDisruptionBudget` and `ServiceMonitor`. This is the entry point.
 
-new Plone(chart, 'my-plone', {
-  variant: PloneVariant.VOLTO,
-  siteId: 'MySite',
-  backend: {
-    image: 'plone/plone-backend:6.1.3',
-    replicas: 3,
-  },
-  frontend: {
-    image: 'plone/plone-frontend:16.0.0',
-    replicas: 2,
-  },
-});
-```
+`PloneHttpcache`
+:   Adds a Varnish caching layer through the mittwald [kube-httpcache](https://github.com/mittwald/kube-httpcache) Helm chart. Self-contained: it needs no operator in the cluster.
 
----
+`PloneVinylCache`
+:   Adds a Varnish caching layer through the [cloud-vinyl](https://github.com/bluedynamics/cloud-vinyl) operator. Requires the operator to be installed in the cluster.
 
-### `PloneHttpcache`
+To choose between the two cache constructs, read {doc}`/explanation/architecture`.
 
-Varnish HTTP caching layer using the [kube-httpcache](https://github.com/mittwald/kube-httpcache) Helm chart. Provides cluster-wide cache invalidation.
+## Choose a frontend variant
 
-**Properties:**
-- `httpcacheServiceName` - Name of the Varnish service
+The `Plone` construct deploys one of two frontends, selected with `variant`:
 
-**Example:**
 ```typescript
-import { PloneHttpcache } from '@bluedynamics/cdk8s-plone';
+import { Plone, PloneVariant } from '@bluedynamics/cdk8s-plone';
 
-new PloneHttpcache(chart, 'cache', {
-  plone: ploneInstance,
-  existingSecret: 'varnish-secret',
-  replicas: 2,
+// Volto: React single-page frontend talking to the REST API backend (default).
+new Plone(chart, 'plone', {
+  variant: PloneVariant.VOLTO,
+  backend: {},
+  frontend: {},
 });
-```
-
----
-
-## Configuration interfaces
-
-### `PloneOptions`
 
-Main configuration interface for the Plone construct.
-
-| Property | Type | Required | Default | Description |
-|----------|------|----------|---------|-------------|
-| `version` | `string` | No | - | Version of your project |
-| `siteId` | `string` | No | `'Plone'` | Plone site ID in ZODB |
-| `variant` | `PloneVariant` | No | `VOLTO` | Deployment variant (VOLTO or BLICCA) |
-| `backend` | `PloneBaseOptions` | Yes | - | Backend configuration |
-| `frontend` | `PloneBaseOptions` | Conditional | - | Frontend configuration (required for VOLTO) |
-| `imagePullSecrets` | `string[]` | No | - | Image pull secrets for private registries |
-
-**Example:**
-```typescript
-const options: PloneOptions = {
-  version: '1.0.0',
-  siteId: 'MySite',
-  variant: PloneVariant.VOLTO,
-  backend: { /* ... */ },
-  frontend: { /* ... */ },
-  imagePullSecrets: ['my-registry-secret'],
-};
+// Blicca: the backend renders the UI server-side, so there is no separate frontend.
+new Plone(chart, 'plone', {
+  variant: PloneVariant.BLICCA,
+  backend: {},
+});
 ```
 
----
+```{note}
+`PloneVariant.CLASSICUI` is a deprecated alias for `PloneVariant.BLICCA`, kept for backward compatibility.
+It keeps its legacy value (`'classicui'`), so existing configuration keeps working unchanged.
+The alias will be removed in a future major release.
+```
 
-### `PloneBaseOptions`
+For the conceptual difference between the variants, see {ref}`deployment-variants`.
 
-Configuration for backend or frontend components.
+## Configure the backend and frontend
 
-#### Container configuration
+Both `backend` and `frontend` take the same options (`PloneBaseOptions`).
+The examples below cover the common groups.
+See the {doc}`API reference <api/index>` for every field, its type, and its default.
 
-| Property | Type | Required | Default | Description |
-|----------|------|----------|---------|-------------|
-| `image` | `string` | No | `plone/plone-backend:latest` (backend) / `plone/plone-frontend:latest` (frontend) | Container image |
-| `imagePullPolicy` | `string` | No | `IfNotPresent` | Image pull policy |
-| `replicas` | `number` | No | `2` | Number of pod replicas |
-| `environment` | `Env` | No | - | Environment variables (cdk8s-plus-30 `Env`) |
+### Images and replicas
 
-**Example:**
 ```typescript
-import { Env } from 'cdk8s-plus-30';
-
 backend: {
   image: 'plone/plone-backend:6.1.3',
   replicas: 3,
   imagePullPolicy: 'Always',
-  environment: {
-    variables: {
-      SITE: Env.value('MySite'),
-      DEBUG_MODE: Env.value('off'),
-    },
-  },
 }
 ```
 
-#### Resource configuration
+### Resource requests and limits
 
-| Property | Type | Default | Description |
-|----------|------|---------|-------------|
-| `requestCpu` | `string` | `200m` | CPU request |
-| `limitCpu` | `string` | `500m` | CPU limit |
-| `requestMemory` | `string` | `256Mi` | Memory request |
-| `limitMemory` | `string` | `512Mi` (backend) / `1Gi` (frontend) | Memory limit |
-
-**Example:**
 ```typescript
 backend: {
-  image: 'plone/plone-backend:6.1.3',
   requestCpu: '500m',
   limitCpu: '2',
   requestMemory: '512Mi',
@@ -144,112 +86,36 @@ backend: {
 }
 ```
 
-#### High availability
+### High availability
 
-| Property | Type | Description |
-|----------|------|-------------|
-| `minAvailable` | `number \| string` | Minimum pods available during updates (for PodDisruptionBudget). Accepts an absolute number or a percentage string such as `"50%"`. |
-| `maxUnavailable` | `number \| string` | Maximum unavailable pods during updates. Accepts an absolute number or a percentage string such as `"50%"`. |
+A `PodDisruptionBudget` is created automatically when `replicas` is `2` or more, or when you set `minAvailable` or `maxUnavailable` explicitly.
+Both accept an absolute number or a percentage string such as `"50%"`.
 
-**Example:**
 ```typescript
 backend: {
-  image: 'plone/plone-backend:6.1.3',
   replicas: 5,
-  minAvailable: 3,  // At least 3 pods must be available during updates
+  minAvailable: 3, // keep at least 3 pods available during voluntary disruptions
 }
 ```
 
-#### Readiness probe
+### Probes
 
-| Property | Type | Default | Description |
-|----------|------|---------|-------------|
-| `readinessEnabled` | `boolean` | `true` | Enable readiness probe |
-| `readinessInitialDelaySeconds` | `number` | `10` | Seconds before first probe |
-| `readinessTimeoutSeconds` | `number` | `15` | Probe timeout |
-| `readinessPeriodSeconds` | `number` | `10` | Probe frequency |
-| `readinessSuccessThreshold` | `number` | `1` | Consecutive successes required |
-| `readinessFailureThreshold` | `number` | `3` | Consecutive failures before marking unready |
+Readiness probes are enabled by default; liveness probes are **disabled** by default.
 
-**Example:**
 ```typescript
-backend: {
-  image: 'plone/plone-backend:6.1.3',
+frontend: {
   readinessEnabled: true,
   readinessInitialDelaySeconds: 10,
-  readinessTimeoutSeconds: 5,
-  readinessPeriodSeconds: 10,
-  readinessFailureThreshold: 3,
-}
-```
-
-#### Liveness probe
-
-| Property | Type | Default | Description |
-|----------|------|---------|-------------|
-| `livenessEnabled` | `boolean` | `false` | Enable liveness probe (recommended `true` for frontend) |
-| `livenessInitialDelaySeconds` | `number` | `30` | Seconds before first probe |
-| `livenessTimeoutSeconds` | `number` | `5` | Probe timeout |
-| `livenessPeriodSeconds` | `number` | `10` | Probe frequency |
-| `livenessSuccessThreshold` | `number` | `1` | Consecutive successes required |
-| `livenessFailureThreshold` | `number` | `3` | Consecutive failures before restart |
-
-**Example:**
-```typescript
-frontend: {
-  image: 'plone/plone-frontend:16.0.0',
-  livenessEnabled: true,  // Recommended for frontend
+  livenessEnabled: true, // opt in; useful for the frontend
   livenessInitialDelaySeconds: 30,
-  livenessTimeoutSeconds: 5,
-  livenessPeriodSeconds: 30,
-  livenessFailureThreshold: 3,
-}
-```
-
-#### Annotations
-
-| Property | Type | Description |
-|----------|------|-------------|
-| `annotations` | `Record<string, string>` | Deployment metadata annotations |
-| `podAnnotations` | `Record<string, string>` | Pod template annotations (e.g., for Prometheus) |
-| `serviceAnnotations` | `Record<string, string>` | **Deprecated.** Use `service.annotations` instead. Service annotations (e.g., for external-dns) |
-
-**Example:**
-```typescript
-backend: {
-  image: 'plone/plone-backend:6.1.3',
-  podAnnotations: {
-    'prometheus.io/scrape': 'true',
-    'prometheus.io/port': '8080',
-  },
-  serviceAnnotations: {
-    'external-dns.alpha.kubernetes.io/hostname': 'backend.example.com',
-  },
 }
 ```
 
-#### Service
+### Service
 
 Configure the generated Kubernetes `Service` through the grouped `service` option.
-The `service` option is available on both `backend` and `frontend`.
-Curated fields cover the common cases.
-The `overrides` field is an escape hatch for any other `ServiceSpec` field, and it has the highest precedence.
-
-| Property | Type | Description |
-|----------|------|-------------|
-| `service.type` | `string` | Service type: `ClusterIP` (default), `NodePort`, `LoadBalancer`, or `ExternalName` |
-| `service.trafficDistribution` | `string` | Traffic distribution preference, for example `PreferClose` |
-| `service.sessionAffinity` | `string` | Session affinity: `ClientIP` or `None` |
-| `service.externalTrafficPolicy` | `string` | External traffic policy: `Cluster` or `Local` |
-| `service.internalTrafficPolicy` | `string` | Internal traffic policy: `Cluster` or `Local` |
-| `service.publishNotReadyAddresses` | `boolean` | Publish not-ready addresses |
-| `service.loadBalancerClass` | `string` | Load balancer implementation class |
-| `service.loadBalancerSourceRanges` | `string[]` | Allowed source IP ranges for a `LoadBalancer` service |
-| `service.annotations` | `Record<string, string>` | Service metadata annotations (replaces `serviceAnnotations`) |
-| `service.labels` | `Record<string, string>` | Extra Service metadata labels |
-| `service.overrides` | `Record<string, any>` | Raw `ServiceSpec` overrides as a free-form map, with the highest precedence |
-
-**Example:**
+Curated fields cover the common cases; `service.overrides` is an escape hatch for any other `ServiceSpec` field and has the highest precedence.
+
 ```typescript
 backend: {
   service: {
@@ -266,342 +132,64 @@ backend: {
 }
 ```
 
-(monitoring)=
-
-#### Prometheus monitoring
-
-| Property | Type | Default | Description |
-|----------|------|---------|-------------|
-| `servicemonitor` | `boolean` | `false` | Create a Prometheus `ServiceMonitor` for this component. Requires the Prometheus Operator. |
-| `metricsPort` | `string \| number` | main service port | Service port name or number that exposes metrics. |
-| `metricsPath` | `string` | `/metrics` | HTTP path the Prometheus scraper requests. |
-
-You must instrument the backend or frontend container to expose metrics at the configured endpoint.
-For step-by-step setup, see {doc}`/how-to/enable-prometheus-monitoring`.
-
-**Example:**
-```typescript
-backend: {
-  image: 'plone/plone-backend:6.1.3',
-  servicemonitor: true,
-  metricsPath: '/metrics',
-},
-frontend: {
-  image: 'plone/plone-frontend:16.0.0',
-  servicemonitor: true,
-  metricsPort: 9090,
-}
+```{note}
+The top-level `serviceAnnotations` option is deprecated. Use `service.annotations` instead.
 ```
 
-#### Scheduling
-
-| Property | Type | Default | Description |
-|----------|------|---------|-------------|
-| `nodeSelector` | `Record<string, string>` | - | Constrain pods to nodes whose labels match all entries. |
+### Environment variables
 
-For tainted nodes and taint-based scheduling, see {doc}`/how-to/schedule-pods`.
+Pass environment variables with the cdk8s-plus `Env` API, including values sourced from a `Secret`.
 
-**Example:**
 ```typescript
+import { Env } from 'cdk8s-plus-30';
+
 backend: {
-  image: 'plone/plone-backend:6.1.3',
-  nodeSelector: {
-    'topology.kubernetes.io/region': 'fsn1',
+  environment: {
+    variables: {
+      RELSTORAGE_DSN: Env.fromSecret(dbSecret, 'dsn'),
+    },
   },
 }
 ```
 
-#### Security context
-
-| Property | Type | Default | Description |
-|----------|------|---------|-------------|
-| `securityContext` | `PloneSecurityContext` | - | Container security settings (capabilities, UID/GID, read-only root, privilege escalation). |
+### Annotations, scheduling, security, and monitoring
 
-**`PloneSecurityContext` fields:**
+These groups each have a dedicated how-to guide:
 
-| Property | Type | Description |
-|----------|------|-------------|
-| `capabilities` | `PloneCapabilities` | Linux capabilities to add or drop. |
-| `runAsUser` | `number` | Run the container as this UID. |
-| `runAsGroup` | `number` | Run the container as this GID. |
-| `runAsNonRoot` | `boolean` | Require the container to run as non-root. |
-| `readOnlyRootFilesystem` | `boolean` | Mount the root filesystem read-only. |
-| `allowPrivilegeEscalation` | `boolean` | Allow the process to gain more privileges than its parent. |
-| `privileged` | `boolean` | Run the container in privileged mode. |
-
-**`PloneCapabilities` fields:**
-
-| Property | Type | Description |
-|----------|------|-------------|
-| `add` | `string[]` | Capabilities to add (e.g., `'SYS_PTRACE'`). |
-| `drop` | `string[]` | Capabilities to drop (e.g., `'ALL'`). |
+- {doc}`/how-to/schedule-pods` — `nodeSelector` and `tolerations`
+- {doc}`/how-to/configure-security-context` — `securityContext` hardening
+- {doc}`/how-to/enable-prometheus-monitoring` — `servicemonitor`, `metricsPort`, `metricsPath`
 
-For a hardening walk-through, see {doc}`/how-to/configure-security-context`.
+## Add a cache
 
-**Example:**
 ```typescript
-backend: {
-  image: 'plone/plone-backend:6.1.3',
-  securityContext: {
-    runAsNonRoot: true,
-    runAsUser: 500,
-    readOnlyRootFilesystem: true,
-    allowPrivilegeEscalation: false,
-    capabilities: {
-      drop: ['ALL'],
-    },
-  },
-}
-```
-
----
+import { PloneHttpcache } from '@bluedynamics/cdk8s-plone';
 
-### `PloneHttpcacheOptions`
-
-Configuration for the Varnish HTTP cache layer.
-
-| Property | Type | Required | Default | Description |
-|----------|------|----------|---------|-------------|
-| `plone` | `Plone` | Yes | - | Plone construct to attach cache to |
-| `varnishVcl` | `string` | No | - | VCL configuration as string. Takes precedence over `varnishVclFile`. |
-| `varnishVclFile` | `string` | No | built-in `config/varnish.tpl.vcl` | Path to a VCL template file |
-| `existingSecret` | `string` | No | - | Kubernetes secret for Varnish admin credentials |
-| `replicas` | `number` | No | `2` | Number of Varnish replicas |
-| `requestCpu` | `string` | No | `100m` | CPU request |
-| `limitCpu` | `string` | No | `500m` | CPU limit |
-| `requestMemory` | `string` | No | `100Mi` | Memory request |
-| `limitMemory` | `string` | No | `500Mi` | Memory limit |
-| `servicemonitor` | `boolean` | No | `false` | Enable Prometheus `ServiceMonitor` |
-| `exporterEnabled` | `boolean` | No | `true` | Enable Prometheus exporter sidecar |
-| `chartVersion` | `string` | No | chart latest | kube-httpcache Helm chart version |
-| `appVersion` | `string` | No | matches `chartVersion` | kube-httpcache container image tag |
-| `extraEnvVars` | `HttpcacheEnvVar[]` | No | - | Additional env vars for the kube-httpcache container |
-| `tolerations` | `HttpcacheToleration[]` | No | - | Pod tolerations for tainted nodes |
-
-**`HttpcacheEnvVar` fields:**
-
-| Property | Type | Description |
-|----------|------|-------------|
-| `name` | `string` | Environment variable name |
-| `value` | `string` | Environment variable value |
-
-**`HttpcacheToleration` fields:**
-
-| Property | Type | Default | Description |
-|----------|------|---------|-------------|
-| `key` | `string` | - | Taint key to tolerate |
-| `operator` | `string` | `Equal` | `Equal` or `Exists` |
-| `value` | `string` | - | Taint value (required for `Equal`) |
-| `effect` | `string` | - | `NoSchedule`, `PreferNoSchedule`, or `NoExecute`. Omit to tolerate all effects. |
-
-**Example:**
-```typescript
+// Self-contained Varnish via the kube-httpcache Helm chart.
 new PloneHttpcache(chart, 'cache', {
   plone: ploneInstance,
   existingSecret: 'varnish-secret',
-  replicas: 3,
-  requestCpu: '250m',
-  limitCpu: '1',
-  requestMemory: '256Mi',
-  limitMemory: '1Gi',
-  servicemonitor: true,
-  exporterEnabled: true,
-});
-```
-
-**VCL Configuration:**
-```typescript
-// Inline VCL
-new PloneHttpcache(chart, 'cache', {
-  plone: ploneInstance,
-  varnishVcl: `
-    vcl 4.1;
-    backend default {
-      .host = "backend-service";
-      .port = "8080";
-    }
-  `,
-});
-
-// VCL from file
-new PloneHttpcache(chart, 'cache', {
-  plone: ploneInstance,
-  varnishVclFile: './varnish/default.vcl',
+  replicas: 2,
 });
 ```
 
-**Extra Environment Variables:**
-
-Pass additional environment variables to the kube-httpcache container.
-These are appended to the built-in env vars (`BACKEND_SERVICE_NAME`, `BACKEND_SERVICE_PORT`, `BACKEND_SITE_ID`, `FRONTEND_SERVICE_NAME`, `FRONTEND_SERVICE_PORT`) and can be referenced in VCL templates using Go template syntax `{{ .Env.VAR_NAME }}`.
-
 ```typescript
-new PloneHttpcache(chart, 'cache', {
-  plone: ploneInstance,
-  varnishVclFile: './config/custom-varnish.tpl.vcl',
-  extraEnvVars: [
-    { name: 'THUMBOR_SERVICE_NAME', value: 'my-thumbor-service' },
-  ],
-});
-```
-
----
+import { PloneVinylCache } from '@bluedynamics/cdk8s-plone';
 
-### `PloneVinylCacheOptions`
-
-Configuration for the Varnish HTTP cache layer via the cloud-vinyl operator.
-Requires the [cloud-vinyl operator](https://github.com/bluedynamics/cloud-vinyl) to be installed in the cluster.
-
-| Property | Type | Required | Default | Description |
-|----------|------|----------|---------|-------------|
-| `plone` | `Plone` | Yes | - | Plone construct to attach cache to |
-| `image` | `string` | No | `varnish:7.6` | Container image for the Varnish pods |
-| `replicas` | `number` | No | `2` | Number of Varnish replicas |
-| `requestCpu` | `string` | No | `100m` | CPU request |
-| `limitCpu` | `string` | No | `500m` | CPU limit |
-| `requestMemory` | `string` | No | `256Mi` | Memory request |
-| `limitMemory` | `string` | No | `512Mi` | Memory limit |
-| `storage` | `VinylCacheStorage[]` | No | - | Varnish storage backends. If omitted, the operator falls back to the varnishd default (~100 MB malloc), which is almost always too small. |
-| `extraBackends` | `VinylCacheBackend[]` | No | - | Additional backends appended after the auto-generated Plone backends. |
-| `director` | `string` | No | `shard` | Director type: `shard`, `round_robin`, `random`, `hash` |
-| `shardBy` | `string` | No | operator default (`HASH`) | Shard director: value to hash (`HASH` or `URL`). Requires cloud-vinyl ≥ 0.4.2. |
-| `shardHealthy` | `string` | No | operator default (`CHOSEN`) | Shard director: backend health requirement (`CHOSEN` or `ALL`). Requires cloud-vinyl ≥ 0.4.2. |
-| `shardRampup` | `string` | No | operator default (`30s`) | Shard director: ramp-up window for newly added backends. |
-| `shardReplicas` | `number` | No | operator default (`67`) | Shard director: Ketama replicas per backend. |
-| `vclRecvSnippet` | `string` | No | built-in `plone-vinyl-recv.vcl` | Custom VCL snippet for `vcl_recv` |
-| `vclBackendResponseSnippet` | `string` | No | built-in `plone-vinyl-backend-response.vcl` | Custom VCL snippet for `vcl_backend_response` |
-| `vclDeliverSnippet` | `string` | No | - | Custom VCL snippet for `vcl_deliver` |
-| `vclHitSnippet` | `string` | No | - | Custom VCL snippet for `vcl_hit` |
-| `vclMissSnippet` | `string` | No | - | Custom VCL snippet for `vcl_miss` |
-| `vclPassSnippet` | `string` | No | - | Custom VCL snippet for `vcl_pass` |
-| `vclPipeSnippet` | `string` | No | - | Custom VCL snippet for `vcl_pipe` |
-| `vclSynthSnippet` | `string` | No | - | Custom VCL snippet for `vcl_synth` |
-| `vclPurgeSnippet` | `string` | No | - | Custom VCL snippet for `vcl_purge` |
-| `vclHashSnippet` | `string` | No | - | Custom VCL snippet for `vcl_hash` |
-| `vclInitSnippet` | `string` | No | - | Custom VCL snippet for `vcl_init` |
-| `vclFiniSnippet` | `string` | No | - | Custom VCL snippet for `vcl_fini` |
-| `vclBackendFetchSnippet` | `string` | No | - | Custom VCL snippet for `vcl_backend_fetch` |
-| `vclBackendErrorSnippet` | `string` | No | - | Custom VCL snippet for `vcl_backend_error` |
-| `invalidation` | `boolean` | No | `true` | Enable PURGE/BAN/xkey cache invalidation |
-| `monitoring` | `boolean` | No | `false` | Enable Prometheus metrics and `ServiceMonitor` |
-| `tolerations` | `VinylCacheToleration[]` | No | - | Pod tolerations for tainted nodes |
-| `nodeSelector` | `Record<string, string>` | No | - | Constrain Varnish pods to nodes matching all labels. |
-
-**`VinylCacheStorage` fields:**
-
-| Property | Type | Required | Description |
-|----------|------|----------|-------------|
-| `name` | `string` | Yes | Internal storage identifier (must match `^[a-zA-Z][a-zA-Z0-9_]*$`) |
-| `type` | `'malloc' \| 'file'` | Yes | Storage backend type |
-| `size` | `string` | Yes | Kubernetes resource quantity (e.g. `"1Gi"`, `"500M"`) |
-| `path` | `string` | for `file` | Filesystem path for file-type storage |
-
-**`VinylCacheBackend` fields:**
-
-| Property | Type | Required | Default | Description |
-|----------|------|----------|---------|-------------|
-| `name` | `string` | Yes | - | VCL identifier (must match `^[a-zA-Z][a-zA-Z0-9_]*$`) |
-| `serviceName` | `string` | Yes | - | Kubernetes Service name to use as backend |
-| `port` | `number` | Yes | - | Service port |
-| `probe` | `VinylCacheBackendProbe` | No | - | Health probe configuration |
-| `weight` | `number` | No | operator default | Relative weight in the director. `0` marks the backend as standby. |
-
-**`VinylCacheBackendProbe` fields:**
-
-| Property | Type | Default | Description |
-|----------|------|---------|-------------|
-| `url` | `string` | `/` | URL to probe |
-| `interval` | `string` | `5s` | Probe interval |
-| `timeout` | `string` | `2s` | Probe timeout |
-| `window` | `number` | `10` | Number of recent probes evaluated |
-| `threshold` | `number` | `8` | Healthy threshold within the window |
-| `expectedResponse` | `number` | `200` | Expected HTTP status code |
-
-**`VinylCacheToleration` fields:**
-
-| Property | Type | Default | Description |
-|----------|------|---------|-------------|
-| `key` | `string` | - | Taint key to tolerate |
-| `operator` | `string` | `Equal` | `Equal` or `Exists` |
-| `value` | `string` | - | Taint value (required for `Equal`) |
-| `effect` | `string` | - | `NoSchedule`, `PreferNoSchedule`, or `NoExecute`. Omit to tolerate all effects. |
-
-**Example:**
-```typescript
+// Operator-managed Varnish via the cloud-vinyl operator.
 const cache = new PloneVinylCache(chart, 'cache', {
   plone: ploneInstance,
-  replicas: 2,
-  requestCpu: '200m',
-  limitCpu: '1',
-  requestMemory: '256Mi',
-  limitMemory: '1Gi',
+  storage: [{ name: 's0', type: 'malloc', size: '1500M' }],
   monitoring: true,
 });
-
-// Use the service name for IngressRoute
-console.log(cache.vinylCacheServiceName);
-```
-
-**Custom VCL Snippets:**
-```typescript
-new PloneVinylCache(chart, 'cache', {
-  plone: ploneInstance,
-  vclRecvSnippet: `
-    // Custom routing logic
-    if (req.url ~ "^/api/") {
-      set req.backend_hint = plone_backend.backend();
-    }
-  `,
-});
-```
-
-**Storage sizing:**
-```typescript
-new PloneVinylCache(chart, 'cache', {
-  plone: ploneInstance,
-  limitMemory: '2Gi',
-  storage: [
-    { name: 's0', type: 'malloc', size: '1500M' },
-  ],
-});
 ```
 
-Without an explicit `storage` entry, varnishd runs with its stock default (~100 MB malloc) regardless of the container's memory limit. Size malloc storage below the pod's memory limit to leave headroom for varnishd overhead and transient allocations.
-
-**vs PloneHttpcache:**
-- `PloneHttpcache` deploys Varnish via mittwald Helm chart (self-contained, no operator needed)
-- `PloneVinylCache` creates a VinylCache CR managed by the cloud-vinyl operator (requires operator in cluster)
-- VinylCache provides structured VCL generation, agent-based config delivery, and built-in invalidation proxy
-
----
-
-## PloneVariant enum
-
-Defines the deployment variant:
-
-| Value | Description |
-|-------|-------------|
-| `PloneVariant.VOLTO` | React single-page frontend talking to the REST API backend (default) |
-| `PloneVariant.BLICCA` | The Plone backend renders the UI server-side and serves HTML directly |
-| `PloneVariant.CLASSICUI` | Deprecated alias for `PloneVariant.BLICCA`, kept for backward compatibility |
-
-`BLICCA` is the new name for the former `CLASSICUI` variant.
-Both select the same backend-only deployment.
-`CLASSICUI` keeps its legacy value (`'classicui'`), so existing configuration using `CLASSICUI` or that literal keeps working unchanged.
-The `CLASSICUI` alias will be removed in a future major release.
-
-**Example:**
-```typescript
-import { PloneVariant } from '@bluedynamics/cdk8s-plone';
-
-// Volto (React single-page frontend)
-variant: PloneVariant.VOLTO
-
-// Blicca (server-side rendered)
-variant: PloneVariant.BLICCA
+```{important}
+`PloneVinylCache` without an explicit `storage` entry runs varnishd with its stock default (~100 MB malloc) regardless of the container memory limit.
+Size malloc storage below the pod's memory limit to leave headroom for varnishd overhead.
 ```
 
----
+For the full walk-through, including custom VCL snippets and shard-director tuning, see {doc}`/how-to/deploy-with-vinyl-cache`.
 
 ## Complete example
 
@@ -614,11 +202,9 @@ const app = new App();
 const chart = new Chart(app, 'PloneDeployment');
 
 const plone = new Plone(chart, 'my-plone', {
-  version: '1.0.0',
   siteId: 'MySite',
   variant: PloneVariant.VOLTO,
   imagePullSecrets: ['registry-secret'],
-
   backend: {
     image: 'plone/plone-backend:6.1.3',
     replicas: 3,
@@ -627,27 +213,16 @@ const plone = new Plone(chart, 'my-plone', {
     requestMemory: '512Mi',
     limitMemory: '2Gi',
     minAvailable: 2,
-    readinessEnabled: true,
-    readinessInitialDelaySeconds: 10,
     environment: {
       variables: {
         SITE: Env.value('MySite'),
       },
     },
-    podAnnotations: {
-      'prometheus.io/scrape': 'true',
-    },
   },
-
   frontend: {
     image: 'plone/plone-frontend:16.0.0',
     replicas: 2,
-    requestCpu: '250m',
-    limitCpu: '1',
-    requestMemory: '256Mi',
-    limitMemory: '1Gi',
     livenessEnabled: true,
-    livenessInitialDelaySeconds: 30,
   },
 });
 
@@ -655,22 +230,16 @@ new PloneHttpcache(chart, 'cache', {
   plone: plone,
   existingSecret: 'varnish-secret',
   replicas: 2,
-  requestCpu: '250m',
-  requestMemory: '256Mi',
   servicemonitor: true,
 });
 
 app.synth();
 ```
 
----
-
 ## See also
 
-- {doc}`/tutorials/01-quick-start` — Get started guide
-- {doc}`/how-to/deploy-production-volto` — Production-ready Volto deployment
+- {doc}`API reference <api/index>` — every option, type, and default (generated)
+- {doc}`/tutorials/01-quick-start` — first deployment, step by step
+- {doc}`/how-to/deploy-volto` — production-ready Volto deployment
 - {doc}`/how-to/deploy-blicca` — Blicca deployment
-- {doc}`/how-to/deploy-with-vinyl-cache` — `PloneVinylCache` walk-through
-- {doc}`/how-to/enable-prometheus-monitoring` — Wire up `ServiceMonitor`
-- {doc}`/how-to/configure-security-context` — Harden backend and frontend pods
-- {doc}`/how-to/schedule-pods` — `nodeSelector` and `tolerations`
+- {doc}`/explanation/architecture` — how the pieces fit together