API reference#

Complete API reference for cdk8s-plone constructs, generated from the TypeScript source code. This is the authoritative reference for every option, type, default, and required flag.

Overview#

The cdk8s-plone library provides the following constructs:

  • Plone: main construct for deploying Plone CMS, with support for both the Volto (React frontend) and Blicca (server-side rendered) variants

  • PloneHttpcache: Varnish caching layer via the mittwald kube-httpcache Helm chart (self-contained)

  • PloneVinylCache: Varnish caching layer via the cloud-vinyl operator (requires the operator in-cluster)

Language support#

This API documentation shows TypeScript usage examples. The library is also available for Python via JSII transpilation:

For Python-specific usage, the API remains the same but follows Python naming conventions (snake_case instead of camelCase).

Constructs #

Plone #

Plone construct for deploying Plone CMS to Kubernetes.

This construct creates all necessary Kubernetes resources for running Plone:

  • Deployment(s) for backend (and optionally frontend)

  • Service(s) for network access

  • Optional PodDisruptionBudget for high availability

Supports two deployment variants:

  • 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

Example

new Plone(chart, 'my-plone', {
  variant: PloneVariant.VOLTO,
  backend: {
    image: 'plone/plone-backend:6.0.10',
    replicas: 3,
  },
  frontend: {
    image: 'plone/plone-frontend:16.0.0',
  },
});

Initializers #

import { Plone } from '@bluedynamics/cdk8s-plone'

new Plone(scope: Construct, id: string, options?: PloneOptions)

Name

Type

Description

scope

constructs.Construct

No description.

id

string

No description.

options

PloneOptions

No description.
scopeRequired #

  • Type: constructs.Construct

idRequired #

  • Type: string

optionsOptional #

Methods #

Name

Description

toString

Returns a string representation of this construct.

with

Applies one or more mixins to this construct.
toString #
public toString(): string

Returns a string representation of this construct.

with #
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.

mixinsRequired #

  • Type: …constructs.IMixin[]

The mixins to apply.

Static Functions #

Name

Description

isConstruct

Checks if x is a construct.
isConstruct #
import { Plone } from '@bluedynamics/cdk8s-plone'

Plone.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.

xRequired #

  • Type: any

Any object.

Properties #

Name

Type

Description

node

constructs.Node

The tree node.

backendServiceName

string

Name of the backend Kubernetes service.

siteId

string

The Plone site ID in ZODB.

variant

PloneVariant

The deployment variant being used (VOLTO or BLICCA).

frontendServiceName

string

Name of the frontend Kubernetes service.
nodeRequired #
public readonly node: Node;

  • Type: constructs.Node

The tree node.

backendServiceNameRequired #
public readonly backendServiceName: string;

  • Type: string

Name of the backend Kubernetes service.

Use this to reference the backend service from other constructs.

siteIdRequired #
public readonly siteId: string;

  • Type: string

The Plone site ID in ZODB.

variantRequired #
public readonly variant: PloneVariant;

The deployment variant being used (VOLTO or BLICCA).

frontendServiceNameOptional #
public readonly frontendServiceName: string;

  • Type: string

Name of the frontend Kubernetes service.

Only set when variant is VOLTO, otherwise undefined.

PloneHttpcache #

PloneHttpcache construct for deploying Varnish HTTP caching layer.

Uses the mittwald/kube-httpcache Helm chart to deploy Varnish as a caching proxy in front of Plone backend and/or frontend services.

The cache automatically connects to the Plone services and provides HTTP cache invalidation capabilities.

Example

const plone = new Plone(chart, 'plone');
const cache = new PloneHttpcache(chart, 'cache', {
  plone: plone,
  existingSecret: 'varnish-secret',
});

Initializers #

import { PloneHttpcache } from '@bluedynamics/cdk8s-plone'

new PloneHttpcache(scope: Construct, id: string, options: PloneHttpcacheOptions)

Name

Type

Description

scope

constructs.Construct

No description.

id

string

No description.

options

PloneHttpcacheOptions

No description.
scopeRequired #

  • Type: constructs.Construct

idRequired #

  • Type: string

optionsRequired #

Methods #

Name

Description

toString

Returns a string representation of this construct.

with

Applies one or more mixins to this construct.
toString #
public toString(): string

Returns a string representation of this construct.

with #
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.

mixinsRequired #

  • Type: …constructs.IMixin[]

The mixins to apply.

Static Functions #

Name

Description

isConstruct

Checks if x is a construct.
isConstruct #
import { PloneHttpcache } from '@bluedynamics/cdk8s-plone'

PloneHttpcache.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.

xRequired #

  • Type: any

Any object.

Properties #

Name

Type

Description

node

constructs.Node

The tree node.

httpcacheServiceName

string

Name of the Varnish service created by the Helm chart.
nodeRequired #
public readonly node: Node;

  • Type: constructs.Node

The tree node.

httpcacheServiceNameRequired #
public readonly httpcacheServiceName: string;

  • Type: string

Name of the Varnish service created by the Helm chart.

Use this to reference the cache service from ingress or other constructs.

PloneVinylCache #

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

const plone = new Plone(chart, 'plone');
const cache = new PloneVinylCache(chart, 'cache', {
  plone: plone,
  replicas: 2,
});
// Use cache.vinylCacheServiceName for IngressRoute

Initializers #

import { PloneVinylCache } from '@bluedynamics/cdk8s-plone'

new PloneVinylCache(scope: Construct, id: string, options: PloneVinylCacheOptions)

Name

Type

Description

scope

constructs.Construct

No description.

id

string

No description.

options

PloneVinylCacheOptions

