@bluedynamics/cdk8s-plone 0.1.23 → 0.1.25

package/API.md

@@ -389,6 +389,176 @@ Use this to reference the cache service from ingress or other constructs.
 ---
 
 
+### PloneVinylCache <a name="PloneVinylCache" id="@bluedynamics/cdk8s-plone.PloneVinylCache"></a>
+
+PloneVinylCache construct for deploying Varnish Cache via cloud-vinyl operator.
+
+Creates a VinylCache custom resource with Plone backend/frontend services
+auto-configured as backends. The cloud-vinyl operator manages the full
+Varnish lifecycle including VCL generation, agent delivery, and monitoring.
+
+Requires the cloud-vinyl operator to be installed in the cluster.
+
+*Example*
+
+```typescript
+const plone = new Plone(chart, 'plone');
+const cache = new PloneVinylCache(chart, 'cache', {
+  plone: plone,
+  replicas: 2,
+});
+// Use cache.vinylCacheServiceName for IngressRoute
+```
+
+
+#### Initializers <a name="Initializers" id="@bluedynamics/cdk8s-plone.PloneVinylCache.Initializer"></a>
+
+```typescript
+import { PloneVinylCache } from '@bluedynamics/cdk8s-plone'
+
+new PloneVinylCache(scope: Construct, id: string, options: PloneVinylCacheOptions)
+```
+
+| **Name** | **Type** | **Description** |
+| --- | --- | --- |
+| <code><a href="#@bluedynamics/cdk8s-plone.PloneVinylCache.Initializer.parameter.scope">scope</a></code> | <code>constructs.Construct</code> | *No description.* |
+| <code><a href="#@bluedynamics/cdk8s-plone.PloneVinylCache.Initializer.parameter.id">id</a></code> | <code>string</code> | *No description.* |
+| <code><a href="#@bluedynamics/cdk8s-plone.PloneVinylCache.Initializer.parameter.options">options</a></code> | <code><a href="#@bluedynamics/cdk8s-plone.PloneVinylCacheOptions">PloneVinylCacheOptions</a></code> | *No description.* |
+
+---
+
+##### `scope`<sup>Required</sup> <a name="scope" id="@bluedynamics/cdk8s-plone.PloneVinylCache.Initializer.parameter.scope"></a>
+
+- *Type:* constructs.Construct
+
+---
+
+##### `id`<sup>Required</sup> <a name="id" id="@bluedynamics/cdk8s-plone.PloneVinylCache.Initializer.parameter.id"></a>
+
+- *Type:* string
+
+---
+
+##### `options`<sup>Required</sup> <a name="options" id="@bluedynamics/cdk8s-plone.PloneVinylCache.Initializer.parameter.options"></a>
+
+- *Type:* <a href="#@bluedynamics/cdk8s-plone.PloneVinylCacheOptions">PloneVinylCacheOptions</a>
+
+---
+
+#### Methods <a name="Methods" id="Methods"></a>
+
+| **Name** | **Description** |
+| --- | --- |
+| <code><a href="#@bluedynamics/cdk8s-plone.PloneVinylCache.toString">toString</a></code> | Returns a string representation of this construct. |
+| <code><a href="#@bluedynamics/cdk8s-plone.PloneVinylCache.with">with</a></code> | Applies one or more mixins to this construct. |
+
+---
+
+##### `toString` <a name="toString" id="@bluedynamics/cdk8s-plone.PloneVinylCache.toString"></a>
+
+```typescript
+public toString(): string
+```
+
+Returns a string representation of this construct.
+
+##### `with` <a name="with" id="@bluedynamics/cdk8s-plone.PloneVinylCache.with"></a>
+
+```typescript
+public with(mixins: ...IMixin[]): IConstruct
+```
+
+Applies one or more mixins to this construct.
+
+Mixins are applied in order. The list of constructs is captured at the
+start of the call, so constructs added by a mixin will not be visited.
+Use multiple `with()` calls if subsequent mixins should apply to added
+constructs.
+
+###### `mixins`<sup>Required</sup> <a name="mixins" id="@bluedynamics/cdk8s-plone.PloneVinylCache.with.parameter.mixins"></a>
+
+- *Type:* ...constructs.IMixin[]
+
+The mixins to apply.
+
+---
+
+#### Static Functions <a name="Static Functions" id="Static Functions"></a>
+
+| **Name** | **Description** |
+| --- | --- |
+| <code><a href="#@bluedynamics/cdk8s-plone.PloneVinylCache.isConstruct">isConstruct</a></code> | Checks if `x` is a construct. |
+
+---
+
+##### `isConstruct` <a name="isConstruct" id="@bluedynamics/cdk8s-plone.PloneVinylCache.isConstruct"></a>
+
+```typescript
+import { PloneVinylCache } from '@bluedynamics/cdk8s-plone'
+
+PloneVinylCache.isConstruct(x: any)
+```
+
+Checks if `x` is a construct.
+
+Use this method instead of `instanceof` to properly detect `Construct`
+instances, even when the construct library is symlinked.
+
+Explanation: in JavaScript, multiple copies of the `constructs` library on
+disk are seen as independent, completely different libraries. As a
+consequence, the class `Construct` in each copy of the `constructs` library
+is seen as a different class, and an instance of one class will not test as
+`instanceof` the other class. `npm install` will not create installations
+like this, but users may manually symlink construct libraries together or
+use a monorepo tool: in those cases, multiple copies of the `constructs`
+library can be accidentally installed, and `instanceof` will behave
+unpredictably. It is safest to avoid using `instanceof`, and using
+this type-testing method instead.
+
+###### `x`<sup>Required</sup> <a name="x" id="@bluedynamics/cdk8s-plone.PloneVinylCache.isConstruct.parameter.x"></a>
+
+- *Type:* any
+
+Any object.
+
+---
+
+#### Properties <a name="Properties" id="Properties"></a>
+
+| **Name** | **Type** | **Description** |
+| --- | --- | --- |
+| <code><a href="#@bluedynamics/cdk8s-plone.PloneVinylCache.property.node">node</a></code> | <code>constructs.Node</code> | The tree node. |
+| <code><a href="#@bluedynamics/cdk8s-plone.PloneVinylCache.property.vinylCacheServiceName">vinylCacheServiceName</a></code> | <code>string</code> | Name of the VinylCache service created by the operator. |
+
+---
+
+##### `node`<sup>Required</sup> <a name="node" id="@bluedynamics/cdk8s-plone.PloneVinylCache.property.node"></a>
+
+```typescript
+public readonly node: Node;
+```
+
+- *Type:* constructs.Node
+
+The tree node.
+
+---
+
+##### `vinylCacheServiceName`<sup>Required</sup> <a name="vinylCacheServiceName" id="@bluedynamics/cdk8s-plone.PloneVinylCache.property.vinylCacheServiceName"></a>
+
+```typescript
+public readonly vinylCacheServiceName: string;
+```
+
+- *Type:* string
+
+Name of the VinylCache service created by the operator.
+
+Use this to reference the cache service from ingress or other constructs.
+
+---
+
+
 ## Structs <a name="Structs" id="Structs"></a>
 
 ### HttpcacheEnvVar <a name="HttpcacheEnvVar" id="@bluedynamics/cdk8s-plone.HttpcacheEnvVar"></a>
