@bluedynamics/cdk8s-plone 0.1.35 → 0.1.37

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

@@ -0,0 +1,123 @@
+---
+myst:
+  html_meta:
+    "description": "Create a Prometheus ServiceMonitor for the Plone backend, frontend, or Varnish cache to expose metrics."
+    "property=og:description": "Create a Prometheus ServiceMonitor for the Plone backend, frontend, or Varnish cache to expose metrics."
+    "property=og:title": "Enable Prometheus monitoring"
+    "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">
+  <div class="metadata-content">
+    <p><strong>Type</strong>: How-To (Task-oriented)</p>
+    <p><strong>Difficulty</strong>: Intermediate</p>
+    <p><strong>Time</strong>: 15 minutes</p>
+  </div>
+</div>
+
+This guide shows you how to expose Plone metrics to Prometheus by creating a `ServiceMonitor` for the backend, the frontend, or the Varnish cache.
+
+## Prerequisites
+
+- The [Prometheus Operator](https://github.com/prometheus-operator/prometheus-operator) installed in the cluster (it provides the `ServiceMonitor` CRD).
+- A `Prometheus` resource that selects the `ServiceMonitor` resources you create (check `serviceMonitorSelector` and `serviceMonitorNamespaceSelector`).
+- A Plone container instrumented to expose metrics over HTTP. Plone itself does not ship a Prometheus endpoint; you need an add-on (such as a WSGI middleware) or a sidecar exporter.
+
+## Enable the ServiceMonitor on the backend
+
+```typescript
+import { Plone, PloneVariant } from '@bluedynamics/cdk8s-plone';
+
+new Plone(chart, 'plone', {
+  variant: PloneVariant.VOLTO,
+  backend: {
+    image: 'plone/plone-backend:6.1.3',
+    servicemonitor: true,
+    metricsPath: '/metrics',
+  },
+  frontend: {
+    image: 'plone/plone-frontend:16.0.0',
+  },
+});
+```
+
+`servicemonitor: true` instructs `cdk8s-plone` to emit a `ServiceMonitor` that scrapes the backend Service on its main port at `/metrics`.
+
+## Scrape the frontend on a dedicated port
+
+Volto can expose metrics on a separate port through middleware such as [`express-prometheus-middleware`](https://www.npmjs.com/package/express-prometheus-middleware).
+Point `cdk8s-plone` at that port:
+
+```typescript
+frontend: {
+  image: 'plone/plone-frontend:16.0.0',
+  servicemonitor: true,
+  metricsPort: 9090,
+  metricsPath: '/metrics',
+}
+```
+
+`metricsPort` accepts a port number or a Service port name.
+
+## Scrape the Varnish cache
+
+`PloneHttpcache` and `PloneVinylCache` each accept their own monitoring switch.
+
+```typescript
+import { PloneHttpcache } from '@bluedynamics/cdk8s-plone';
+
+new PloneHttpcache(chart, 'cache', {
+  plone: ploneInstance,
+  servicemonitor: true,
+  exporterEnabled: true,
+});
+```
+
+`exporterEnabled` (default `true`) deploys the Varnish exporter sidecar that the `ServiceMonitor` scrapes.
+
+For the cloud-vinyl operator:
+
+```typescript
+import { PloneVinylCache } from '@bluedynamics/cdk8s-plone';
+
+new PloneVinylCache(chart, 'cache', {
+  plone: ploneInstance,
+  monitoring: true,
+});
+```
+
+## Verify the rollout
+
+```shell
+# Generate manifests and confirm the ServiceMonitor exists
+cdk8s synth
+grep -l 'kind: ServiceMonitor' dist/*.yaml
+
+# Apply and inspect on the cluster
+kubectl apply -f dist/
+kubectl get servicemonitor -n <namespace>
+kubectl describe servicemonitor <name> -n <namespace>
+```
+
+If Prometheus is not picking up the new target, confirm:
+
+- The `ServiceMonitor` namespace matches the `Prometheus` resource's `serviceMonitorNamespaceSelector`.
+- The `ServiceMonitor` labels match the `Prometheus` resource's `serviceMonitorSelector`.
+- The metrics endpoint returns HTTP 200 from a pod in the cluster:
+
+  ```shell
+  kubectl run -it --rm curl --image=curlimages/curl --restart=Never -- \
+    curl -sf http://<service>.<namespace>:<port>/metrics | head
+  ```
+
+## See also
+
+- {doc}`/reference/configuration-options` — Reference for `servicemonitor`, `metricsPort`, `metricsPath`.
+- [Prometheus Operator documentation](https://prometheus-operator.dev/) — `ServiceMonitor` selectors and lifecycle.

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

@@ -1,9 +1,18 @@
+---
+myst:
+  html_meta:
+    "description": "Goal-oriented how-to guides for solving specific cdk8s-plone deployment and configuration problems."
+    "property=og:description": "Goal-oriented how-to guides for solving specific cdk8s-plone deployment and configuration problems."
+    "property=og:title": "How-to guides"
+    "keywords": "Plone, cdk8s, Kubernetes, how-to, deployment, configuration"
+---
+
 ```{image} ../_static/kup6s-icon-howto.svg
 :align: center
 :class: section-icon-large
 ```
 
-# How-To Guides
+# How-to guides
 
 **Goal-oriented guides showing you how to solve specific problems with cdk8s-plone.**
 
@@ -42,21 +51,20 @@ deploy-with-vinyl-cache
 maxdepth: 1
 titlesonly: true
 ---
+configure-security-context
+schedule-pods
 ```
 
-*Configuration guides will be added in future releases.*
-
-## Operations & Maintenance
+## Operations & maintenance
 
 ```{toctree}
 ---
 maxdepth: 1
 titlesonly: true
 ---
+enable-prometheus-monitoring
 ```
 
-*Operations guides will be added in future releases.*
-
 ## Troubleshooting
 
 *This section will be populated with troubleshooting guides in future releases.*

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

@@ -0,0 +1,150 @@
+---
+myst:
+  html_meta:
+    "description": "Constrain Plone backend, frontend, and Varnish pods to specific Kubernetes nodes using nodeSelector and tolerations."
+    "property=og:description": "Constrain Plone backend, frontend, and Varnish pods to specific Kubernetes nodes using nodeSelector and tolerations."
+    "property=og:title": "Schedule pods to specific nodes"
+    "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">
+  <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 control where Plone backend, frontend, and Varnish pods run.
+Use `nodeSelector` to require specific node labels and tolerations to schedule onto tainted nodes.
+
+## Prerequisites
+
+- A working Plone deployment using `cdk8s-plone`.
+- Cluster labels and taints already configured on the target nodes.
+
+  ```shell
+  kubectl get nodes --show-labels
+  kubectl describe node <node> | grep Taints
+  ```
+
+## Constrain pods to labeled nodes
+
+Add `nodeSelector` to `backend`, `frontend`, or both.
+Every label in the selector must match for a node to be considered.
+
+```typescript
+import { Plone, PloneVariant } from '@bluedynamics/cdk8s-plone';
+
+new Plone(chart, 'plone', {
+  variant: PloneVariant.VOLTO,
+  backend: {
+    image: 'plone/plone-backend:6.1.3',
+    nodeSelector: {
+      'topology.kubernetes.io/region': 'fsn1',
+      'workload': 'plone',
+    },
+  },
+  frontend: {
+    image: 'plone/plone-frontend:16.0.0',
+    nodeSelector: {
+      'workload': 'plone',
+    },
+  },
+});
+```
+
+## Schedule the cache onto the same nodes
+
+`PloneVinylCache` exposes the same `nodeSelector` option.
+
+```typescript
+import { PloneVinylCache } from '@bluedynamics/cdk8s-plone';
+
+new PloneVinylCache(chart, 'cache', {
+  plone: ploneInstance,
+  nodeSelector: {
+    'workload': 'plone',
+  },
+});
+```
+
+`PloneHttpcache` schedules through the underlying mittwald Helm chart and does not expose a `nodeSelector` option directly.
+Use cluster-level affinity rules or taints when you need to constrain those pods.
+
+## Tolerate tainted nodes
+
+When nodes carry a taint, pods must declare a matching toleration before the scheduler places them there.
+Both cache constructs accept a `tolerations` list.
+
+```typescript
+new PloneHttpcache(chart, 'cache', {
+  plone: ploneInstance,
+  tolerations: [
+    {
+      key: 'workload',
+      operator: 'Equal',
+      value: 'plone',
+      effect: 'NoSchedule',
+    },
+  ],
+});
+```
+
+```typescript
+new PloneVinylCache(chart, 'cache', {
+  plone: ploneInstance,
+  tolerations: [
+    {
+      key: 'workload',
+      operator: 'Equal',
+      value: 'plone',
+      effect: 'NoSchedule',
+    },
+  ],
+});
+```
+
+`operator: 'Exists'` matches any value for that key.
+Omit `effect` to tolerate every effect for the matching taint.
+
+## Combine selector and toleration
+
+Selectors and tolerations work together: the selector narrows the candidate nodes, and the toleration unblocks the scheduler when those nodes are tainted.
+
+```typescript
+new PloneVinylCache(chart, 'cache', {
+  plone: ploneInstance,
+  nodeSelector: {
+    'workload': 'plone',
+  },
+  tolerations: [
+    { key: 'workload', operator: 'Equal', value: 'plone', effect: 'NoSchedule' },
+  ],
+});
+```
+
+## Verify the rollout
+
+```shell
+cdk8s synth
+kubectl apply -f dist/
+
+# Confirm pods landed on the expected nodes
+kubectl get pods -n <namespace> -o wide
+```
+
+A pod stuck in `Pending` with `0/N nodes are available: ... node(s) had untolerated taint` means a taint is not tolerated.
+`0/N nodes are available: ... node(s) didn't match Pod's node affinity/selector` means the `nodeSelector` does not match any node.
+
+## See also
+
+- {doc}`/reference/configuration-options` — `nodeSelector`, `HttpcacheToleration`, `VinylCacheToleration` reference.
+- [Kubernetes: Assigning Pods to Nodes](https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/) — Selectors, affinity, and taints.

package/documentation/sources/how-to/setup-prerequisites.md

@@ -1,8 +1,17 @@
-# Setup Prerequisites
+---
+myst:
+  html_meta:
+    "description": "Install kubectl, Node.js or Python, CDK8S, and prepare a Kubernetes cluster to deploy Plone with cdk8s-plone."
+    "property=og:description": "Install kubectl, Node.js or Python, CDK8S, and prepare a Kubernetes cluster to deploy Plone with cdk8s-plone."
+    "property=og:title": "Setup prerequisites"
+    "keywords": "Plone, cdk8s, Kubernetes, kubectl, Node.js, Python, prerequisites"
+---
+
+# Setup prerequisites
 
 Prepare your environment for deploying Plone with cdk8s-plone.
 
-## Required Tools
+## Required tools
 
 ### kubectl
 
@@ -12,12 +21,12 @@ Command-line tool for deploying and managing Kubernetes resources.
 - [Install kubectl](https://kubernetes.io/docs/tasks/tools/#kubectl)
 
 **Verify installation:**
-```bash
+```shell
 kubectl version --client
 ```
 
 **Configure cluster access:**
-```bash
+```shell
 # Verify you can connect to your cluster
 kubectl cluster-info
 kubectl get nodes
@@ -33,18 +42,18 @@ Required for TypeScript/JavaScript development.
 **Installation:**
 - [Install Node.js](https://nodejs.org/)
 - Or use [nvm](https://github.com/nvm-sh/nvm):
-  ```bash
+  ```shell
   nvm install --lts
   nvm use --lts
   ```
 
 **Verify installation:**
-```bash
+```shell
 node --version
 npm --version
 ```
 
-### Python (for Python Development)
+### Python (for Python development)
 
 Required for Python development.
 
@@ -55,7 +64,7 @@ Required for Python development.
 - [Install Python](https://www.python.org/downloads/)
 
 **Verify installation:**
-```bash
+```shell
 python --version
 pip --version
 ```
@@ -65,16 +74,16 @@ pip --version
 The CDK8S command-line tool for project initialization and synthesis.
 
 **Installation:**
-```bash
+```shell
 npm install -g cdk8s-cli
 ```
 
 **Verify installation:**
-```bash
+```shell
 cdk8s --version
 ```
 
-## Optional Tools
+## Optional tools
 
 ### Helm
 
@@ -84,7 +93,7 @@ Required only if you want to generate Helm charts instead of raw Kubernetes mani
 - [Install Helm](https://helm.sh/docs/intro/install/)
 
 **Verify installation:**
-```bash
+```shell
 helm version
 ```
 
@@ -96,7 +105,7 @@ Terminal-based UI for managing Kubernetes clusters (recommended for development)
 - [Install k9s](https://k9scli.io/topics/install/)
 
 **Usage:**
-```bash
+```shell
 k9s
 ```
 
@@ -108,7 +117,7 @@ Tools for switching between Kubernetes contexts and namespaces.
 - [Install kubectx](https://github.com/ahmetb/kubectx#installation)
 
 **Usage:**
-```bash
+```shell
 kubectx                  # List contexts
 kubectx my-cluster       # Switch context
 kubens my-namespace      # Switch namespace
@@ -118,10 +127,10 @@ kubens my-namespace      # Switch namespace
 
 You need access to a Kubernetes cluster for deployment.
 
-### Local Development Clusters
+### Local development clusters
 
 **Minikube**
-```bash
+```shell
 # Install
 # https://minikube.sigs.k8s.io/docs/start/
 
@@ -133,7 +142,7 @@ kubectl cluster-info
 ```
 
 **kind (Kubernetes in Docker)**
-```bash
+```shell
 # Install
 # https://kind.sigs.k8s.io/docs/user/quick-start/
 
@@ -149,7 +158,7 @@ kubectl cluster-info
 - Verify with `kubectl cluster-info`
 
 **k3d (Lightweight Kubernetes)**
-```bash
+```shell
 # Install
 # https://k3d.io/
 
@@ -160,10 +169,10 @@ k3d cluster create plone-dev
 kubectl cluster-info
 ```
 
-### Cloud Kubernetes Services
+### Cloud Kubernetes services
 
 **Google Kubernetes Engine (GKE)**
-```bash
+```shell
 # Create cluster
 gcloud container clusters create plone-cluster \
   --num-nodes=3 \
@@ -174,7 +183,7 @@ gcloud container clusters get-credentials plone-cluster
 ```
 
 **Amazon EKS**
-```bash
+```shell
 # Create cluster using eksctl
 eksctl create cluster \
   --name plone-cluster \
@@ -186,7 +195,7 @@ kubectl get nodes
 ```
 
 **Azure Kubernetes Service (AKS)**
-```bash
+```shell
 # Create cluster
 az aks create \
   --resource-group myResourceGroup \
@@ -200,9 +209,9 @@ az aks get-credentials \
   --name plone-cluster
 ```
 
-## Cluster Requirements
+## Cluster requirements
 
-### Minimum Resources
+### Minimum resources
 
 **For development/testing:**
 - **Nodes:** 1-2 nodes
@@ -216,7 +225,7 @@ az aks get-credentials \
 - **Memory:** 8GB+ per node
 - **Storage:** 50GB+ per node
 
-### Required Kubernetes Features
+### Required Kubernetes features
 
 - **Version:** Kubernetes 1.20+
 - **Networking:** CNI plugin installed
@@ -224,17 +233,17 @@ az aks get-credentials \
 - **DNS:** CoreDNS or equivalent
 
 **Verify storage classes:**
-```bash
+```shell
 kubectl get storageclasses
 ```
 
 If no storage class exists, you need to configure one for your cluster.
 
-## Namespace Setup
+## Namespace setup
 
 Create a namespace for your Plone deployment:
 
-```bash
+```shell
 # Create namespace
 kubectl create namespace plone
 
@@ -245,20 +254,20 @@ kubectl config set-context --current --namespace=plone
 kubectl config view --minify | grep namespace:
 ```
 
-## Image Registry Access
+## Image registry access
 
-### Public Registries
+### Public registries
 
 No configuration needed for public Plone images:
 - `plone/plone-backend:6.1.3`
 - `plone/plone-frontend:16.0.0`
 
-### Private Registries
+### Private registries
 
 Create a pull secret for private registries:
 
 **Docker Hub:**
-```bash
+```shell
 kubectl create secret docker-registry docker-hub \
   --docker-server=docker.io \
   --docker-username=YOUR_USERNAME \
@@ -267,7 +276,7 @@ kubectl create secret docker-registry docker-hub \
 ```
 
 **Google Container Registry:**
-```bash
+```shell
 kubectl create secret docker-registry gcr-secret \
   --docker-server=gcr.io \
   --docker-username=_json_key \
@@ -276,7 +285,7 @@ kubectl create secret docker-registry gcr-secret \
 ```
 
 **Azure Container Registry:**
-```bash
+```shell
 kubectl create secret docker-registry acr-secret \
   --docker-server=myregistry.azurecr.io \
   --docker-username=YOUR_USERNAME \
@@ -291,7 +300,7 @@ new Plone(chart, 'my-plone', {
 });
 ```
 
-## Verification Checklist
+## Verification checklist
 
 Before proceeding, verify:
 
@@ -304,7 +313,7 @@ Before proceeding, verify:
 - [ ] Image pull secrets created (if using private registries)
 
 **Verify everything:**
-```bash
+```shell
 # Check tools
 kubectl version --client
 cdk8s --version
@@ -319,13 +328,13 @@ kubectl get storageclasses
 kubectl get namespace plone
 ```
 
-## Next Steps
+## Next steps
 
 Now that your environment is ready:
 
-1. **Start the tutorial**: Follow the [Quick Start](../tutorials/01-quick-start.md) guide
-2. **Explore examples**: Check the [example project](https://github.com/bluedynamics/cdk8s-plone-example)
-3. **Read about variants**: Learn about [Plone variants](../explanation/features.md#deployment-variants)
+1. **Start the tutorial**: Follow the {doc}`/tutorials/01-quick-start` guide.
+2. **Explore examples**: Check the [example project](https://github.com/bluedynamics/cdk8s-plone-example).
+3. **Read about variants**: Learn about {ref}`deployment-variants` in the features overview.
 
 ## Troubleshooting
 
@@ -347,8 +356,8 @@ Now that your environment is ready:
 - Verify RBAC permissions: `kubectl auth can-i create deployments`
 - Contact your cluster administrator for proper permissions
 
-## See Also
+## See also
 
-- [Quick Start Tutorial](../tutorials/01-quick-start.md) - Get started with deployment
-- [Architecture Overview](../explanation/architecture.md) - Understanding the system
-- [Configuration Options](../reference/configuration-options.md) - Complete configuration reference
+- {doc}`/tutorials/01-quick-start` — Get started with deployment.
+- {doc}`/explanation/architecture` — Understand the system.
+- {doc}`/reference/configuration-options` — Complete configuration reference.

package/documentation/sources/index.md

@@ -1,4 +1,13 @@
-# cdk8s-plone Documentation
+---
+myst:
+  html_meta:
+    "description": "Documentation for cdk8s-plone, a TypeScript and Python library for deploying Plone CMS to Kubernetes with CDK8S."
+    "property=og:description": "Documentation for cdk8s-plone, a TypeScript and Python library for deploying Plone CMS to Kubernetes with CDK8S."
+    "property=og:title": "cdk8s-plone documentation"
+    "keywords": "Plone, cdk8s, Kubernetes, Volto, CMS, infrastructure as code"
+---
+
+# cdk8s-plone documentation
 
 ```{image} _static/kup6s-icon-plone.svg
 :alt: cdk8s-plone logo
@@ -22,7 +31,7 @@ cdk8s-plone is a TypeScript construct library for [CDK8S](https://cdk8s.io/) tha
 - Component-level configuration options
 - Built on CDK8S for infrastructure as code
 
-## Documentation Structure
+## Documentation structure
 
 This documentation follows the [Diátaxis framework](https://diataxis.fr/), organizing content into four categories based on what you need:
 
@@ -71,23 +80,23 @@ This documentation follows the [Diátaxis framework](https://diataxis.fr/), orga
 
 ::::
 
-## Quick Links
+## Quick links
 
-### Getting Started
-- [Quick Start](tutorials/01-quick-start.md) - Deploy your first Plone instance
-- [Setup Prerequisites](how-to/setup-prerequisites.md) - Prepare cluster infrastructure
-- [Features Overview](explanation/features.md) - Explore capabilities
+### Getting started
+- {doc}`tutorials/01-quick-start` — Deploy your first Plone instance
+- {doc}`how-to/setup-prerequisites` — Prepare cluster infrastructure
+- {doc}`explanation/features` — Explore capabilities
 
 ### Configuration
-- [Configuration Options](reference/configuration-options.md) - Complete configuration reference
-- [Architecture Overview](explanation/architecture.md) - High-level design
+- {doc}`reference/configuration-options` — Complete configuration reference
+- {doc}`explanation/architecture` — High-level design
 
-### Common Tasks
-- Scale Resources - Adjust CPU and memory limits (coming soon)
-- Configure Monitoring - Set up Prometheus metrics (coming soon)
-- Backup and Restore - Protect your data (coming soon)
+### Common tasks
+- {doc}`how-to/configure-security-context` — Harden backend and frontend pods
+- {doc}`how-to/enable-prometheus-monitoring` — Wire up `ServiceMonitor`
+- {doc}`how-to/schedule-pods` — `nodeSelector` and tolerations
 
-## Table of Contents
+## Table of contents
 
 ```{toctree}
 ---