Klio API reference

Packages

• klio.cnpg.io/v1alpha1

klio.cnpg.io/v1alpha1

Package v1alpha1 contains API Schema definitions for the klio v1alpha1 API group.

Resource Types

• PluginConfiguration
• Server

CompressionAlgorithm

Underlying type: string

CompressionAlgorithm is the name of a Kopia compression algorithm. The special value "none" disables compression.

Validation:

• Enum: [none deflate-best-compression deflate-best-speed deflate-default gzip gzip-best-compression gzip-best-speed pgzip pgzip-best-compression pgzip-best-speed s2-better s2-default s2-parallel-4 s2-parallel-8 zstd zstd-better-compression zstd-fastest]

Appears in:

• CompressionPolicy

CompressionPolicy

CompressionPolicy configures the Kopia compression policy applied to base backup data. A minSize above a non-zero maxSize would match no file at all: Kopia accepts such a policy and then silently skips compression for every file, so it is rejected at admission instead.

Appears in:

• Tier1Configuration
• Tier1PluginConfiguration
• Tier2Configuration
• Tier2PluginConfiguration

Field	Description	Required	Default	Validation
algorithm CompressionAlgorithm	Algorithm is the name of the Kopia compression algorithm to use.	True		Enum: [none deflate-best-compression deflate-best-speed deflate-default gzip gzip-best-compression gzip-best-speed pgzip pgzip-best-compression pgzip-best-speed s2-better s2-default s2-parallel-4 s2-parallel-8 zstd zstd-better-compression zstd-fastest] Required: {}
minSize integer	MinSize is the minimum file size, in bytes, to attempt compression for. Files smaller than this are stored uncompressed. Zero means no minimum.			Minimum: 0 Optional: {}
maxSize integer	MaxSize is the maximum file size, in bytes, to attempt compression for. Files larger than this are stored uncompressed. Zero means no maximum.			Minimum: 0 Optional: {}

EmbeddedObjectMeta

EmbeddedObjectMeta contains metadata for embedded objects.

Appears in:

• PodTemplateSpec

Field	Description	Required	Default	Validation
labels object (keys:string, values:string)				Optional: {}
annotations object (keys:string, values:string)				Optional: {}

FileReference

FileReference specifies a file from a volume source.

Appears in:

• FileSource

Field	Description	Required	Default	Validation
volume VolumeSource	Volume is the volume source to mount.	True
path string	Path is the file path within the mounted volume.	True

FileSource

FileSource specifies a source for a file. This wrapper allows future alternatives to be added without breaking the API.

Validation:

• ExactlyOneOf: [fileReference]

Appears in:

• Tier1Configuration
• Tier2Configuration

Field	Description	Required	Default	Validation
fileReference FileReference	FileReference specifies a file from a volume source.			Optional: {}

ImageConfiguration

ImageConfiguration contains the information needed to download the Klio image.

Appears in:

• ServerSpec

Field	Description	Required	Default	Validation
image string	Image is the image to be used for the Klio server	True
imagePullPolicy PullPolicy	ImagePullPolicy defines the policy for pulling the image		IfNotPresent	Optional: {}
imagePullSecrets LocalObjectReference array	ImagePullSecrets is an optional list of references to secrets in the same namespace to use for pulling any of the images			Optional: {}

PluginConfiguration

PluginConfiguration is the Schema for the client configuration API.

Field	Description	Required	Default	Validation
apiVersion string	klio.cnpg.io/v1alpha1	True
kind string	PluginConfiguration	True
metadata ObjectMeta	Refer to Kubernetes API documentation for fields of metadata.	True
spec PluginConfigurationSpec		True
status PluginConfigurationStatus				Optional: {}

PluginConfigurationSpec

PluginConfigurationSpec defines the desired state of client configuration.

Appears in:

• PluginConfiguration

