CRD Reference

All resources use the API group openvox.voxpupuli.org/v1alpha1.

Resource Hierarchy

graph TD
    Cfg["Config"]
    CA["CertificateAuthority"]
    SP["SigningPolicy"]
    NC["NodeClassifier"]
    RP["ReportProcessor"]
    Cert["Certificate"]
    Srv["Server"]
    DB["Database"]
    Pool["Pool"]

    Cfg -->|authorityRef| CA
    Cfg -.->|nodeClassifierRef| NC
    Cfg -.->|databaseRef| DB
    SP -.->|certificateAuthorityRef| CA
    Cert -->|authorityRef| CA
    Srv -->|certificateRef| Cert
    DB -->|certificateRef| Cert
    Srv -->|configRef| Cfg
    RP -.->|configRef| Cfg
    Srv -->|poolRefs| Pool

Each resource references its parent. The operator reconciles them in order: a Config references a CertificateAuthority via authorityRef, optionally a NodeClassifier via nodeClassifierRef, and optionally a Database via databaseRef (which auto-wires the PuppetDB connection URL). A CertificateAuthority must be Ready before a Certificate can be signed, and a Certificate must be Signed before a Server or Database creates its Deployment. SigningPolicies, NodeClassifiers, and ReportProcessors can be created at any time and take effect within ~60 seconds.

Resources

Kind	Short Name	Purpose
Config	cfg	Shared config (puppet.conf, auth.conf), OpenVox DB connection
CertificateAuthority	ca	CA infrastructure: PVC, keys, 3 CA Secrets (cert, key, CRL)
SigningPolicy	sp	Declarative CSR signing policy for a CA
NodeClassifier	nc	External Node Classifier (ENC) endpoint
Certificate	cert	Lifecycle of a single certificate (request, sign)
Server	-	OpenVox Server Deployment (CA and/or server role)
Database	db	OpenVox DB Deployment with external PostgreSQL
Pool	-	Networking resource: Service for Servers that reference this Pool
ReportProcessor	rp	Webhook-based report forwarding endpoint

Shared Types

These types are reused across multiple CRDs.

ImageSpec

Field	Type	Default	Description
repository	string	ghcr.io/slauger/openvox-server-8	Container image repository
tag	string	latest	Container image tag
pullPolicy	string	IfNotPresent	Image pull policy
pullSecrets	[]LocalObjectReference	-	Image pull secrets

StorageSpec

Field	Type	Default	Description
size	string	1Gi	Requested storage size
storageClass	string	-	Storage class name (empty = default)

CodeSpec

code on Config and Server is a list of code sources. Each entry sets exactly one source (claimName or image, not both) and an optional mount target (environment or mountPath, not both).

Field	Type	Default	Description
claimName	string	-	Name of an existing PVC containing Puppet code (mutually exclusive with image)
image	string	-	OCI image reference containing Puppet code, Kubernetes 1.35+ or 1.31+ with feature gate (mutually exclusive with claimName)
imagePullPolicy	string	IfNotPresent	When to pull the code image
imagePullSecret	string	-	Secret name for pulling from private registries
environment	string	-	Mount this source as a single Puppet environment at <environmentpath>/<environment>. Must be unique across the list (mutually exclusive with mountPath)
mountPath	string	-	Mount this source at an absolute path under the Puppet codedir (/etc/puppetlabs/code), e.g. the global modules dir or hieradata (mutually exclusive with environment)

Mount target rules:

• 0 entries - an emptyDir is mounted at environmentpath so Puppet Server can bootstrap its default production environment.
• 1 entry without environment/mountPath - the source is mounted as the whole environments tree at environmentpath (the pre-list behaviour).
• More than 1 entry - each entry must set environment or mountPath; environment values must be unique. mountPath must be under /etc/puppetlabs/code.

Entries are mounted read-only. A Server's code replaces (does not merge with) the Config's code.

code:
  - image: registry/control-repo-production:latest
    environment: production                 # -> <environmentpath>/production
  - claimName: shared-modules
    mountPath: /etc/puppetlabs/code/modules # global modules dir

PodSecurityContextSpec

Used by CertificateAuthority, Server and Database to override the pod-level security context of managed pods. All fields are optional; an unset field keeps the operator default.

Field	Type	Default	Description
runAsUser	int64	1001	UID the pod runs as
runAsGroup	int64	0	Primary GID the pod runs as
runAsNonRoot	bool	true	Require the pod to run as a non-root user
fsGroup	int64	1001	Supplemental group applied to mounted volumes. The kubelet chowns the volume to this group, letting the non-root user write to CSI-provisioned volumes that would otherwise be owned by root.
fsGroupChangePolicy	string	OnRootMismatch	When volume ownership is changed to match fsGroup (OnRootMismatch or Always)

By default the operator sets a matching fsGroup so managed pods can write to freshly provisioned CSI volumes (e.g. Ceph RBD/CephFS), which are typically owned by root:root. Override these fields on OpenShift or PodSecurity-restricted namespaces that assign their own UID/GID ranges.