@bluedynamics/cdk8s-plone 0.1.36 → 0.1.37

package/.jsii

@@ -7,7 +7,7 @@
     ]
   },
   "dependencies": {
-    "cdk8s": "^2.70.61",
+    "cdk8s": "^2.70.68",
     "cdk8s-plus-30": "^2.4.10",
     "constructs": "^10.4.2"
   },
@@ -96,7 +96,7 @@
     "stability": "stable"
   },
   "homepage": "https://github.com/bluedynamics/cdk8s-plone.git",
-  "jsiiVersion": "5.9.40 (build 8be98bb)",
+  "jsiiVersion": "5.9.44 (build 150b837)",
   "license": "Apache-2.0",
   "metadata": {
     "jsii": {
@@ -2852,6 +2852,6 @@
       "symbolId": "src/vinylcache:VinylCacheToleration"
     }
   },
-  "version": "0.1.36",
-  "fingerprint": "Ufk/ThxeVlsfac24o/slWV/jPtliQCOpuRC08b4OaPs="
+  "version": "0.1.37",
+  "fingerprint": "rqqbRO9tw8jfYJJ8yRLP4FujYP+s1XI39yoPynOIT1M="
 }

package/documentation/sources/explanation/architecture.md

@@ -1,4 +1,13 @@
-# Architecture Overview
+---
+myst:
+  html_meta:
+    "description": "Architecture and design of cdk8s-plone deployments: components, caching options, and production considerations."
+    "property=og:description": "Architecture and design of cdk8s-plone deployments: components, caching options, and production considerations."
+    "property=og:title": "Architecture overview"
+    "keywords": "Plone, cdk8s, Kubernetes, architecture, design, Volto, Varnish, caching"
+---
+
+# Architecture overview
 
 Understanding the architecture and design of cdk8s-plone deployments.
 
@@ -6,9 +15,9 @@ Understanding the architecture and design of cdk8s-plone deployments.
 
 cdk8s-plone provides CDK8S constructs for deploying Plone CMS on Kubernetes. The library handles all Kubernetes resources needed for a production-grade Plone deployment.
 
-## Key Features
+## Key features
 
-### Deployment Variants
+### Deployment variants
 
 cdk8s-plone supports two deployment variants:
 
@@ -25,7 +34,7 @@ cdk8s-plone supports two deployment variants:
 - Traditional Plone experience
 - Simpler deployment model
 
-### High Availability
+### High availability
 
 **Replica Management**
 - Configurable number of replicas for backend and frontend
@@ -42,7 +51,7 @@ cdk8s-plone supports two deployment variants:
 - Liveness probes: Automatic restart of unhealthy pods
 - Configurable delays, timeouts, and thresholds
 