No description.
scopeRequired #

  • Type: constructs.Construct

idRequired #

  • Type: string

optionsRequired #

Methods #

Name

Description

toString

Returns a string representation of this construct.

with

Applies one or more mixins to this construct.
toString #
public toString(): string

Returns a string representation of this construct.

with #
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.

mixinsRequired #

  • Type: …constructs.IMixin[]

The mixins to apply.

Static Functions #

Name

Description

isConstruct

Checks if x is a construct.
isConstruct #
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.

xRequired #

  • Type: any

Any object.

Properties #

Name

Type

Description

node

constructs.Node

The tree node.

vinylCacheServiceName

string

Name of the VinylCache service created by the operator.
nodeRequired #
public readonly node: Node;

  • Type: constructs.Node

The tree node.

vinylCacheServiceNameRequired #
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 #

HttpcacheEnvVar #

An environment variable to pass to the kube-httpcache container.

Initializer #

import { HttpcacheEnvVar } from '@bluedynamics/cdk8s-plone'

const httpcacheEnvVar: HttpcacheEnvVar = { ... }

Properties #

Name

Type

Description

name

string

The name of the environment variable.

value

string

The value of the environment variable.
nameRequired #
public readonly name: string;

  • Type: string

The name of the environment variable.

valueRequired #
public readonly value: string;

  • Type: string

The value of the environment variable.

HttpcacheToleration #

A Kubernetes toleration for the Varnish pods.

Initializer #

import { HttpcacheToleration } from '@bluedynamics/cdk8s-plone'

const httpcacheToleration: HttpcacheToleration = { ... }

Properties #

Name

Type

Description

key

string

The taint key to tolerate.

effect

string

The taint effect to tolerate (NoSchedule, PreferNoSchedule, NoExecute).

operator

string

The operator (Equal or Exists).

value

string

The taint value to match (when operator is Equal).
keyRequired #
public readonly key: string;

  • Type: string

The taint key to tolerate.

effectOptional #
public readonly effect: string;

  • Type: string

  • Default: tolerate all effects

The taint effect to tolerate (NoSchedule, PreferNoSchedule, NoExecute).

operatorOptional #
public readonly operator: string;

  • Type: string

  • Default: ‘Equal’

The operator (Equal or Exists).

valueOptional #
public readonly value: string;

  • Type: string

  • Default: no value

The taint value to match (when operator is Equal).

PloneBaseOptions #

Base options for Plone backend or frontend configuration.

These options control container image, replica count, resource limits, environment variables, and health probes.

Initializer #

import { PloneBaseOptions } from '@bluedynamics/cdk8s-plone'

const ploneBaseOptions: PloneBaseOptions = { ... }

Properties #

Name

Type

Description

annotations

{[ key: string ]: string}

Annotations to add to the Deployment metadata.

environment

cdk8s-plus-30.Env

Environment variables to set in the container.

image

string

Container image to use for the deployment.

imagePullPolicy

string

Image pull policy for the container.

limitCpu

string

CPU limit for the container.

limitMemory

string

Memory limit for the container.

livenessEnabled

boolean

Enable liveness probe for the container.

livenessFailureThreshold

number

Minimum consecutive failures for the liveness probe to be considered failed.

livenessInitialDelaySeconds

number

Number of seconds after container start before liveness probe is initiated.

livenessPeriodSeconds

number

How often (in seconds) to perform the liveness probe.

livenessSuccessThreshold

number

Minimum consecutive successes for the liveness probe to be considered successful.

livenessTimeoutSeconds

number

Number of seconds after which the liveness probe times out.

maxUnavailable

string | number

Maximum number of pods that can be unavailable during updates.

metricsPath

string

Path to scrape metrics from.

metricsPort

string | number

Port name or number to scrape metrics from.

minAvailable

string | number

Minimum number of pods that must be available during updates.

nodeSelector

{[ key: string ]: string}

Node selector labels for pod scheduling.

podAnnotations

{[ key: string ]: string}

Annotations to add to the Pod template metadata.

readinessEnabled

boolean

Enable readiness probe for the container.

readinessFailureThreshold

number

Minimum consecutive failures for the readiness probe to be considered failed.

readinessInitialDelaySeconds

number

Number of seconds after container start before readiness probe is initiated.

readinessPeriodSeconds

number

How often (in seconds) to perform the readiness probe.

readinessSuccessThreshold

number

Minimum consecutive successes for the readiness probe to be considered successful.

readinessTimeoutSeconds

number

Number of seconds after which the readiness probe times out.

replicas

number

Number of pod replicas to run.

requestCpu

string

CPU request for the container.

requestMemory

string

Memory request for the container.

securityContext

PloneSecurityContext

Security context for the container.

service

PloneServiceSpec

Service configuration: type, trafficDistribution, sessionAffinity, annotations/labels, and a raw overrides escape hatch for any other ServiceSpec field.

serviceAnnotations

{[ key: string ]: string}

Annotations to add to the Service metadata.

servicemonitor

boolean

Enable Prometheus ServiceMonitor for metrics collection.
annotationsOptional #
public readonly annotations: {[ key: string ]: string};

  • Type: {[ key: string ]: string}

  • Default: no additional annotations

Annotations to add to the Deployment metadata.

Example

{ 'deployment.kubernetes.io/revision': '1' }
environmentOptional #
public readonly environment: Env;

  • Type: cdk8s-plus-30.Env

  • Default: undefined (no additional environment variables)

Environment variables to set in the container.

Use cdk8s-plus-30 Env class to define variables and sources.