Field	Description	Required	Default	Validation
serverAddress string	ServerAddress is the address of the Klio server	True		MinLength: 1 Required: {}
tier1 Tier1PluginConfiguration	Tier1 is the Tier 1 configuration			Optional: {}
tier2 Tier2PluginConfiguration	Tier2 is the Tier 2 configuration			Optional: {}
walPrefetch WALPrefetchConfiguration	WALPrefetch configures WAL prefetching behavior during recovery operations.			Optional: {}
clientSecretName string	ClientSecretName is the name of the secret containing the client credentials	True		MinLength: 1 Required: {}
serverSecretName string	ServerSecretName is the name of the secret containing the server TLS certificate	True		MinLength: 1 Required: {}
clusterName string	ClusterName is the name of the PostgreSQL cluster we are connecting to	True		MinLength: 1 Required: {}
pprof boolean	Pprof enables the pprof endpoint for performance profiling			Optional: {}
mode ServerMode	Mode selects the operation mode of the plugin.	True	standard	Enum: [standard read-only]
containers Container array	Containers allows defining a list of containers that will be merged with the Klio sidecar containers. This enables users to customize the sidecars with additional environment variables, volume mounts, resource limits, and other container settings without polluting the PostgreSQL container environment. Merge behavior: - Containers are matched by name (klio-plugin, klio-restore) - User customizations serve as the base - Klio required values (name, args, CONTAINER_NAME env var) always override user values - User-defined environment variables and volume mounts are preserved - Template defaults are applied only for fields not set by the user or Klio			MaxItems: 2 Optional: {}

PluginConfigurationStatus

PluginConfigurationStatus defines the observed state of ClientConfig.

Appears in:

• PluginConfiguration

Field	Description	Required	Default	Validation
conditions Condition array	Conditions represent the latest available observations of the PluginConfiguration's state.			Optional: {}

PodTemplateSpec

PodTemplateSpec describes the data a pod should have when created from a template.

Appears in:

• ServerSpec

Field	Description	Required	Default	Validation
metadata EmbeddedObjectMeta	Refer to Kubernetes API documentation for fields of metadata.			Optional: {}
spec PodSpec				Optional: {}

RetentionPolicy

RetentionPolicy defines how many backups we should keep.

Appears in:

• Tier1PluginConfiguration
• Tier2PluginConfiguration

Field	Description	Required	Default	Validation
keepLatest integer	KeepLatest is the number of latest backups to keep optional	True
keepAnnual integer	KeepAnnual is the number of annual backups to keep optional	True
keepMonthly integer	KeepMonthly is the number of monthly backups to keep optional	True
keepWeekly integer	KeepWeekly is the number of weekly backups to keep optional	True
keepDaily integer	KeepDaily is the number of daily backups to keep optional	True
keepHourly integer	KeepHourly is the number of hourly backups to keep optional	True

S3Configuration

S3Configuration is the configuration to a S3 defined tier 2.

Appears in:

• Tier2Configuration

Field	Description	Required	Default	Validation
bucketName string	BucketName is the name of the bucket	True
prefix string	Prefix is the path within the bucket under which all Klio objects are stored, allowing a single bucket to be shared across multiple deployments.			Optional: {}
endpoint string	Endpoint is the endpoint to be used			Optional: {}
region string	Region is the region to be used			Optional: {}
accessKeyId SecretKeySelector	The S3 access key ID			Optional: {}
secretAccessKey SecretKeySelector	The S3 access key			Optional: {}
sessionToken SecretKeySelector	The S3 session token			Optional: {}
customCaBundle SecretKeySelector	A pointer to a custom CA bundle			Optional: {}

Server

Server is the Schema for the servers API.

Field	Description	Required	Default	Validation
apiVersion string	klio.cnpg.io/v1alpha1	True
kind string	Server	True
metadata ObjectMeta	Refer to Kubernetes API documentation for fields of metadata.	True
spec ServerSpec		True
status ServerStatus				Optional: {}

ServerMode

Underlying type: string

ServerMode defines the operation mode of the Server.

Appears in:

• PluginConfigurationSpec
• ServerSpec

Field	Description
standard	ModeStandard corresponds to server with standard read/write permissions.
read-only	ModeReadOnly corresponds to a server with read-only permissions.

ServerSpec

ServerSpec defines the desired state of Server.

Appears in:

• Server

Field	Description	Required	Default	Validation
image string	Image is the image to be used for the Klio server	True
imagePullPolicy PullPolicy	ImagePullPolicy defines the policy for pulling the image		IfNotPresent	Optional: {}
imagePullSecrets LocalObjectReference array	ImagePullSecrets is an optional list of references to secrets in the same namespace to use for pulling any of the images			Optional: {}
tlsSecretName string	TLSSecretName is the name of the Kubernetes secret containing the server-side certificate to be used for the Klio server.	True
caSecretName string	ClientCASecretName is the name of the Kubernetes secret containing the CA certificate to be used by the Klio server to validate the users.	True
mode ServerMode	Mode selects the operation mode of the server.	True	standard	Enum: [standard read-only]
tier1 Tier1Configuration	Tier1 is the Tier 1 configuration	True
tier2 Tier2Configuration	Tier2 is the Tier 2 configuration	True
storage Storage	Storage is the configuration of the single PersistentVolumeClaim mounted at /klio, hosting base backups, WAL, the work queue, and the Tier 1/Tier 2 caches as fixed subdirectories (data, queue, cache_tier1, cache_tier2).	True
template PodTemplateSpec	Template to override the default StatefulSet of the Klio server. WARNING: Modifying this template may break the server functionality if not done carefully. This field is primarily intended for advanced configuration such as telemetry setup. Use at your own risk and ensure thorough testing before applying changes.			Optional: {}

