Klio API reference
Packages
klio.cnpg.io/v1alpha1
Package v1alpha1 contains API Schema definitions for the klio v1alpha1 API group.
Resource Types
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 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:
| 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:
| Field | Description | Required | Default | Validation |
|---|---|---|---|---|
labels object (keys:string, values:string) | Optional: {} | |||
annotations object (keys:string, values:string) | Optional: {} |
EncryptionFiles
EncryptionFiles is the Age-encrypted encryption key and the Age identity used to decrypt it, read from a single volume.
Appears in:
| Field | Description | Required | Default | Validation |
|---|---|---|---|---|
volume VolumeSource | Volume is the volume source that holds the encryption key file and the identity file. | True | ExactlyOneOf: [secret configMap projected csi] | |
keyPath string | KeyPath is the path of the Age-encrypted encryption key file within the volume. | True | MaxLength: 1024 MinLength: 1 Required: {} | |
identityPath string | IdentityPath is the path of the Age identity (private key) file within the volume, used to decrypt the encryption key. | True | MaxLength: 1024 MinLength: 1 Required: {} |
ImageConfiguration
ImageConfiguration contains the information needed to download the Klio image.
Appears in:
| 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:
| 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: {} | ||
tls PluginTLSConfiguration | TLS configures the PKI of the plugin: the identity the PostgreSQL instances present to the Klio server and the CA used to verify it. | True | 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) - 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: 1 Optional: {} |
PluginConfigurationStatus
PluginConfigurationStatus defines the observed state of ClientConfig.
Appears in:
| Field | Description | Required | Default | Validation |
|---|---|---|---|---|
conditions Condition array | Conditions represent the latest available observations of the PluginConfiguration's state. | Optional: {} |
PluginTLSConfiguration
PluginTLSConfiguration contains the information needed to configure the PKI of the plugin.
Appears in:
| Field | Description | Required | Default | Validation |
|---|---|---|---|---|
clientIdentity TLSIdentity | ClientIdentity is the TLS identity the PostgreSQL instances present to the Klio server: the client certificate and its matching private key. | True | Required: {} | |
serverCa VolumeFileReference | ServerCA is the CA bundle used to verify the Klio server. It is mounted into PostgreSQL instance pods and used for both base backups (Kopia, via --server-cert-ca-file) and WAL streaming (gRPC). The referenced file must contain the PEM-encoded CA certificate(s). | True | Required: {} |
PodTemplateSpec
PodTemplateSpec describes the data a pod should have when created from a template.
Appears in:
| 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:
| Field | Description | Required | Default | Validation |
|---|---|---|---|---|
latest integer | Latest is the number of latest backups to keep. Zero disables retention: every backup is kept, the same as leaving this policy unset. | Minimum: 0 Optional: {} |
S3Configuration
S3Configuration is the configuration to a S3 defined tier 2.
Appears in:
| 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: {} | ||
credentialsFile VolumeFileReference | CredentialsFile is an AWS shared credentials file (INI format) mounted from a volume. It is mutually exclusive with accessKeyId, secretAccessKey and sessionToken. | Optional: {} | ||
profile string | Profile is the profile to use within CredentialsFile. | Optional: {} | ||
customCaBundle VolumeFileReference | CustomCABundle is a PEM-encoded CA bundle, mounted from a volume, that is trusted when connecting to the S3 endpoint. | 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:
| 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:
| 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: {} | ||
tls TLSConfiguration | TLS configures the PKI of the Klio server: the identity it presents and the CA used to verify clients. | 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:
Storage
Storage defines the configuration for the Klio server's PersistentVolumeClaim.
Appears in:
| 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:
| Field | Description | Required | Default | Validation |
|---|---|---|---|---|
serverIdentity TLSIdentity | ServerIdentity is the TLS identity presented to clients: the server certificate and its matching private key. | True | Required: {} | |
clientCa VolumeFileReference | ClientCA is the CA bundle used to verify client certificates. It must contain the PEM-encoded CA certificate(s). | True | Required: {} |
TLSIdentity
TLSIdentity is the certificate and private key a component uses to authenticate itself over TLS.
Appears in:
| Field | Description | Required | Default | Validation |
|---|---|---|---|---|
volume VolumeSource | Volume is the volume source that holds the certificate and the private key. | True | ExactlyOneOf: [secret configMap projected csi] | |
certPath string | CertPath is the path of the certificate file within the volume. | True | MaxLength: 1024 MinLength: 1 Required: {} | |
keyPath string | KeyPath is the path of the private key file within the volume. | True | MaxLength: 1024 MinLength: 1 Required: {} |
Tier1Configuration
Tier1Configuration is the tier 1 configuration.
Appears in:
| Field | Description | Required | Default | Validation |
|---|---|---|---|---|
encryption EncryptionFiles | Encryption specifies the Age-encrypted encryption key file and the Age identity (private key) file used to decrypt it. | True | ||
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:
| 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:
| Field | Description | Required | Default | Validation |
|---|---|---|---|---|
s3 S3Configuration | S3 contains the configuration parameters for an S3-based tier 2. | True | ||
encryption EncryptionFiles | Encryption specifies the Age-encrypted encryption key file and the Age identity (private key) file used to decrypt it. | True | ||
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:
| 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: {} |
VolumeFileReference
VolumeFileReference specifies a file from a volume source.
Appears in:
| Field | Description | Required | Default | Validation |
|---|---|---|---|---|
volume VolumeSource | Volume is the volume source to mount. | True | ExactlyOneOf: [secret configMap projected csi] | |
path string | Path is the file path within the mounted volume. | True | MaxLength: 1024 MinLength: 1 Required: {} |
VolumeSource
VolumeSource is the subset of volume sources Klio can read files from.
Validation:
- ExactlyOneOf: [secret configMap projected csi]
Appears in:
| Field | Description | Required | Default | Validation |
|---|---|---|---|---|
secret SecretVolumeSource | Secret is a volume populated by a Secret. | Optional: {} | ||
configMap ConfigMapVolumeSource | ConfigMap is a volume populated by a ConfigMap. | Optional: {} | ||
projected ProjectedVolumeSource | Projected is a projected volume (secrets, config maps, cluster trust bundles, ...). | Optional: {} | ||
csi CSIVolumeSource | CSI is a volume provided by a CSI driver. | Optional: {} |
WALPrefetchConfiguration
WALPrefetchConfiguration configures WAL prefetching during recovery.
Appears in:
| 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 |