imageOptional #
public readonly image: string;

  • Type: string

  • Default: ‘plone/plone-backend:latest’ for backend, ‘plone/plone-frontend:latest’ for frontend

Container image to use for the deployment.

Example

'plone/plone-backend:6.0.10' or 'plone/plone-frontend:16.0.0'
imagePullPolicyOptional #
public readonly imagePullPolicy: string;

  • Type: string

  • Default: ‘IfNotPresent’

Image pull policy for the container.

limitCpuOptional #
public readonly limitCpu: string;

  • Type: string

  • Default: ‘500m’ for both backend and frontend

CPU limit for the container.

Example

'500m' or '1' or '2000m'
limitMemoryOptional #
public readonly limitMemory: string;

  • Type: string

  • Default: ‘512Mi’ for backend, ‘1Gi’ for frontend

Memory limit for the container.

Example

'512Mi' or '1Gi'
livenessEnabledOptional #
public readonly livenessEnabled: boolean;

  • Type: boolean

  • Default: false

Enable liveness probe for the container.

Liveness probes determine when to restart a container. Recommended: true for frontend, false for backend (Zope has its own recovery).

livenessFailureThresholdOptional #
public readonly livenessFailureThreshold: number;

  • Type: number

  • Default: 3

Minimum consecutive failures for the liveness probe to be considered failed.

livenessInitialDelaySecondsOptional #
public readonly livenessInitialDelaySeconds: number;

  • Type: number

  • Default: 30

Number of seconds after container start before liveness probe is initiated.

livenessPeriodSecondsOptional #
public readonly livenessPeriodSeconds: number;

  • Type: number

  • Default: 10

How often (in seconds) to perform the liveness probe.

livenessSuccessThresholdOptional #
public readonly livenessSuccessThreshold: number;

  • Type: number

  • Default: 1

Minimum consecutive successes for the liveness probe to be considered successful.

livenessTimeoutSecondsOptional #
public readonly livenessTimeoutSeconds: number;

  • Type: number

  • Default: 5

Number of seconds after which the liveness probe times out.

maxUnavailableOptional #
public readonly maxUnavailable: string | number;

  • Type: string | number

  • Default: undefined (not set)

Maximum number of pods that can be unavailable during updates.

Can be an absolute number (e.g., 1) or a percentage (e.g., ‘50%’). Used in PodDisruptionBudget if specified.

metricsPathOptional #
public readonly metricsPath: string;

  • Type: string

  • Default: ‘/metrics’

Path to scrape metrics from.

Only used when servicemonitor is enabled.

metricsPortOptional #
public readonly metricsPort: string | number;

  • Type: string | number

  • Default: uses the main service port

Port name or number to scrape metrics from.

Only used when servicemonitor is enabled.

minAvailableOptional #
public readonly minAvailable: string | number;

  • Type: string | number

  • Default: undefined (not set)

Minimum number of pods that must be available during updates.

Can be an absolute number (e.g., 1) or a percentage (e.g., ‘50%’). Used in PodDisruptionBudget if specified.

nodeSelectorOptional #
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

{ 'topology.kubernetes.io/region': 'fsn1' }
podAnnotationsOptional #
public readonly podAnnotations: {[ key: string ]: string};

  • Type: {[ key: string ]: string}

  • Default: no additional annotations

Annotations to add to the Pod template metadata.

Common for Prometheus, Istio, backup policies, etc.

Example

{ 'prometheus.io/scrape': 'true', 'prometheus.io/port': '8080' }
readinessEnabledOptional #
public readonly readinessEnabled: boolean;

  • Type: boolean

  • Default: true

Enable readiness probe for the container.

Readiness probes determine when a container is ready to accept traffic.

readinessFailureThresholdOptional #
public readonly readinessFailureThreshold: number;

  • Type: number

  • Default: 3

Minimum consecutive failures for the readiness probe to be considered failed.

readinessInitialDelaySecondsOptional #
public readonly readinessInitialDelaySeconds: number;

  • Type: number

  • Default: 10

Number of seconds after container start before readiness probe is initiated.

readinessPeriodSecondsOptional #
public readonly readinessPeriodSeconds: number;

  • Type: number

  • Default: 10

How often (in seconds) to perform the readiness probe.

readinessSuccessThresholdOptional #
public readonly readinessSuccessThreshold: number;

  • Type: number

  • Default: 1

Minimum consecutive successes for the readiness probe to be considered successful.

readinessTimeoutSecondsOptional #
public readonly readinessTimeoutSeconds: number;

  • Type: number

  • Default: 15

Number of seconds after which the readiness probe times out.

replicasOptional #
public readonly replicas: number;

  • Type: number

  • Default: 2

Number of pod replicas to run.

requestCpuOptional #
public readonly requestCpu: string;

  • Type: string

  • Default: ‘200m’

CPU request for the container.

Example

'200m' or '0.5'
requestMemoryOptional #
public readonly requestMemory: string;

  • Type: string

  • Default: ‘256Mi’

Memory request for the container.

Example

'256Mi' or '512Mi'
securityContextOptional #
public readonly securityContext: PloneSecurityContext;

Security context for the container.

Use to set capabilities, run as non-root, read-only filesystem, etc.

Example

{ capabilities: { add: ['SYS_PTRACE'] } }
serviceOptional #
public readonly service: PloneServiceSpec;

Service configuration: type, trafficDistribution, sessionAffinity, annotations/labels, and a raw overrides escape hatch for any other ServiceSpec field.

Applies to this component’s Service.

Example

{ type: 'LoadBalancer', trafficDistribution: 'PreferClose' }
~~serviceAnnotations~~Optional #

  • Deprecated: use service.annotations instead

