@bluedynamics/cdk8s-plone 0.1.40 → 0.1.42

package/docs/superpowers/specs/2026-06-12-configurable-service-spec-design.md

@@ -0,0 +1,192 @@
+# Design: Generisch steuerbare Service-Resourcen
+
+**Datum:** 2026-06-12
+**Branch:** `feat/configurable-service-spec`
+**Status:** Approved (Design)
+
+## Problem
+
+Die von cdk8s-plone generierten Kubernetes-`Service`-Resourcen sind schlecht
+steuerbar. Konkreter Anlass: Es soll `spec.trafficDistribution` gesetzt werden
+können — das geht aktuell nicht. Generell ist die `Service`-Spec faktisch
+hartcodiert: In [`src/service.ts`](../../../src/service.ts) baut `PloneService`
+über das rohe `k8s.KubeService` nur `spec.ports` + `spec.selector`. Alle anderen
+Felder (`type`, `sessionAffinity`, `externalTrafficPolicy`,
+`internalTrafficPolicy`, `publishNotReadyAddresses`, `loadBalancerClass`,
+`trafficDistribution`, …) sind nicht durchgereicht.
+
+Zusätzlich ist das Plumbing nicht wartbar: Nach oben (in
+[`src/plone.ts`](../../../src/plone.ts)) wird pro Feld einzeln geplumbt — aktuell
+nur `serviceAnnotations`. Jedes neue Feld bräuchte Änderungen an mehreren Stellen.
+
+## Ziel
+
+Service-Spec-Felder konfigurierbar machen — möglichst generisch, mit wenig
+Pflegeaufwand pro Feld, JSII-/Python-kompatibel, ohne Breaking Change.
+
+## Designentscheidungen (bestätigt)
+
+- **Hybrid-Ansatz:** Kuratierte typisierte Props für die häufigen Felder PLUS
+  ein generischer Escape-Hatch für alles Übrige.
+- **Gruppiertes Plumbing:** Ein einziges `service`-Objekt in `PloneBaseOptions`
+  statt flacher Einzel-Props. Neue Felder ändern nur den Config-Typ.
+- **`overrides`-Präzedenz:** `overrides` darf *alles* überschreiben (auch
+  `ports`/`selector`) — volle Kontrolle für Power-User, dokumentiert.
+
+## Lösung
+
+### 1. Neuer Config-Typ `PloneServiceSpec` (in `src/service.ts`)
+
+```typescript
+export interface PloneServiceSpec {
+  // Kuratierte, häufig gebrauchte Felder (alle optional, typisiert, dokumentiert):
+  readonly type?: string;                       // ClusterIP | NodePort | LoadBalancer | ExternalName
+  readonly trafficDistribution?: string;        // z.B. 'PreferClose'
+  readonly sessionAffinity?: string;            // 'ClientIP' | 'None'
+  readonly externalTrafficPolicy?: string;      // 'Cluster' | 'Local'
+  readonly internalTrafficPolicy?: string;      // 'Cluster' | 'Local'
+  readonly publishNotReadyAddresses?: boolean;
+  readonly loadBalancerClass?: string;
+  readonly loadBalancerSourceRanges?: string[];
+  readonly annotations?: { [name: string]: string };  // ersetzt serviceAnnotations
+  readonly labels?: { [name: string]: string };
+
+  // Escape-Hatch für alles Übrige (ipFamilyPolicy, clusterIP, ...):
+  readonly overrides?: { [key: string]: any };
+}
+```
+
+Der `overrides`-Typ ist ein freiform-Record `{ [key: string]: any }` — deckt
+jedes aktuelle und künftige k8s-Service-Feld ab, ohne dass Code angefasst werden
+muss.
+
+> **JSII-Constraint (entdeckt bei der Umsetzung):** Ursprünglich war
+> `overrides?: k8s.ServiceSpec` geplant. JSII lehnt das ab
+> (`JSII3000: Exported APIs cannot use un-exported type`), weil die generierten
+> Typen aus `src/imports/k8s.ts` nicht Teil der JSII-Assembly sind. Den gesamten
+> k8s-Import zu re-exportieren würde die öffentliche API mit der kompletten
+> Kubernetes-API zumüllen. Ein freiform-Record ist die idiomatische, voll
+> JSII-/Python-fähige (Python: `dict`) Lösung für einen generischen Escape-Hatch
+> und bleibt „für alles" offen. Die kuratierten Felder bleiben typisiert.
+
+### 2. `PloneServiceOptions` erweitern
+
+`PloneServiceOptions` (das interne Interface von `PloneService`) bekommt ein
+optionales `spec?: PloneServiceSpec`. Die bestehenden Pflichtfelder
+(`targetPort`, `selectorLabel`, `portName`) bleiben unverändert. Das bestehende
+`annotations` und `labels` auf `PloneServiceOptions` bleiben erhalten
+(construct-managed Defaults), werden aber mit den Werten aus `spec` zusammen-
+geführt (siehe Merge-Regeln).
+
+### 3. Merge-Reihenfolge in `PloneService`
+
+Vorhersagbar, shallow (ServiceSpec-Felder sind weitgehend flach):
+
+```
+finalSpec = { ...generatedBase, ...curatedFields, ...overrides }
+```
+
+Präzedenz steigend:
+
+1. **Construct-Basis:** `ports`, `selector` (aus `targetPort`/`portName`/`selectorLabel`).
+2. **Kuratierte Felder:** alle gesetzten Felder aus `spec` (außer `annotations`,
+   `labels`, `overrides`).
+3. **`overrides`:** `k8s.ServiceSpec`-Partial — höchste Präzedenz, überschreibt
+   auch `ports`/`selector`. Dokumentiert als „at your own risk".
+
+`annotations` und `labels` aus `spec` fließen in `metadata` (nicht in `spec`):
+- `metadata.labels = { ...spec.labels, ...constructManagedLabels }`
+  (construct-managed `part-of`/`managed-by` gewinnen — wie bisher).
+- `metadata.annotations = { ...serviceAnnotations (deprecated), ...spec.annotations }`
+  (neue `spec.annotations` gewinnen bei Konflikt).
+
+### 4. Plumbing: ein Punkt in `PloneBaseOptions` (`src/plone.ts`)
+
+```typescript
+/**
+ * Service configuration (type, trafficDistribution, sessionAffinity,
+ * annotations, raw spec overrides, ...). Applies to the component's Service.
+ */
+readonly service?: PloneServiceSpec;
+
+/**
+ * @deprecated use `service.annotations` instead
+ */
+readonly serviceAnnotations?: { [name: string]: string };
+```
+
+`backend`/`frontend` erben beide aus `PloneBaseOptions`, daher gilt die
+`service`-Config automatisch für beide Services an genau einer Stelle.
+
+In `plone.ts` (Backend-Service ~Z. 468, Frontend-Service ~Z. 570) wird
+`spec` durchgereicht und die deprecated `serviceAnnotations` weiter unterstützt:
+
+```typescript
+new PloneService(backendDeployment, 'service', {
+  // ... unverändert: labels, targetPort, selectorLabel, portName ...
+  spec: {
+    ...backend.service,
+    annotations: { ...backend.serviceAnnotations, ...backend.service?.annotations },
+  },
+});
+```
+
+### 5. Backward-Compatibility
+
+`serviceAnnotations` bleibt funktionsfähig, wird als `@deprecated` markiert und
+mit `service.annotations` zusammengeführt (neue Variante gewinnt). Kein Breaking
+Change. Bestehende Snapshots ohne `service` bleiben unverändert (alle neuen
+Felder sind optional, ungesetzt → keine Spec-Änderung).
+
+### 6. Tests (`test/service.test.ts`)
+
+Neue Snapshot-/Assertion-Fälle:
+
+- `trafficDistribution: 'PreferClose'` → erscheint in `spec`.
+- `type: 'LoadBalancer'` + `loadBalancerSourceRanges` → erscheinen in `spec`.
+- `sessionAffinity` / `externalTrafficPolicy` gesetzt.
+- `overrides` (z.B. `ipFamilyPolicy`) → erscheint in `spec`.
+- Präzedenz: `overrides` schlägt kuratiertes Feld (z.B. beide setzen `type`,
+  `overrides` gewinnt).
+- Backward-Compat: nur `serviceAnnotations` gesetzt → unverändertes Verhalten;
+  `serviceAnnotations` + `service.annotations` → korrekt gemergt.
+
+Snapshots aktualisieren via `npx projen test -- -u`.
+
+### 7. Dokumentation
+
+Beim Schreiben/Editieren der Doku den Skill **`plone-doc-style:author`**
+verwenden (Diataxis-Quadranten-Zuordnung, MyST-Markup, Style-Enforcement),
+soweit es sinnvoll ist — d.h. für die handgeschriebenen Seiten unter
+`documentation/sources/` (Reference + How-to). Nicht für auto-generierte
+Artefakte (`API.md`).
+
+- **`API.md`** ist auto-generiert (`npx projen docgen`) — kein manuelles Edit,
+  aber nach Implementierung neu generieren.
+- **`documentation/sources/reference/configuration-options.md`:** Den Abschnitt
+  „Annotations" (~Z. 200) zu einem Abschnitt „Service" erweitern bzw. einen
+  neuen Abschnitt für `PloneServiceSpec` ergänzen: Tabelle der kuratierten
+  Felder + `overrides`, mit Beispiel (`trafficDistribution`, `LoadBalancer`).
+  `serviceAnnotations` als deprecated kennzeichnen und auf `service.annotations`
+  verweisen.
+- **`documentation/sources/how-to/`:** In `deploy-production-volto.md` ein
+  kurzes Beispiel ergänzen (z.B. `trafficDistribution: 'PreferClose'` für
+  topologie-nahes Routing), falls thematisch passend.
+- Doku-Build prüfen: `cd documentation && make docs`.
+
+## Betroffene Dateien
+
+- `src/service.ts` — neuer `PloneServiceSpec`-Typ, erweiterte `PloneServiceOptions`, Merge-Logik.
+- `src/plone.ts` — `service`-Prop in `PloneBaseOptions`, Plumbing in Backend/Frontend, `serviceAnnotations` deprecaten.
+- `test/service.test.ts` (+ Snapshots) — neue Testfälle.
+- `documentation/sources/reference/configuration-options.md` — Service-Config dokumentieren.
+- `documentation/sources/how-to/deploy-production-volto.md` — optionales Beispiel.
+- `API.md` — regenerieren via `npx projen docgen`.
+
+## Nicht im Scope (YAGNI)
+
+- Multi-Port-Services (mehrere `ports`-Einträge) — über `overrides` möglich,
+  aber kein kuratiertes Feature.
+- Eigene Validierung der Enum-Strings (`type`, `sessionAffinity`, …) — k8s
+  validiert serverseitig; wir bilden die Strings 1:1 ab.
+- Separate Service-Configs pro Service jenseits von backend/frontend.