ServerStatus

ServerStatus defines the observed state of Server.

Appears in:

• Server

Storage

Storage defines the configuration for the Klio server's PersistentVolumeClaim.

Appears in:

• ServerSpec

Field	Description	Required	Default	Validation
pvcTemplate PersistentVolumeClaimSpec	PersistentVolumeClaimTemplate is used to generate the PVC that backs the /klio directory tree for this server.	True

TLSConfiguration

TLSConfiguration contains the information needed to configure the PKI infrastructure of the Klio server.

Appears in:

• ServerSpec

Field	Description	Required	Default	Validation
tlsSecretName string	TLSSecretName is the name of the Kubernetes secret containing the server-side certificate to be used for the Klio server.	True
caSecretName string	ClientCASecretName is the name of the Kubernetes secret containing the CA certificate to be used by the Klio server to validate the users.	True

Tier1Configuration

Tier1Configuration is the tier 1 configuration.

Appears in:

• ServerSpec

Field	Description	Required	Default	Validation
encryptionKeyFile FileSource	EncryptionKeyFile specifies the Age-encrypted encryption key file.	True		ExactlyOneOf: [fileReference]
identityFile FileSource	IdentityFile specifies the Age identity (private key) file used to decrypt the encryption key.	True		ExactlyOneOf: [fileReference]
compression CompressionPolicy	Compression defines the repository-wide (global) compression policy applied to base backups stored on tier1. Individual clusters can override it through their PluginConfiguration.			Optional: {}

Tier1PluginConfiguration

Tier1PluginConfiguration configures tier1 backup and recovery settings.

Appears in:

• PluginConfigurationSpec

Field	Description	Required	Default	Validation
retention RetentionPolicy	RetentionPolicy defines how many backups we should keep			Optional: {}
compression CompressionPolicy	Compression defines the compression policy applied to this cluster's base backups on tier1. It overrides the tier1 repository-wide policy configured on the Server.			Optional: {}

Tier2Configuration

Tier2Configuration is the tier 2 configuration.

Appears in:

• ServerSpec

Field	Description	Required	Default	Validation
s3 S3Configuration	S3 contains the configuration parameters for an S3-based tier 2.	True
encryptionKeyFile FileSource	EncryptionKeyFile specifies the Age-encrypted encryption key file.	True		ExactlyOneOf: [fileReference]
identityFile FileSource	IdentityFile specifies the Age identity (private key) file used to decrypt the encryption key.	True		ExactlyOneOf: [fileReference]
compression CompressionPolicy	Compression defines the repository-wide (global) compression policy applied to base backups stored on tier2. Individual clusters can override it through their PluginConfiguration.			Optional: {}

Tier2PluginConfiguration

Tier2PluginConfiguration configures tier2 backup and recovery settings.

Appears in:

• PluginConfigurationSpec

Field	Description	Required	Default	Validation
enableBackup boolean	EnableBackup controls whether WAL and base backups should be stored in tier2			Optional: {}
enableRecovery boolean	EnableRecovery controls whether tier2 should be included in the recovery source list			Optional: {}
retention RetentionPolicy	RetentionPolicy defines how many backups we should keep			Optional: {}
compression CompressionPolicy	Compression defines the compression policy applied to this cluster's base backups on tier2. It overrides the tier2 repository-wide policy configured on the Server.			Optional: {}

WALPrefetchConfiguration

WALPrefetchConfiguration configures WAL prefetching during recovery.

Appears in:

• PluginConfigurationSpec

Field	Description	Required	Default	Validation
count integer	Count is the number of WAL files to prefetch ahead during recovery. A value of 0 disables prefetching.	True	2	Maximum: 64 Minimum: 0
maxConcurrentDownloads integer	MaxConcurrentDownloads is the maximum number of concurrent WAL downloads.	True	4	Maximum: 64 Minimum: 1