public readonly serviceAnnotations: {[ key: string ]: string};

  • Type: {[ key: string ]: string}

  • Default: no additional annotations

Annotations to add to the Service metadata.

Common for external-dns, load balancers, service mesh, etc.

Example

{ 'external-dns.alpha.kubernetes.io/hostname': 'plone.example.com' }
servicemonitorOptional #
public readonly servicemonitor: boolean;

  • Type: boolean

  • Default: false

Enable Prometheus ServiceMonitor for metrics collection.

Requires Prometheus Operator to be installed in the cluster. When enabled, a ServiceMonitor resource will be created to scrape metrics.

PloneCapabilities #

Linux capabilities to add or drop on a container.

Initializer #

import { PloneCapabilities } from '@bluedynamics/cdk8s-plone'

const ploneCapabilities: PloneCapabilities = { ... }

Properties #

Name

Type

Description

add

string[]

Capabilities to add (e.g. ‘SYS_PTRACE’, ‘NET_ADMIN’).

drop

string[]

Capabilities to drop (e.g. ‘ALL’, ‘NET_RAW’).
addOptional #
public readonly add: string[];

  • Type: string[]

  • Default: no capabilities added

Capabilities to add (e.g. ‘SYS_PTRACE’, ‘NET_ADMIN’).

dropOptional #
public readonly drop: string[];

  • Type: string[]

  • Default: no capabilities dropped

Capabilities to drop (e.g. ‘ALL’, ‘NET_RAW’).

PloneHttpcacheOptions #

Configuration options for PloneHttpcache (Varnish caching layer).

Initializer #

import { PloneHttpcacheOptions } from '@bluedynamics/cdk8s-plone'

const ploneHttpcacheOptions: PloneHttpcacheOptions = { ... }

Properties #

Name

Type

Description

plone

Plone

The Plone construct to attach the HTTP cache to.

appVersion

string

Version of the kube-httpcache Container Image to use.

chartVersion

string

Version of the kube-httpcache Helm chart to use.

existingSecret

string

Name of an existing Kubernetes secret containing Varnish admin credentials.

exporterEnabled

boolean

Enable the Prometheus exporter for Varnish metrics.

extraEnvVars

HttpcacheEnvVar[]

Additional environment variables to pass to the kube-httpcache container.

limitCpu

string

CPU limit for Varnish pods.

limitMemory

string

Memory limit for Varnish pods.

replicas

number

Number of Varnish pod replicas to run.

requestCpu

string

CPU request for Varnish pods.

requestMemory

string

Memory request for Varnish pods.

servicemonitor

boolean

Enable Prometheus ServiceMonitor for metrics collection.

tolerations

HttpcacheToleration[]

Tolerations for the Varnish pods.

varnishVcl

string

Varnish VCL configuration as a string.

varnishVclFile

string

Path to a Varnish VCL configuration file.
ploneRequired #
public readonly plone: Plone;

The Plone construct to attach the HTTP cache to.

The cache will automatically connect to the backend and frontend services.

appVersionOptional #
public readonly appVersion: string;

  • Type: string

  • Default: undefined (chartVersion = with each chart release there is an image release too )

Version of the kube-httpcache Container Image to use.

If not specified, the latest version from the repository will be used.

chartVersionOptional #
public readonly chartVersion: string;

  • Type: string

  • Default: undefined (latest)

Version of the kube-httpcache Helm chart to use.

If not specified, the latest version from the repository will be used.

existingSecretOptional #
public readonly existingSecret: string;

  • Type: string

  • Default: undefined (no existing secret)

Name of an existing Kubernetes secret containing Varnish admin credentials.

The secret should be created separately in the same namespace.

exporterEnabledOptional #
public readonly exporterEnabled: boolean;

  • Type: boolean

  • Default: true

Enable the Prometheus exporter for Varnish metrics.

When enabled, the exporter sidecar container will be deployed alongside Varnish.

extraEnvVarsOptional #
public readonly extraEnvVars: HttpcacheEnvVar[];

Additional environment variables to pass to the kube-httpcache container.

These are appended to the built-in env vars (BACKEND_SERVICE_NAME, etc.) and can be referenced in VCL templates using Go template syntax: {{ .Env.VAR_NAME }}

limitCpuOptional #
public readonly limitCpu: string;

  • Type: string

  • Default: ‘500m’

CPU limit for Varnish pods.

limitMemoryOptional #
public readonly limitMemory: string;

  • Type: string

  • Default: ‘500Mi’

Memory limit for Varnish pods.

replicasOptional #
public readonly replicas: number;

  • Type: number

  • Default: 2

Number of Varnish pod replicas to run.

requestCpuOptional #
public readonly requestCpu: string;

  • Type: string

  • Default: ‘100m’

CPU request for Varnish pods.

requestMemoryOptional #
public readonly requestMemory: string;

  • Type: string

  • Default: ‘100Mi’

Memory request for Varnish pods.

servicemonitorOptional #
public readonly servicemonitor: boolean;

  • Type: boolean

  • Default: false

Enable Prometheus ServiceMonitor for metrics collection.

Requires Prometheus Operator to be installed in the cluster.

tolerationsOptional #
public readonly tolerations: HttpcacheToleration[];

Tolerations for the Varnish pods.

Use this to allow scheduling on nodes with specific taints, e.g. nodes tainted with kubernetes.io/arch=amd64:NoSchedule.

varnishVclOptional #
public readonly varnishVcl: string;

  • Type: string

  • Default: loaded from varnishVclFile or default config file

Varnish VCL configuration as a string.

If provided, this takes precedence over varnishVclFile.