package/documentation/sources/explanation/architecture.md

@@ -21,19 +21,20 @@ cdk8s-plone provides CDK8S constructs for deploying Plone CMS on Kubernetes. The
 
 cdk8s-plone supports two deployment variants:
 
-**Volto (Modern)**
+**Volto (React single-page frontend)**
 - React-based frontend (Volto)
 - REST API backend (Plone)
 - Separate services for frontend and backend
-- Modern user experience
 - Headless CMS architecture
 
-**Classic UI (Traditional)**
-- Server-side rendered Plone
+**Blicca (server-side rendered)**
+- The Plone backend renders the UI and serves HTML directly
 - Single integrated service
-- Traditional Plone experience
 - Simpler deployment model
 
+Blicca is the new name for the variant Plone formerly called "Classic UI".
+Both approaches are equally current; they differ in where rendering happens, not in how modern they are.
+
 ### High availability
 
 **Replica Management**
@@ -251,7 +252,7 @@ For a typical Volto deployment, cdk8s-plone creates:
 - Better resource utilization
 - Clear separation of concerns
 
-**When to use Classic UI:**
+**When to use Blicca:**
 - Simpler deployment model
 - Lower resource requirements
 - Legacy integrations

package/documentation/sources/explanation/features.md

@@ -19,17 +19,19 @@ Complete overview of cdk8s-plone features and capabilities.
 
 cdk8s-plone supports two deployment modes to match your requirements:
 