@@ -545,6 +715,7 @@ const ploneBaseOptions: PloneBaseOptions = { ... }
 | <code><a href="#@bluedynamics/cdk8s-plone.PloneBaseOptions.property.metricsPath">metricsPath</a></code> | <code>string</code> | Path to scrape metrics from. |
 | <code><a href="#@bluedynamics/cdk8s-plone.PloneBaseOptions.property.metricsPort">metricsPort</a></code> | <code>string \| number</code> | Port name or number to scrape metrics from. |
 | <code><a href="#@bluedynamics/cdk8s-plone.PloneBaseOptions.property.minAvailable">minAvailable</a></code> | <code>string \| number</code> | Minimum number of pods that must be available during updates. |
+| <code><a href="#@bluedynamics/cdk8s-plone.PloneBaseOptions.property.nodeSelector">nodeSelector</a></code> | <code>{[ key: string ]: string}</code> | Node selector labels for pod scheduling. |
 | <code><a href="#@bluedynamics/cdk8s-plone.PloneBaseOptions.property.podAnnotations">podAnnotations</a></code> | <code>{[ key: string ]: string}</code> | Annotations to add to the Pod template metadata. |
 | <code><a href="#@bluedynamics/cdk8s-plone.PloneBaseOptions.property.readinessEnabled">readinessEnabled</a></code> | <code>boolean</code> | Enable readiness probe for the container. |
 | <code><a href="#@bluedynamics/cdk8s-plone.PloneBaseOptions.property.readinessFailureThreshold">readinessFailureThreshold</a></code> | <code>number</code> | Minimum consecutive failures for the readiness probe to be considered failed. |