varnishVclFileOptional #
public readonly varnishVclFile: string;

  • Type: string

  • Default: uses default config/varnish.tpl.vcl

Path to a Varnish VCL configuration file.

If not provided, uses the default VCL file included in the library.

PloneOptions #

Main configuration options for Plone deployment.

Initializer #

import { PloneOptions } from '@bluedynamics/cdk8s-plone'

const ploneOptions: PloneOptions = { ... }

Properties #

Name

Type

Description

backend

PloneBaseOptions

Backend (Plone API) configuration.

frontend

PloneBaseOptions

Frontend (Volto) configuration.

imagePullSecrets

string[]

Names of Kubernetes secrets to use for pulling private container images.

siteId

string

Plone site ID in the ZODB.

variant

PloneVariant

Plone deployment variant to use.

version

string

Version string for labeling the deployment.
backendOptional #
public readonly backend: PloneBaseOptions;

  • Type: PloneBaseOptions

  • Default: {} (uses default values from PloneBaseOptions)

Backend (Plone API) configuration.

frontendOptional #
public readonly frontend: PloneBaseOptions;

  • Type: PloneBaseOptions

  • Default: {} (uses default values from PloneBaseOptions)

Frontend (Volto) configuration.

Only used when variant is PloneVariant.VOLTO.

imagePullSecretsOptional #
public readonly imagePullSecrets: string[];

  • Type: string[]

  • Default: [] (no image pull secrets)

Names of Kubernetes secrets to use for pulling private container images.

These secrets must exist in the same namespace as the deployment.

Example

['my-registry-secret']
siteIdOptional #
public readonly siteId: string;

  • Type: string

  • Default: ‘Plone’

Plone site ID in the ZODB.

This is used to construct the internal API path for Volto frontend.

variantOptional #
public readonly variant: PloneVariant;

Plone deployment variant to use.

versionOptional #
public readonly version: string;

  • Type: string

  • Default: ‘undefined’

Version string for labeling the deployment.

This is used in Kubernetes labels and doesn’t affect the actual image versions.

PloneSecurityContext #

Security context for a Plone container.

Controls privilege and access settings.

Initializer #

import { PloneSecurityContext } from '@bluedynamics/cdk8s-plone'

const ploneSecurityContext: PloneSecurityContext = { ... }

Properties #

Name

Type

Description

allowPrivilegeEscalation

boolean

Allow privilege escalation for the container process.

capabilities

PloneCapabilities

Linux capabilities to add or drop.

privileged

boolean

Run the container in privileged mode.

readOnlyRootFilesystem

boolean

Mount the root filesystem as read-only.

runAsGroup

number

Run the container as a specific group ID.

runAsNonRoot

boolean

Require the container to run as non-root.

runAsUser

number

Run the container as a specific user ID.
allowPrivilegeEscalationOptional #
public readonly allowPrivilegeEscalation: boolean;

  • Type: boolean

  • Default: undefined

Allow privilege escalation for the container process.

capabilitiesOptional #
public readonly capabilities: PloneCapabilities;

Linux capabilities to add or drop.

Example

{ add: ['SYS_PTRACE'] }
privilegedOptional #
public readonly privileged: boolean;

  • Type: boolean

  • Default: undefined

Run the container in privileged mode.

readOnlyRootFilesystemOptional #
public readonly readOnlyRootFilesystem: boolean;

  • Type: boolean

  • Default: undefined

Mount the root filesystem as read-only.

runAsGroupOptional #
public readonly runAsGroup: number;

  • Type: number

  • Default: container default

Run the container as a specific group ID.

runAsNonRootOptional #
public readonly runAsNonRoot: boolean;

  • Type: boolean

  • Default: undefined

Require the container to run as non-root.

runAsUserOptional #
public readonly runAsUser: number;

  • Type: number

  • Default: container default

Run the container as a specific user ID.

PloneServiceSpec #

Configuration for the generated Kubernetes Service spec.

Curated fields cover the common cases; use overrides as an escape hatch for any other ServiceSpec field. overrides has the highest precedence and can override every field, including the construct-managed ports/selector (at your own risk).

Initializer #

import { PloneServiceSpec } from '@bluedynamics/cdk8s-plone'

const ploneServiceSpec: PloneServiceSpec = { ... }

Properties #

Name

Type

Description

annotations

{[ key: string ]: string}

Annotations to add to the Service metadata.

externalTrafficPolicy

string

External traffic policy, ‘Cluster’ | ‘Local’.

internalTrafficPolicy

string

Internal traffic policy, ‘Cluster’ | ‘Local’.

labels

{[ key: string ]: string}

Extra labels to add to the Service metadata.

loadBalancerClass

string

Load balancer implementation class.

loadBalancerSourceRanges

string[]

Source IP ranges allowed to access a LoadBalancer service.

overrides

{[ key: string ]: any}

Raw ServiceSpec overrides as a free-form map (e.g. { ipFamilyPolicy: 'PreferDualStack' }). Highest precedence — merged on top of all curated fields and the construct-managed base. Use for any ServiceSpec field not covered above. Keys and values are passed through to the Service spec verbatim and are not validated by this construct.

publishNotReadyAddresses

boolean

Publish not-ready addresses (e.g. for headless services with StatefulSets).

sessionAffinity

string

Session affinity, ‘ClientIP’ | ‘None’.

trafficDistribution

string

Traffic distribution preference, e.g. ‘PreferClose’ for topology-aware routing.

type

string

Service type, e.g. ClusterIP | NodePort | LoadBalancer | ExternalName.
annotationsOptional #
public readonly annotations: {[ key: string ]: string};

  • Type: {[ key: string ]: string}

  • Default: none