-### HTTP Caching Layer
+### HTTP caching layer
 
 **Varnish Integration**
 - Uses [kube-httpcache](https://github.com/mittwald/kube-httpcache) Helm chart
@@ -57,7 +66,7 @@ cdk8s-plone supports two deployment variants:
 - Better scalability
 - Automatic cache invalidation on content changes
 
-### Caching Options
+### Caching options
 
 cdk8s-plone supports two HTTP caching approaches:
 
@@ -75,7 +84,7 @@ cdk8s-plone supports two HTTP caching approaches:
 
 Choose PloneHttpcache for standalone deployments without cloud-vinyl. Choose PloneVinylCache when the operator is available for centralized cache management.
 
-### Multi-Language Support
+### Multi-language support
 
 The library is published in multiple languages:
 
@@ -89,7 +98,7 @@ The library is published in multiple languages:
 - Pythonic API
 - Published to PyPI: `cdk8s-plone`
 
-## Architecture Diagram
+## Architecture diagram
 
 ```mermaid
 graph TB
@@ -139,7 +148,7 @@ graph TB
     Backend3 --> DB
 ```
 
-## Component Responsibilities
+## Component responsibilities
 
 ### Backend
 
@@ -195,7 +204,7 @@ graph TB
 - Horizontal: Add replicas for cache distribution
 - Vertical: Increase memory for larger cache
 
-## Kubernetes Resources Created
+## Kubernetes resources created
 
 For a typical Volto deployment, cdk8s-plone creates:
 
@@ -217,9 +226,9 @@ For a typical Volto deployment, cdk8s-plone creates:
 - Secret (admin credentials)
 - ServiceMonitor (optional, for Prometheus)
 
-## Design Decisions
+## Design decisions
 
-### CDK8S Constructs
+### CDK8S constructs
 
 **Why CDK8S?**
 - Type-safe infrastructure as code
@@ -234,7 +243,7 @@ For a typical Volto deployment, cdk8s-plone creates:
 - Easier testing
 - Composition over configuration
 
-### Separate Frontend/Backend
+### Separate frontend and backend
 
 **Volto Architecture:**
 - Independent scaling of frontend and backend
@@ -248,7 +257,7 @@ For a typical Volto deployment, cdk8s-plone creates:
 - Legacy integrations
 - Specific add-on requirements
 
-### Optional Varnish Layer
+### Optional Varnish layer
 
 **Design Choice:**
 - Varnish is optional, not mandatory
@@ -262,7 +271,7 @@ For a typical Volto deployment, cdk8s-plone creates:
 - Better performance at scale
 - Reduced backend load
 
-### Health Probes
+### Health probes
 
 **Readiness Probe:**
 - Enabled by default for backend
@@ -274,9 +283,9 @@ For a typical Volto deployment, cdk8s-plone creates:
 - Recommended enabled for frontend (detect SSR hangs)
 - Configurable thresholds
 
-## Production Considerations
+## Production considerations
 
-### Resource Planning
+### Resource planning
 
 **Backend:**
 - Plan for catalog size and query complexity
@@ -292,7 +301,7 @@ For a typical Volto deployment, cdk8s-plone creates:
 - Memory size determines cache capacity
 - Monitor hit rates and adjust sizing
 
-### High Availability
+### High availability
 
 **Recommendations:**
 - Minimum 2 replicas per component
@@ -321,9 +330,8 @@ For a typical Volto deployment, cdk8s-plone creates:
 - Grafana for visualization
 - Kubernetes events monitoring
 
-## See Also
+## See also
 
-- [Plone Variants](plone-variants.md) - Detailed comparison of Volto vs Classic UI
-- [Scaling Patterns](scaling-patterns.md) - Horizontal and vertical scaling strategies
-- [Configuration Options](../reference/configuration-options.md) - Complete configuration reference
-- [Quick Start](../tutorials/01-quick-start.md) - Getting started tutorial
+- {doc}`features` — Feature overview and deployment variants.
+- {doc}`/reference/configuration-options` — Complete configuration reference.
+- {doc}`/tutorials/01-quick-start` — Getting started tutorial.

package/documentation/sources/explanation/features.md

@@ -1,10 +1,21 @@
+---
+myst:
+  html_meta:
+    "description": "Overview of cdk8s-plone features: deployment variants, high availability, caching, resource management, monitoring, and multi-language support."
+    "property=og:description": "Overview of cdk8s-plone features: deployment variants, high availability, caching, resource management, monitoring, and multi-language support."
+    "property=og:title": "Features"
+    "keywords": "Plone, cdk8s, Kubernetes, features, Volto, Varnish, Prometheus"
+---
+
 # Features
 
 Complete overview of cdk8s-plone features and capabilities.
 
-## Core Features
+## Core features
+
+(deployment-variants)=
 
-### Deployment Variants
+### Deployment variants
 
 cdk8s-plone supports two deployment modes to match your requirements:
 
@@ -20,9 +31,9 @@ cdk8s-plone supports two deployment modes to match your requirements:
 - Traditional Plone experience
 - Best for: Legacy migrations, existing add-ons, simpler deployments
 
-See [Plone Variants](plone-variants.md) for detailed comparison.
+See {doc}`architecture` for a deeper architectural comparison of the two variants.
 
-### High Availability
+### High availability
 
 **Configurable Replicas**
 - Set any number of replicas for backend and frontend
@@ -42,7 +53,7 @@ backend: {
 }
 ```
 
-### HTTP Caching with Varnish
+### HTTP caching with Varnish
 
 cdk8s-plone supports two caching backends: the self-contained mittwald kube-httpcache Helm chart (`PloneHttpcache`) and the operator-managed cloud-vinyl VinylCache (`PloneVinylCache`).
 
@@ -69,7 +80,7 @@ cdk8s-plone supports two caching backends: the self-contained mittwald kube-http
 - Cache hit/miss metrics
 - Performance monitoring
 
-### Resource Management
+### Resource management
 
 **Fine-Grained Control**
 - CPU requests and limits
@@ -87,7 +98,7 @@ backend: {
 }
 ```
 
-### Health Monitoring
+### Health monitoring
 
 **Readiness Probes**
 - Ensures pods are ready before receiving traffic
@@ -112,7 +123,7 @@ frontend: {
 }
 ```
 
-### Environment Configuration
+### Environment configuration
 
 **Flexible Environment Variables**
 - Use cdk8s-plus-30 Env API
@@ -134,7 +145,7 @@ backend: {
 }
 ```
 
-### Kubernetes Annotations
+### Kubernetes annotations
 
 **Three Levels of Annotations**
 - **Deployment annotations**: Metadata for the deployment resource
@@ -154,7 +165,7 @@ backend: {
 }
 ```
 
-### Private Registry Support
+### Private registry support
 
 **Image Pull Secrets**
 - Support for private container registries
@@ -169,17 +180,17 @@ new Plone(chart, 'my-plone', {
 })
 ```
 
-## Multi-Language Support
+## Multi-language support
 
-### TypeScript/JavaScript
+### TypeScript and JavaScript
 
-**Native CDK8S Experience**
+**Native CDK8S experience**
 - Full TypeScript type definitions
 - IDE autocomplete and validation
 - Familiar syntax for web developers
 
 **Installation:**
-```bash
+```shell
 npm install @bluedynamics/cdk8s-plone
 ```
 
@@ -195,13 +206,13 @@ new Plone(chart, 'my-plone', {
 
 ### Python
 
-**JSII-Generated Bindings**
+**JSII-generated bindings**
 - Pythonic API
 - Type hints support
 - Familiar syntax for Python developers
 
 **Installation:**
-```bash
+```shell
 pip install cdk8s-plone
 ```
 
@@ -215,11 +226,11 @@ Plone(chart, "my-plone",
 )
 ```
 
-## Infrastructure as Code Benefits
+## Infrastructure as code benefits
 
-### Type Safety
+### Type safety
 
-**Compile-Time Validation**
+**Compile-time validation**
 - Catch configuration errors before deployment
 - IDE validation and autocomplete
 - Refactoring support
@@ -235,7 +246,7 @@ backend: {
 
 ### Reusability
 
-**Construct Composition**
+**Construct composition**
 - Create custom constructs
 - Encapsulate best practices
 - Share across projects
@@ -266,7 +277,7 @@ class ProductionPlone extends Construct {
 
 ### Testing
 
-**Unit Testing**
+**Unit testing**
 - Test infrastructure definitions
 - Validate resource creation
 - Catch regressions early
@@ -284,9 +295,9 @@ test('creates backend deployment', () => {
 });
 ```
 
-### Programmatic Control
+### Programmatic control
 
-**Dynamic Configuration**
+**Dynamic configuration**
 - Use loops and conditionals
 - Environment-based configuration
 - Dynamic resource generation
@@ -305,9 +316,9 @@ environments.forEach(env => {
 });
 ```
 
-## Production-Ready Features
+## Production-ready features
 
-### Manifest Generation
+### Manifest generation
 
 **Standard Kubernetes YAML**
 - Generates standard Kubernetes manifests
@@ -315,22 +326,22 @@ environments.forEach(env => {
 - Apply with `kubectl apply -f`
 
 **Output:**
-```bash
+```shell
 cdk8s synth
 # Creates dist/ directory with YAML files
 kubectl apply -f dist/
 ```
 
-### Helm Chart Integration
+### Helm chart integration
 
-**PloneHttpcache Uses Helm**
+**PloneHttpcache uses Helm**
 - Leverages battle-tested kube-httpcache chart
 - Automatic updates available
 - Community-maintained
 
-### Monitoring Integration
+### Monitoring integration
 
-**Prometheus Ready**
+**Prometheus ready**
 - ServiceMonitor support for Varnish
 - Pod annotations for scraping
 - Standard metrics endpoints
@@ -344,7 +355,7 @@ new PloneHttpcache(chart, 'cache', {
 });
 ```
 
-## Upcoming Features
+## Upcoming features
 
 Features planned for future releases:
 
@@ -353,9 +364,9 @@ Features planned for future releases:
 
 **Note:** Ingress and TLS management are intentionally out of scope - these should be handled by your cluster's ingress controller and cert-manager. RelStorage with PostgreSQL is already supported through external database configuration (separation of concerns).
 
-## See Also
+## See also
 
-- [Architecture Overview](architecture.md) - System architecture and design
-- [Configuration Options](../reference/configuration-options.md) - Complete configuration reference
-- [Quick Start](../tutorials/01-quick-start.md) - Getting started tutorial
-- [Example Project](https://github.com/bluedynamics/cdk8s-plone-example) - Complete working example
+- {doc}`architecture` — System architecture and design.
+- {doc}`/reference/configuration-options` — Complete configuration reference.
+- {doc}`/tutorials/01-quick-start` — Getting started tutorial.
+- [Example project](https://github.com/bluedynamics/cdk8s-plone-example) — Complete working example.

package/documentation/sources/explanation/index.md

@@ -1,3 +1,12 @@
+---
+myst:
+  html_meta:
+    "description": "Understanding-oriented discussion of cdk8s-plone concepts, architecture, and design decisions."
+    "property=og:description": "Understanding-oriented discussion of cdk8s-plone concepts, architecture, and design decisions."
+    "property=og:title": "Explanation"
+    "keywords": "Plone, cdk8s, Kubernetes, architecture, design, concepts"
+---
+
 ```{image} ../_static/kup6s-icon-explanation.svg
 :align: center
 :class: section-icon-large
@@ -9,7 +18,7 @@
 
 Explanation guides clarify and illuminate particular topics. They broaden the understanding of cdk8s-plone and help you make informed decisions about how to use it.
 
-## Architecture & Concepts
+## Architecture and concepts
 
 ```{toctree}
 ---
@@ -20,7 +29,7 @@ features
 architecture
 ```
 
-## Key Topics
+## Key topics
 
 *This section will explain:*
 - Plone architecture and component relationships
@@ -34,7 +43,7 @@ architecture
 - Scaling and high availability considerations
 - Performance optimization
 
-## Design Decisions
+## Design decisions
 
 *This section will document:*
 - Why certain defaults were chosen

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

@@ -0,0 +1,148 @@
+---
+myst:
+  html_meta:
+    "description": "Harden Plone backend and frontend pods with a Kubernetes container security context: capabilities, UID/GID, read-only root, privilege escalation."
+    "property=og:description": "Harden Plone backend and frontend pods with a Kubernetes container security context: capabilities, UID/GID, read-only root, privilege escalation."
+    "property=og:title": "Configure security context"
+    "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">
+  <div class="metadata-content">
+    <p><strong>Type</strong>: How-To (Task-oriented)</p>
+    <p><strong>Difficulty</strong>: Intermediate</p>
+    <p><strong>Time</strong>: 10 minutes</p>
+  </div>
+</div>
+
+This guide shows you how to harden backend and frontend pods by setting a Kubernetes container security context through `cdk8s-plone`.
+Use it when your cluster enforces Pod Security Standards, when an admission webhook rejects permissive pods, or when you want to apply least-privilege defaults.
+
+## Prerequisites
+
+- A working Plone deployment using `cdk8s-plone`.
+- A Plone image that runs as a non-root user (the official `plone/plone-backend` and `plone/plone-frontend` images do).
+- Cluster knowledge of any namespace-level Pod Security Standards in effect.
+
+## Apply a baseline hardened context
+
+Set `securityContext` on `backend` or `frontend` (or both).
+
+```typescript
+import { Plone, PloneVariant } from '@bluedynamics/cdk8s-plone';
+
+new Plone(chart, 'plone', {
+  variant: PloneVariant.VOLTO,
+  backend: {
+    image: 'plone/plone-backend:6.1.3',
+    securityContext: {
+      runAsNonRoot: true,
+      allowPrivilegeEscalation: false,
+      capabilities: {
+        drop: ['ALL'],
+      },
+    },
+  },
+  frontend: {
+    image: 'plone/plone-frontend:16.0.0',
+    securityContext: {
+      runAsNonRoot: true,
+      allowPrivilegeEscalation: false,
+      capabilities: {
+        drop: ['ALL'],
+      },
+    },
+  },
+});
+```
+
+These four settings satisfy the Kubernetes **restricted** Pod Security Standard for containers that do not need extra capabilities.
+
+## Pin the UID and GID
+
+If your cluster requires explicit user and group IDs (for example, when you mount shared volumes), set them:
+
+```typescript
+backend: {
+  image: 'plone/plone-backend:6.1.3',
+  securityContext: {
+    runAsUser: 500,
+    runAsGroup: 500,
+    runAsNonRoot: true,
+  },
+}
+```
+
+The official Plone backend image already uses UID `500`.
+Match that UID to keep file permissions consistent with the image.
+
+## Mount the root filesystem read-only
+
+```typescript
+backend: {
+  image: 'plone/plone-backend:6.1.3',
+  securityContext: {
+    runAsNonRoot: true,
+    readOnlyRootFilesystem: true,
+    allowPrivilegeEscalation: false,
+    capabilities: {
+      drop: ['ALL'],
+    },
+  },
+}
+```
+
+```{warning}
+A read-only root filesystem breaks any container that writes outside mounted volumes.
+Plone's Zope writes temporary files; verify the pod stays `Ready` after rollout.
+Mount writable `emptyDir` volumes for `/tmp` and the Zope `var/` directory through `podAnnotations` or the underlying `Deployment` patches if you hit `EROFS` errors.
+```
+
+## Add a specific capability
+
+When you must add a Linux capability, drop everything else first.
+
+```typescript
+backend: {
+  image: 'plone/plone-backend:6.1.3',
+  securityContext: {
+    runAsNonRoot: true,
+    allowPrivilegeEscalation: false,
+    capabilities: {
+      add: ['SYS_PTRACE'],
+      drop: ['ALL'],
+    },
+  },
+}
+```
+
+## Verify the rollout
+
+```shell
+# Generate manifests
+cdk8s synth
+
+# Confirm the securityContext appears on the pod template
+grep -A 10 securityContext dist/*.yaml
+
+# Apply and check pod status
+kubectl apply -f dist/
+kubectl rollout status deployment/<plone-backend-deployment> -n <namespace>
+
+# Inspect the running container
+kubectl exec -n <namespace> deployment/<plone-backend-deployment> -- id
+```
+
+A pod that fails to start with `CreateContainerConfigError` or `permission denied` usually points to a UID, capability, or read-only conflict.
+
+## See also
+
+- {doc}`/reference/configuration-options` — Full `PloneSecurityContext` reference.
+- [Kubernetes Pod Security Standards](https://kubernetes.io/docs/concepts/security/pod-security-standards/) — Cluster-level policy reference.