@bluedynamics/cdk8s-plone 0.1.5 → 0.1.6

package/documentation/sources/explanation/architecture.md

@@ -0,0 +1,311 @@
+# Architecture Overview
+
+Understanding the architecture and design of cdk8s-plone deployments.
+
+## Overview
+
+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
+
+### Deployment Variants
+
+cdk8s-plone supports two deployment variants:
+
+**Volto (Modern)**
+- 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
+- Single integrated service
+- Traditional Plone experience
+- Simpler deployment model
+
+### High Availability
+
+**Replica Management**
+- Configurable number of replicas for backend and frontend
+- Default: 2 replicas for each component
+- Supports horizontal scaling
+
+**Pod Disruption Budgets**
+- Ensures minimum availability during cluster operations
+- Configurable `minAvailable` and `maxUnavailable` thresholds
+- Protects against voluntary disruptions (node drains, updates)
+
+**Health Probes**
+- Readiness probes: Traffic routing only to healthy pods
+- Liveness probes: Automatic restart of unhealthy pods
+- Configurable delays, timeouts, and thresholds
+
+### HTTP Caching Layer
+
+**Varnish Integration**
+- Uses [kube-httpcache](https://github.com/mittwald/kube-httpcache) Helm chart
+- Cluster-wide cache invalidation
+- HTTP/2 support
+- Configurable VCL
+- Prometheus metrics export
+
+**Benefits**
+- Reduced backend load
+- Improved response times
+- Better scalability
+- Automatic cache invalidation on content changes
+
+### Multi-Language Support
+
+The library is published in multiple languages:
+
+**TypeScript/JavaScript**
+- Native CDK8S experience
+- Full TypeScript types
+- Published to npm: `@bluedynamics/cdk8s-plone`
+
+**Python**
+- JSII-generated Python bindings
+- Pythonic API
+- Published to PyPI: `cdk8s-plone`
+
+## Architecture Diagram
+
+```mermaid
+graph TB
+    subgraph "External Access"
+        Client[Client/Browser]
+        Ingress[Ingress Controller]
+    end
+
+    subgraph "HTTP Cache Layer (Optional)"
+        Varnish[Varnish Cache<br/>kube-httpcache]
+    end
+
+    subgraph "Plone Frontend (Volto)"
+        FrontendSvc[Frontend Service]
+        Frontend1[Frontend Pod 1]
+        Frontend2[Frontend Pod 2]
+    end
+
+    subgraph "Plone Backend (API)"
+        BackendSvc[Backend Service]
+        Backend1[Backend Pod 1]
+        Backend2[Backend Pod 2]
+        Backend3[Backend Pod 3]
+    end
+
+    subgraph "Data Layer"
+        DB[(External Database<br/>PostgreSQL/MySQL/Oracle<br/>with RelStorage)]
+    end
+
+    Client --> Ingress
+    Ingress --> Varnish
+    Varnish -.cache miss.-> FrontendSvc
+    Varnish -.invalidation.-> BackendSvc
+
+    FrontendSvc --> Frontend1
+    FrontendSvc --> Frontend2
+
+    Frontend1 --> BackendSvc
+    Frontend2 --> BackendSvc
+
+    BackendSvc --> Backend1
+    BackendSvc --> Backend2
+    BackendSvc --> Backend3
+
+    Backend1 --> DB
+    Backend2 --> DB
+    Backend3 --> DB
+```
+
+## Component Responsibilities
+
+### Backend
+
+**Responsibilities:**
+- Plone REST API
+- Content management
+- ZODB with RelStorage (external database)
+- Search indexing
+- Workflow engine
+
+**Resources:**
+- CPU: Compute-intensive operations (catalog queries, indexing)
+- Memory: ZODB cache, Python processes
+- Storage: Delegated to external database (PostgreSQL/MySQL/Oracle)
+
+**Scaling:**
+- Horizontal: Add replicas for read scalability with RelStorage
+- Vertical: Increase resources for large catalogs
+- External database handles storage and multi-writer scenarios
+
+### Frontend (Volto)
+
+**Responsibilities:**
+- React single-page application
+- Server-side rendering (SSR)
+- API client
+- User interface
+
+**Resources:**
+- CPU: SSR rendering, JavaScript execution
+- Memory: Node.js processes, SSR caching
+- Storage: Minimal (build artifacts only)
+
+**Scaling:**
+- Horizontal: Add replicas for traffic handling
+- Vertical: Increase resources for SSR performance
+- No shared storage needed (stateless)
+
+### HTTP Cache (Varnish)
+
+**Responsibilities:**
+- HTTP caching
+- Cache invalidation
+- Request routing
+- Load distribution
+
+**Resources:**
+- CPU: Request processing, cache lookup
+- Memory: Cache storage
+- Storage: Not required (in-memory cache)
+
+**Scaling:**
+- Horizontal: Add replicas for cache distribution
+- Vertical: Increase memory for larger cache
+
+## Kubernetes Resources Created
+
+For a typical Volto deployment, cdk8s-plone creates:
+
+**Backend:**
+- Deployment (backend pods)
+- Service (internal)
+- PodDisruptionBudget (optional)
+- ConfigMap (optional, for configuration)
+
+**Frontend:**
+- Deployment (frontend pods)
+- Service (internal)
+- PodDisruptionBudget (optional)
+
+**HTTP Cache (optional):**
+- StatefulSet (Varnish pods)
+- Service (entry point)
+- ConfigMap (VCL configuration)
+- Secret (admin credentials)
+- ServiceMonitor (optional, for Prometheus)
+
+## Design Decisions
+
+### CDK8S Constructs
+
+**Why CDK8S?**
+- Type-safe infrastructure as code
+- Reusable components
+- Familiar programming languages
+- No templating required
+- IDE support and IntelliSense
+
+**Benefits:**
+- Reduced boilerplate
+- Better error detection
+- Easier testing
+- Composition over configuration
+
+### Separate Frontend/Backend
+
+**Volto Architecture:**
+- Independent scaling of frontend and backend
+- Frontend can be restarted without affecting backend
+- Better resource utilization
+- Clear separation of concerns
+
+**When to use Classic UI:**
+- Simpler deployment model
+- Lower resource requirements
+- Legacy integrations
+- Specific add-on requirements
+
+### Optional Varnish Layer
+
+**Design Choice:**
+- Varnish is optional, not mandatory
+- Uses established Helm chart (kube-httpcache)
+- Cluster-wide cache invalidation
+- Production-tested solution
+
+**Trade-offs:**
+- Additional complexity
+- More resources required
+- Better performance at scale
+- Reduced backend load
+
+### Health Probes
+
+**Readiness Probe:**
+- Enabled by default for backend
+- Prevents traffic to unready pods
+- Fast startup detection
+
+**Liveness Probe:**
+- Disabled by default for backend (Plone is resilient)
+- Recommended enabled for frontend (detect SSR hangs)
+- Configurable thresholds
+
+## Production Considerations
+
+### Resource Planning
+
+**Backend:**
+- Plan for catalog size and query complexity
+- ZODB cache size affects memory needs
+- Indexing operations are CPU-intensive
+
+**Frontend:**
+- SSR requires CPU resources
+- Memory for Node.js processes
+- Scale based on traffic patterns
+
+**Cache:**
+- Memory size determines cache capacity
+- Monitor hit rates and adjust sizing
+
+### High Availability
+
+**Recommendations:**
+- Minimum 2 replicas per component
+- Configure PodDisruptionBudgets
+- Use node affinity for distribution
+- Enable health probes
+
+**Database:**
+- External database required (PostgreSQL, MySQL, or Oracle)
+- Uses RelStorage for ZODB persistence
+- Enables true multi-writer deployments
+- Better backup and recovery options
+- MySQL derivatives (MariaDB, Percona) and Oracle are supported but untested
+
+### Monitoring
+
+**Metrics to Track:**
+- Pod resource usage (CPU, memory)
+- Request rates and latencies
+- Cache hit rates
+- Error rates
+- Health probe failures
+
+**Tools:**
+- Prometheus for metrics collection
+- Grafana for visualization
+- Kubernetes events monitoring
+
+## 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

package/documentation/sources/explanation/features.md

@@ -0,0 +1,353 @@
+# Features
+
+Complete overview of cdk8s-plone features and capabilities.
+
+## Core Features
+
+### Deployment Variants
+
+cdk8s-plone supports two deployment modes to match your requirements:
+
+**Volto (Modern React Frontend)**
+- Modern React-based user interface
+- Headless CMS architecture
+- Separate frontend and backend services
+- Best for: New projects, modern UX requirements, API-first architectures
+
+**Classic UI (Traditional Plone)**
+- Server-side rendered interface
+- Integrated single-service deployment
+- Traditional Plone experience
+- Best for: Legacy migrations, existing add-ons, simpler deployments
+
+See [Plone Variants](plone-variants.md) for detailed comparison.
+
+### High Availability
+
+**Configurable Replicas**
+- Set any number of replicas for backend and frontend
+- Default: 2 replicas per component
+- Supports horizontal scaling for increased capacity
+
+**Pod Disruption Budgets**
+- Ensures minimum availability during voluntary disruptions
+- Prevents too many pods being unavailable simultaneously
+- Configurable `minAvailable` or `maxUnavailable` thresholds
+
+**Example:**
+```typescript
+backend: {
+  replicas: 5,
+  minAvailable: 3,  // Keep at least 3 pods running
+}
+```
+
+### HTTP Caching with Varnish
+
+**kube-httpcache Integration**
+- Production-grade Varnish deployment
+- Cluster-wide cache invalidation
+- Automatic invalidation on content changes
+- HTTP/2 support
+
+**Benefits:**
+- Dramatically reduced backend load
+- Faster response times
+- Better scalability
+- Lower resource requirements
+
+**Monitoring:**
+- Built-in Prometheus exporter
+- Cache hit/miss metrics
+- Performance monitoring
+
+### Resource Management
+
+**Fine-Grained Control**
+- CPU requests and limits
+- Memory requests and limits
+- Per-component configuration
+- Kubernetes-native resource management
+
+**Example:**
+```typescript
+backend: {
+  requestCpu: '500m',
+  limitCpu: '2',
+  requestMemory: '512Mi',
+  limitMemory: '2Gi',
+}
+```
+
+### Health Monitoring
+
+**Readiness Probes**
+- Ensures pods are ready before receiving traffic
+- Configurable delays and thresholds
+- Enabled by default for backend
+- Prevents downtime during startup
+
+**Liveness Probes**
+- Automatic restart of unhealthy pods
+- Configurable for backend and frontend
+- Recommended for frontend to detect SSR hangs
+- Prevents stuck processes
+
+**Example:**
+```typescript
+frontend: {
+  livenessEnabled: true,
+  livenessInitialDelaySeconds: 30,
+  livenessFailureThreshold: 3,
+  readinessEnabled: true,
+  readinessInitialDelaySeconds: 10,
+}
+```
+
+### Environment Configuration
+
+**Flexible Environment Variables**
+- Use cdk8s-plus-30 Env API
+- Support for values, ConfigMaps, and Secrets
+- Per-component environment configuration
+
+**Example:**
+```typescript
+import { Env } from 'cdk8s-plus-30';
+
+backend: {
+  environment: {
+    variables: {
+      SITE: Env.value('MySite'),
+      DB_USER: Env.fromSecret('db-credentials', 'username'),
+      CORS_ALLOW: Env.fromConfigMap('app-config', 'cors-origins'),
+    },
+  },
+}
+```
+
+### Kubernetes Annotations
+
+**Three Levels of Annotations**
+- **Deployment annotations**: Metadata for the deployment resource
+- **Pod annotations**: Applied to pod templates (Prometheus, service mesh)
+- **Service annotations**: Applied to services (external-dns, load balancers)
+
+**Example:**
+```typescript
+backend: {
+  podAnnotations: {
+    'prometheus.io/scrape': 'true',
+    'prometheus.io/port': '8080',
+  },
+  serviceAnnotations: {
+    'external-dns.alpha.kubernetes.io/hostname': 'backend.example.com',
+  },
+}
+```
+
+### Private Registry Support
+
+**Image Pull Secrets**
+- Support for private container registries
+- Multiple secrets supported
+- Applied to all deployments
+
+**Example:**
+```typescript
+new Plone(chart, 'my-plone', {
+  imagePullSecrets: ['docker-registry', 'gcr-registry'],
+  backend: { image: 'private-registry.io/plone-backend:6.1.3' },
+})
+```
+
+## Multi-Language Support
+
+### TypeScript/JavaScript
+
+**Native CDK8S Experience**
+- Full TypeScript type definitions
+- IDE autocomplete and validation
+- Familiar syntax for web developers
+
+**Installation:**
+```bash
+npm install @bluedynamics/cdk8s-plone
+```
+
+**Example:**
+```typescript
+import { Plone, PloneVariant } from '@bluedynamics/cdk8s-plone';
+
+new Plone(chart, 'my-plone', {
+  variant: PloneVariant.VOLTO,
+  backend: { image: 'plone/plone-backend:6.1.3' },
+});
+```
+
+### Python
+
+**JSII-Generated Bindings**
+- Pythonic API
+- Type hints support
+- Familiar syntax for Python developers
+
+**Installation:**
+```bash
+pip install cdk8s-plone
+```
+
+**Example:**
+```python
+from cdk8s_plone import Plone, PloneVariant
+
+Plone(chart, "my-plone",
+    variant=PloneVariant.VOLTO,
+    backend={"image": "plone/plone-backend:6.1.3"}
+)
+```
+
+## Infrastructure as Code Benefits
+
+### Type Safety
+
+**Compile-Time Validation**
+- Catch configuration errors before deployment
+- IDE validation and autocomplete
+- Refactoring support
+
+**Example:**
+```typescript
+// TypeScript catches this error at compile time
+backend: {
+  image: 'plone/plone-backend:6.1.3',
+  replicas: 'three',  // ❌ Type error: Expected number
+}
+```
+
+### Reusability
+
+**Construct Composition**
+- Create custom constructs
+- Encapsulate best practices
+- Share across projects
+
+**Example:**
+```typescript
+class ProductionPlone extends Construct {
+  constructor(scope: Construct, id: string) {
+    super(scope, id);
+
+    const plone = new Plone(this, 'plone', {
+      variant: PloneVariant.VOLTO,
+      backend: {
+        replicas: 3,
+        minAvailable: 2,
+        requestCpu: '500m',
+        limitCpu: '2',
+      },
+    });
+
+    new PloneHttpcache(this, 'cache', {
+      plone: plone,
+      replicas: 2,
+    });
+  }
+}
+```
+
+### Testing
+
+**Unit Testing**
+- Test infrastructure definitions
+- Validate resource creation
+- Catch regressions early
+
+**Example:**
+```typescript
+test('creates backend deployment', () => {
+  const chart = Testing.chart();
+  new Plone(chart, 'test-plone', {
+    backend: { image: 'plone/plone-backend:6.1.3' },
+  });
+
+  const results = Testing.synth(chart);
+  expect(results).toMatchSnapshot();
+});
+```
+
+### Programmatic Control
+
+**Dynamic Configuration**
+- Use loops and conditionals
+- Environment-based configuration
+- Dynamic resource generation
+
+**Example:**
+```typescript
+const environments = ['dev', 'staging', 'prod'];
+
+environments.forEach(env => {
+  new Plone(chart, `plone-${env}`, {
+    backend: {
+      replicas: env === 'prod' ? 5 : 2,
+      requestMemory: env === 'prod' ? '1Gi' : '512Mi',
+    },
+  });
+});
+```
+
+## Production-Ready Features
+
+### Manifest Generation
+
+**Standard Kubernetes YAML**
+- Generates standard Kubernetes manifests
+- No proprietary formats
+- Apply with `kubectl apply -f`
+
+**Output:**
+```bash
+cdk8s synth
+# Creates dist/ directory with YAML files
+kubectl apply -f dist/
+```
+
+### Helm Chart Integration
+
+**PloneHttpcache Uses Helm**
+- Leverages battle-tested kube-httpcache chart
+- Automatic updates available
+- Community-maintained
+
+### Monitoring Integration
+
+**Prometheus Ready**
+- ServiceMonitor support for Varnish
+- Pod annotations for scraping
+- Standard metrics endpoints
+
+**Example:**
+```typescript
+new PloneHttpcache(chart, 'cache', {
+  plone: plone,
+  servicemonitor: true,  // Creates ServiceMonitor
+  exporterEnabled: true,  // Enables Prometheus exporter sidecar
+});
+```
+
+## Upcoming Features
+
+Features planned for future releases:
+
+- **Backup Integration**: Automated backup configurations
+- **Monitoring Dashboards**: Pre-built Grafana dashboards
+
+**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
+
+- [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

package/documentation/sources/explanation/index.md

@@ -0,0 +1,51 @@
+```{image} ../_static/kup6s-icon-explanation.svg
+:align: center
+:class: section-icon-large
+```
+
+# Explanation
+
+**Understanding-oriented discussion of concepts, architecture, and design decisions.**
+
+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
+
+```{toctree}
+---
+maxdepth: 1
+titlesonly: true
+---
+features
+architecture
+```
+
+## Key Topics
+
+*This section will explain:*
+- Plone architecture and component relationships
+- Backend and Frontend integration
+- Storage architecture for Plone data
+- CDK8S construct patterns and best practices
+- Configuration management strategies
+
+*Future topics:*
+- Security considerations
+- Scaling and high availability considerations
+- Performance optimization
+
+## Design Decisions
+
+*This section will document:*
+- Why certain defaults were chosen
+- Trade-offs in configuration approaches
+- Integration strategies with external services
+- Testing philosophy
+
+---
+
+**Ready to get started?** Jump into the [Tutorials](../tutorials/index.md) for hands-on lessons.
+
+**Need to solve a problem?** See the [How-To Guides](../how-to/index.md) for task-oriented solutions.
+
+**Looking for specifications?** Check the [Reference](../reference/index.md) section for API documentation.