Annotations to add to the Service metadata.

externalTrafficPolicyOptional #
public readonly externalTrafficPolicy: string;

  • Type: string

  • Default: Cluster (Kubernetes default)

External traffic policy, ‘Cluster’ | ‘Local’.

internalTrafficPolicyOptional #
public readonly internalTrafficPolicy: string;

  • Type: string

  • Default: Cluster (Kubernetes default)

Internal traffic policy, ‘Cluster’ | ‘Local’.

labelsOptional #
public readonly labels: {[ key: string ]: string};

  • Type: {[ key: string ]: string}

  • Default: none

Extra labels to add to the Service metadata.

loadBalancerClassOptional #
public readonly loadBalancerClass: string;

  • Type: string

  • Default: none

Load balancer implementation class.

loadBalancerSourceRangesOptional #
public readonly loadBalancerSourceRanges: string[];

  • Type: string[]

  • Default: none

Source IP ranges allowed to access a LoadBalancer service.

overridesOptional #
public readonly overrides: {[ key: string ]: any};

  • Type: {[ key: string ]: any}

  • Default: none

Raw ServiceSpec overrides as a free-form map (e.g. { ipFamilyPolicy: 'PreferDualStack' }). Highest precedence — merged on top of all curated fields and the construct-managed base. Use for any ServiceSpec field not covered above. Keys and values are passed through to the Service spec verbatim and are not validated by this construct.

publishNotReadyAddressesOptional #
public readonly publishNotReadyAddresses: boolean;

  • Type: boolean

  • Default: false

Publish not-ready addresses (e.g. for headless services with StatefulSets).

sessionAffinityOptional #
public readonly sessionAffinity: string;

  • Type: string

  • Default: None (Kubernetes default)

Session affinity, ‘ClientIP’ | ‘None’.

trafficDistributionOptional #
public readonly trafficDistribution: string;

  • Type: string

  • Default: none

Traffic distribution preference, e.g. ‘PreferClose’ for topology-aware routing.

typeOptional #
public readonly type: string;

  • Type: string

  • Default: ClusterIP (Kubernetes default)

Service type, e.g. ClusterIP | NodePort | LoadBalancer | ExternalName.

PloneVinylCacheOptions #

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 #

import { PloneVinylCacheOptions } from '@bluedynamics/cdk8s-plone'

const ploneVinylCacheOptions: PloneVinylCacheOptions = { ... }

Properties #

Name

Type

Description

plone

Plone

The Plone construct to attach the cache to.

director

string

Director type for load distribution.

extraBackends

VinylCacheBackend[]

Additional backends to add after the auto-generated Plone backends.

image

string

Container image for the Varnish pods.

invalidation

boolean

Enable cache invalidation (PURGE, BAN, xkey).

limitCpu

string

CPU limit for Varnish pods.

limitMemory

string

Memory limit for Varnish pods.

monitoring

boolean

Enable Prometheus monitoring.

nodeSelector

{[ key: string ]: string}

Node selector labels for the Varnish pods.

replicas

number

Number of Varnish pod replicas.

requestCpu

string

CPU request for Varnish pods.

requestMemory

string

Memory request for Varnish pods.

shardBy

string

Shard director: what value is hashed for shard selection.

shardHealthy

string

Shard director: which backends the director considers when selecting a shard.

shardRampup

string

Shard director: time after adding a backend before it receives its full share of traffic, preventing thundering-herd.

shardReplicas

number

Shard director: number of Ketama replicas per backend in the hash ring.

storage

VinylCacheStorage[]

Varnish storage backends (spec.storage).

tolerations

VinylCacheToleration[]

Tolerations for the Varnish pods.

vclBackendErrorSnippet

string

Custom VCL snippet for vcl_backend_error subroutine.

vclBackendFetchSnippet

string

Custom VCL snippet for vcl_backend_fetch subroutine.

vclBackendResponseSnippet

string

Custom VCL snippet for vcl_backend_response subroutine.

vclDeliverSnippet

string

Custom VCL snippet for vcl_deliver subroutine.

vclFiniSnippet

string

Custom VCL snippet for vcl_fini subroutine.

vclHashSnippet

string

Custom VCL snippet for vcl_hash subroutine.

vclHitSnippet

string

Custom VCL snippet for vcl_hit subroutine.

vclInitSnippet

string

Custom VCL snippet for vcl_init subroutine.

vclMissSnippet

string

Custom VCL snippet for vcl_miss subroutine.

vclPassSnippet

string

Custom VCL snippet for vcl_pass subroutine.

vclPipeSnippet

string

Custom VCL snippet for vcl_pipe subroutine.

vclPurgeSnippet

string

Custom VCL snippet for vcl_purge subroutine.

vclRecvSnippet

string

Custom VCL snippet for vcl_recv subroutine.

vclSynthSnippet

string

Custom VCL snippet for vcl_synth subroutine.
ploneRequired #
public readonly plone: Plone;

The Plone construct to attach the cache to.

Backends are auto-configured from the Plone services.

directorOptional #
public readonly director: string;

  • Type: string

  • Default: ‘shard’

Director type for load distribution.

extraBackendsOptional #
public readonly extraBackends: VinylCacheBackend[];

Additional backends to add after the auto-generated Plone backends.

Uses the same backend type structure as the VinylCache CRD.

imageOptional #
public readonly image: string;

  • Type: string

  • Default: ‘varnish:7.6’

Container image for the Varnish pods.

invalidationOptional #
public readonly invalidation: boolean;

  • Type: boolean

  • Default: true