@@ -811,6 +982,28 @@ Used in PodDisruptionBudget if specified.
 
 ---
 
+##### `nodeSelector`<sup>Optional</sup> <a name="nodeSelector" id="@bluedynamics/cdk8s-plone.PloneBaseOptions.property.nodeSelector"></a>
+
+```typescript
+public readonly nodeSelector: {[ key: string ]: string};
+```
+
+- *Type:* {[ key: string ]: string}
+- *Default:* no node selector
+
+Node selector labels for pod scheduling.
+
+Use to constrain pods to nodes with matching labels, e.g. for region affinity.
+
+---
+
+*Example*
+
+```typescript
+{ 'topology.kubernetes.io/region': 'fsn1' }
+```
+
+
 ##### `podAnnotations`<sup>Optional</sup> <a name="podAnnotations" id="@bluedynamics/cdk8s-plone.PloneBaseOptions.property.podAnnotations"></a>
 
 ```typescript
@@ -1372,6 +1565,291 @@ This is used in Kubernetes labels and doesn't affect the actual image versions.
 
 ---
 
+### PloneVinylCacheOptions <a name="PloneVinylCacheOptions" id="@bluedynamics/cdk8s-plone.PloneVinylCacheOptions"></a>
+
+Configuration options for PloneVinylCache (cloud-vinyl operator).
+
+Creates a VinylCache custom resource that the cloud-vinyl operator
+reconciles into a Varnish Cache cluster with agent-based VCL delivery.
+
+Requires the cloud-vinyl operator to be installed in the cluster.
+
+#### Initializer <a name="Initializer" id="@bluedynamics/cdk8s-plone.PloneVinylCacheOptions.Initializer"></a>
+
+```typescript
+import { PloneVinylCacheOptions } from '@bluedynamics/cdk8s-plone'
+
+const ploneVinylCacheOptions: PloneVinylCacheOptions = { ... }
+```
+
+#### Properties <a name="Properties" id="Properties"></a>
+
+| **Name** | **Type** | **Description** |
+| --- | --- | --- |
+| <code><a href="#@bluedynamics/cdk8s-plone.PloneVinylCacheOptions.property.plone">plone</a></code> | <code><a href="#@bluedynamics/cdk8s-plone.Plone">Plone</a></code> | The Plone construct to attach the cache to. |
+| <code><a href="#@bluedynamics/cdk8s-plone.PloneVinylCacheOptions.property.director">director</a></code> | <code>string</code> | Director type for load distribution. |
+| <code><a href="#@bluedynamics/cdk8s-plone.PloneVinylCacheOptions.property.image">image</a></code> | <code>string</code> | Container image for the Varnish pods. |
+| <code><a href="#@bluedynamics/cdk8s-plone.PloneVinylCacheOptions.property.invalidation">invalidation</a></code> | <code>boolean</code> | Enable cache invalidation (PURGE, BAN, xkey). |
+| <code><a href="#@bluedynamics/cdk8s-plone.PloneVinylCacheOptions.property.limitCpu">limitCpu</a></code> | <code>string</code> | CPU limit for Varnish pods. |
+| <code><a href="#@bluedynamics/cdk8s-plone.PloneVinylCacheOptions.property.limitMemory">limitMemory</a></code> | <code>string</code> | Memory limit for Varnish pods. |
+| <code><a href="#@bluedynamics/cdk8s-plone.PloneVinylCacheOptions.property.monitoring">monitoring</a></code> | <code>boolean</code> | Enable Prometheus monitoring (metrics + ServiceMonitor). |
+| <code><a href="#@bluedynamics/cdk8s-plone.PloneVinylCacheOptions.property.replicas">replicas</a></code> | <code>number</code> | Number of Varnish pod replicas. |
+| <code><a href="#@bluedynamics/cdk8s-plone.PloneVinylCacheOptions.property.requestCpu">requestCpu</a></code> | <code>string</code> | CPU request for Varnish pods. |
+| <code><a href="#@bluedynamics/cdk8s-plone.PloneVinylCacheOptions.property.requestMemory">requestMemory</a></code> | <code>string</code> | Memory request for Varnish pods. |
+| <code><a href="#@bluedynamics/cdk8s-plone.PloneVinylCacheOptions.property.tolerations">tolerations</a></code> | <code><a href="#@bluedynamics/cdk8s-plone.VinylCacheToleration">VinylCacheToleration</a>[]</code> | Tolerations for the Varnish pods. |
+| <code><a href="#@bluedynamics/cdk8s-plone.PloneVinylCacheOptions.property.vclBackendResponseSnippet">vclBackendResponseSnippet</a></code> | <code>string</code> | Custom VCL snippet for vcl_backend_response subroutine. |
+| <code><a href="#@bluedynamics/cdk8s-plone.PloneVinylCacheOptions.property.vclRecvSnippet">vclRecvSnippet</a></code> | <code>string</code> | Custom VCL snippet for vcl_recv subroutine. |
+
+---
+
+##### `plone`<sup>Required</sup> <a name="plone" id="@bluedynamics/cdk8s-plone.PloneVinylCacheOptions.property.plone"></a>
+
+```typescript
+public readonly plone: Plone;
+```
+
+- *Type:* <a href="#@bluedynamics/cdk8s-plone.Plone">Plone</a>
+
+The Plone construct to attach the cache to.
+
+Backends are auto-configured from the Plone services.
+
+---
+
+##### `director`<sup>Optional</sup> <a name="director" id="@bluedynamics/cdk8s-plone.PloneVinylCacheOptions.property.director"></a>
+
+```typescript
+public readonly director: string;
+```
+
+- *Type:* string
+- *Default:* 'shard'
+
+Director type for load distribution.
+
+---
+
+##### `image`<sup>Optional</sup> <a name="image" id="@bluedynamics/cdk8s-plone.PloneVinylCacheOptions.property.image"></a>
+
+```typescript
+public readonly image: string;
+```
+
+- *Type:* string
+- *Default:* 'varnish:7.6'
+
+Container image for the Varnish pods.
+
+---
+
+##### `invalidation`<sup>Optional</sup> <a name="invalidation" id="@bluedynamics/cdk8s-plone.PloneVinylCacheOptions.property.invalidation"></a>
+
+```typescript
+public readonly invalidation: boolean;
+```
+
+- *Type:* boolean
+- *Default:* true
+
+Enable cache invalidation (PURGE, BAN, xkey).
+
+---
+
+##### `limitCpu`<sup>Optional</sup> <a name="limitCpu" id="@bluedynamics/cdk8s-plone.PloneVinylCacheOptions.property.limitCpu"></a>
+
+```typescript
+public readonly limitCpu: string;
+```
+
+- *Type:* string
+- *Default:* '500m'
+
+CPU limit for Varnish pods.
+
+---
+
+##### `limitMemory`<sup>Optional</sup> <a name="limitMemory" id="@bluedynamics/cdk8s-plone.PloneVinylCacheOptions.property.limitMemory"></a>
+
+```typescript
+public readonly limitMemory: string;
+```
+
+- *Type:* string
+- *Default:* '512Mi'
+
+Memory limit for Varnish pods.
+
+---
+
+##### `monitoring`<sup>Optional</sup> <a name="monitoring" id="@bluedynamics/cdk8s-plone.PloneVinylCacheOptions.property.monitoring"></a>
+
+```typescript
+public readonly monitoring: boolean;
+```
+
+- *Type:* boolean
+- *Default:* false
+
+Enable Prometheus monitoring (metrics + ServiceMonitor).
+
+---
+
+##### `replicas`<sup>Optional</sup> <a name="replicas" id="@bluedynamics/cdk8s-plone.PloneVinylCacheOptions.property.replicas"></a>
+
+```typescript
+public readonly replicas: number;
+```
+
+- *Type:* number
+- *Default:* 2
+
+Number of Varnish pod replicas.
+
+---
+
+##### `requestCpu`<sup>Optional</sup> <a name="requestCpu" id="@bluedynamics/cdk8s-plone.PloneVinylCacheOptions.property.requestCpu"></a>
+
+```typescript
+public readonly requestCpu: string;
+```
+
+- *Type:* string
+- *Default:* '100m'
+
+CPU request for Varnish pods.
+
+---
+
+##### `requestMemory`<sup>Optional</sup> <a name="requestMemory" id="@bluedynamics/cdk8s-plone.PloneVinylCacheOptions.property.requestMemory"></a>
+
+```typescript
+public readonly requestMemory: string;
+```
+
+- *Type:* string
+- *Default:* '256Mi'
+
+Memory request for Varnish pods.
+
+---
+
+##### `tolerations`<sup>Optional</sup> <a name="tolerations" id="@bluedynamics/cdk8s-plone.PloneVinylCacheOptions.property.tolerations"></a>
+
+```typescript
+public readonly tolerations: VinylCacheToleration[];
+```
+
+- *Type:* <a href="#@bluedynamics/cdk8s-plone.VinylCacheToleration">VinylCacheToleration</a>[]
+- *Default:* no tolerations
+
+Tolerations for the Varnish pods.
+
+---
+
+##### `vclBackendResponseSnippet`<sup>Optional</sup> <a name="vclBackendResponseSnippet" id="@bluedynamics/cdk8s-plone.PloneVinylCacheOptions.property.vclBackendResponseSnippet"></a>
+
+```typescript
+public readonly vclBackendResponseSnippet: string;
+```
+
+- *Type:* string
+- *Default:* uses built-in plone-vinyl-backend-response.vcl
+
+Custom VCL snippet for vcl_backend_response subroutine.
+
+Replaces the default Plone backend_response snippet.
+
+---
+
+##### `vclRecvSnippet`<sup>Optional</sup> <a name="vclRecvSnippet" id="@bluedynamics/cdk8s-plone.PloneVinylCacheOptions.property.vclRecvSnippet"></a>
+
+```typescript
+public readonly vclRecvSnippet: string;
+```
+
+- *Type:* string
+- *Default:* uses built-in plone-vinyl-recv.vcl
+
+Custom VCL snippet for vcl_recv subroutine.
+
+Replaces the default Plone recv snippet.
+
+---
+
+### VinylCacheToleration <a name="VinylCacheToleration" id="@bluedynamics/cdk8s-plone.VinylCacheToleration"></a>
+
+A Kubernetes toleration for the Varnish pods.
+
+#### Initializer <a name="Initializer" id="@bluedynamics/cdk8s-plone.VinylCacheToleration.Initializer"></a>
+
+```typescript
+import { VinylCacheToleration } from '@bluedynamics/cdk8s-plone'
+
+const vinylCacheToleration: VinylCacheToleration = { ... }
+```
+
+#### Properties <a name="Properties" id="Properties"></a>
+
+| **Name** | **Type** | **Description** |
+| --- | --- | --- |
+| <code><a href="#@bluedynamics/cdk8s-plone.VinylCacheToleration.property.key">key</a></code> | <code>string</code> | The taint key to tolerate. |
+| <code><a href="#@bluedynamics/cdk8s-plone.VinylCacheToleration.property.effect">effect</a></code> | <code>string</code> | The taint effect to tolerate (NoSchedule, PreferNoSchedule, NoExecute). |
+| <code><a href="#@bluedynamics/cdk8s-plone.VinylCacheToleration.property.operator">operator</a></code> | <code>string</code> | The operator (Equal or Exists). |
+| <code><a href="#@bluedynamics/cdk8s-plone.VinylCacheToleration.property.value">value</a></code> | <code>string</code> | The taint value to match (when operator is Equal). |
+
+---
+
+##### `key`<sup>Required</sup> <a name="key" id="@bluedynamics/cdk8s-plone.VinylCacheToleration.property.key"></a>
+
+```typescript
+public readonly key: string;
+```
+
+- *Type:* string
+
+The taint key to tolerate.
+
+---
+
+##### `effect`<sup>Optional</sup> <a name="effect" id="@bluedynamics/cdk8s-plone.VinylCacheToleration.property.effect"></a>
+
+```typescript
+public readonly effect: string;
+```
+
+- *Type:* string
+- *Default:* tolerate all effects
+
+The taint effect to tolerate (NoSchedule, PreferNoSchedule, NoExecute).
+
+---
+
+##### `operator`<sup>Optional</sup> <a name="operator" id="@bluedynamics/cdk8s-plone.VinylCacheToleration.property.operator"></a>
+
+```typescript
+public readonly operator: string;
+```
+
+- *Type:* string
+- *Default:* 'Equal'
+
+The operator (Equal or Exists).
+
+---
+
+##### `value`<sup>Optional</sup> <a name="value" id="@bluedynamics/cdk8s-plone.VinylCacheToleration.property.value"></a>
+
+```typescript
+public readonly value: string;
+```
+
+- *Type:* string
+- *Default:* no value
+
+The taint value to match (when operator is Equal).
+
+---
+
 
 
 ## Enums <a name="Enums" id="Enums"></a>

package/README.md

@@ -13,7 +13,7 @@ cdk8s-plone provides CDK8S constructs for deploying [Plone CMS](https://plone.or
 **Key Features:**
 - 🚀 Supports Volto (modern React frontend) and Classic UI
 - 📦 High availability with configurable replicas
-- ⚡ Optional Varnish HTTP caching layer
+- ⚡ Optional Varnish HTTP caching via kube-httpcache (`PloneHttpcache`) or cloud-vinyl VinylCache operator (`PloneVinylCache`)
 - 🔧 Fine-grained resource and probe configuration
 - 🌍 Multi-language support (TypeScript/JavaScript and Python)
 - ✅ Type-safe infrastructure as code

package/documentation/sources/explanation/architecture.md

@@ -57,6 +57,24 @@ cdk8s-plone supports two deployment variants:
 - Better scalability
 - Automatic cache invalidation on content changes
 
+### Caching Options
+
+cdk8s-plone supports two HTTP caching approaches:
+
+**PloneHttpcache (mittwald/kube-httpcache)**
+- Self-contained: deploys Varnish via Helm chart, no operator needed
+- Full VCL template with Go template variable injection
+- Prometheus exporter sidecar for metrics
+
+**PloneVinylCache (cloud-vinyl operator)**
+- Operator-managed: creates a VinylCache custom resource
+- Structured VCL generation with snippet injection hooks
+- Built-in cache invalidation proxy (PURGE, BAN, xkey)
+- Agent-based VCL delivery and Prometheus metrics
+- Requires the [cloud-vinyl operator](https://github.com/bluedynamics/cloud-vinyl) in the cluster
+
+Choose PloneHttpcache for standalone deployments without cloud-vinyl. Choose PloneVinylCache when the operator is available for centralized cache management.
+
 ### Multi-Language Support
 
 The library is published in multiple languages:

package/documentation/sources/explanation/features.md

@@ -44,12 +44,20 @@ backend: {
 
 ### HTTP Caching with Varnish
 
-**kube-httpcache Integration**
-- Production-grade Varnish deployment
+cdk8s-plone supports two caching backends: the self-contained mittwald kube-httpcache Helm chart (`PloneHttpcache`) and the operator-managed cloud-vinyl VinylCache (`PloneVinylCache`).
+
+**kube-httpcache Integration (PloneHttpcache)**
+- Production-grade Varnish deployment, no operator required
 - Cluster-wide cache invalidation
 - Automatic invalidation on content changes
 - HTTP/2 support
 
+**cloud-vinyl VinylCache Integration (PloneVinylCache)**
+- Operator-managed Varnish via VinylCache custom resource
+- Structured VCL generation with snippet injection hooks
+- Built-in cache invalidation proxy (PURGE, BAN, xkey)
+- Requires the cloud-vinyl operator in the cluster
+
 **Benefits:**
 - Dramatically reduced backend load
 - Faster response times

package/documentation/sources/how-to/deploy-with-vinyl-cache.md

@@ -0,0 +1,115 @@
+```{image} ../_static/kup6s-icon-howto.svg
+:align: center
+:class: section-icon-large
+```
+
+# Deploy with Cloud-Vinyl Cache
+
+<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>
+
+## Prerequisites
+
+- The **cloud-vinyl operator** must be installed in your cluster
+- A working Plone deployment using `cdk8s-plone`
+- `@bluedynamics/cdk8s-plone` version with VinylCache support
+
+## Steps
+
+### 1. Add PloneVinylCache to Your Deployment
+
+```typescript
+import { Plone, PloneVinylCache } from '@bluedynamics/cdk8s-plone';
+
+const plone = new Plone(chart, 'plone', {
+  backend: { image: 'plone/plone-backend:6.1.3' },
+  frontend: { image: 'plone/plone-frontend:16.0.0' },
+});
+
+const cache = new PloneVinylCache(chart, 'cache', {
+  plone: plone,
+  replicas: 2,
+});
+```
+
+### 2. Use the Cache Service in Your IngressRoute
+
+The cache exposes a service that should be used as the upstream in your IngressRoute:
+
+```typescript
+// Use cache.vinylCacheServiceName as the service target
+// instead of plone.frontendServiceName
+```
+
+### 3. Build and Deploy
+
+```bash
+npm run build
+# Review generated manifests
+# Deploy via ArgoCD or kubectl apply
+```
+
+### 4. Verify
+
+```bash
+# Check VinylCache status
+kubectl get vinylcache -n <namespace>
+
+# Check Varnish pods
+kubectl get pods -n <namespace> -l app.kubernetes.io/managed-by=cloud-vinyl
+```
+
+## Customization
+
+### Custom VCL
+
+Override the default Plone VCL snippets for custom caching logic:
+
+```typescript
+new PloneVinylCache(chart, 'cache', {
+  plone: plone,
+  vclRecvSnippet: fs.readFileSync('./config/custom-recv.vcl', 'utf8'),
+  vclBackendResponseSnippet: fs.readFileSync('./config/custom-beresp.vcl', 'utf8'),
+});
+```
+
+### Cache Invalidation
+
+Invalidation is enabled by default (PURGE, BAN, xkey). Configure `plone.cachepurging` to point to the VinylCache invalidation proxy endpoint.
+
+To disable invalidation:
+
+```typescript
+new PloneVinylCache(chart, 'cache', {
+  plone: plone,
+  invalidation: false,
+});
+```
+
+## Migrating from PloneHttpcache
+
+Replace `PloneHttpcache` with `PloneVinylCache`:
+
+```typescript
+// Before (mittwald)
+// import { PloneHttpcache } from '@bluedynamics/cdk8s-plone';
+// const cache = new PloneHttpcache(chart, 'cache', {
+//   plone, varnishVcl: '...', existingSecret: 'secret',
+// });
+// const serviceName = cache.httpcacheServiceName;
+
+// After (cloud-vinyl)
+import { PloneVinylCache } from '@bluedynamics/cdk8s-plone';
+const cache = new PloneVinylCache(chart, 'cache', { plone });
+const serviceName = cache.vinylCacheServiceName;
+```
+
+Key differences:
+- No VCL template needed (operator generates VCL from structured config)
+- No `existingSecret` needed (operator manages agent authentication)
+- Service name property is `vinylCacheServiceName` (not `httpcacheServiceName`)

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

@@ -32,6 +32,7 @@ titlesonly: true
 ---
 deploy-production-volto
 deploy-classic-ui
+deploy-with-vinyl-cache
 ```
 
 ## Configuration