-**Volto (Modern React Frontend)**
-- Modern React-based user interface
+**Volto (React single-page frontend)**
+- React-based user interface
 - Headless CMS architecture
 - Separate frontend and backend services
-- Best for: New projects, modern UX requirements, API-first architectures
+- Best for: API-first architectures, SPA frontends
 
-**Classic UI (Traditional Plone)**
-- Server-side rendered interface
+**Blicca (server-side rendered Plone)**
+- The Plone backend renders the UI and serves HTML directly
 - Integrated single-service deployment
-- Traditional Plone experience
-- Best for: Legacy migrations, existing add-ons, simpler deployments
+- Best for: single-service setups, legacy migrations, existing add-ons
+
+Blicca is the new name for the variant Plone formerly called "Classic UI".
+Both are equally current; they differ in their rendering approach.
 
 See {doc}`architecture` for a deeper architectural comparison of the two variants.
 

package/documentation/sources/how-to/{deploy-classic-ui.md → deploy-blicca.md}

@@ -1,37 +1,40 @@
 ---
 myst:
   html_meta:
-    "description": "Deploy the Classic UI example: server-side rendered Plone with PostgreSQL, Varnish caching, and ingress with TLS."
-    "property=og:description": "Deploy the Classic UI example: server-side rendered Plone with PostgreSQL, Varnish caching, and ingress with TLS."
-    "property=og:title": "Deploy Classic UI example"
-    "keywords": "Plone, cdk8s, Kubernetes, Classic UI, PostgreSQL, Varnish, ingress"
+    "description": "Deploy the Blicca example: server-side rendered Plone with PostgreSQL, Varnish caching, and ingress with TLS."
+    "property=og:description": "Deploy the Blicca example: server-side rendered Plone with PostgreSQL, Varnish caching, and ingress with TLS."
+    "property=og:title": "Deploy Blicca example"
+    "keywords": "Plone, cdk8s, Kubernetes, Blicca, Classic UI, PostgreSQL, Varnish, ingress"
 ---
 