Enable cache invalidation (PURGE, BAN, xkey).

limitCpuOptional #
public readonly limitCpu: string;

  • Type: string

  • Default: ‘500m’

CPU limit for Varnish pods.

limitMemoryOptional #
public readonly limitMemory: string;

  • Type: string

  • Default: ‘512Mi’

Memory limit for Varnish pods.

monitoringOptional #
public readonly monitoring: boolean;

  • Type: boolean

  • Default: false

Enable Prometheus monitoring.

When true this turns on operator metrics, a ServiceMonitor, and the prometheus_varnish_exporter sidecar (required for cache hit-ratio and backend-health metrics).

nodeSelectorOptional #
public readonly nodeSelector: {[ key: string ]: string};

  • Type: {[ key: string ]: string}

  • Default: no node selector

Node selector labels for the Varnish pods.

Constrains pods to nodes matching all specified labels.

replicasOptional #
public readonly replicas: number;

  • Type: number

  • Default: 2

Number of Varnish pod replicas.

requestCpuOptional #
public readonly requestCpu: string;

  • Type: string

  • Default: ‘100m’

CPU request for Varnish pods.

requestMemoryOptional #
public readonly requestMemory: string;

  • Type: string

  • Default: ‘256Mi’

Memory request for Varnish pods.

shardByOptional #
public readonly shardBy: string;

  • Type: string

  • Default: operator default (“HASH”)

Shard director: what value is hashed for shard selection.

“HASH” uses the Varnish hash (default); “URL” uses the request URL. Only applied when director is “shard”. Requires cloud-vinyl operator >= 0.4.2.

shardHealthyOptional #
public readonly shardHealthy: string;

  • Type: string

  • Default: operator default (“CHOSEN”)

Shard director: which backends the director considers when selecting a shard.

“CHOSEN” (default) only considers the chosen backend healthy; “ALL” requires all backends to be healthy. Only applied when director is “shard”. Requires cloud-vinyl operator >= 0.4.2.

shardRampupOptional #
public readonly shardRampup: string;

  • Type: string

  • Default: operator default (“30s”)

Shard director: time after adding a backend before it receives its full share of traffic, preventing thundering-herd.

Only applied when director is “shard”.

shardReplicasOptional #
public readonly shardReplicas: number;

  • Type: number

  • Default: operator default (67)

Shard director: number of Ketama replicas per backend in the hash ring.

Only applied when director is “shard”.

storageOptional #
public readonly storage: VinylCacheStorage[];

  • Type: VinylCacheStorage[]

  • Default: no storage configured; operator uses varnishd default (~100MB malloc)

Varnish storage backends (spec.storage).

Each entry becomes a -s <name>=<type>,<options> argument to varnishd. If omitted, the operator ships varnishd with its stock default (~100 MB malloc) — almost always too small. Set an explicit malloc size at least matching the pod’s memory request to use the allocated memory for caching.

Example

storage: [{ name: 's0', type: 'malloc', size: '1Gi' }]
tolerationsOptional #
public readonly tolerations: VinylCacheToleration[];

Tolerations for the Varnish pods.

vclBackendErrorSnippetOptional #
public readonly vclBackendErrorSnippet: string;

  • Type: string

  • Default: no snippet

Custom VCL snippet for vcl_backend_error subroutine.

vclBackendFetchSnippetOptional #
public readonly vclBackendFetchSnippet: string;

  • Type: string

  • Default: no snippet

Custom VCL snippet for vcl_backend_fetch subroutine.

vclBackendResponseSnippetOptional #
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.

vclDeliverSnippetOptional #
public readonly vclDeliverSnippet: string;

  • Type: string

  • Default: no snippet

Custom VCL snippet for vcl_deliver subroutine.

vclFiniSnippetOptional #
public readonly vclFiniSnippet: string;

  • Type: string

  • Default: no snippet

Custom VCL snippet for vcl_fini subroutine.

vclHashSnippetOptional #
public readonly vclHashSnippet: string;

  • Type: string

  • Default: no snippet

Custom VCL snippet for vcl_hash subroutine.

vclHitSnippetOptional #
public readonly vclHitSnippet: string;

  • Type: string

  • Default: no snippet

Custom VCL snippet for vcl_hit subroutine.

vclInitSnippetOptional #
public readonly vclInitSnippet: string;

  • Type: string

  • Default: no snippet

Custom VCL snippet for vcl_init subroutine.

vclMissSnippetOptional #
public readonly vclMissSnippet: string;

  • Type: string

  • Default: no snippet

Custom VCL snippet for vcl_miss subroutine.

vclPassSnippetOptional #
public readonly vclPassSnippet: string;

  • Type: string

  • Default: no snippet

Custom VCL snippet for vcl_pass subroutine.

vclPipeSnippetOptional #
public readonly vclPipeSnippet: string;

  • Type: string

  • Default: no snippet

Custom VCL snippet for vcl_pipe subroutine.

vclPurgeSnippetOptional #
public readonly vclPurgeSnippet: string;

  • Type: string

  • Default: no snippet

Custom VCL snippet for vcl_purge subroutine.

vclRecvSnippetOptional #
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.

vclSynthSnippetOptional #
public readonly vclSynthSnippet: string;

  • Type: string

  • Default: no snippet

Custom VCL snippet for vcl_synth subroutine.

VinylCacheBackend #

An additional backend for the VinylCache.

Initializer #

import { VinylCacheBackend } from '@bluedynamics/cdk8s-plone'

const vinylCacheBackend: VinylCacheBackend = { ... }

Properties #

Name

Type

Description

name

string

VCL identifier for this backend.

port

number

Port to use for this backend.

serviceName

string

Kubernetes Service name to use as backend.

probe

VinylCacheBackendProbe

Health probe configuration.

weight

number

Relative weight for the director.
nameRequired #
public readonly name: string;

  • Type: string

VCL identifier for this backend.

Must match ^[a-zA-Z][a-zA-Z0-9_]*$.

portRequired #
public readonly port: number;

  • Type: number

Port to use for this backend.

serviceNameRequired #
public readonly serviceName: string;

  • Type: string

Kubernetes Service name to use as backend.

probeOptional #
public readonly probe: VinylCacheBackendProbe;

Health probe configuration.

weightOptional #
public readonly weight: number;

  • Type: number

  • Default: operator default

Relative weight for the director.

0 means standby.

VinylCacheBackendProbe #

Health probe configuration for a VinylCache backend.

Initializer #

import { VinylCacheBackendProbe } from '@bluedynamics/cdk8s-plone'

const vinylCacheBackendProbe: VinylCacheBackendProbe = { ... }

Properties #

Name

Type

Description

expectedResponse

number

Expected HTTP response status code.

interval

string

How often to probe the backend.

threshold

number

Minimum successful probes within window for healthy status.

timeout

string

Maximum time to wait for a probe response.

url

string

URL to probe.

window

number

Number of most recent probes to consider.
expectedResponseOptional #
public readonly expectedResponse: number;

  • Type: number

  • Default: 200

Expected HTTP response status code.

intervalOptional #
public readonly interval: string;

  • Type: string

  • Default: ‘5s’

How often to probe the backend.

thresholdOptional #
public readonly threshold: number;

  • Type: number

  • Default: 8

Minimum successful probes within window for healthy status.

timeoutOptional #
public readonly timeout: string;

  • Type: string

  • Default: ‘2s’

Maximum time to wait for a probe response.

urlOptional #
public readonly url: string;

  • Type: string

  • Default: ‘/’

URL to probe.

windowOptional #
public readonly window: number;

  • Type: number

  • Default: 10

Number of most recent probes to consider.

VinylCacheStorage #

A Varnish storage backend configuration.

Maps to spec.storage[] on the VinylCache CRD. The operator emits one -s <name>=<type>,<options> argument per entry to varnishd.

Without any storage entry the operator falls back to the varnishd default (~100 MB malloc), which is almost always too small for real workloads.

Initializer #

import { VinylCacheStorage } from '@bluedynamics/cdk8s-plone'

const vinylCacheStorage: VinylCacheStorage = { ... }

Properties #

Name

Type

Description

name

string

Internal storage identifier used in the varnishd -s argument.

type

string

Storage backend type.

path

string

Filesystem path for file-type storage.

size

string

Storage allocation as a Kubernetes resource quantity (e.g. “1Gi”, “500M”). Required for malloc; required for file.
nameRequired #
public readonly name: string;

  • Type: string

Internal storage identifier used in the varnishd -s argument.

Must be unique within the VinylCache and match ^[a-zA-Z][a-zA-Z0-9_]*$.

typeRequired #
public readonly type: string;

  • Type: string

Storage backend type.

Only “malloc” and “file” are permitted by the admission webhook.

pathOptional #
public readonly path: string;

  • Type: string

  • Default: required for type “file”

Filesystem path for file-type storage.

Ignored for malloc.

sizeOptional #
public readonly size: string;

  • Type: string

  • Default: required for both malloc and file

Storage allocation as a Kubernetes resource quantity (e.g. “1Gi”, “500M”). Required for malloc; required for file.

VinylCacheToleration #

A Kubernetes toleration for the Varnish pods.

Initializer #

import { VinylCacheToleration } from '@bluedynamics/cdk8s-plone'

const vinylCacheToleration: VinylCacheToleration = { ... }

Properties #

Name

Type

Description

key

string

The taint key to tolerate.

effect

string

The taint effect to tolerate (NoSchedule, PreferNoSchedule, NoExecute).

operator

string

The operator (Equal or Exists).

value

string

The taint value to match (when operator is Equal).
keyRequired #
public readonly key: string;

  • Type: string

The taint key to tolerate.

effectOptional #
public readonly effect: string;

  • Type: string

  • Default: tolerate all effects

The taint effect to tolerate (NoSchedule, PreferNoSchedule, NoExecute).

operatorOptional #
public readonly operator: string;

  • Type: string

  • Default: ‘Equal’

The operator (Equal or Exists).

valueOptional #
public readonly value: string;

  • Type: string

  • Default: no value

The taint value to match (when operator is Equal).

Enums #

PloneVariant #

Plone deployment variants.

Members #

Name

Description

VOLTO

Volto variant: ReactJS single-page frontend (Volto) talking to the Plone REST API.

BLICCA

Blicca variant: the Plone backend renders the UI server-side and serves the HTML directly.

CLASSICUI

Deprecated alias for the Blicca variant (formerly “Classic UI”).
VOLTO #

Volto variant: ReactJS single-page frontend (Volto) talking to the Plone REST API.

Deploys both frontend and backend services.

BLICCA #

Blicca variant: the Plone backend renders the UI server-side and serves the HTML directly.

Deploys only the backend service.

~~CLASSICUI~~ #

  • Deprecated: Renamed to {@link BLICCA }. Kept for backward compatibility and selects the same backend-only deployment. Existing configuration using CLASSICUI (or the literal value 'classicui') keeps working unchanged. Will be removed in a future major release.

Deprecated alias for the Blicca variant (formerly “Classic UI”).

This API reference is automatically generated from the TypeScript source code. For the latest version, run npx projen docgen in the project root.