-# Deploy Classic UI example
+# Deploy Blicca example
 
-This guide shows you how to deploy the Classic UI example to your Kubernetes cluster.
+This guide shows you how to deploy the Blicca example to your Kubernetes cluster.
+
+Blicca is the new name for what Plone formerly called "Classic UI".
 
 ## What you'll deploy
 
-The [Classic UI example](https://github.com/bluedynamics/cdk8s-plone/tree/main/examples/classic-ui) provides traditional Plone with server-side rendering:
+The [Blicca example](https://github.com/bluedynamics/cdk8s-plone/tree/main/examples/blicca) provides Plone with server-side rendering:
 
-- **Plone 6.1 Classic UI** (traditional interface, no separate frontend)
+- **Plone 6.1 Blicca** (backend renders the UI, no separate frontend)
 - **PostgreSQL** with RelStorage (CloudNativePG or Bitnami)
 - **Varnish HTTP caching** with kube-httpcache
 - **Ingress** with TLS (Traefik or Kong)
 - **Simpler architecture** (single backend service)
 
-## Classic UI vs Volto
+## Blicca vs Volto
 
-| Feature | Classic UI | Volto |
+| Feature | Blicca | Volto |
 |---------|-----------|-------|
 | **Architecture** | Single backend | Frontend + Backend |
 | **Rendering** | Server-side | Client-side (React) |
 | **Deployment** | Simpler | More complex |
-| **Best for** | Migrations, intranets | Modern projects |
+| **Best for** | Single-service setups, migrations | API-first projects, SPA frontends |
 
 :::{tip}
-Choose Classic UI if you're migrating from older Plone versions or need specific Classic UI add-ons. For new projects, consider [Volto](deploy-production-volto.md).
+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).
 :::
 
 ## Prerequisites
@@ -49,7 +52,7 @@ See [Setup Prerequisites](setup-prerequisites.md) for detailed instructions.
 
 ```shell
 git clone https://github.com/bluedynamics/cdk8s-plone.git
-cd cdk8s-plone/examples/classic-ui
+cd cdk8s-plone/examples/blicca
 ```
 
 ## Step 2: Install dependencies
@@ -91,7 +94,8 @@ DATABASE=cloudnativepg
 ```
 
 :::{note}
-Classic UI only needs one image (backend). There's no frontend image configuration.
+Blicca only needs one image (backend).
+There's no frontend image configuration.
 :::
 
 ## Step 5: Generate manifests
@@ -100,28 +104,28 @@ Classic UI only needs one image (backend). There's no frontend image configurati
 npm run synth
 ```
 
-Creates `dist/plone-classic.k8s.yaml` (~27 KB, smaller than Volto's 32 KB).
+Creates `dist/plone-blicca.k8s.yaml` (~27 KB, smaller than Volto's 32 KB).
 
 ## Step 6: Review manifests
 
 ```shell
 # Count resources
-grep "^kind:" dist/plone-classic.k8s.yaml | sort | uniq -c
+grep "^kind:" dist/plone-blicca.k8s.yaml | sort | uniq -c
 
 # Dry run
-kubectl apply --dry-run=client -f dist/plone-classic.k8s.yaml
+kubectl apply --dry-run=client -f dist/plone-blicca.k8s.yaml
 ```
 
 ## Step 7: Deploy
 
 ```shell
-kubectl apply -f dist/plone-classic.k8s.yaml
+kubectl apply -f dist/plone-blicca.k8s.yaml
 ```
 
 Or to a specific namespace:
 
 ```shell
-kubectl apply -f dist/plone-classic.k8s.yaml -n plone
+kubectl apply -f dist/plone-blicca.k8s.yaml -n plone
 ```
 
 ## Step 8: Monitor deployment
@@ -137,7 +141,7 @@ kubectl wait --for=condition=ready pod \
 ```
 
 :::{note}
-Classic UI deploys fewer pods than Volto (no frontend pods).
+Blicca deploys fewer pods than Volto (no frontend pods).
 :::
 
 ## Step 9: Verify services
@@ -147,7 +151,7 @@ kubectl get svc -l app.kubernetes.io/part-of=plone
 ```
 
 You should see:
-- `plone-backend` (Classic UI service)
+- `plone-backend` (Blicca service)
 - `plone-httpcache` (Varnish cache)
 - Database service
 
@@ -174,17 +178,17 @@ Once DNS and TLS are ready:
    - **Site ID**: `Plone`
    - **Title**: Your site name
    - **Language**: Select language
-   - **Add-ons**: Choose Classic UI add-ons
+   - **Add-ons**: Choose Blicca add-ons
 4. Click "Create Plone Site"
 
 ## Key differences from Volto
 
 ### Architecture
 
-Classic UI routing is simpler - all traffic goes to the backend:
+Blicca routing is simpler - all traffic goes to the backend:
 
 ```
-Traffic → Ingress → Varnish → Plone Backend (Classic UI)
+Traffic → Ingress → Varnish → Plone Backend (Blicca)
 ```
 
 Compared to Volto:
@@ -195,7 +199,7 @@ Traffic → Ingress → {Varnish → Frontend, Backend}
 
 ### Ingress routes
 
-Classic UI uses virtual host rewriting for direct backend access:
+Blicca uses virtual host rewriting for direct backend access:
 
 - **Cached**: Routes through Varnish to backend
 - **Uncached**: Direct to backend with VirtualHostBase rewrite
@@ -225,7 +229,7 @@ Common issues:
 - Memory limits too low
 - Image pull errors
 
-### Classic UI interface not loading
+### Blicca interface not loading
 
 1. Check if backend pods are running:
    ```shell
@@ -244,14 +248,14 @@ Common issues:
 
 ### Add-on compatibility
 
-Some add-ons are Volto-specific. For Classic UI:
-- Use Classic UI themes (not Volto themes)
-- Check add-on compatibility with Plone 6 Classic UI
+Some add-ons are Volto-specific. For Blicca:
+- Use Blicca themes (not Volto themes)
+- Check add-on compatibility with Plone 6 Blicca
 - Avoid Volto-specific frontend add-ons
 
 ## Migrating to Volto
 
-If you want to migrate from Classic UI to Volto later:
+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)
@@ -268,7 +272,7 @@ Edit `main.ts` to customize:
 
 ```typescript
 const plone = new Plone(this, 'plone', {
-  variant: PloneVariant.CLASSICUI,
+  variant: PloneVariant.BLICCA,
   backend: {
     image: 'plone/plone-backend:6.1.3',
     replicas: 2,
@@ -281,9 +285,9 @@ const plone = new Plone(this, 'plone', {
 
 ### Varnish caching
 
-Edit `config/varnish.tpl.vcl` for caching rules specific to Classic UI.
+Edit `config/varnish.tpl.vcl` for caching rules specific to Blicca.
 
-Classic UI VCL is simpler than Volto's - all traffic routes to one backend.
+Blicca VCL is simpler than Volto's - all traffic routes to one backend.
 
 ## Scaling
 
@@ -298,14 +302,14 @@ backend: {
 Then:
 ```shell
 npm run synth
-kubectl apply -f dist/plone-classic.k8s.yaml
+kubectl apply -f dist/plone-blicca.k8s.yaml
 ```
 
 ## Performance
 
-Classic UI performance characteristics:
+Blicca performance characteristics:
 
-- **Server-side rendering** can be slower than Volto's client-side
+- **Server-side rendering** moves rendering work to the backend, so Varnish caching matters
 - **Varnish caching** is critical for performance
 - **Database** is the main bottleneck (use CloudNativePG for HA)
 - **Fewer HTTP requests** than Volto (no separate frontend API calls)
@@ -313,18 +317,18 @@ Classic UI performance characteristics:
 ## Cleanup
 
 ```shell
-kubectl delete -f dist/plone-classic.k8s.yaml
+kubectl delete -f dist/plone-blicca.k8s.yaml
 ```
 
 ## Next steps
 
 - Follow {doc}`enable-prometheus-monitoring` to add Prometheus monitoring.
 - Configure [CloudNativePG backups](https://cloudnative-pg.io/documentation/).
-- Customize the Classic UI theme through [Plone 6 Classic UI documentation](https://6.docs.plone.org/classic-ui/).
+- Customize the theme through the [Plone 6 Classic UI documentation](https://6.docs.plone.org/classic-ui/) (upstream docs; Blicca is the new name for Classic UI).
 
 ## See also
 
-- {doc}`deploy-production-volto` — For the modern React UI.
+- {doc}`deploy-production-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

@@ -324,6 +324,6 @@ kubectl delete -f dist/plone-example.k8s.yaml
 
 ## See also
 
-- {doc}`deploy-classic-ui` — For the traditional Plone interface.
+- {doc}`deploy-blicca` — For the server-side rendered Plone UI.
 - {doc}`setup-prerequisites` — Detailed cluster setup.
 - {doc}`/reference/configuration-options` — API reference.

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

@@ -40,7 +40,7 @@ maxdepth: 1
 titlesonly: true
 ---
 deploy-production-volto
-deploy-classic-ui
+deploy-blicca
 deploy-with-vinyl-cache
 ```
 

package/documentation/sources/reference/api/index.md

@@ -15,7 +15,7 @@ Complete API reference for cdk8s-plone constructs, generated from TypeScript sou
 
 The cdk8s-plone library provides the following main constructs:
 
-- **Plone**: Main construct for deploying Plone CMS with support for both Volto (React frontend) and Classic UI variants
+- **Plone**: Main construct for deploying Plone CMS with support for both Volto (React frontend) and Blicca (server-side rendered) variants
 - **PloneHttpcache**: HTTP caching layer using Varnish for improved performance
 
 ## Language support

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

@@ -16,13 +16,13 @@ Complete reference for all configuration options in cdk8s-plone.
 ### `Plone`
 
 Main construct for deploying Plone CMS. Supports two variants:
-- **VOLTO**: Modern React frontend with REST API backend (default)
-- **CLASSICUI**: Traditional server-side rendered Plone
+- **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
 
 **Properties:**
 - `backendServiceName` - Name of the backend Kubernetes service
 - `frontendServiceName` - Name of the frontend service (VOLTO only)
-- `variant` - Deployment variant (VOLTO or CLASSICUI)
+- `variant` - Deployment variant (VOLTO or BLICCA)
 - `siteId` - Plone site ID in ZODB (default: 'Plone')
 
 **Example:**
@@ -75,7 +75,7 @@ Main configuration interface for the Plone construct.
 |----------|------|----------|---------|-------------|
 | `version` | `string` | No | - | Version of your project |
 | `siteId` | `string` | No | `'Plone'` | Plone site ID in ZODB |
-| `variant` | `PloneVariant` | No | `VOLTO` | Deployment variant (VOLTO or CLASSICUI) |
+| `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 |
@@ -212,7 +212,7 @@ frontend: {
 |----------|------|-------------|
 | `annotations` | `Record<string, string>` | Deployment metadata annotations |
 | `podAnnotations` | `Record<string, string>` | Pod template annotations (e.g., for Prometheus) |
-| `serviceAnnotations` | `Record<string, string>` | Service annotations (e.g., for external-dns) |
+| `serviceAnnotations` | `Record<string, string>` | **Deprecated.** Use `service.annotations` instead. Service annotations (e.g., for external-dns) |
 
 **Example:**
 ```typescript
@@ -228,6 +228,44 @@ backend: {
 }
 ```
 
+#### 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:**
+```typescript
+backend: {
+  service: {
+    type: 'LoadBalancer',
+    trafficDistribution: 'PreferClose',
+    loadBalancerSourceRanges: ['10.0.0.0/8'],
+    annotations: {
+      'external-dns.alpha.kubernetes.io/hostname': 'backend.example.com',
+    },
+    overrides: {
+      ipFamilyPolicy: 'PreferDualStack',
+    },
+  },
+}
+```
+
 (monitoring)=
 
 #### Prometheus monitoring
@@ -543,18 +581,24 @@ Defines the deployment variant:
 
 | Value | Description |
 |-------|-------------|
-| `PloneVariant.VOLTO` | Modern React frontend with REST API backend (default) |
-| `PloneVariant.CLASSICUI` | Traditional server-side rendered Plone |
+| `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 (modern)
+// Volto (React single-page frontend)
 variant: PloneVariant.VOLTO
 
-// Classic UI
-variant: PloneVariant.CLASSICUI
+// Blicca (server-side rendered)
+variant: PloneVariant.BLICCA
 ```
 
 ---
@@ -625,7 +669,7 @@ app.synth();
 
 - {doc}`/tutorials/01-quick-start` — Get started guide
 - {doc}`/how-to/deploy-production-volto` — Production-ready Volto deployment
-- {doc}`/how-to/deploy-classic-ui` — Classic UI 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

package/documentation/sources/tutorials/01-quick-start.md

@@ -147,7 +147,7 @@ Now that you have a basic Plone deployment:
 
 - **Configure resources**: See {doc}`/reference/configuration-options` for CPU and memory options.
 - **Add monitoring**: Follow {doc}`/how-to/enable-prometheus-monitoring`.
-- **Explore variants**: Read about Volto and Classic UI in {doc}`/explanation/features`.
+- **Explore variants**: Read about Volto and Blicca in {doc}`/explanation/features`.
 - **Harden pods**: Apply {doc}`/how-to/configure-security-context`.
 
 ## Troubleshooting