diff --git a/gatsby-config.js b/gatsby-config.js index eddbe4e19ff..ea1d771b185 100644 --- a/gatsby-config.js +++ b/gatsby-config.js @@ -71,6 +71,7 @@ const sourceToPluginConfig = { name: "jdbc_connector", path: "product_docs/docs/jdbc_connector", }, + klio: { name: "klio", path: "product_docs/docs/klio" }, language_pack: { name: "language_pack", path: "product_docs/docs/language_pack", @@ -443,6 +444,7 @@ module.exports = { seealso: "note", hint: "tip", interactive: "interactive", + caution: "warning", }, }, ], diff --git a/product_docs/docs/klio/0/_helm_chart_values.mdx b/product_docs/docs/klio/0/_helm_chart_values.mdx new file mode 100644 index 00000000000..cb79fe1185a --- /dev/null +++ b/product_docs/docs/klio/0/_helm_chart_values.mdx @@ -0,0 +1,42 @@ +| Key | Type | Default | Description | +| -------------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | +| certmanager.clusterDomain | string | `"cluster.local"` | The DNS domain of the cluster | +| certmanager.createMetricsCertificate | bool | `true` | Create certificates for the metrics service. | +| certmanager.createPluginClientCertificate | bool | `true` | Create certificates for the plugin client. | +| certmanager.createPluginServerCertificate | bool | `true` | Create certificates for the plugin server. | +| certmanager.duration | string | `"2160h"` | The duration of the certificates. | +| certmanager.enable | bool | `true` | Enable cert-manager integration for certificate creation. | +| certmanager.renewBefore | string | `"360h"` | The renew before time for the certificates. | +| controllerManager.affinity | object | `{}` | Affinity rules for the operator deployment. | +| controllerManager.manager.args | list | `["--metrics-bind-address=:8443","--leader-elect","--health-probe-bind-address=:8081","--plugin-server-cert=/pluginServer/tls.crt","--plugin-server-key=/pluginServer/tls.key","--plugin-client-cert=/pluginClient/tls.crt","--plugin-server-address=:9090"]` | List of command line arguments to pass to the controller manager. | +| controllerManager.manager.containerSecurityContext | object | `{"allowPrivilegeEscalation":false,"capabilities":{"drop":["ALL"]}}` | The security context for the controller manager container. | +| controllerManager.manager.env | object | `{"SIDECAR_IMAGE":"docker.enterprisedb.com/k8s/klio:v0.0.15"}` | The environment variables to set in the controller manager container. | +| controllerManager.manager.image.pullPolicy | string | `"Always"` | The controller manager container imagePullPolicy. | +| controllerManager.manager.image.pullSecrets | list | `[]` | The list of imagePullSecrets. | +| controllerManager.manager.image.repository | string | `"docker.enterprisedb.com/k8s/klio-operator"` | The image to use for the controller manager container. | +| controllerManager.manager.image.tag | string | `"v0.0.15"` | The tag to use for the controller manager container image. | +| controllerManager.manager.livenessProbe | object | `{"httpGet":{"path":"/healthz","port":8081},"initialDelaySeconds":15,"periodSeconds":20}` | Liveness probe configuration. | +| controllerManager.manager.readinessProbe | object | `{"httpGet":{"path":"/readyz","port":8081},"initialDelaySeconds":5,"periodSeconds":10}` | Readiness probe configuration. | +| controllerManager.manager.resources | object | `{"limits":{"cpu":"500m","memory":"128Mi"},"requests":{"cpu":"10m","memory":"64Mi"}}` | The resources to allocate. | +| controllerManager.nodeSelector | object | `{}` | NodeSelector for the operator deployment. | +| controllerManager.podSecurityContext | object | `{"runAsNonRoot":true,"seccompProfile":{"type":"RuntimeDefault"}}` | The security context for the controller manager pod. | +| controllerManager.priorityClassName | string | `""` | Priority class name for the controller manager pod. | +| controllerManager.serviceAccount.annotations | object | `{}` | The annotations to add to the service account. | +| controllerManager.tolerations | list | `[]` | Tolerations for the operator deployment. | +| controllerManager.topologySpreadConstraints | list | `[]` | Topology Spread Constraints for the operator deployment. | +| fullnameOverride | string | `""` | Override the fully qualified name of the Helm Chart. | +| kubernetesClusterDomain | string | `"cluster.local"` | The domain for the Kubernetes cluster. | +| metricsService.enable | bool | `true` | Enable the metrics service for the controller manager. | +| metricsService.metricsServiceSecret | string | `"klio-metrics-server-cert"` | The name of the secret containing the TLS certificate for the metrics service. | +| metricsService.ports | list | `[{"name":"https","port":8443,"protocol":"TCP","targetPort":8443}]` | The port the metrics service will listen on. | +| metricsService.type | string | `"ClusterIP"` | Service type for the metrics service. | +| nameOverride | string | `"klio"` | Override the name of the Helm Chart. | +| plugin.clientSecret | string | `"klio-plugin-client-tls"` | The Client TLS certificate. | +| plugin.name | string | `"klio.enterprisedb.io"` | The name the plugin will use to register itself with the CNPG Operator. | +| plugin.port | int | `9090` | The port the plugin will listen on. It must match the "--plugin-server-address" argument. | +| plugin.serverSecret | string | `"klio-plugin-server-tls"` | The Server TLS certificate. | +| prometheus.enable | bool | `true` | To enable a ServiceMonitor to export metrics to Prometheus set true. | +| serviceAccount.annotations | object | `{}` | The annotations to add to the service account. | +| serviceAccount.automount | bool | `true` | Automount service account token. | +| serviceAccount.create | bool | `true` | Specifies whether a service account should be created. | +| serviceAccount.name | string | `""` | The name of the service account | diff --git a/product_docs/docs/klio/0/api/_klio_api.mdx b/product_docs/docs/klio/0/api/_klio_api.mdx new file mode 100644 index 00000000000..3a2b99505c2 --- /dev/null +++ b/product_docs/docs/klio/0/api/_klio_api.mdx @@ -0,0 +1,344 @@ +# Packages + +- [klio.enterprisedb.io/v1alpha1](#klioenterprisedbiov1alpha1) + +## klio.enterprisedb.io/v1alpha1 + +Package v1alpha1 contains API Schema definitions for the klio v1alpha1 API group. + +### Resource Types + +- [PluginConfiguration](#pluginconfiguration) +- [Server](#server) + +#### Cache + +Cache defines the configuration for the cache directory. + +*Appears in:* + +- [Tier1Configuration](#tier1configuration) +- [Tier2Configuration](#tier2configuration) + +| Field | Description | Required | Default | Validation | +| --------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | -------- | ------- | ---------- | +| `pvcTemplate` *[PersistentVolumeClaimSpec](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.36/#persistentvolumeclaimspec-v1-core)* | | True | | | + +#### Data + +Data defines the configuration for the data directory. + +*Appears in:* + +- [Tier1Configuration](#tier1configuration) + +| Field | Description | Required | Default | Validation | +| --------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | -------- | ------- | ---------- | +| `pvcTemplate` *[PersistentVolumeClaimSpec](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.36/#persistentvolumeclaimspec-v1-core)* | Template to be used to generate the Persistent Volume Claim needed for the data folder,
containing base backups and WAL files. | True | | | + +#### EmbeddedObjectMeta + +EmbeddedObjectMeta contains metadata for embedded objects. + +*Appears in:* + +- [PodTemplateSpec](#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](#filesource) + +| Field | Description | Required | Default | Validation | +| -------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ | -------- | ------- | ---------- | +| `volume` *[VolumeSource](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.36/#volumesource-v1-core)* | 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](#tier1configuration) +- [Tier2Configuration](#tier2configuration) + +| Field | Description | Required | Default | Validation | +| ------------------------------------------------- | ---------------------------------------------------- | -------- | ------- | ------------------- | +| `fileReference` *[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](#serverspec) + +| Field | Description | Required | Default | Validation | +| ---------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | -------- | ------------ | ------------------- | +| `image` *string* | Image is the image to be used for the Klio server | True | | | +| `imagePullPolicy` *[PullPolicy](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.36/#pullpolicy-v1-core)* | ImagePullPolicy defines the policy for pulling the image | | IfNotPresent | Optional: {}
| +| `imagePullSecrets` *[LocalObjectReference](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.36/#localobjectreference-v1-core) 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.enterprisedb.io/v1alpha1` | True | | | +| `kind` *string* | `PluginConfiguration` | True | | | +| `metadata` *[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.36/#objectmeta-v1-meta)* | Refer to Kubernetes API documentation for fields of `metadata`. | True | | | +| `spec` *[PluginConfigurationSpec](#pluginconfigurationspec)* | | True | | | +| `status` *[PluginConfigurationStatus](#pluginconfigurationstatus)* | | | | Optional: {}
| + +#### PluginConfigurationSpec + +PluginConfigurationSpec defines the desired state of client configuration. + +*Appears in:* + +- [PluginConfiguration](#pluginconfiguration) + +| Field | Description | Required | Default | Validation | +| ------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- | -------- | -------------------------------------- | +| `serverAddress` *string* | ServerAddress is the address of the Klio server | True | | MinLength: 1
Required: {}
| +| `tier1` *[Tier1PluginConfiguration](#tier1pluginconfiguration)* | Tier1 is the Tier 1 configuration | | | Optional: {}
| +| `tier2` *[Tier2PluginConfiguration](#tier2pluginconfiguration)* | Tier2 is the Tier 2 configuration | | | Optional: {}
| +| `walPrefetch` *[WALPrefetchConfiguration](#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](#servermode)* | Mode selects the operation mode of the plugin. | True | standard | Enum: [standard read-only]
| +| `containers` *[Container](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.36/#container-v1-core) 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-wal, 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: 3
Optional: {}
| + +#### PluginConfigurationStatus + +PluginConfigurationStatus defines the observed state of ClientConfig. + +*Appears in:* + +- [PluginConfiguration](#pluginconfiguration) + +| Field | Description | Required | Default | Validation | +| ------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------- | -------- | ------- | ------------------- | +| `conditions` *[Condition](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.36/#condition-v1-meta) 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](#serverspec) + +| Field | Description | Required | Default | Validation | +| -------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- | -------- | ------- | ------------------- | +| `metadata` *[EmbeddedObjectMeta](#embeddedobjectmeta)* | Refer to Kubernetes API documentation for fields of `metadata`. | | | Optional: {}
| +| `spec` *[PodSpec](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.36/#podspec-v1-core)* | | | | Optional: {}
| + +#### Queue + +Queue defines the configuration for the directory hosting the +task queue. + +*Appears in:* + +- [ServerSpec](#serverspec) + +| Field | Description | Required | Default | Validation | +| --------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | -------- | ------- | ---------- | +| `pvcTemplate` *[PersistentVolumeClaimSpec](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.36/#persistentvolumeclaimspec-v1-core)* | PersistentVolumeClaimTemplate is used to generate the configuration for
the PVC hosting the work queue. | True | | | + +#### RetentionPolicy + +RetentionPolicy defines how many backups we should keep. + +*Appears in:* + +- [Tier1PluginConfiguration](#tier1pluginconfiguration) +- [Tier2PluginConfiguration](#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](#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](https://pkg.go.dev/github.com/cloudnative-pg/machinery/pkg/api#SecretKeySelector)* | The S3 access key ID | | | Optional: {}
| +| `secretAccessKey` *[SecretKeySelector](https://pkg.go.dev/github.com/cloudnative-pg/machinery/pkg/api#SecretKeySelector)* | The S3 access key | | | Optional: {}
| +| `sessionToken` *[SecretKeySelector](https://pkg.go.dev/github.com/cloudnative-pg/machinery/pkg/api#SecretKeySelector)* | The S3 session token | | | Optional: {}
| +| `customCaBundle` *[SecretKeySelector](https://pkg.go.dev/github.com/cloudnative-pg/machinery/pkg/api#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.enterprisedb.io/v1alpha1` | True | | | +| `kind` *string* | `Server` | True | | | +| `metadata` *[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.36/#objectmeta-v1-meta)* | Refer to Kubernetes API documentation for fields of `metadata`. | True | | | +| `spec` *[ServerSpec](#serverspec)* | | True | | | +| `status` *[ServerStatus](#serverstatus)* | | | | Optional: {}
| + +#### ServerMode + +*Underlying type:* *string* + +ServerMode defines the operation mode of the Server. + +*Appears in:* + +- [PluginConfigurationSpec](#pluginconfigurationspec) +- [ServerSpec](#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](#server) + +| Field | Description | Required | Default | Validation | +| ---------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------------ | --------------------------------- | +| `image` *string* | Image is the image to be used for the Klio server | True | | | +| `imagePullPolicy` *[PullPolicy](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.36/#pullpolicy-v1-core)* | ImagePullPolicy defines the policy for pulling the image | | IfNotPresent | Optional: {}
| +| `imagePullSecrets` *[LocalObjectReference](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.36/#localobjectreference-v1-core) 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](#servermode)* | Mode selects the operation mode of the server. | True | standard | Enum: [standard read-only]
| +| `tier1` *[Tier1Configuration](#tier1configuration)* | Tier1 is the Tier 1 configuration | True | | | +| `tier2` *[Tier2Configuration](#tier2configuration)* | Tier2 is the Tier 2 configuration | True | | | +| `queue` *[Queue](#queue)* | Queue is the configuration of the PVC that should host
the task queue. | | | Optional: {}
| +| `template` *[PodTemplateSpec](#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](#server) + +#### TLSConfiguration + +TLSConfiguration contains the information needed to configure +the PKI infrastructure of the Klio server. + +*Appears in:* + +- [ServerSpec](#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](#serverspec) + +| Field | Description | Required | Default | Validation | +| ----------------------------------------------- | --------------------------------------------------------------------------------------------------- | -------- | ------- | ------------------------------------ | +| `cache` *[Cache](#cache)* | Cache is the configuration of the PVC that should be
used for the cache. | True | | | +| `data` *[Data](#data)* | Data is the configuration of the PVC that should be used
for the base backups. | True | | | +| `encryptionKeyFile` *[FileSource](#filesource)* | EncryptionKeyFile specifies the Age-encrypted encryption key file. | True | | ExactlyOneOf: [fileReference]
| +| `identityFile` *[FileSource](#filesource)* | IdentityFile specifies the Age identity (private key) file used to
decrypt the encryption key. | True | | ExactlyOneOf: [fileReference]
| + +#### Tier1PluginConfiguration + +Tier1PluginConfiguration configures tier1 backup and recovery settings. + +*Appears in:* + +- [PluginConfigurationSpec](#pluginconfigurationspec) + +| Field | Description | Required | Default | Validation | +| ------------------------------------------------- | ------------------------------------------------------- | -------- | ------- | ------------------- | +| `retention` *[RetentionPolicy](#retentionpolicy)* | RetentionPolicy defines how many backups we should keep | | | Optional: {}
| + +#### Tier2Configuration + +Tier2Configuration is the tier 2 configuration. + +*Appears in:* + +- [ServerSpec](#serverspec) + +| Field | Description | Required | Default | Validation | +| ----------------------------------------------- | --------------------------------------------------------------------------------------------------- | -------- | ------- | ------------------------------------ | +| `cache` *[Cache](#cache)* | Cache is the configuration of the PVC that should be
used for the cache. | True | | | +| `s3` *[S3Configuration](#s3configuration)* | S3 contains the configuration parameters for an S3-based tier 2. | True | | | +| `encryptionKeyFile` *[FileSource](#filesource)* | EncryptionKeyFile specifies the Age-encrypted encryption key file. | True | | ExactlyOneOf: [fileReference]
| +| `identityFile` *[FileSource](#filesource)* | IdentityFile specifies the Age identity (private key) file used to
decrypt the encryption key. | True | | ExactlyOneOf: [fileReference]
| + +#### Tier2PluginConfiguration + +Tier2PluginConfiguration configures tier2 backup and recovery settings. + +*Appears in:* + +- [PluginConfigurationSpec](#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)* | RetentionPolicy defines how many backups we should keep | | | Optional: {}
| + +#### WALPrefetchConfiguration + +WALPrefetchConfiguration configures WAL prefetching during recovery. + +*Appears in:* + +- [PluginConfigurationSpec](#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
| diff --git a/product_docs/docs/klio/0/api/index.mdx b/product_docs/docs/klio/0/api/index.mdx new file mode 100644 index 00000000000..cb906d7971d --- /dev/null +++ b/product_docs/docs/klio/0/api/index.mdx @@ -0,0 +1,8 @@ +--- +title: API Reference +navigation: + - klio_api + - '!_klio_api' +indexCards: extra +--- + diff --git a/product_docs/docs/klio/0/api/klio_api.mdx b/product_docs/docs/klio/0/api/klio_api.mdx new file mode 100644 index 00000000000..358980a553e --- /dev/null +++ b/product_docs/docs/klio/0/api/klio_api.mdx @@ -0,0 +1,10 @@ +--- +title: Klio API reference +originalFilePath: >- + https://github.com/EnterpriseDB/klio/blob/main/documentation/web/versioned_docs/version-0.0.15/user/api/klio_api.mdx + +--- + +import KlioAPI from "./_klio_api.mdx"; + + diff --git a/product_docs/docs/klio/0/architectures.mdx b/product_docs/docs/klio/0/architectures.mdx new file mode 100644 index 00000000000..c54b69194a6 --- /dev/null +++ b/product_docs/docs/klio/0/architectures.mdx @@ -0,0 +1,239 @@ +--- +title: Architectures & Tiers +originalFilePath: >- + https://github.com/EnterpriseDB/klio/blob/main/documentation/web/versioned_docs/version-0.0.15/user/architectures.md +sidebar_position: 3 + +--- + +Klio employs a multi-tiered architecture designed to balance performance, +resilience, and cost. This approach separates immediate, high-speed backup and +recovery operations from long-term archival and disaster recovery (DR) needs. +The architecture is built around three distinct storage tiers, each serving a +specific purpose in the data lifecycle. + +![Multi-tiered architecture overview](images/overview-multi-tiers.png) + +* * * + +## Tier 0: Volume Snapshots + +!!!note + +Tier 0 is part of our long-term vision and will be introduced in a future +release. +!!! + +**Tier 0** leverages Kubernetes Volume Snapshots, if supported by the +underlying storage class. It consists of instantaneous, point-in-time snapshots +of all volumes used by the PostgreSQL cluster, including the `PGDATA` directory +and any tablespaces. + +This tier is not intended for long-term storage but acts as the **initial +source** for a base backup. By reading from a static snapshot, Klio avoids +impacting the performance of the running database. From a disaster recovery +perspective, these snapshots are often considered "ephemeral," as most local +storage solutions keep them within the same disks, unlike some cloud providers +or storage classes that allow them to be archived to object storage. +Volume snapshot objects reside in the same Kubernetes namespace of a PostgreSQL +cluster. + +Klio coordinates the creation of the snapshot as supported by CloudNativePG and +then uses it to **asynchronously offload** the base backup data to Tier 1. +Klio also manages retention policies for volume snapshots objects for a given +PostgreSQL cluster. + +* * * + +## Tier 1: Primary Storage (The Klio Server) + +**Tier 1** is the core operational tier, also referred to as the **Main Tier** +or **Klio Server**. It's designed for speed and provides immediate access to +all necessary backup artifacts for most recovery scenarios. + +This tier consists of a **local Persistent Volume (PV)** deployed by the +Klio Server. It can be located in the same namespace as the PostgreSQL cluster +or in a different one within the same Kubernetes cluster +(see the ["Tier 1 Architectures" section below](#tier-1-architectures)). + +Its purpose is to store the **WAL archive** and the **catalog of physical base +backups**. Its high-throughput, low-latency nature is optimized for several key +tasks: + +- Receiving a continuous stream of WAL files directly from the PostgreSQL + primary. +- Storing base backups created from the primary or offloaded from Tier 0. +- Serving as the source for asynchronously replicating data to Tier 2. +- Managing retention policies for all tiers. + +### Tier 1 Architectures + +Klio supports several flexible deployment architectures for its Tier 1 storage. + +On the physical layer, it is recommended that both compute and, most +importantly, storage are separate from the PostgreSQL clusters. + +!!!warning + +Placing Tier 1 on the same nodes and storage as the PostgreSQL clusters +severely impacts the business continuity objectives of your organization. +!!! + +On the logical layer, a **Klio Server** can reside in the same namespace as the +PostgreSQL cluster(s) it manages or in a separate, dedicated namespace. + +When choosing an architecture, it's important to consider +**security and tenancy**. +PostgreSQL clusters managed by a single Klio Server share the same master +encryption key. For this reason, it's recommended to use separate Klio Servers +for clusters that serve different tenants or have distinct security +requirements. + +#### Clusters and Klio Server in the Same Namespace + +The simplest deployment places the Klio Server in the same namespace as the +PostgreSQL cluster(s). + +This can be a **dedicated 1:1 mapping** (one Klio Server per cluster): + +![Cluster and Klio server in the same namespace](images/tier1-namespace-single.png) + +Or a **shared N:1 mapping** where one server manages all clusters in the +namespace. + +![Multiple clusters share a Klio server in the same namespace](images/tier1-namespace-multi.png) + +#### Clusters and Klio Server in Different Namespaces + +For greater isolation or centralized management, the Klio Server can be +deployed in a namespace separate from the PostgreSQL clusters it protects. + +The following diagram shows a PostgreSQL cluster being backed up by a Klio +Server in another namespace: + +![Cluster and Klio server in a different namespace](images/tier1-shared-single.png) + +This model also allows a central Klio Server to manage clusters that reside in +different namespaces, as shown below: + +![Multiple clusters share a Klio server in the same namespace](images/tier1-shared-multi.png) + +### Reserving Nodes for Klio Workloads + +For dedicated performance and resource isolation, you can reserve specific +worker nodes for Klio pods using Kubernetes taints and tolerations. + +1. **Taint the Node**: Apply a taint to the desired node. This prevents most + pods from being scheduled on it. + + ```sh + kubectl taint node node-role.kubernetes.io/klio=:NoSchedule + ``` + +2. **Add Toleration to Klio Server**: Add the corresponding toleration to your + Klio `Server` resource, adding it to `.spec.template`. + This allows the Klio Server to be scheduled on the tainted node. + + ```yaml + # In your Server resource definition + spec: + template: + spec: + containers: [] + tolerations: + - key: "node-role.kubernetes.io/klio" + operator: "Exists" + effect: "NoSchedule" + ``` + +* * * + +## Tier 2: Secondary Storage (Object Storage) + +**Tier 2** provides durable, long-term storage for robust disaster recovery +(DR) strategies. It's physically and logically separate from the primary +Kubernetes cluster and typically consists of an external object storage system, +such as Amazon S3, Google Cloud Storage, or Azure Blob Storage. +Storing backups off-site ensures **geographical redundancy**, protecting data +against a full cluster or site failure. + +Klio asynchronously relays both base backups and WAL files from Tier 1 to +Tier 2. This decoupling ensures that primary backup and recovery operations in +Tier 1 are not directly affected by the latency or availability of the remote +object storage. + +Additionally, Tier 2 can serve as a read-only fallback source. In a distributed +CloudNativePG topology, this allows a Klio server at a secondary site to use +the shared Tier 2 storage to bootstrap a new cluster, enhancing DR +capabilities. + +### Snapshot Pinning + +When Tier 2 is enabled, Klio automatically pins snapshots in Tier 1 with a +`klio.io/tier2` pin. This mechanism prevents retention policies from +automatically deleting snapshots before they have been successfully migrated +to Tier 2. + +The pinning workflow operates as follows: + +1. When a backup is created with Tier 2 enabled, all snapshot components + (tablespaces, PGDATA, control file, and metadata) are tagged with the + `klio.io/tier2` pin. +2. The pin protects the snapshot from being removed by retention policy + enforcement, even if it would otherwise be eligible for deletion. +3. After the snapshot is successfully migrated to Tier 2, Klio removes the + pin, allowing normal retention policy management to resume. + +This ensures data integrity during the asynchronous migration process and +guarantees that no backup is lost due to retention policies running before +migration completes. + +### Restoring from Tier 2 + +When a backup is requested for restore, Klio will first look for it in Tier 1. +If the backup is not found in Tier 1, Klio will automatically check Tier 2. +This fallback mechanism ensures that backups that have been migrated to Tier 2 +are still accessible for restore operations. + +When Tier 2 is enabled and a backup exists in both tiers, Tier 1 takes +precedence as restore from it will be faster. + +### Read-Only Server Mode + +The Klio server supports **read-only mode** (`mode: read-only`), which serves +backups and WAL files from Tier 2 object storage without accepting write +operations. This mode is designed for disaster recovery scenarios where you +need restore capabilities without the cost of local storage or the risk of +accepting new backups. + +Read-only servers are particularly useful for CloudNativePG +[Replica Clusters](https://cloudnative-pg.io/docs/current/replica_cluster/) in +secondary regions or datacenters. Multiple read-only servers can restore from +a single S3 bucket populated by one primary server. + +In read-only mode, all read and restore operations from Tier 2 function +normally, while write operations (backup creation, WAL streaming, retention +policies) are rejected. + +See the [Configuring Read-Only Mode](klio_server.mdx#read-only-mode) +section for configuration examples. + +* * * + +## Planning Your Backup Strategy + +When planning your backup strategy with Klio, **Tier 1 is the most critical +layer** to define architecturally. You have several options, ranging from +running Klio servers on any worker node using your cluster's primary storage +solution, to dedicating a single worker node with local storage for a +centralized Klio server. + +**Tier 0** capabilities are determined by the underlying Kubernetes +`StorageClass`. Klio is particularly valuable when using local storage +solutions (such as LVM with TopoLVM or OpenEBS), as it can **offload** volume +snapshot backups to Tier 1, freeing up high-performance local disk space via +retention policies. + +**Tier 2** is often determined by your organization's infrastructure teams, who +have likely already selected one or more standard object storage solutions for +long-term archival. diff --git a/product_docs/docs/klio/0/backup_and_restore.mdx b/product_docs/docs/klio/0/backup_and_restore.mdx new file mode 100644 index 00000000000..493260b187c --- /dev/null +++ b/product_docs/docs/klio/0/backup_and_restore.mdx @@ -0,0 +1,310 @@ +--- +title: Backup and Restore +originalFilePath: >- + https://github.com/EnterpriseDB/klio/blob/main/documentation/web/versioned_docs/version-0.0.15/user/backup_and_restore.md +sidebar_position: 7 + +--- + +This guide explains how to take backups of PostgreSQL clusters managed by +CloudNativePG and restore them using Klio. + +## Overview + +Klio follows PostgreSQL's native physical backup and recovery mechanisms, +leveraging CloudNativePG's backup and restore capabilities through its +[`Backup` resource](https://cloudnative-pg.io/documentation/current/cloudnative-pg.v1/#postgresql-cnpg-io-v1-Backup) +and +[`ScheduledBackup` resource](https://cloudnative-pg.io/documentation/current/cloudnative-pg.v1/#postgresql-cnpg-io-v1-ScheduledBackup). + +A working **online backup** is composed of: + +- A **physical base backup**: A filesystem copy of the PostgreSQL data directory. +- A set of **WAL (Write-Ahead Log) files**: Continuous logs of all changes made + to the database during the entire period of the base backup. + +!!!important + +It is recommended to periodically test backup restores to ensure correct +recovery procedures. +!!! + +## Prerequisites + +Before performing backup and restore operations, ensure you have: + +- A running [Klio server](klio_server.mdx) with proper configuration +- A PostgreSQL cluster configured with the [Klio plugin](plugin_configuration.mdx) + +## Taking a Backup + +With the Klio plugin configured, you can take on-demand backups using +CloudNativePG's [`Backup` resource](https://cloudnative-pg.io/documentation/current/cloudnative-pg.v1/#postgresql-cnpg-io-v1-Backup) +or the [Kubectl plugin](https://cloudnative-pg.io/documentation/current/kubectl-plugin/#requesting-a-new-physical-backup) +for CNPG. + +### Create a Backup + +You can trigger a new backup by creating a `Backup` resource. + +```yaml +apiVersion: postgresql.cnpg.io/v1 +kind: Backup +metadata: + name: my-cluster-backup-20251027 + namespace: default +spec: + method: plugin + target: primary + cluster: + name: my-cluster + pluginConfiguration: + name: klio.enterprisedb.io +``` + +Apply the manifest: + +```bash +kubectl apply -f backup.yaml +``` + +Alternatively, you can request a backup directly using the + [`kubectl cnpg` plugin](https://cloudnative-pg.io/documentation/current/kubectl-plugin/#requesting-a-new-physical-backup): + +```bash +kubectl cnpg backup my-cluster \ + --method plugin \ + --plugin-name klio.enterprisedb.io \ + --backup-target primary +``` + +If you don’t specify the `--backup-name` option, the `cnpg backup` command +automatically generates one using the format `-`, +which is suitable in most cases. + +For a complete list of available options, run: + +```bash +kubectl cnpg backup --help +``` + +### Monitor Backup Progress + +Check the backup status: + +```bash +# Watch the backup status +kubectl get backup my-cluster-backup-20251027 -w + +# Get detailed backup information +kubectl describe backup my-cluster-backup-20251027 +``` + +A successful backup will show: + +``` +NAME AGE CLUSTER METHOD PHASE ERROR +my-cluster-backup-20251027 2m my-cluster plugin Completed +``` + +### Scheduled Backups + +You can schedule automatic backups using CloudNativePG's +[`ScheduledBackup` resource](https://cloudnative-pg.io/documentation/current/cloudnative-pg.v1/#postgresql-cnpg-io-v1-ScheduledBackup). + +```yaml +apiVersion: postgresql.cnpg.io/v1 +kind: ScheduledBackup +metadata: + name: my-cluster-daily-backup + namespace: default +spec: + # Cron schedule: daily at 2:00 AM + schedule: "0 0 2 * * *" + method: plugin + target: primary + cluster: + name: my-cluster + pluginConfiguration: + name: klio.enterprisedb.io +``` + +Apply the scheduled backup: + +```bash +kubectl apply -f scheduled-backup.yaml +``` + +## Backup Retention and Maintenance + +Klio automatically manages backup retention based on the +[retention policies](plugin_configuration.mdx#retention-policies) defined in the +`PluginConfiguration` referred by the `Cluster`. + +!!!important + +Deleting a `Backup` resource through `kubectl` only removes the Kubernetes +object. The actual backup data in the Klio server will be retained according to +the retention policy. +!!! + +## Finding Your backupID for Recovery + +To restore a specific backup, you need its backupID, otherwise Klio will +choose the latest one autonomously. +You can list all available, completed Backup resources using kubectl: + +```bash +kubectl get backups -n +``` + +Once you identify the backup you want to use, you can identify its backupID + +```bash +kubectl get backup -n -o jsonpath='{.status.backupId}' +``` + +## Restoring from a Backup + +Klio supports restoring PostgreSQL clusters from backups using CloudNativePG's +recovery mechanism. Unlike traditional in-place recovery, Klio follows +CloudNativePG's approach of **bootstrapping a new cluster** from a backup, +which ensures data integrity and allows for flexible recovery scenarios. + +### How Recovery Works + +Klio integrates with CloudNativePG's recovery process by performing the +following actions during a restore: + +1. **Restores the base backup**: Copies the physical backup data to the new + cluster's data directory. Uses `klio restore` command under the hood. +2. **Restores WAL files**: Klio is configured to retrieve the WAL files from + required for the PostgreSQL recovery as needed. + Uses `klio get-wal` command under the hood. + +The execution of these commands is driven by CloudNativePG's recovery +mechanism, which ensures that the PostgreSQL server starts correctly after +the restore. + +A restored cluster operates independently of the original cluster. By default, +it will **not** perform backups unless you explicitly configure the Klio plugin +for backup operations in the new cluster's specification. + +### Full Restore + +To restore from a backup, create a new `Cluster` resource with a +`bootstrap.recovery` section that references the Klio plugin: + +```yaml +apiVersion: postgresql.cnpg.io/v1 +kind: Cluster +metadata: + name: my-restored-cluster + namespace: default +spec: + instances: 3 + + # Bootstrap from a Klio backup + bootstrap: + recovery: + source: source + # OPTIONAL: Specify the backup to restore from + backupID: my-cluster-backup-YYYYMMDDHHMMSS + + # Reference the Klio plugin configuration + externalClusters: + - name: source + plugin: + name: klio.enterprisedb.io + parameters: + pluginConfigurationRef: my-restore-config + + storage: + size: 10Gi +``` + +!!!note + +Klio will choose the latest backup available in case the `backupID` field is +omitted. +!!! + +Create a corresponding `PluginConfiguration` that specifies which backup to +restore: + +```yaml +apiVersion: klio.enterprisedb.io/v1alpha1 +kind: PluginConfiguration +metadata: + name: my-restore-config + namespace: default +spec: + # Connection details + serverAddress: klio-server.default + clientSecretName: my-client-credentials + serverSecretName: klio-server-tls + + # Optional: specify the original cluster name if different + clusterName: my-cluster +``` + +The client credentials secret (`my-client-credentials`) should contain the +necessary authentication information to access the Klio server, as described +in the [Klio plugin configuration guide](plugin_configuration.mdx#client-credentials-secret). + +!!!note + +The `clusterName` field in the `PluginConfiguration` and the `commonName` +of the certificate should match the name of the **original cluster** that +was backed up, not the name of the new restored cluster. +!!! + +Apply both resources: + +```bash +kubectl apply -f restore-config.yaml +kubectl apply -f restored-cluster.yaml +``` + +### Point-in-Time Recovery (PITR) + +Klio supports Point-in-Time Recovery, allowing you to restore your database +to a specific moment in time rather than the latest available state. This is +useful for recovering from accidental data deletion or corruption. + +The process involves specifying a recovery target in the `Cluster` resource. +The available recovery targets are described in the +[CloudNativePG documentation](https://cloudnative-pg.io/documentation/current/recovery/#recovery-targets). + +#### Example: recover to a `targetTime` + +Restore to a specific timestamp: + +```yaml +apiVersion: postgresql.cnpg.io/v1 +kind: Cluster +metadata: + name: my-pitr-cluster +spec: + bootstrap: + recovery: + source: source + # Recover to a specific point in time + recoveryTarget: + targetTime: "2025-11-06 15:00:00.0000+00" + # other cluster spec fields... +``` + +!!!important + +The target of a point in time recovery must fall between the time the base +backup was completed and the time of the latest transaction recorded in the +available WAL files. +!!! + +!!!note + +During the Point in Time Recovery, if `targetTime` or `targetLSN` are specified, +Klio will automatically choose the closest backup for the PITR, if not defined +with the `backupID` field. +!!! diff --git a/product_docs/docs/klio/0/cli/index.mdx b/product_docs/docs/klio/0/cli/index.mdx new file mode 100644 index 00000000000..0348cf5d66a --- /dev/null +++ b/product_docs/docs/klio/0/cli/index.mdx @@ -0,0 +1,32 @@ +--- +title: CLI Reference +navigation: + - klio_admin_delete-backup + - klio_admin_list-backups + - klio_admin_queue-status + - klio_admin_refresh + - klio_admin + - klio_backup_delete + - klio_backup_get-metadata + - klio_backup_list + - klio_backup_maintenance + - klio_backup_run + - klio_backup_verify + - klio_backup + - klio_get-metadata + - klio_get-wal + - klio_reset-lsn + - klio_restore + - klio_retention_get + - klio_retention_set + - klio_retention + - klio_send-wal + - klio_server_start + - klio_server + - klio_wal-player_generate + - klio_wal-player_play + - klio_wal-player + - klio +indexCards: extra +--- + diff --git a/product_docs/docs/klio/0/cli/klio.mdx b/product_docs/docs/klio/0/cli/klio.mdx new file mode 100644 index 00000000000..8eb446c2821 --- /dev/null +++ b/product_docs/docs/klio/0/cli/klio.mdx @@ -0,0 +1,40 @@ +--- +title: klio +originalFilePath: >- + https://github.com/EnterpriseDB/klio/blob/main/documentation/web/versioned_docs/version-0.0.15/user/cli/klio.md + +--- + +Klio is a Cloud Native Backup & Recovery solution + +### Options + +``` + --config string config file (default is $HOME/.klio.yaml) + --debug enable debug logging + -h, --help help for klio + --log-destination string where the log stream will be written + --log-field-level string JSON log field to report severity in (default: level) + --log-field-timestamp string JSON log field to report timestamp in (default: ts) + --log-level string the desired log level, one of error, info, debug and trace (default "info") + --pprof-server string enable the PPROF server using the specified address + -t, --toggle Help message for toggle + --zap-devel Development Mode defaults(encoder=consoleEncoder,logLevel=Debug,stackTraceLevel=Warn). Production Mode defaults(encoder=jsonEncoder,logLevel=Info,stackTraceLevel=Error) + --zap-encoder encoder Zap log encoding (one of 'json' or 'console') + --zap-log-level level Zap Level to configure the verbosity of logging. Can be one of 'debug', 'info', 'error', 'panic' or any integer value > 0 which corresponds to custom debug levels of increasing verbosity + --zap-stacktrace-level level Zap Level at and above which stacktraces are captured (one of 'info', 'error', 'panic'). + --zap-time-encoding time-encoding Zap time encoding (one of 'epoch', 'millis', 'nano', 'iso8601', 'rfc3339' or 'rfc3339nano'). Defaults to 'epoch'. +``` + +### SEE ALSO + +- [klio admin](klio_admin.mdx) - Server administration commands +- [klio backup](klio_backup.mdx) - Manage physical backups +- [klio get-metadata](klio_get-metadata.mdx) - Get the metadata of a cluster from the target Klio server +- [klio get-wal](klio_get-wal.mdx) - Get a WAL from the target Klio server +- [klio reset-lsn](klio_reset-lsn.mdx) - Reset the replication status to the latest flush LSN +- [klio restore](klio_restore.mdx) - Restore a PostgreSQL cluster from a Klio server +- [klio retention](klio_retention.mdx) - Manage the retention policy +- [klio send-wal](klio_send-wal.mdx) - Upload the cluster's WALs to the target Klio server +- [klio server](klio_server.mdx) - Starts and manage a Klio server +- [klio wal-player](klio_wal-player.mdx) - WAL Player Commands diff --git a/product_docs/docs/klio/0/cli/klio_admin.mdx b/product_docs/docs/klio/0/cli/klio_admin.mdx new file mode 100644 index 00000000000..8db3d397662 --- /dev/null +++ b/product_docs/docs/klio/0/cli/klio_admin.mdx @@ -0,0 +1,39 @@ +--- +title: klio admin +originalFilePath: >- + https://github.com/EnterpriseDB/klio/blob/main/documentation/web/versioned_docs/version-0.0.15/user/cli/klio_admin.md + +--- + +Server administration commands + +### Options + +``` + -h, --help help for admin +``` + +### Options inherited from parent commands + +``` + --config string config file (default is $HOME/.klio.yaml) + --debug enable debug logging + --log-destination string where the log stream will be written + --log-field-level string JSON log field to report severity in (default: level) + --log-field-timestamp string JSON log field to report timestamp in (default: ts) + --log-level string the desired log level, one of error, info, debug and trace (default "info") + --pprof-server string enable the PPROF server using the specified address + --zap-devel Development Mode defaults(encoder=consoleEncoder,logLevel=Debug,stackTraceLevel=Warn). Production Mode defaults(encoder=jsonEncoder,logLevel=Info,stackTraceLevel=Error) + --zap-encoder encoder Zap log encoding (one of 'json' or 'console') + --zap-log-level level Zap Level to configure the verbosity of logging. Can be one of 'debug', 'info', 'error', 'panic' or any integer value > 0 which corresponds to custom debug levels of increasing verbosity + --zap-stacktrace-level level Zap Level at and above which stacktraces are captured (one of 'info', 'error', 'panic'). + --zap-time-encoding time-encoding Zap time encoding (one of 'epoch', 'millis', 'nano', 'iso8601', 'rfc3339' or 'rfc3339nano'). Defaults to 'epoch'. +``` + +### SEE ALSO + +- [klio](klio.mdx) - Klio is a Cloud Native Backup & Recovery solution +- [klio admin delete-backup](klio_admin_delete-backup.mdx) - Delete a backup from the Klio server +- [klio admin list-backups](klio_admin_list-backups.mdx) - List the backups available in the Klio server +- [klio admin queue-status](klio_admin_queue-status.mdx) - Show the status of the task queue (pending backups and pending WALs) +- [klio admin refresh](klio_admin_refresh.mdx) - Refresh the Kopia cache and policies diff --git a/product_docs/docs/klio/0/cli/klio_admin_delete-backup.mdx b/product_docs/docs/klio/0/cli/klio_admin_delete-backup.mdx new file mode 100644 index 00000000000..20633dbd042 --- /dev/null +++ b/product_docs/docs/klio/0/cli/klio_admin_delete-backup.mdx @@ -0,0 +1,43 @@ +--- +title: klio admin delete-backup +originalFilePath: >- + https://github.com/EnterpriseDB/klio/blob/main/documentation/web/versioned_docs/version-0.0.15/user/cli/klio_admin_delete-backup.md + +--- + +Delete a backup from the Klio server + +``` +klio admin delete-backup [backupName] [flags] +``` + +### Options + +``` + --cluster string The name of the cluster that owns the backup + -h, --help help for delete-backup + --socketPath string Unix socket used by the administration server (default "/tmp/.klio-admin") + --tier1 Delete the backup from tier1 (local cache) + --tier2 Delete the backup from tier2 (object storage) +``` + +### Options inherited from parent commands + +``` + --config string config file (default is $HOME/.klio.yaml) + --debug enable debug logging + --log-destination string where the log stream will be written + --log-field-level string JSON log field to report severity in (default: level) + --log-field-timestamp string JSON log field to report timestamp in (default: ts) + --log-level string the desired log level, one of error, info, debug and trace (default "info") + --pprof-server string enable the PPROF server using the specified address + --zap-devel Development Mode defaults(encoder=consoleEncoder,logLevel=Debug,stackTraceLevel=Warn). Production Mode defaults(encoder=jsonEncoder,logLevel=Info,stackTraceLevel=Error) + --zap-encoder encoder Zap log encoding (one of 'json' or 'console') + --zap-log-level level Zap Level to configure the verbosity of logging. Can be one of 'debug', 'info', 'error', 'panic' or any integer value > 0 which corresponds to custom debug levels of increasing verbosity + --zap-stacktrace-level level Zap Level at and above which stacktraces are captured (one of 'info', 'error', 'panic'). + --zap-time-encoding time-encoding Zap time encoding (one of 'epoch', 'millis', 'nano', 'iso8601', 'rfc3339' or 'rfc3339nano'). Defaults to 'epoch'. +``` + +### SEE ALSO + +- [klio admin](klio_admin.mdx) - Server administration commands diff --git a/product_docs/docs/klio/0/cli/klio_admin_list-backups.mdx b/product_docs/docs/klio/0/cli/klio_admin_list-backups.mdx new file mode 100644 index 00000000000..1dab105dc86 --- /dev/null +++ b/product_docs/docs/klio/0/cli/klio_admin_list-backups.mdx @@ -0,0 +1,40 @@ +--- +title: klio admin list-backups +originalFilePath: >- + https://github.com/EnterpriseDB/klio/blob/main/documentation/web/versioned_docs/version-0.0.15/user/cli/klio_admin_list-backups.md + +--- + +List the backups available in the Klio server + +``` +klio admin list-backups [flags] +``` + +### Options + +``` + -h, --help help for list-backups + --socketPath string Unix socket used by the administration server (default "/tmp/.klio-admin") +``` + +### Options inherited from parent commands + +``` + --config string config file (default is $HOME/.klio.yaml) + --debug enable debug logging + --log-destination string where the log stream will be written + --log-field-level string JSON log field to report severity in (default: level) + --log-field-timestamp string JSON log field to report timestamp in (default: ts) + --log-level string the desired log level, one of error, info, debug and trace (default "info") + --pprof-server string enable the PPROF server using the specified address + --zap-devel Development Mode defaults(encoder=consoleEncoder,logLevel=Debug,stackTraceLevel=Warn). Production Mode defaults(encoder=jsonEncoder,logLevel=Info,stackTraceLevel=Error) + --zap-encoder encoder Zap log encoding (one of 'json' or 'console') + --zap-log-level level Zap Level to configure the verbosity of logging. Can be one of 'debug', 'info', 'error', 'panic' or any integer value > 0 which corresponds to custom debug levels of increasing verbosity + --zap-stacktrace-level level Zap Level at and above which stacktraces are captured (one of 'info', 'error', 'panic'). + --zap-time-encoding time-encoding Zap time encoding (one of 'epoch', 'millis', 'nano', 'iso8601', 'rfc3339' or 'rfc3339nano'). Defaults to 'epoch'. +``` + +### SEE ALSO + +- [klio admin](klio_admin.mdx) - Server administration commands diff --git a/product_docs/docs/klio/0/cli/klio_admin_queue-status.mdx b/product_docs/docs/klio/0/cli/klio_admin_queue-status.mdx new file mode 100644 index 00000000000..f3bc08ccec7 --- /dev/null +++ b/product_docs/docs/klio/0/cli/klio_admin_queue-status.mdx @@ -0,0 +1,41 @@ +--- +title: klio admin queue-status +originalFilePath: >- + https://github.com/EnterpriseDB/klio/blob/main/documentation/web/versioned_docs/version-0.0.15/user/cli/klio_admin_queue-status.md + +--- + +Show the status of the task queue (pending backups and pending WALs) + +``` +klio admin queue-status [flags] +``` + +### Options + +``` + -h, --help help for queue-status + --json Output in JSON format + --socketPath string Unix socket used by the administration server (default "/tmp/.klio-admin") +``` + +### Options inherited from parent commands + +``` + --config string config file (default is $HOME/.klio.yaml) + --debug enable debug logging + --log-destination string where the log stream will be written + --log-field-level string JSON log field to report severity in (default: level) + --log-field-timestamp string JSON log field to report timestamp in (default: ts) + --log-level string the desired log level, one of error, info, debug and trace (default "info") + --pprof-server string enable the PPROF server using the specified address + --zap-devel Development Mode defaults(encoder=consoleEncoder,logLevel=Debug,stackTraceLevel=Warn). Production Mode defaults(encoder=jsonEncoder,logLevel=Info,stackTraceLevel=Error) + --zap-encoder encoder Zap log encoding (one of 'json' or 'console') + --zap-log-level level Zap Level to configure the verbosity of logging. Can be one of 'debug', 'info', 'error', 'panic' or any integer value > 0 which corresponds to custom debug levels of increasing verbosity + --zap-stacktrace-level level Zap Level at and above which stacktraces are captured (one of 'info', 'error', 'panic'). + --zap-time-encoding time-encoding Zap time encoding (one of 'epoch', 'millis', 'nano', 'iso8601', 'rfc3339' or 'rfc3339nano'). Defaults to 'epoch'. +``` + +### SEE ALSO + +- [klio admin](klio_admin.mdx) - Server administration commands diff --git a/product_docs/docs/klio/0/cli/klio_admin_refresh.mdx b/product_docs/docs/klio/0/cli/klio_admin_refresh.mdx new file mode 100644 index 00000000000..cdf1a9e3d16 --- /dev/null +++ b/product_docs/docs/klio/0/cli/klio_admin_refresh.mdx @@ -0,0 +1,40 @@ +--- +title: klio admin refresh +originalFilePath: >- + https://github.com/EnterpriseDB/klio/blob/main/documentation/web/versioned_docs/version-0.0.15/user/cli/klio_admin_refresh.md + +--- + +Refresh the Kopia cache and policies + +``` +klio admin refresh [flags] +``` + +### Options + +``` + -h, --help help for refresh + --socketPath string Unix socket used by the administration server (default "/tmp/.klio-admin") +``` + +### Options inherited from parent commands + +``` + --config string config file (default is $HOME/.klio.yaml) + --debug enable debug logging + --log-destination string where the log stream will be written + --log-field-level string JSON log field to report severity in (default: level) + --log-field-timestamp string JSON log field to report timestamp in (default: ts) + --log-level string the desired log level, one of error, info, debug and trace (default "info") + --pprof-server string enable the PPROF server using the specified address + --zap-devel Development Mode defaults(encoder=consoleEncoder,logLevel=Debug,stackTraceLevel=Warn). Production Mode defaults(encoder=jsonEncoder,logLevel=Info,stackTraceLevel=Error) + --zap-encoder encoder Zap log encoding (one of 'json' or 'console') + --zap-log-level level Zap Level to configure the verbosity of logging. Can be one of 'debug', 'info', 'error', 'panic' or any integer value > 0 which corresponds to custom debug levels of increasing verbosity + --zap-stacktrace-level level Zap Level at and above which stacktraces are captured (one of 'info', 'error', 'panic'). + --zap-time-encoding time-encoding Zap time encoding (one of 'epoch', 'millis', 'nano', 'iso8601', 'rfc3339' or 'rfc3339nano'). Defaults to 'epoch'. +``` + +### SEE ALSO + +- [klio admin](klio_admin.mdx) - Server administration commands diff --git a/product_docs/docs/klio/0/cli/klio_backup.mdx b/product_docs/docs/klio/0/cli/klio_backup.mdx new file mode 100644 index 00000000000..38b2a654fd2 --- /dev/null +++ b/product_docs/docs/klio/0/cli/klio_backup.mdx @@ -0,0 +1,41 @@ +--- +title: klio backup +originalFilePath: >- + https://github.com/EnterpriseDB/klio/blob/main/documentation/web/versioned_docs/version-0.0.15/user/cli/klio_backup.md + +--- + +Manage physical backups + +### Options + +``` + -h, --help help for backup +``` + +### Options inherited from parent commands + +``` + --config string config file (default is $HOME/.klio.yaml) + --debug enable debug logging + --log-destination string where the log stream will be written + --log-field-level string JSON log field to report severity in (default: level) + --log-field-timestamp string JSON log field to report timestamp in (default: ts) + --log-level string the desired log level, one of error, info, debug and trace (default "info") + --pprof-server string enable the PPROF server using the specified address + --zap-devel Development Mode defaults(encoder=consoleEncoder,logLevel=Debug,stackTraceLevel=Warn). Production Mode defaults(encoder=jsonEncoder,logLevel=Info,stackTraceLevel=Error) + --zap-encoder encoder Zap log encoding (one of 'json' or 'console') + --zap-log-level level Zap Level to configure the verbosity of logging. Can be one of 'debug', 'info', 'error', 'panic' or any integer value > 0 which corresponds to custom debug levels of increasing verbosity + --zap-stacktrace-level level Zap Level at and above which stacktraces are captured (one of 'info', 'error', 'panic'). + --zap-time-encoding time-encoding Zap time encoding (one of 'epoch', 'millis', 'nano', 'iso8601', 'rfc3339' or 'rfc3339nano'). Defaults to 'epoch'. +``` + +### SEE ALSO + +- [klio](klio.mdx) - Klio is a Cloud Native Backup & Recovery solution +- [klio backup delete](klio_backup_delete.mdx) - Deletes the metadata with the provided name +- [klio backup get-metadata](klio_backup_get-metadata.mdx) - Gets the metadata of the backup with the provided name +- [klio backup list](klio_backup_list.mdx) - Gets the metadata of all backups +- [klio backup maintenance](klio_backup_maintenance.mdx) - Gets the metadata of all backups +- [klio backup run](klio_backup_run.mdx) - Backup the PostgreSQL cluster to the opened Klio server +- [klio backup verify](klio_backup_verify.mdx) - Verify the integrity of backups diff --git a/product_docs/docs/klio/0/cli/klio_backup_delete.mdx b/product_docs/docs/klio/0/cli/klio_backup_delete.mdx new file mode 100644 index 00000000000..215fa061402 --- /dev/null +++ b/product_docs/docs/klio/0/cli/klio_backup_delete.mdx @@ -0,0 +1,40 @@ +--- +title: klio backup delete +originalFilePath: >- + https://github.com/EnterpriseDB/klio/blob/main/documentation/web/versioned_docs/version-0.0.15/user/cli/klio_backup_delete.md + +--- + +Deletes the metadata with the provided name + +``` +klio backup delete [backupName] [flags] +``` + +### Options + +``` + -h, --help help for delete + -n, --name string The backup name +``` + +### Options inherited from parent commands + +``` + --config string config file (default is $HOME/.klio.yaml) + --debug enable debug logging + --log-destination string where the log stream will be written + --log-field-level string JSON log field to report severity in (default: level) + --log-field-timestamp string JSON log field to report timestamp in (default: ts) + --log-level string the desired log level, one of error, info, debug and trace (default "info") + --pprof-server string enable the PPROF server using the specified address + --zap-devel Development Mode defaults(encoder=consoleEncoder,logLevel=Debug,stackTraceLevel=Warn). Production Mode defaults(encoder=jsonEncoder,logLevel=Info,stackTraceLevel=Error) + --zap-encoder encoder Zap log encoding (one of 'json' or 'console') + --zap-log-level level Zap Level to configure the verbosity of logging. Can be one of 'debug', 'info', 'error', 'panic' or any integer value > 0 which corresponds to custom debug levels of increasing verbosity + --zap-stacktrace-level level Zap Level at and above which stacktraces are captured (one of 'info', 'error', 'panic'). + --zap-time-encoding time-encoding Zap time encoding (one of 'epoch', 'millis', 'nano', 'iso8601', 'rfc3339' or 'rfc3339nano'). Defaults to 'epoch'. +``` + +### SEE ALSO + +- [klio backup](klio_backup.mdx) - Manage physical backups diff --git a/product_docs/docs/klio/0/cli/klio_backup_get-metadata.mdx b/product_docs/docs/klio/0/cli/klio_backup_get-metadata.mdx new file mode 100644 index 00000000000..7b227bb14f5 --- /dev/null +++ b/product_docs/docs/klio/0/cli/klio_backup_get-metadata.mdx @@ -0,0 +1,40 @@ +--- +title: klio backup get-metadata +originalFilePath: >- + https://github.com/EnterpriseDB/klio/blob/main/documentation/web/versioned_docs/version-0.0.15/user/cli/klio_backup_get-metadata.md + +--- + +Gets the metadata of the backup with the provided name + +``` +klio backup get-metadata [backupName] [flags] +``` + +### Options + +``` + -h, --help help for get-metadata + -n, --name string The backup name +``` + +### Options inherited from parent commands + +``` + --config string config file (default is $HOME/.klio.yaml) + --debug enable debug logging + --log-destination string where the log stream will be written + --log-field-level string JSON log field to report severity in (default: level) + --log-field-timestamp string JSON log field to report timestamp in (default: ts) + --log-level string the desired log level, one of error, info, debug and trace (default "info") + --pprof-server string enable the PPROF server using the specified address + --zap-devel Development Mode defaults(encoder=consoleEncoder,logLevel=Debug,stackTraceLevel=Warn). Production Mode defaults(encoder=jsonEncoder,logLevel=Info,stackTraceLevel=Error) + --zap-encoder encoder Zap log encoding (one of 'json' or 'console') + --zap-log-level level Zap Level to configure the verbosity of logging. Can be one of 'debug', 'info', 'error', 'panic' or any integer value > 0 which corresponds to custom debug levels of increasing verbosity + --zap-stacktrace-level level Zap Level at and above which stacktraces are captured (one of 'info', 'error', 'panic'). + --zap-time-encoding time-encoding Zap time encoding (one of 'epoch', 'millis', 'nano', 'iso8601', 'rfc3339' or 'rfc3339nano'). Defaults to 'epoch'. +``` + +### SEE ALSO + +- [klio backup](klio_backup.mdx) - Manage physical backups diff --git a/product_docs/docs/klio/0/cli/klio_backup_list.mdx b/product_docs/docs/klio/0/cli/klio_backup_list.mdx new file mode 100644 index 00000000000..c448499d685 --- /dev/null +++ b/product_docs/docs/klio/0/cli/klio_backup_list.mdx @@ -0,0 +1,39 @@ +--- +title: klio backup list +originalFilePath: >- + https://github.com/EnterpriseDB/klio/blob/main/documentation/web/versioned_docs/version-0.0.15/user/cli/klio_backup_list.md + +--- + +Gets the metadata of all backups + +``` +klio backup list [flags] +``` + +### Options + +``` + -h, --help help for list +``` + +### Options inherited from parent commands + +``` + --config string config file (default is $HOME/.klio.yaml) + --debug enable debug logging + --log-destination string where the log stream will be written + --log-field-level string JSON log field to report severity in (default: level) + --log-field-timestamp string JSON log field to report timestamp in (default: ts) + --log-level string the desired log level, one of error, info, debug and trace (default "info") + --pprof-server string enable the PPROF server using the specified address + --zap-devel Development Mode defaults(encoder=consoleEncoder,logLevel=Debug,stackTraceLevel=Warn). Production Mode defaults(encoder=jsonEncoder,logLevel=Info,stackTraceLevel=Error) + --zap-encoder encoder Zap log encoding (one of 'json' or 'console') + --zap-log-level level Zap Level to configure the verbosity of logging. Can be one of 'debug', 'info', 'error', 'panic' or any integer value > 0 which corresponds to custom debug levels of increasing verbosity + --zap-stacktrace-level level Zap Level at and above which stacktraces are captured (one of 'info', 'error', 'panic'). + --zap-time-encoding time-encoding Zap time encoding (one of 'epoch', 'millis', 'nano', 'iso8601', 'rfc3339' or 'rfc3339nano'). Defaults to 'epoch'. +``` + +### SEE ALSO + +- [klio backup](klio_backup.mdx) - Manage physical backups diff --git a/product_docs/docs/klio/0/cli/klio_backup_maintenance.mdx b/product_docs/docs/klio/0/cli/klio_backup_maintenance.mdx new file mode 100644 index 00000000000..5d5ba9adf27 --- /dev/null +++ b/product_docs/docs/klio/0/cli/klio_backup_maintenance.mdx @@ -0,0 +1,39 @@ +--- +title: klio backup maintenance +originalFilePath: >- + https://github.com/EnterpriseDB/klio/blob/main/documentation/web/versioned_docs/version-0.0.15/user/cli/klio_backup_maintenance.md + +--- + +Gets the metadata of all backups + +``` +klio backup maintenance [flags] +``` + +### Options + +``` + -h, --help help for maintenance +``` + +### Options inherited from parent commands + +``` + --config string config file (default is $HOME/.klio.yaml) + --debug enable debug logging + --log-destination string where the log stream will be written + --log-field-level string JSON log field to report severity in (default: level) + --log-field-timestamp string JSON log field to report timestamp in (default: ts) + --log-level string the desired log level, one of error, info, debug and trace (default "info") + --pprof-server string enable the PPROF server using the specified address + --zap-devel Development Mode defaults(encoder=consoleEncoder,logLevel=Debug,stackTraceLevel=Warn). Production Mode defaults(encoder=jsonEncoder,logLevel=Info,stackTraceLevel=Error) + --zap-encoder encoder Zap log encoding (one of 'json' or 'console') + --zap-log-level level Zap Level to configure the verbosity of logging. Can be one of 'debug', 'info', 'error', 'panic' or any integer value > 0 which corresponds to custom debug levels of increasing verbosity + --zap-stacktrace-level level Zap Level at and above which stacktraces are captured (one of 'info', 'error', 'panic'). + --zap-time-encoding time-encoding Zap time encoding (one of 'epoch', 'millis', 'nano', 'iso8601', 'rfc3339' or 'rfc3339nano'). Defaults to 'epoch'. +``` + +### SEE ALSO + +- [klio backup](klio_backup.mdx) - Manage physical backups diff --git a/product_docs/docs/klio/0/cli/klio_backup_run.mdx b/product_docs/docs/klio/0/cli/klio_backup_run.mdx new file mode 100644 index 00000000000..3b134e0921c --- /dev/null +++ b/product_docs/docs/klio/0/cli/klio_backup_run.mdx @@ -0,0 +1,42 @@ +--- +title: klio backup run +originalFilePath: >- + https://github.com/EnterpriseDB/klio/blob/main/documentation/web/versioned_docs/version-0.0.15/user/cli/klio_backup_run.md + +--- + +Backup the PostgreSQL cluster to the opened Klio server + +``` +klio backup run [flags] +``` + +### Options + +``` + --enable-tier2-backup When enabled, require the backup to be sent to tier2 + -h, --help help for run + -n, --name string The backup name + --wait-for-wals When enabled, wait until all the required WAL files have been archived in tier1 before declaring the backup completed. (default true) +``` + +### Options inherited from parent commands + +``` + --config string config file (default is $HOME/.klio.yaml) + --debug enable debug logging + --log-destination string where the log stream will be written + --log-field-level string JSON log field to report severity in (default: level) + --log-field-timestamp string JSON log field to report timestamp in (default: ts) + --log-level string the desired log level, one of error, info, debug and trace (default "info") + --pprof-server string enable the PPROF server using the specified address + --zap-devel Development Mode defaults(encoder=consoleEncoder,logLevel=Debug,stackTraceLevel=Warn). Production Mode defaults(encoder=jsonEncoder,logLevel=Info,stackTraceLevel=Error) + --zap-encoder encoder Zap log encoding (one of 'json' or 'console') + --zap-log-level level Zap Level to configure the verbosity of logging. Can be one of 'debug', 'info', 'error', 'panic' or any integer value > 0 which corresponds to custom debug levels of increasing verbosity + --zap-stacktrace-level level Zap Level at and above which stacktraces are captured (one of 'info', 'error', 'panic'). + --zap-time-encoding time-encoding Zap time encoding (one of 'epoch', 'millis', 'nano', 'iso8601', 'rfc3339' or 'rfc3339nano'). Defaults to 'epoch'. +``` + +### SEE ALSO + +- [klio backup](klio_backup.mdx) - Manage physical backups diff --git a/product_docs/docs/klio/0/cli/klio_backup_verify.mdx b/product_docs/docs/klio/0/cli/klio_backup_verify.mdx new file mode 100644 index 00000000000..329b9ca7588 --- /dev/null +++ b/product_docs/docs/klio/0/cli/klio_backup_verify.mdx @@ -0,0 +1,49 @@ +--- +title: klio backup verify +originalFilePath: >- + https://github.com/EnterpriseDB/klio/blob/main/documentation/web/versioned_docs/version-0.0.15/user/cli/klio_backup_verify.md + +--- + +Verify the integrity of backups + +### Synopsis + +Verify the integrity of backups in the repository. + +By default, verifies only the backup names passed as arguments. +Use --all to verify all backups in the repository. +Use --tiers to select which tiers to verify (default: both). + +``` +klio backup verify [backup-names...] [flags] +``` + +### Options + +``` + --all Verify all backups instead of specific names + -h, --help help for verify + --tiers string Tiers to verify (tier1, tier2, or tier1,tier2) (default "tier1,tier2") +``` + +### Options inherited from parent commands + +``` + --config string config file (default is $HOME/.klio.yaml) + --debug enable debug logging + --log-destination string where the log stream will be written + --log-field-level string JSON log field to report severity in (default: level) + --log-field-timestamp string JSON log field to report timestamp in (default: ts) + --log-level string the desired log level, one of error, info, debug and trace (default "info") + --pprof-server string enable the PPROF server using the specified address + --zap-devel Development Mode defaults(encoder=consoleEncoder,logLevel=Debug,stackTraceLevel=Warn). Production Mode defaults(encoder=jsonEncoder,logLevel=Info,stackTraceLevel=Error) + --zap-encoder encoder Zap log encoding (one of 'json' or 'console') + --zap-log-level level Zap Level to configure the verbosity of logging. Can be one of 'debug', 'info', 'error', 'panic' or any integer value > 0 which corresponds to custom debug levels of increasing verbosity + --zap-stacktrace-level level Zap Level at and above which stacktraces are captured (one of 'info', 'error', 'panic'). + --zap-time-encoding time-encoding Zap time encoding (one of 'epoch', 'millis', 'nano', 'iso8601', 'rfc3339' or 'rfc3339nano'). Defaults to 'epoch'. +``` + +### SEE ALSO + +- [klio backup](klio_backup.mdx) - Manage physical backups diff --git a/product_docs/docs/klio/0/cli/klio_get-metadata.mdx b/product_docs/docs/klio/0/cli/klio_get-metadata.mdx new file mode 100644 index 00000000000..7aea5033a08 --- /dev/null +++ b/product_docs/docs/klio/0/cli/klio_get-metadata.mdx @@ -0,0 +1,39 @@ +--- +title: klio get-metadata +originalFilePath: >- + https://github.com/EnterpriseDB/klio/blob/main/documentation/web/versioned_docs/version-0.0.15/user/cli/klio_get-metadata.md + +--- + +Get the metadata of a cluster from the target Klio server + +``` +klio get-metadata [flags] +``` + +### Options + +``` + -h, --help help for get-metadata +``` + +### Options inherited from parent commands + +``` + --config string config file (default is $HOME/.klio.yaml) + --debug enable debug logging + --log-destination string where the log stream will be written + --log-field-level string JSON log field to report severity in (default: level) + --log-field-timestamp string JSON log field to report timestamp in (default: ts) + --log-level string the desired log level, one of error, info, debug and trace (default "info") + --pprof-server string enable the PPROF server using the specified address + --zap-devel Development Mode defaults(encoder=consoleEncoder,logLevel=Debug,stackTraceLevel=Warn). Production Mode defaults(encoder=jsonEncoder,logLevel=Info,stackTraceLevel=Error) + --zap-encoder encoder Zap log encoding (one of 'json' or 'console') + --zap-log-level level Zap Level to configure the verbosity of logging. Can be one of 'debug', 'info', 'error', 'panic' or any integer value > 0 which corresponds to custom debug levels of increasing verbosity + --zap-stacktrace-level level Zap Level at and above which stacktraces are captured (one of 'info', 'error', 'panic'). + --zap-time-encoding time-encoding Zap time encoding (one of 'epoch', 'millis', 'nano', 'iso8601', 'rfc3339' or 'rfc3339nano'). Defaults to 'epoch'. +``` + +### SEE ALSO + +- [klio](klio.mdx) - Klio is a Cloud Native Backup & Recovery solution diff --git a/product_docs/docs/klio/0/cli/klio_get-wal.mdx b/product_docs/docs/klio/0/cli/klio_get-wal.mdx new file mode 100644 index 00000000000..85e3e7179dc --- /dev/null +++ b/product_docs/docs/klio/0/cli/klio_get-wal.mdx @@ -0,0 +1,41 @@ +--- +title: klio get-wal +originalFilePath: >- + https://github.com/EnterpriseDB/klio/blob/main/documentation/web/versioned_docs/version-0.0.15/user/cli/klio_get-wal.md + +--- + +Get a WAL from the target Klio server + +``` +klio get-wal [wal-name] [target-file] [flags] +``` + +### Options + +``` + -h, --help help for get-wal + --partial Use a partial WAL file if a the completed WAL file is not present. Defaults to false + --tier string The tier where we should look for WAL. Accepted values: 'tier1' and 'tier2' (default "tier1") +``` + +### Options inherited from parent commands + +``` + --config string config file (default is $HOME/.klio.yaml) + --debug enable debug logging + --log-destination string where the log stream will be written + --log-field-level string JSON log field to report severity in (default: level) + --log-field-timestamp string JSON log field to report timestamp in (default: ts) + --log-level string the desired log level, one of error, info, debug and trace (default "info") + --pprof-server string enable the PPROF server using the specified address + --zap-devel Development Mode defaults(encoder=consoleEncoder,logLevel=Debug,stackTraceLevel=Warn). Production Mode defaults(encoder=jsonEncoder,logLevel=Info,stackTraceLevel=Error) + --zap-encoder encoder Zap log encoding (one of 'json' or 'console') + --zap-log-level level Zap Level to configure the verbosity of logging. Can be one of 'debug', 'info', 'error', 'panic' or any integer value > 0 which corresponds to custom debug levels of increasing verbosity + --zap-stacktrace-level level Zap Level at and above which stacktraces are captured (one of 'info', 'error', 'panic'). + --zap-time-encoding time-encoding Zap time encoding (one of 'epoch', 'millis', 'nano', 'iso8601', 'rfc3339' or 'rfc3339nano'). Defaults to 'epoch'. +``` + +### SEE ALSO + +- [klio](klio.mdx) - Klio is a Cloud Native Backup & Recovery solution diff --git a/product_docs/docs/klio/0/cli/klio_reset-lsn.mdx b/product_docs/docs/klio/0/cli/klio_reset-lsn.mdx new file mode 100644 index 00000000000..62d472c52af --- /dev/null +++ b/product_docs/docs/klio/0/cli/klio_reset-lsn.mdx @@ -0,0 +1,39 @@ +--- +title: klio reset-lsn +originalFilePath: >- + https://github.com/EnterpriseDB/klio/blob/main/documentation/web/versioned_docs/version-0.0.15/user/cli/klio_reset-lsn.md + +--- + +Reset the replication status to the latest flush LSN + +``` +klio reset-lsn [flags] +``` + +### Options + +``` + -h, --help help for reset-lsn +``` + +### Options inherited from parent commands + +``` + --config string config file (default is $HOME/.klio.yaml) + --debug enable debug logging + --log-destination string where the log stream will be written + --log-field-level string JSON log field to report severity in (default: level) + --log-field-timestamp string JSON log field to report timestamp in (default: ts) + --log-level string the desired log level, one of error, info, debug and trace (default "info") + --pprof-server string enable the PPROF server using the specified address + --zap-devel Development Mode defaults(encoder=consoleEncoder,logLevel=Debug,stackTraceLevel=Warn). Production Mode defaults(encoder=jsonEncoder,logLevel=Info,stackTraceLevel=Error) + --zap-encoder encoder Zap log encoding (one of 'json' or 'console') + --zap-log-level level Zap Level to configure the verbosity of logging. Can be one of 'debug', 'info', 'error', 'panic' or any integer value > 0 which corresponds to custom debug levels of increasing verbosity + --zap-stacktrace-level level Zap Level at and above which stacktraces are captured (one of 'info', 'error', 'panic'). + --zap-time-encoding time-encoding Zap time encoding (one of 'epoch', 'millis', 'nano', 'iso8601', 'rfc3339' or 'rfc3339nano'). Defaults to 'epoch'. +``` + +### SEE ALSO + +- [klio](klio.mdx) - Klio is a Cloud Native Backup & Recovery solution diff --git a/product_docs/docs/klio/0/cli/klio_restore.mdx b/product_docs/docs/klio/0/cli/klio_restore.mdx new file mode 100644 index 00000000000..d9d4b1586c4 --- /dev/null +++ b/product_docs/docs/klio/0/cli/klio_restore.mdx @@ -0,0 +1,42 @@ +--- +title: klio restore +originalFilePath: >- + https://github.com/EnterpriseDB/klio/blob/main/documentation/web/versioned_docs/version-0.0.15/user/cli/klio_restore.md + +--- + +Restore a PostgreSQL cluster from a Klio server + +``` +klio restore [destination] [flags] +``` + +### Options + +``` + --backup-id string The ID of the backup to be restored. Defaults to the latest backup found for the cluster + -h, --help help for restore + --tablespaces strings A comma-separated list of tablespace_name:tablespace_path to customize the restore location of a tablespace. + --target-time string If specified, Klio will recover from the most recent backup that was taken before the time specified. This allows to configure PostgreSQL to do a point-in-time recovery with the specified target time. +``` + +### Options inherited from parent commands + +``` + --config string config file (default is $HOME/.klio.yaml) + --debug enable debug logging + --log-destination string where the log stream will be written + --log-field-level string JSON log field to report severity in (default: level) + --log-field-timestamp string JSON log field to report timestamp in (default: ts) + --log-level string the desired log level, one of error, info, debug and trace (default "info") + --pprof-server string enable the PPROF server using the specified address + --zap-devel Development Mode defaults(encoder=consoleEncoder,logLevel=Debug,stackTraceLevel=Warn). Production Mode defaults(encoder=jsonEncoder,logLevel=Info,stackTraceLevel=Error) + --zap-encoder encoder Zap log encoding (one of 'json' or 'console') + --zap-log-level level Zap Level to configure the verbosity of logging. Can be one of 'debug', 'info', 'error', 'panic' or any integer value > 0 which corresponds to custom debug levels of increasing verbosity + --zap-stacktrace-level level Zap Level at and above which stacktraces are captured (one of 'info', 'error', 'panic'). + --zap-time-encoding time-encoding Zap time encoding (one of 'epoch', 'millis', 'nano', 'iso8601', 'rfc3339' or 'rfc3339nano'). Defaults to 'epoch'. +``` + +### SEE ALSO + +- [klio](klio.mdx) - Klio is a Cloud Native Backup & Recovery solution diff --git a/product_docs/docs/klio/0/cli/klio_retention.mdx b/product_docs/docs/klio/0/cli/klio_retention.mdx new file mode 100644 index 00000000000..12a80938b96 --- /dev/null +++ b/product_docs/docs/klio/0/cli/klio_retention.mdx @@ -0,0 +1,37 @@ +--- +title: klio retention +originalFilePath: >- + https://github.com/EnterpriseDB/klio/blob/main/documentation/web/versioned_docs/version-0.0.15/user/cli/klio_retention.md + +--- + +Manage the retention policy + +### Options + +``` + -h, --help help for retention +``` + +### Options inherited from parent commands + +``` + --config string config file (default is $HOME/.klio.yaml) + --debug enable debug logging + --log-destination string where the log stream will be written + --log-field-level string JSON log field to report severity in (default: level) + --log-field-timestamp string JSON log field to report timestamp in (default: ts) + --log-level string the desired log level, one of error, info, debug and trace (default "info") + --pprof-server string enable the PPROF server using the specified address + --zap-devel Development Mode defaults(encoder=consoleEncoder,logLevel=Debug,stackTraceLevel=Warn). Production Mode defaults(encoder=jsonEncoder,logLevel=Info,stackTraceLevel=Error) + --zap-encoder encoder Zap log encoding (one of 'json' or 'console') + --zap-log-level level Zap Level to configure the verbosity of logging. Can be one of 'debug', 'info', 'error', 'panic' or any integer value > 0 which corresponds to custom debug levels of increasing verbosity + --zap-stacktrace-level level Zap Level at and above which stacktraces are captured (one of 'info', 'error', 'panic'). + --zap-time-encoding time-encoding Zap time encoding (one of 'epoch', 'millis', 'nano', 'iso8601', 'rfc3339' or 'rfc3339nano'). Defaults to 'epoch'. +``` + +### SEE ALSO + +- [klio](klio.mdx) - Klio is a Cloud Native Backup & Recovery solution +- [klio retention get](klio_retention_get.mdx) - Gets the currently applied retention policy +- [klio retention set](klio_retention_set.mdx) - Sets the currently applied retention policy diff --git a/product_docs/docs/klio/0/cli/klio_retention_get.mdx b/product_docs/docs/klio/0/cli/klio_retention_get.mdx new file mode 100644 index 00000000000..6db82622bab --- /dev/null +++ b/product_docs/docs/klio/0/cli/klio_retention_get.mdx @@ -0,0 +1,39 @@ +--- +title: klio retention get +originalFilePath: >- + https://github.com/EnterpriseDB/klio/blob/main/documentation/web/versioned_docs/version-0.0.15/user/cli/klio_retention_get.md + +--- + +Gets the currently applied retention policy + +``` +klio retention get [flags] +``` + +### Options + +``` + -h, --help help for get +``` + +### Options inherited from parent commands + +``` + --config string config file (default is $HOME/.klio.yaml) + --debug enable debug logging + --log-destination string where the log stream will be written + --log-field-level string JSON log field to report severity in (default: level) + --log-field-timestamp string JSON log field to report timestamp in (default: ts) + --log-level string the desired log level, one of error, info, debug and trace (default "info") + --pprof-server string enable the PPROF server using the specified address + --zap-devel Development Mode defaults(encoder=consoleEncoder,logLevel=Debug,stackTraceLevel=Warn). Production Mode defaults(encoder=jsonEncoder,logLevel=Info,stackTraceLevel=Error) + --zap-encoder encoder Zap log encoding (one of 'json' or 'console') + --zap-log-level level Zap Level to configure the verbosity of logging. Can be one of 'debug', 'info', 'error', 'panic' or any integer value > 0 which corresponds to custom debug levels of increasing verbosity + --zap-stacktrace-level level Zap Level at and above which stacktraces are captured (one of 'info', 'error', 'panic'). + --zap-time-encoding time-encoding Zap time encoding (one of 'epoch', 'millis', 'nano', 'iso8601', 'rfc3339' or 'rfc3339nano'). Defaults to 'epoch'. +``` + +### SEE ALSO + +- [klio retention](klio_retention.mdx) - Manage the retention policy diff --git a/product_docs/docs/klio/0/cli/klio_retention_set.mdx b/product_docs/docs/klio/0/cli/klio_retention_set.mdx new file mode 100644 index 00000000000..c6c57385d1b --- /dev/null +++ b/product_docs/docs/klio/0/cli/klio_retention_set.mdx @@ -0,0 +1,45 @@ +--- +title: klio retention set +originalFilePath: >- + https://github.com/EnterpriseDB/klio/blob/main/documentation/web/versioned_docs/version-0.0.15/user/cli/klio_retention_set.md + +--- + +Sets the currently applied retention policy + +``` +klio retention set [flags] +``` + +### Options + +``` + -h, --help help for set + --keep-annual int Number of most recent annual backup kept + --keep-daily int Number of most recent daily backup kept + --keep-hourly int Number of most recent hourly backup kept + --keep-latest int Number of most recent latest backup kept + --keep-monthly int Number of most recent monthly backup kept + --keep-weekly int Number of most recent weekly backup kept +``` + +### Options inherited from parent commands + +``` + --config string config file (default is $HOME/.klio.yaml) + --debug enable debug logging + --log-destination string where the log stream will be written + --log-field-level string JSON log field to report severity in (default: level) + --log-field-timestamp string JSON log field to report timestamp in (default: ts) + --log-level string the desired log level, one of error, info, debug and trace (default "info") + --pprof-server string enable the PPROF server using the specified address + --zap-devel Development Mode defaults(encoder=consoleEncoder,logLevel=Debug,stackTraceLevel=Warn). Production Mode defaults(encoder=jsonEncoder,logLevel=Info,stackTraceLevel=Error) + --zap-encoder encoder Zap log encoding (one of 'json' or 'console') + --zap-log-level level Zap Level to configure the verbosity of logging. Can be one of 'debug', 'info', 'error', 'panic' or any integer value > 0 which corresponds to custom debug levels of increasing verbosity + --zap-stacktrace-level level Zap Level at and above which stacktraces are captured (one of 'info', 'error', 'panic'). + --zap-time-encoding time-encoding Zap time encoding (one of 'epoch', 'millis', 'nano', 'iso8601', 'rfc3339' or 'rfc3339nano'). Defaults to 'epoch'. +``` + +### SEE ALSO + +- [klio retention](klio_retention.mdx) - Manage the retention policy diff --git a/product_docs/docs/klio/0/cli/klio_send-wal.mdx b/product_docs/docs/klio/0/cli/klio_send-wal.mdx new file mode 100644 index 00000000000..5f5395331cc --- /dev/null +++ b/product_docs/docs/klio/0/cli/klio_send-wal.mdx @@ -0,0 +1,40 @@ +--- +title: klio send-wal +originalFilePath: >- + https://github.com/EnterpriseDB/klio/blob/main/documentation/web/versioned_docs/version-0.0.15/user/cli/klio_send-wal.md + +--- + +Upload the cluster's WALs to the target Klio server + +``` +klio send-wal [flags] +``` + +### Options + +``` + -h, --help help for send-wal + --primary Wait for the current instance to become a primary (default true) +``` + +### Options inherited from parent commands + +``` + --config string config file (default is $HOME/.klio.yaml) + --debug enable debug logging + --log-destination string where the log stream will be written + --log-field-level string JSON log field to report severity in (default: level) + --log-field-timestamp string JSON log field to report timestamp in (default: ts) + --log-level string the desired log level, one of error, info, debug and trace (default "info") + --pprof-server string enable the PPROF server using the specified address + --zap-devel Development Mode defaults(encoder=consoleEncoder,logLevel=Debug,stackTraceLevel=Warn). Production Mode defaults(encoder=jsonEncoder,logLevel=Info,stackTraceLevel=Error) + --zap-encoder encoder Zap log encoding (one of 'json' or 'console') + --zap-log-level level Zap Level to configure the verbosity of logging. Can be one of 'debug', 'info', 'error', 'panic' or any integer value > 0 which corresponds to custom debug levels of increasing verbosity + --zap-stacktrace-level level Zap Level at and above which stacktraces are captured (one of 'info', 'error', 'panic'). + --zap-time-encoding time-encoding Zap time encoding (one of 'epoch', 'millis', 'nano', 'iso8601', 'rfc3339' or 'rfc3339nano'). Defaults to 'epoch'. +``` + +### SEE ALSO + +- [klio](klio.mdx) - Klio is a Cloud Native Backup & Recovery solution diff --git a/product_docs/docs/klio/0/cli/klio_server.mdx b/product_docs/docs/klio/0/cli/klio_server.mdx new file mode 100644 index 00000000000..9e35383dc84 --- /dev/null +++ b/product_docs/docs/klio/0/cli/klio_server.mdx @@ -0,0 +1,36 @@ +--- +title: klio server +originalFilePath: >- + https://github.com/EnterpriseDB/klio/blob/main/documentation/web/versioned_docs/version-0.0.15/user/cli/klio_server.md + +--- + +Starts and manage a Klio server + +### Options + +``` + -h, --help help for server +``` + +### Options inherited from parent commands + +``` + --config string config file (default is $HOME/.klio.yaml) + --debug enable debug logging + --log-destination string where the log stream will be written + --log-field-level string JSON log field to report severity in (default: level) + --log-field-timestamp string JSON log field to report timestamp in (default: ts) + --log-level string the desired log level, one of error, info, debug and trace (default "info") + --pprof-server string enable the PPROF server using the specified address + --zap-devel Development Mode defaults(encoder=consoleEncoder,logLevel=Debug,stackTraceLevel=Warn). Production Mode defaults(encoder=jsonEncoder,logLevel=Info,stackTraceLevel=Error) + --zap-encoder encoder Zap log encoding (one of 'json' or 'console') + --zap-log-level level Zap Level to configure the verbosity of logging. Can be one of 'debug', 'info', 'error', 'panic' or any integer value > 0 which corresponds to custom debug levels of increasing verbosity + --zap-stacktrace-level level Zap Level at and above which stacktraces are captured (one of 'info', 'error', 'panic'). + --zap-time-encoding time-encoding Zap time encoding (one of 'epoch', 'millis', 'nano', 'iso8601', 'rfc3339' or 'rfc3339nano'). Defaults to 'epoch'. +``` + +### SEE ALSO + +- [klio](klio.mdx) - Klio is a Cloud Native Backup & Recovery solution +- [klio server start](klio_server_start.mdx) - Starts a Klio server diff --git a/product_docs/docs/klio/0/cli/klio_server_start.mdx b/product_docs/docs/klio/0/cli/klio_server_start.mdx new file mode 100644 index 00000000000..db319916b97 --- /dev/null +++ b/product_docs/docs/klio/0/cli/klio_server_start.mdx @@ -0,0 +1,42 @@ +--- +title: klio server start +originalFilePath: >- + https://github.com/EnterpriseDB/klio/blob/main/documentation/web/versioned_docs/version-0.0.15/user/cli/klio_server_start.md + +--- + +Starts a Klio server + +``` +klio server start [flags] +``` + +### Options + +``` + -h, --help help for start + --socketPath string Unix socket used by the administration server (default "/tmp/.klio-admin") + --tier1 Enables Tier1 server components (default true) + --tier2 Enables Tier2 server components +``` + +### Options inherited from parent commands + +``` + --config string config file (default is $HOME/.klio.yaml) + --debug enable debug logging + --log-destination string where the log stream will be written + --log-field-level string JSON log field to report severity in (default: level) + --log-field-timestamp string JSON log field to report timestamp in (default: ts) + --log-level string the desired log level, one of error, info, debug and trace (default "info") + --pprof-server string enable the PPROF server using the specified address + --zap-devel Development Mode defaults(encoder=consoleEncoder,logLevel=Debug,stackTraceLevel=Warn). Production Mode defaults(encoder=jsonEncoder,logLevel=Info,stackTraceLevel=Error) + --zap-encoder encoder Zap log encoding (one of 'json' or 'console') + --zap-log-level level Zap Level to configure the verbosity of logging. Can be one of 'debug', 'info', 'error', 'panic' or any integer value > 0 which corresponds to custom debug levels of increasing verbosity + --zap-stacktrace-level level Zap Level at and above which stacktraces are captured (one of 'info', 'error', 'panic'). + --zap-time-encoding time-encoding Zap time encoding (one of 'epoch', 'millis', 'nano', 'iso8601', 'rfc3339' or 'rfc3339nano'). Defaults to 'epoch'. +``` + +### SEE ALSO + +- [klio server](klio_server.mdx) - Starts and manage a Klio server diff --git a/product_docs/docs/klio/0/cli/klio_wal-player.mdx b/product_docs/docs/klio/0/cli/klio_wal-player.mdx new file mode 100644 index 00000000000..37b63f2a122 --- /dev/null +++ b/product_docs/docs/klio/0/cli/klio_wal-player.mdx @@ -0,0 +1,37 @@ +--- +title: klio wal-player +originalFilePath: >- + https://github.com/EnterpriseDB/klio/blob/main/documentation/web/versioned_docs/version-0.0.15/user/cli/klio_wal-player.md + +--- + +WAL Player Commands + +### Options + +``` + -h, --help help for wal-player +``` + +### Options inherited from parent commands + +``` + --config string config file (default is $HOME/.klio.yaml) + --debug enable debug logging + --log-destination string where the log stream will be written + --log-field-level string JSON log field to report severity in (default: level) + --log-field-timestamp string JSON log field to report timestamp in (default: ts) + --log-level string the desired log level, one of error, info, debug and trace (default "info") + --pprof-server string enable the PPROF server using the specified address + --zap-devel Development Mode defaults(encoder=consoleEncoder,logLevel=Debug,stackTraceLevel=Warn). Production Mode defaults(encoder=jsonEncoder,logLevel=Info,stackTraceLevel=Error) + --zap-encoder encoder Zap log encoding (one of 'json' or 'console') + --zap-log-level level Zap Level to configure the verbosity of logging. Can be one of 'debug', 'info', 'error', 'panic' or any integer value > 0 which corresponds to custom debug levels of increasing verbosity + --zap-stacktrace-level level Zap Level at and above which stacktraces are captured (one of 'info', 'error', 'panic'). + --zap-time-encoding time-encoding Zap time encoding (one of 'epoch', 'millis', 'nano', 'iso8601', 'rfc3339' or 'rfc3339nano'). Defaults to 'epoch'. +``` + +### SEE ALSO + +- [klio](klio.mdx) - Klio is a Cloud Native Backup & Recovery solution +- [klio wal-player generate](klio_wal-player_generate.mdx) - Generate a directory of WAL files +- [klio wal-player play](klio_wal-player_play.mdx) - Send to Klio a directory of WAL files diff --git a/product_docs/docs/klio/0/cli/klio_wal-player_generate.mdx b/product_docs/docs/klio/0/cli/klio_wal-player_generate.mdx new file mode 100644 index 00000000000..4339dd4cfb3 --- /dev/null +++ b/product_docs/docs/klio/0/cli/klio_wal-player_generate.mdx @@ -0,0 +1,41 @@ +--- +title: klio wal-player generate +originalFilePath: >- + https://github.com/EnterpriseDB/klio/blob/main/documentation/web/versioned_docs/version-0.0.15/user/cli/klio_wal-player_generate.md + +--- + +Generate a directory of WAL files + +``` +klio wal-player generate [output-directory] [flags] +``` + +### Options + +``` + -h, --help help for generate + --length int How many WAL files should be generated. Required. + --wal-size int The WAL file size in MBs. Defaults to 16 MB (default 16) +``` + +### Options inherited from parent commands + +``` + --config string config file (default is $HOME/.klio.yaml) + --debug enable debug logging + --log-destination string where the log stream will be written + --log-field-level string JSON log field to report severity in (default: level) + --log-field-timestamp string JSON log field to report timestamp in (default: ts) + --log-level string the desired log level, one of error, info, debug and trace (default "info") + --pprof-server string enable the PPROF server using the specified address + --zap-devel Development Mode defaults(encoder=consoleEncoder,logLevel=Debug,stackTraceLevel=Warn). Production Mode defaults(encoder=jsonEncoder,logLevel=Info,stackTraceLevel=Error) + --zap-encoder encoder Zap log encoding (one of 'json' or 'console') + --zap-log-level level Zap Level to configure the verbosity of logging. Can be one of 'debug', 'info', 'error', 'panic' or any integer value > 0 which corresponds to custom debug levels of increasing verbosity + --zap-stacktrace-level level Zap Level at and above which stacktraces are captured (one of 'info', 'error', 'panic'). + --zap-time-encoding time-encoding Zap time encoding (one of 'epoch', 'millis', 'nano', 'iso8601', 'rfc3339' or 'rfc3339nano'). Defaults to 'epoch'. +``` + +### SEE ALSO + +- [klio wal-player](klio_wal-player.mdx) - WAL Player Commands diff --git a/product_docs/docs/klio/0/cli/klio_wal-player_play.mdx b/product_docs/docs/klio/0/cli/klio_wal-player_play.mdx new file mode 100644 index 00000000000..7fcfe171ce4 --- /dev/null +++ b/product_docs/docs/klio/0/cli/klio_wal-player_play.mdx @@ -0,0 +1,41 @@ +--- +title: klio wal-player play +originalFilePath: >- + https://github.com/EnterpriseDB/klio/blob/main/documentation/web/versioned_docs/version-0.0.15/user/cli/klio_wal-player_play.md + +--- + +Send to Klio a directory of WAL files + +``` +klio wal-player play [directory] [flags] +``` + +### Options + +``` + --block-size int Block size in KiB. Max 8192 (8 MiB). Defaults to 2048. (default 2048) + -h, --help help for play + -j, --jobs int Number of parallel jobs to use when sending WALs (default 1) +``` + +### Options inherited from parent commands + +``` + --config string config file (default is $HOME/.klio.yaml) + --debug enable debug logging + --log-destination string where the log stream will be written + --log-field-level string JSON log field to report severity in (default: level) + --log-field-timestamp string JSON log field to report timestamp in (default: ts) + --log-level string the desired log level, one of error, info, debug and trace (default "info") + --pprof-server string enable the PPROF server using the specified address + --zap-devel Development Mode defaults(encoder=consoleEncoder,logLevel=Debug,stackTraceLevel=Warn). Production Mode defaults(encoder=jsonEncoder,logLevel=Info,stackTraceLevel=Error) + --zap-encoder encoder Zap log encoding (one of 'json' or 'console') + --zap-log-level level Zap Level to configure the verbosity of logging. Can be one of 'debug', 'info', 'error', 'panic' or any integer value > 0 which corresponds to custom debug levels of increasing verbosity + --zap-stacktrace-level level Zap Level at and above which stacktraces are captured (one of 'info', 'error', 'panic'). + --zap-time-encoding time-encoding Zap time encoding (one of 'epoch', 'millis', 'nano', 'iso8601', 'rfc3339' or 'rfc3339nano'). Defaults to 'epoch'. +``` + +### SEE ALSO + +- [klio wal-player](klio_wal-player.mdx) - WAL Player Commands diff --git a/product_docs/docs/klio/0/helm_chart.mdx b/product_docs/docs/klio/0/helm_chart.mdx new file mode 100644 index 00000000000..a6d3b8ccddc --- /dev/null +++ b/product_docs/docs/klio/0/helm_chart.mdx @@ -0,0 +1,384 @@ +--- +title: EDB Klio Operator Helm Chart +navTitle: '' +originalFilePath: >- + https://github.com/EnterpriseDB/klio/blob/main/documentation/web/versioned_docs/version-0.0.15/user/helm_chart.mdx +sidebar_position: 90 + +--- + + + +import PartialValues from "./_helm_chart_values.mdx"; + + + +The EDB Klio Operator Helm chart allows you to deploy the Klio +Operator in your Kubernetes cluster. It is distributed as a private +OCI image. + +!!!important Namespace Selection + +We have used the `cnpg-system` namespace for all examples on this page. + +If you have deployed CloudNativePG in a different namespace, ensure you replace +`cnpg-system` with your specific namespace in all commands. +The Klio Operator must reside in the same namespace as the CloudNativePG +operator. +!!! + +## Prerequisites + +Before installing the Klio Operator, ensure you have: + +- **Helm** – see the [Helm installation guide](https://helm.sh/docs/intro/install/) +- **Kubernetes** cluster with appropriate permissions +- **Credentials** to access the registry hosting the Helm chart, the Klio operator + image, and the Klio operand image. +- **CloudNativePG Operator** already installed in your Kubernetes cluster. + See the [CloudNativePG installation guide](https://cloudnative-pg.io/documentation/current/installation_upgrade/). +- **cert-manager** (optional, but strongly recommended for managing TLS certificates). + See the [cert-manager installation guide](https://cert-manager.io/docs/installation/). +- **Prometheus Operator** (optional, for operator monitoring). + See the [Prometheus Operator installation guide](https://prometheus-operator.dev/docs/getting-started/installation/). + +## Installation + +### Step 1: Registry Authentication + +Authenticate with the EDB registry where the Helm chart is hosted: + +```sh +helm registry login helm.oci.cloudsmith.io -u enterprisedb/k8s -p +``` + +Replace `` with the required credentials. + +### Step 2: Create an Image Pull Secret + +Create a Kubernetes secret to allow the operator to pull container +images from the registry: + +```sh +kubectl create secret docker-registry klio-registry-secret \ + --docker-server=docker.enterprisedb.com \ + --docker-username=k8s \ + --namespace cnpg-system \ + --docker-password= +``` + +### Step 3: Create a values file + +Create a `values.yaml` file with your configuration. At minimum, set +the image pull secret created in the previous step. If you have not +installed cert-manager or the Prometheus Operator, disable them to +avoid errors during installation: + +```yaml +controllerManager: + manager: + image: + pullSecrets: + - name: klio-registry-secret + +# Uncomment if cert-manager is not installed +# certmanager: +# enable: false + +# Uncomment if the Prometheus Operator is not installed +# prometheus: +# enable: false +``` + +See the [Configuration](#configuration) section for the full list of +available parameters. You will reuse this file for future upgrades. + +### Step 4: Install the Helm Chart + +Deploy the Klio Operator to your cluster: + + + +```sh +helm install klio-operator \ + oci://helm.oci.cloudsmith.io/enterprisedb/k8s/klio-operator-chart \ + --version 0.0.15 \ + --namespace cnpg-system \ + -f values.yaml +``` + + + +### Step 5: Verify Installation + +After installation, verify that the Klio Operator is running: + +```sh +kubectl get pods -n cnpg-system -l app.kubernetes.io/name=klio +``` + +You should see the operator pod in a `Running` state. Check the logs to ensure +there are no errors: + +```sh +kubectl logs -n cnpg-system -l app.kubernetes.io/name=klio -f +``` + +Verify that the Custom Resource Definitions (CRDs) were created: + +```sh +kubectl get crds | grep klio.enterprisedb.io +``` + +You should see CRDs like `servers.klio.enterprisedb.io` and +`pluginconfigurations.klio.enterprisedb.io`. + +## Configuration + +### Inspecting the Chart + +You can download the Helm chart to inspect its contents, review the +default values, and understand what resources it will create: + + + +```sh +helm pull oci://helm.oci.cloudsmith.io/enterprisedb/k8s/klio-operator-chart \ + --version 0.0.15 \ + --untar +``` + + + +This downloads the chart and extracts it into the +`klio-operator-chart` folder, where you can review the templates, +the default `values.yaml`, and other chart files. + +### Configuration Reference + + + +### Custom CNPG API Group + +Klio targets the [CloudNativePG](https://cloudnative-pg.io/) API group +(`postgresql.cnpg.io`, version `v1`) by default. If you are running +a CNPG-based operator that uses a different API group or version (for example, +[EDB Postgres® AI for CloudNativePG™ Cluster](https://www.enterprisedb.com/docs/postgres_for_kubernetes/latest/)), +you must tell the Klio operator which group and version to use. + +Set the `--custom-cnpg-group` and `--custom-cnpg-version` flags via +the `controllerManager.manager.args` Helm value: + +```yaml +controllerManager: + manager: + args: + # … other flags … + - "--custom-cnpg-group=postgresql.k8s.enterprisedb.io" + - "--custom-cnpg-version=v1" +``` + +The operator passes these values to every Klio sidecar as the +`CUSTOM_CNPG_GROUP` and `CUSTOM_CNPG_VERSION` environment variables, +so the sidecar and the operator always use the same API group and +version. + +!!!note + +When running on CloudNativePG the defaults +(`postgresql.cnpg.io` / `v1`) are correct and you do not need +to set these flags explicitly. +!!! + +## Upgrades + +A complete upgrade consists of three steps that must be performed in +order: + +1. [Upgrade the CRDs](#upgrade-the-crds) — apply updated CRD manifests +2. [Upgrade the Operator](#upgrade-the-operator) — run `helm upgrade` +3. [Upgrade the Klio Server and client](#upgrade-the-klio-server-and-client) — upgrade operand images + +### Upgrade the CRDs + +!!!important Upgrading CRDs + +Helm does not upgrade CRDs after initial installation +([details](https://helm.sh/docs/topics/charts/#custom-resource-definitions-crds)). +When upgrading to a version that includes CRD changes, apply them +manually before running `helm upgrade` (as explained below). +!!! + +!!!warning CRD breaking changes + +If the CRDs contain breaking changes, old resource definitions may +not work. In this case, resources should be edited when +[upgrading the Klio Server and client](#upgrade-the-klio-server-and-client). +Check the [Upgrade Notes](upgrade_notes.mdx) for version-specific +instructions. +!!! + +#### Step 1: Download the new chart + +Download the new version of the Helm chart to access the updated CRD +manifests: + + + +```sh +helm pull oci://helm.oci.cloudsmith.io/enterprisedb/k8s/klio-operator-chart \ + --version 0.0.15 \ + --untar +``` + + + +#### Step 2: Review CRD changes + +Before applying, review the CRD changes to understand what is being +modified: + +```sh +kubectl diff -f klio-operator-chart/crds/ +``` + +#### Step 3: Apply the updated CRDs + +Apply the CRD manifests to your cluster: + +```sh +kubectl apply --server-side --force-conflicts -f klio-operator-chart/crds/ +``` + +#### Step 4: Clean up + +Remove the extracted chart directory: + +```sh +rm -rf klio-operator-chart +``` + +### Upgrade the Operator + +To upgrade the Klio Operator to a newer version, run the following +Helm upgrade command: + + + +```sh +helm upgrade klio-operator \ + oci://helm.oci.cloudsmith.io/enterprisedb/k8s/klio-operator-chart \ + --version 0.0.15 \ + --namespace cnpg-system \ + -f values.yaml +``` + + + +See the +[Helm upgrade documentation](https://helm.sh/docs/helm/helm_upgrade/#options) +for more details on this and other upgrade options. + +### Upgrade the Klio Server and client + +After upgrading the operator and the CRDs, Klio images in `Server` +resources and the ones used as sidecars in `Cluster` resources should +be upgraded as well. We recommend using the same version for the +operator and the operand. + +!!!info Future improvement + +We plan to reduce the amount of manual work required during upgrades in +future versions of the operator. +!!! + +#### Upgrade Klio servers + +Klio servers are not automatically updated when a new operand image is +released. Update the `spec.image` field with the new image reference: + + + +```sh +kubectl patch server -n \ + --type merge \ + -p '{"spec":{"image":"docker.enterprisedb.com/k8s/klio:v0.0.15"}}' +``` + + + +Verify that the Klio Server pods are running the latest version: + +```sh +kubectl get pods -l klio.enterprisedb.io/klio-server -A \ + -o custom-columns='NAMESPACE:.metadata.namespace,NAME:.metadata.name,IMAGE:.spec.containers[0].image' +``` + +!!!warning + +If the Klio Pod gets into a broken state before the image upgrade, a new Pod +with the image upgrade +[will not be rolled out](https://kubernetes.io/docs/concepts/workloads/controllers/statefulset/#forced-rollback). +In this case you should delete the Klio Pod. The StatefulSet managing it +will recreate it with the chosen image. +!!! + +!!!warning + +Not all parameters can be updated in a StatefulSet. In case a new version of +the operator requires such a change, delete the StatefulSet managing the Klio +Server. The operator will automatically recreate the StatefulSet. +StatefulSets [retain their PVCs by default](https://kubernetes.io/docs/concepts/workloads/controllers/statefulset/#persistentvolumeclaim-retention), +make sure your data is safe before proceeding. + +```sh +kubectl delete statefulset -l klio.enterprisedb.io/klio-server= -n +``` +!!! + +#### Upgrade Klio client sidecars + +The Pods of the CNPG instances need to be recreated to run the new Klio image. +You can use the CNPG `kubectl` plugin to trigger a rolling update: + +```sh +kubectl cnpg restart +``` + +Refer to the +[CloudNativePG documentation](https://cloudnative-pg.io/documentation/current/rolling_update/) +for guidance on performing rolling updates. + +Verify that the sidecar containers are running the latest version: + +```sh +kubectl get pods -l cnpg.io/cluster -A \ + -o jsonpath='{range .items[*]}{.metadata.namespace}{"\t"}{.metadata.name}{"\t"}{range .spec.initContainers[?(@.name=="klio-plugin")]}{.image}{end}{"\n"}{end}' +``` + +## Uninstalling + +To uninstall the Klio Operator: + +```sh +helm uninstall klio-operator --namespace cnpg-system +``` + +!!!warning Data Preservation + +Uninstalling the operator does not automatically remove: + +- Custom Resource Definitions (CRDs) +- Existing Klio resources (Servers, PluginConfigurations) +- Persistent volumes containing backup data + +To completely remove Klio from your cluster, you must manually delete these +resources. +!!! + +To remove the CRDs after uninstalling: + +```sh +kubectl delete crd servers.klio.enterprisedb.io +kubectl delete crd pluginconfigurations.klio.enterprisedb.io +``` diff --git a/product_docs/docs/klio/0/images/basebackups_walarchive.png b/product_docs/docs/klio/0/images/basebackups_walarchive.png new file mode 100644 index 00000000000..8880b8c2ba2 --- /dev/null +++ b/product_docs/docs/klio/0/images/basebackups_walarchive.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:7c4de2c6fa708c49065b625ee92375ae279077a10dc6aad07ecc178b51f291f7 +size 17516 diff --git a/product_docs/docs/klio/0/images/overview-multi-tiers.png b/product_docs/docs/klio/0/images/overview-multi-tiers.png new file mode 100644 index 00000000000..b5171be827b --- /dev/null +++ b/product_docs/docs/klio/0/images/overview-multi-tiers.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:afc1bce7c07c22ae7fc114748b522b99d5c51169b1271896539012fa8da49648 +size 73488 diff --git a/product_docs/docs/klio/0/images/tier1-namespace-multi.png b/product_docs/docs/klio/0/images/tier1-namespace-multi.png new file mode 100644 index 00000000000..c0af30615ab --- /dev/null +++ b/product_docs/docs/klio/0/images/tier1-namespace-multi.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:6921bdaf4b76a8e9b863edfc6614f5a3f6e63e155beff68006bffb6da7429591 +size 95217 diff --git a/product_docs/docs/klio/0/images/tier1-namespace-single.png b/product_docs/docs/klio/0/images/tier1-namespace-single.png new file mode 100644 index 00000000000..879f1b98c0c --- /dev/null +++ b/product_docs/docs/klio/0/images/tier1-namespace-single.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:eb6ae084132f92cec5e0ff7f15b4b5db3f957988af25b3cd224d801fd232d37a +size 38665 diff --git a/product_docs/docs/klio/0/images/tier1-shared-multi.png b/product_docs/docs/klio/0/images/tier1-shared-multi.png new file mode 100644 index 00000000000..6d83dcfc7e2 --- /dev/null +++ b/product_docs/docs/klio/0/images/tier1-shared-multi.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:8fb75f834d4c850d884ede3fba795c499407e89ff79e252051d95080c30ac8d4 +size 75090 diff --git a/product_docs/docs/klio/0/images/tier1-shared-single.png b/product_docs/docs/klio/0/images/tier1-shared-single.png new file mode 100644 index 00000000000..22106089b34 --- /dev/null +++ b/product_docs/docs/klio/0/images/tier1-shared-single.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:582b2289089c5f0d7648d28646ccd00b0ea47080031596bd040cd2de032ee4cb +size 40722 diff --git a/product_docs/docs/klio/0/images/wal-streaming.png b/product_docs/docs/klio/0/images/wal-streaming.png new file mode 100644 index 00000000000..7ba175eab27 --- /dev/null +++ b/product_docs/docs/klio/0/images/wal-streaming.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:3bc19985d9893e142755ffbc7a838ac101a9b5cbb3fe8e5e35b000c51c612f05 +size 34122 diff --git a/product_docs/docs/klio/0/index.mdx b/product_docs/docs/klio/0/index.mdx new file mode 100644 index 00000000000..8946f5876af --- /dev/null +++ b/product_docs/docs/klio/0/index.mdx @@ -0,0 +1,117 @@ +--- +title: Klio Overview +navigation: + - main_concepts + - architectures + - wal_streaming + - klio_server + - plugin_configuration + - backup_and_restore + - managing_storage + - opentelemetry + - walplayer + - helm_chart + - upgrade_notes + - api + - cli + - images + - '!_helm_chart_values' +originalFilePath: >- + https://github.com/EnterpriseDB/klio/blob/main/documentation/web/versioned_docs/version-0.0.15/user/index.mdx +directoryDefaults: + version: 0.0.15 + displayBanner: >- + This is documentation for a Tech Preview of EDB's {{name.ln}} + ({{name.short}}) solution. It is made available AS IS for testing and early + evaluation purposes ONLY! Is is not to be used in production environments. + For details, please refer to EULA + section 9.4. +sidebar_position: 1 + +--- + +**Klio** is a cloud-native solution for enterprise-grade backup and recovery of +PostgreSQL databases managed by [CloudNativePG](https://cloudnative-pg.io) on +Kubernetes. It is designed to handle: + +- The **Write-Ahead Log (WAL) archive** for a given PostgreSQL `Cluster` + resource, within the same Kubernetes namespace as the Klio deployment +- The **catalog of physical base backups** for that same cluster +- Optionally, multiple PostgreSQL clusters + +These critical backup artifacts are stored across two distinct storage tiers: + +- Tier 1 – **Local Volume**: A local Persistent Volume (PV) within the + same namespace as the associated `Cluster` resource. It offers immediate, + high-throughput access for backup and recovery operations. Also referred to as + the **Main Tier** or **Klio Server**. + +- Tier 2 – **Secondary Storage**: An external object storage system where data + from Tier 1 is asynchronously replicated. This tier typically resides outside + the Kubernetes cluster, enabling geographical redundancy and enhancing disaster + recovery (DR) resilience. + +![Multi-tiered architecture overview](images/overview-multi-tiers.png) + +* * * + +## Key Features + +!!!note + +Some of the following features are currently aspirational and under active +development. +!!! + +### WAL Management + +- Native WAL streaming from the primary, eliminating the need for + `archive_command`, with support for: + - Partial WAL file handling + - WAL file compression + - WAL file encryption using user-provided keys + - Controlled replication slot advancement to ensure uninterrupted streaming + - Synchronous replication +- WAL archive storage on a local PVC (Tier 1) +- Extension of base backup retention policy enforcement to WAL files +- Asynchronous WAL relay to Tier 2 object storage + +!!!important + +Klio's WAL management utilizes the `READ_REPLICATION_SLOT` streaming +replication command, which was introduced in PostgreSQL 15. +Therefore, Klio requires PostgreSQL version 15 or greater to function properly. +!!! + +### Base Backup Catalog + +- Physical online base backups from the primary node to Tier 1, with support + for: + - Data deduplication for efficient remote incremental backups + - Compression to optimize storage usage + - Encryption using user-provided keys for data confidentiality +- Backup catalog stored on a file system Persistent Volume Claim (PVC) in Tier 1 +- Integration with CloudNativePG Kubernetes Volume Snapshots (Tier 0), + enabling asynchronous offload to Tier 1 using the same physical backup + process[^1] +- Retention policy enforcement +- Asynchronous replication of base backups to Tier 2 object storage for + long-term durability and disaster recovery + +!!!important + +Kubernetes Volume Snapshot integration (Tier 0) is only available for storage +classes that support volume snapshots. +!!! + +### General Capabilities + +- End-to-end encryption: both in-transit and at-rest +- Designed for seamless integration with Kubernetes-native data protection + tools such as Veeam Kasten, Velero, and others[^1] +- Delivered as a CNPG-I plugin, with an accompanying Kubernetes Operator +- Available as a Certified Red Hat OpenShift Operator[^1] +- Distributed via a Helm chart for streamlined deployment + +[^1]\: Not yet available; planned for a future release. diff --git a/product_docs/docs/klio/0/klio_server.mdx b/product_docs/docs/klio/0/klio_server.mdx new file mode 100644 index 00000000000..b570e1764a6 --- /dev/null +++ b/product_docs/docs/klio/0/klio_server.mdx @@ -0,0 +1,995 @@ +--- +title: The Klio Server +originalFilePath: >- + https://github.com/EnterpriseDB/klio/blob/main/documentation/web/versioned_docs/version-0.0.15/user/klio_server.md +sidebar_position: 5 + +--- + +The Klio server is a central component of the Klio backup solution. It is +defined as the `Server` custom resource in Kubernetes, which creates a +StatefulSet running the Klio server application. + +The Klio server is composed of two main containers: + +- `base`: Manages full and incremental backups using Kopia. +- `wal`: Receives the stream of PostgreSQL Write-Ahead Logs (WAL). + +An additional init container, `init`, is responsible for initializing the +Kopia repository and setting up the necessary configuration. + +The base backups and WAL files are stored in multiple PersistentVolume attached +to the Klio server pod in the `/data/base` and `/data/wal` directories, respectively. + +An additional cache defined by a PersistentVolume is used for the Kopia cache. +This cache allows Kopia to quickly browse repository contents without +having to download from the storage location. + +## Storage Tiers + +### Tier 1: Local Storage + +Tier 1 uses local `PersistentVolumes` for immediate data access. +This is the primary landing zone for backups and WAL files, +providing the fastest recovery times. + +### Tier 2: Remote Object Storage + +Tier 2 offloads data to object storage for long-term retention and disaster +recovery. When Tier 2 is enabled alongside Tier 1, the server uses a work +queue to manage the asynchronous transfer of data from local storage to object +storage. + +Alternatively, you can deploy a **read-only server** with only Tier 2 +configured. This is useful for disaster recovery sites that need to restore +from object storage without the overhead of local storage. See the +[Read-Only Mode](#read-only-mode) section for details. + +Currently, Klio supports Amazon S3 and S3-compatible storage providers. See +the [Object Store](#object-store) section for configuration details. + +### The Work Queue + +When Tier 1 is configured, the Klio Server pods will use a work queue. +The work queue is backed by NATS JetStream with file storage on a separate +`PersistentVolume` mounted at `/queue`. +The queue serves two purposes: + +- **Retention policy enforcement**: Tracks which WAL files are in use before + deletion +- **Tier 2 replication**: When Tier 2 is enabled, manages asynchronous + transfer to object storage + +## Storage Requirements + +The Klio Server uses three distinct PersistentVolumeClaims (PVCs), each +serving a different purpose. Understanding what each PVC contains helps you +size them appropriately for your environment. For guidance on managing +storage capacity and resizing PVCs, see +[Managing Storage](managing_storage.mdx). + +### Data PVC + +The data PVC stores all backup data and WAL archives for Tier 1 storage. + +It holds the base backups and the WAL archive of all the servers that are backed +up. + +The following factors should be considered when defining the PVC size: + +1. WAL file production rate +2. Base backup size +3. Retention policies + +### Cache PVCs + +The cache PVCs (one for Tier 1 and Tier 2 each) are used by Kopia for its +[caching operations](https://kopia.io/docs/advanced/caching/). +They are used to speed up snapshot operations. + +!!!warning + +Klio is currently limited to use the default cache size when creating a Kopia +repository, 5GB for content and 5GB for metadata. +The cache sizes are not hard limits, as the cache is swept periodically, +so users should have a space buffer to account for this additional space. +This limitation will be removed in a future version. +!!! + +### Queue PVC + +The queue PVC is required when Tier 1 is configured. It stores the NATS +JetStream work queue used for retention policy enforcement and asynchronous +Tier 2 replication. + +#### Queue Sizing Guidelines + +The queue stores only task metadata (cluster name and WAL filename), not the +actual WAL content. This means queue size depends on the **number of WAL +segments** generated, not the size of your database. + +**Sizing formula:** + +``` +Queue Size = WAL_segments_per_hour × max_backlog_hours × 300 bytes × 2 +``` + +Where: + +- **WAL_segments_per_hour**: How many WAL segments your database generates per + hour (check with `pg_stat_archiver` or monitor WAL production) +- **max_backlog_hours**: Maximum duration the Tier 2 WAL replication backlog + can grow before the queue fills up and tasks are lost. Backlog builds up + when Tier 2 replication falls behind Tier 1 ingestion — for example, during + Tier 2 outages or when object storage uploads are slower than local disk writes. +- **300 bytes**: Approximate storage per WAL task (message + JetStream overhead) +- **2**: Safety factor + +**Recommended sizes:** + +| Workload | WAL Rate | Recommended Size | +| ---------------- | ------------------ | ---------------- | +| Low write (OLTP) | ~60 segments/hour | **10 MiB** | +| Medium write | ~120 segments/hour | **25 MiB** | +| High write | ~360 segments/hour | **50 MiB** | +| Very high write | >500 segments/hour | **100 MiB** | + +These recommendations assume a 24-hour backlog tolerance and include an +additional **~10x safety margin** beyond the formula result. This margin accounts +for: + +- **Burst workloads**: WAL production can spike significantly above average rates +- **Multiple clusters**: A single Klio server may handle several CNPG clusters +- **Low cost of headroom**: Storage is cheap relative to the risk of queue + overflow, which causes WAL loss + +For shorter tolerance windows, you can reduce the queue size proportionally, but +keep the safety margin. + +!!!tip + +Start with 50 MiB as a conservative default. Monitor queue usage with the +`klio admin queue-status` command and adjust based on actual WAL production +rates in your environment. +!!! + +!!!note + +Large transactions that modify significant amounts of data will automatically +generate multiple WAL segments (PostgreSQL rotates WAL files at ~16 MB by +default). Account for this when estimating your WAL segment rate. +!!! + +## Setting up a new Klio server + +Setting up a Klio server involves creating a `Server` resource along with the +required Kubernetes secrets and certificates. + +### Prerequisites + +Before setting up a Klio server, ensure you have: + +- A Kubernetes cluster with the Klio operator installed +- `kubectl` configured to access your cluster +- [cert-manager](https://cert-manager.io/) installed for certificate + management (recommended) +- [Age](https://github.com/FiloSottile/age) CLI installed locally + (for encrypting the backup encryption key) +- Enough storage resources for the data and cache PersistentVolumeClaims +- Enough storage resources for the queue PersistentVolumeClaim + +### Required Components + +A Klio server setup requires the following components: + +1. **Server Resource**: The main `Server` custom resource +2. **TLS Certificate**: For secure communication +3. **Encryption Key**: Age-encrypted key for backup data at rest +4. **CA Certificate**: For client authentication via mTLS +5. **Storage**: PersistentVolumeClaims for data, cache, and queue + +### Step-by-step setup + +#### 1. Create the Encryption Key + +The encryption key is used to encrypt backup data at rest. +Klio uses [Age](https://github.com/FiloSottile/age) encryption +to protect the key, enabling credential rotation without +touching the Kopia repository. + +See the [Age Encryption](#age-encryption) section for full +setup details. In summary: + +1. Generate an Age key pair (`age-keygen -o identity.txt`) +2. Generate and encrypt a random key + (`openssl rand -hex 32 | age -r -o key.age`) +3. Create Kubernetes Secrets for both files +4. Reference them in the Server spec + +!!!tip + +Use a strong, randomly generated key. This key is critical +for data security and recovery. +!!! + +#### 2. Create CA Certificate + +Using cert-manager, a CA certificate can be created by using the following +Certificate resource: + +```yaml +--- +apiVersion: cert-manager.io/v1 +kind: Issuer +metadata: + name: selfsigned-issuer + namespace: default +spec: + selfSigned: { } +--- +apiVersion: cert-manager.io/v1 +kind: Certificate +metadata: + name: server-sample-ca +spec: + commonName: server-sample-ca + secretName: server-sample-ca + + duration: 2160h # 90d + renewBefore: 360h # 15d + + isCA: true + usages: + - cert sign + + issuerRef: + name: selfsigned-issuer + kind: Issuer + group: cert-manager.io +``` + +Apply the CA configuration with: + +``` +kubectl apply -f ca-configuration.yaml +``` + +In the previous example, the CA to be used for authentication is signed by a +self-signed issuer. This doesn't pose any security issue as this CA is only +used internally and trust is established through configuration. + +The primary concern is the relationship between the client and the certificates +signed by the CA. + +!!!info + +The usage of a self-signed CA is not required by the Klio server. If your +PKI infrastructure already includes a CA for this scope, that CA can be used +for the Klio server, too. +!!! + +#### 3. Create TLS Certificate + +Using cert-manager, create a self-signed certificate (for development) or use +your organization's certificate issuer: + +```yaml +--- +apiVersion: cert-manager.io/v1 +kind: Issuer +metadata: + name: selfsigned-issuer + namespace: default +spec: + selfSigned: { } +--- +apiVersion: cert-manager.io/v1 +kind: Certificate +metadata: + name: my-server-cert + namespace: default +spec: + secretName: my-server-tls + commonName: my-server + dnsNames: + - my-server + - my-server.default + - my-server.default.svc + - my-server.default.svc.cluster.local + duration: 2160h # 90 days + renewBefore: 360h # 15 days + isCA: false + usages: + - server auth + issuerRef: + name: selfsigned-issuer + kind: Issuer + group: cert-manager.io +``` + +Apply the certificate configuration: + +```bash +kubectl apply -f tls-certificate.yaml +``` + +!!!info + +For production environments, use certificates signed by your organization's +Certificate Authority (CA) or a trusted public CA instead of self-signed +certificates. +!!! + +#### 4. Create the Server Resource + +Now create the main `Server` resource: + + + +```yaml +apiVersion: klio.enterprisedb.io/v1alpha1 +kind: Server +metadata: + name: my-server + namespace: default +spec: + # Container image for the Klio server + image: docker.enterprisedb.com/k8s/klio:v0.0.15 + imagePullPolicy: IfNotPresent + imagePullSecrets: [] # Add image pull secrets if needed + + # TLS configuration + tlsSecretName: my-server-tls + + # Client authentication configuration + caSecretName: server-sample-ca + + # Mode: standard (default) or read-only + # Omit this field or set to "standard" for normal read-write operation + # Set to "read-only" for DR/restore-only servers (see Read-Only Mode section) + # mode: standard + + # tier 1 configuration + tier1: + # Cache storage configuration + cache: + pvcTemplate: + storageClassName: standard # Adjust to your storage class (use 'kubectl get storageclass' to see available options) + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 10Gi # Adjust based on your needs + # Data storage pvcTemplate (for backups and WAL) + data: + pvcTemplate: + storageClassName: standard # Adjust to your storage class (use 'kubectl get storageclass' to see available options) + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 100Gi # Adjust based on your backup needs + # Age-encrypted encryption key file + encryptionKeyFile: + fileReference: + volume: + secret: + secretName: my-server-encryption-key + path: encryption-key.age + # Age identity file for decryption + identityFile: + fileReference: + volume: + secret: + secretName: my-server-age-identity + path: identity.txt + + # Queue storage configuration (for NATS work queue) + # Required when tier1 is configured + # See "Queue Sizing Guidelines" section for recommendations + queue: + pvcTemplate: + storageClassName: standard # Adjust to your storage class + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 50Mi # See Queue Sizing Guidelines; 50Mi suits most workloads + + # tier 2 configuration + tier2: + # Cache storage configuration + cache: + pvcTemplate: + resources: + requests: + storage: 1Gi + accessModes: + - ReadWriteOnce + # Age-encrypted encryption key file + encryptionKeyFile: + fileReference: + volume: + secret: + secretName: my-server-encryption-key + path: encryption-key.age + # Age identity file for decryption + identityFile: + fileReference: + volume: + secret: + secretName: my-server-age-identity + path: identity.txt + # S3 access configuration + s3: + prefix: klio + bucketName: klio-bucket + endpoint: https://rustfs:9000 + region: us-east-1 + accessKeyId: + name: rustfs + key: RUSTFS_ACCESS_KEY + secretAccessKey: + name: rustfs + key: RUSTFS_SECRET_KEY + customCaBundle: + name: rustfs-tls + key: tls.crt +``` + + + +The example above uses credential-based S3 authentication. For alternative +authentication methods (IAM roles, IRSA, Pod Identity) and S3-compatible +storage providers, see the [Object Store](#object-store) section. + +Apply the Server resource: + +```bash +kubectl apply -f klio-server.yaml +``` + +#### 5. Verify the Server is Running + +Check the status of your Klio server: + +```bash +# Check the Server resource status +kubectl get server my-server -n default + +# Check the StatefulSet +kubectl get statefulset my-server-klio -n default + +# Check the Pod +kubectl get pods -l klio.enterprisedb.io/klio-server=my-server -n default + +# View logs +kubectl logs -l klio.enterprisedb.io/klio-server=my-server -n default -f +``` + +The server should create a StatefulSet with a pod named `my-server-klio-0`. + +## Read-Only Mode + +Klio servers can operate in read-only mode, allowing them to serve backups and +WAL files from Tier 2 object storage without accepting new backup writes. This +is useful for disaster recovery sites, cost-optimized restore-only deployments, +and multi-region architectures. + +### When to Use Read-Only Mode + +Use read-only mode when you need: + +- **Disaster recovery sites**: Deploy in secondary regions to restore from + shared S3 storage without duplicating backup writes +- **Geographic distribution**: Multiple read-only servers in different regions + can all restore from a single S3 bucket populated by one primary server +- **Read-only access control**: Prevent accidental backup modifications at + certain sites + +### Configuration + +A read-only server requires: + +- `mode: read-only` field in the spec +- `tier2` configuration (S3 object storage) +- **No** `tier1` configuration +- **No** `queue` configuration + + + +```yaml +apiVersion: klio.enterprisedb.io/v1alpha1 +kind: Server +metadata: + name: dr-server + namespace: default +spec: + # Set mode to read-only + mode: read-only + + # Container image for the Klio server + image: docker.enterprisedb.com/k8s/klio:v0.0.15 + imagePullPolicy: IfNotPresent + + # TLS configuration + tlsSecretName: dr-server-tls + + # Client authentication configuration + caSecretName: server-sample-ca + + # Tier 2 configuration (required for read-only mode) + tier2: + # Cache storage configuration + cache: + pvcTemplate: + storageClassName: standard + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 10Gi # Only cache needed, no data storage + + # Age-encrypted encryption key file + encryptionKeyFile: + fileReference: + volume: + secret: + secretName: dr-server-encryption-key + path: encryption-key.age + # Age identity file for decryption + identityFile: + fileReference: + volume: + secret: + secretName: dr-server-age-identity + path: identity.txt + + # S3 access configuration + # See Object Store section for authentication options + s3: + bucketName: klio-backups + region: us-east-1 + accessKeyId: + name: s3-credentials + key: ACCESS_KEY_ID + secretAccessKey: + name: s3-credentials + key: SECRET_ACCESS_KEY +``` + + + +Apply the read-only server: + +```bash +kubectl apply -f dr-server.yaml +``` + +### Using a Read-Only Server for Recovery + +Once deployed, PostgreSQL clusters can use the read-only server as a restore +source through a PluginConfiguration. The server will fetch backups and WAL +files from Tier 2 object storage transparently. + +See the Read-Only Server Mode section in the +[Architectures](architectures.mdx) documentation for detailed use cases and +architectural patterns. + +### Restrictions + +In read-only mode, the following operations are **not available**: + +- Creating new backups +- Sending WAL files to the server +- Applying retention policies +- Any write operations + +## Advanced Configuration + +The `.spec.template` field allows you to customize the Klio server's pod +template. You can add additional containers, volumes, or modify existing +settings. + +!!!warning Advanced Users Only + +The `.spec.template` field is primarily designed for advanced configurations. +While powerful, improper modifications can affect server functionality. +Always test changes in a non-production environment first. +!!! + +!!!note + +The `containers` field within `.spec.template.spec` is mandatory but will be +merged with the default Klio server containers `base` and `wal`. If you do not +need to add containers or modify the default ones, you must still include an +empty list. +!!! + +### Node Affinity and Tolerations + +To dedicate specific nodes for Klio workloads (e.g., for performance isolation +or to separate backup workloads from application workloads), you can use the +`template` field to define affinity and toleration rules. + +```yaml +spec: + template: + spec: + # Mandatory field; merged with default containers + containers: [] + tolerations: + # Allow scheduling on nodes tainted for Klio + - key: node-role.kubernetes.io/klio + operator: Exists + effect: NoSchedule + affinity: + # Require nodes labeled for Klio + nodeAffinity: + requiredDuringSchedulingIgnoredDuringExecution: + nodeSelectorTerms: + - matchExpressions: + - key: node-role.kubernetes.io/klio + operator: Exists +``` + +See [Reserving Nodes for Klio Workloads](architectures.mdx#reserving-nodes-for-klio-workloads) +for details on node tainting. + +### Monitoring + +Refer to the [OpenTelemetry](opentelemetry.mdx#klio-server-with-opentelemetry) +documentation for setting up monitoring and telemetry for the Klio server. + +## Object Store + +Klio uses object storage for Tier 2, providing durable, cost-effective +long-term backup storage. Currently, Klio supports Amazon S3 and S3-compatible +storage providers. + +### S3 + +Tier 2 is configured using the `tier2.s3` field in the Server spec. The +configuration is the same for both AWS S3 and S3-compatible providers. + +#### Basic Configuration with Credentials + +```yaml +tier2: + s3: + bucketName: klio-backups + region: us-east-1 + accessKeyId: + name: s3-credentials + key: ACCESS_KEY_ID + secretAccessKey: + name: s3-credentials + key: SECRET_ACCESS_KEY +``` + +#### S3-Compatible Storage with Custom Endpoint + +For S3-compatible providers, add the `endpoint` field: + +```yaml +tier2: + s3: + bucketName: klio-backups + endpoint: https://minio.example.com:9000 + region: us-east-1 # May be required depending on provider + accessKeyId: + name: s3-credentials + key: ACCESS_KEY_ID + secretAccessKey: + name: s3-credentials + key: SECRET_ACCESS_KEY +``` + +#### Custom CA Certificates + +For providers using self-signed certificates or custom CAs: + +```yaml +tier2: + s3: + bucketName: klio-backups + endpoint: https://minio.example.com:9000 + customCaBundle: + name: minio-ca-cert + key: ca.crt + accessKeyId: + name: s3-credentials + key: ACCESS_KEY_ID + secretAccessKey: + name: s3-credentials + key: SECRET_ACCESS_KEY +``` + +#### AWS IAM Roles (IRSA/Pod Identity) + +For AWS EKS clusters, using +[IAM Roles for Service Accounts (IRSA)](https://docs.aws.amazon.com/eks/latest/userguide/iam-roles-for-service-accounts.html) +or [EKS Pod Identity](https://docs.aws.amazon.com/eks/latest/userguide/pod-identities.html) +is the recommended approach. This provides better security through automatic +credential rotation, reduced secret sprawl, and fine-grained IAM policies. + +To use IAM role-based authentication: + +1. Create an IAM role with appropriate S3 permissions +2. Create a Kubernetes ServiceAccount with the IAM role annotation (for IRSA) + or Pod Identity association (for Pod Identity) +3. Reference the ServiceAccount in the Server spec and omit credentials: + +```yaml +spec: + tier2: + s3: + bucketName: klio-backups + region: us-east-1 + # No accessKeyId or secretAccessKey - use IAM role + + template: + spec: + serviceAccountName: klio-s3-access + containers: [] # Mandatory but merged with defaults +``` + +The AWS SDK will automatically use the pod's IAM role credentials when +`accessKeyId` and `secretAccessKey` are omitted. + +## Encryption + +Klio implements encryption at rest for both base backups and WAL files to +ensure data security throughout the backup lifecycle. + +### Base Backups Encryption + +Base backups are encrypted by Kopia using the encryption key +decrypted from the Age-encrypted key file. Kopia handles +encryption transparently. + +The encryption key is set during repository initialization and is required +for all subsequent backup and restore operations. + +!!!warning Critical + +Store the encryption key securely. Loss of this key means permanent +loss of access to all backup data. There is no key recovery mechanism. +!!! + +### WAL Files Encryption + +WAL files are encrypted using a master key derivation system with authenticated +encryption. The encryption process works as follows: + +1. **Master Key Generation**: A 32-byte master key is derived from the encryption + key using PBKDF2 +2. **Key Enveloping**: The master key itself is encrypted using AES-256-GCM + with a password-derived encryption key to protect the key at rest +3. **Per-File Encryption**: Each WAL file is compressed and then encrypted using + the master key with authenticated encryption before being stored + +WAL files are first compressed using Snappy S2 compression, +then encrypted to ensure both space efficiency and security. + +The same encryption key used for base backups encrypts the WAL files, +ensuring a unified security model across all backup artifacts. + +### Encryption Credential Rotation + +The underlying encryption key (used by Kopia and the WAL keychain) +cannot be changed once set. However, you can rotate the Age identity +without touching the encryption key or the repository: + +1. Generate a new Age key pair +2. Re-encrypt the encryption key file with the new public key +3. Deploy the new identity file and re-encrypted key file + +This rotation only changes how the encryption key is protected, +not the key itself. See [Rotating Age Credentials](#rotating-age-credentials) +for step-by-step instructions. + +!!!tip + +Choose a strong encryption key from the start. Use a password +manager or key management system to generate and store a +cryptographically secure key (recommended: 32+ random characters). +!!! + +### Encryption in Transit + +In addition to encryption at rest, Klio protects both base backups and WAL files +during transmission using TLS (Transport Layer Security). + +All communication between a Klio client and the Klio server is secured +with TLS: + +- **Base Backup Traffic**: Kopia client connections to the base backup server + are encrypted using TLS, protecting backup data as it transfers to the Klio + server +- **WAL Streaming**: PostgreSQL instances streaming WAL files to the Klio server + use gRPC over TLS, ensuring WAL data is encrypted during transmission + +The TLS certificate is configured via the `.spec.tlsSecretName` field in the +Server resource, which references a Kubernetes secret containing the TLS +certificate and private key. This provides end-to-end encryption, ensuring that +backup data is protected both at rest and in transit. + +### Age Encryption + +[Age](https://github.com/FiloSottile/age) is a modern file +encryption tool that Klio supports for protecting the encryption +key. Instead of storing the plaintext encryption key in a +Kubernetes Secret, you encrypt it with an Age public key and +provide the corresponding Age identity (private key) to Klio. + +This enables: + +- **Credential rotation** without touching the Kopia repository + or WAL data. +- **Multiple recipients** for disaster recovery or team access. +- **Offline operations** — re-encryption can be done with the + standard `age` CLI. + +#### Setup + +1. Generate an Age key pair: + +```bash +age-keygen -o identity.txt +# Public key: age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p +``` + +2. Generate a random encryption key and encrypt it: + +```bash +openssl rand -hex 32 | age \ + -r age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p \ + -o encryption-key.age +``` + +3. Create Kubernetes Secrets for both files: + +```bash +kubectl create secret generic klio-encryption-key-age \ + --from-file=encryption-key.age +kubectl create secret generic klio-age-identity \ + --from-file=identity.txt +``` + +4. Reference them in the Server spec: + +```yaml +tier1: + encryptionKeyFile: + fileReference: + volume: + secret: + secretName: klio-encryption-key-age + path: encryption-key.age + identityFile: + fileReference: + volume: + secret: + secretName: klio-age-identity + path: identity.txt +``` + +The same configuration applies to `tier2`. + +!!!note + +Only standard Age identities (X25519 keys) are supported. +Age plugins (e.g., `age-plugin-yubikey`) are not supported +directly, but you can encrypt the key file to both a +plugin-based recipient and a standard X25519 recipient. +!!! + +#### Using External Secret Managers + +The `encryptionKeyFile` and `identityFile` fields accept any +Kubernetes `VolumeSource`, not just Secrets. This enables +integration with external secret management systems: + +```yaml +tier1: + encryptionKeyFile: + fileReference: + volume: + csi: + driver: secrets-store.csi.k8s.io + readOnly: true + volumeAttributes: + secretProviderClass: klio-aws-secrets + path: encryption-key.age +``` + +#### Rotating Age Credentials + +To rotate the Age identity without touching the encryption key +or the repository: + +1. Generate a new Age key pair: + +```bash +age-keygen -o new-identity.txt +``` + +2. Re-encrypt the key file with the new public key: + +```bash +age -d -i identity.txt encryption-key.age | \ + age -r -o encryption-key-new.age +``` + +3. Update the Kubernetes Secrets: + +```bash +kubectl create secret generic klio-encryption-key-age \ + --from-file=encryption-key.age=encryption-key-new.age \ + --dry-run=client -o yaml | kubectl apply -f - +kubectl create secret generic klio-age-identity \ + --from-file=identity.txt=new-identity.txt \ + --dry-run=client -o yaml | kubectl apply -f - +``` + +4. Restart the Klio server pod to pick up the new files. + +5. Securely delete the old identity and plaintext files. + +!!!note + +If you are upgrading from a version that used the +`encryptionKey` field (`SecretKeySelector`), see the +[Upgrade Notes](upgrade_notes.mdx#encryption-key-management-breaking-change) +for migration instructions. +!!! + +## Authentication + +Klio uses mTLS Authentication for securing access to both the base backup server +and the WAL streaming server. Authentication is handled by verifying the client +certificates against the CA certificate which has been created when configuring +the Klio server. + +### Creating a client-side certificate + +To create a client-side certificate, you need a issuer that will sign all the +certificates with a CA known by the Klio server. Supposing that such a issuer is +called `server-sample-ca` and available in the current namespace, you can create +a client certificate with the following Certificate object: + +```yaml +apiVersion: cert-manager.io/v1 +kind: Certificate +metadata: + name: client-sample-tls +spec: + secretName: client-sample-tls + commonName: klio@cluster-1 + + duration: 2160h # 90d + renewBefore: 360h # 15d + + isCA: false + usages: + - client auth + + issuerRef: + name: server-sample-ca + kind: Issuer + group: cert-manager.io +``` + +If used the example proposed in the [server configuration documentation +page](#2-create-ca-certificate), the issuer can be created with: + +```yaml +apiVersion: cert-manager.io/v1 +kind: Issuer +metadata: + name: server-sample-ca +spec: + ca: + secretName: server-sample-ca +``` diff --git a/product_docs/docs/klio/0/main_concepts.mdx b/product_docs/docs/klio/0/main_concepts.mdx new file mode 100644 index 00000000000..c174bdce4ad --- /dev/null +++ b/product_docs/docs/klio/0/main_concepts.mdx @@ -0,0 +1,130 @@ +--- +title: Main Concepts +originalFilePath: >- + https://github.com/EnterpriseDB/klio/blob/main/documentation/web/versioned_docs/version-0.0.15/user/main_concepts.md +sidebar_position: 2 + +--- + +Klio is built on top of two foundational technologies: + +- PostgreSQL's native physical backup infrastructure +- The CloudNativePG Interface (CNPG-I) for backup and recovery + +PostgreSQL has provided **native continuous backup and point-in-time recovery +(PITR) capabilities since version 8.0, released in 2005**, enabling reliable +disaster recovery and business continuity for mission-critical systems +worldwide. + +!!!info + +PostgreSQL offers logical backups using tools like `pg_dump`, which generate a +logical representation of the database as SQL statements or data files. Logical +backups do not provide continuous protection or point-in-time recovery +capabilities. As a result, they are not suitable for **business continuity +scenarios** in mission-critical environments where minimizing downtime and data +loss is essential. +!!! + +At its core, [PostgreSQL’s continuous backup and recovery](https://www.postgresql.org/docs/current/continuous-archiving.html) +system uses **physical (file system level) copies** combined with **write-ahead +log (WAL) archiving**. +This approach enables consistent, recoverable backups while keeping systems +online, a strategy proven effective in production environments for over two +decades. + +In a PostgreSQL backup solution, the infrastructure typically consists of: + +- **WAL Archive**: A designated location for continuously archived WAL + (write-ahead log) files, preserving all changes made to the database to + support data durability and recovery. +- **Physical Base Backups**: A consistent copy of all data files used by + PostgreSQL (primarily the `PGDATA` directory and any tablespaces), forming + the foundational layer for any recovery operation. + +The diagram below illustrates the relationship between physical base backups +and the WAL archive over time: + +![Physical backups, WAL archive, and time](images/basebackups_walarchive.png) + +* * * + +## WAL Archive + +The WAL archive is central to **continuous backup** in PostgreSQL and is +essential for: + +- **Hot (Online) Backups**: Allowing physical base backups to be taken from any + node (primary or standby) without shutting down PostgreSQL, ensuring backups + can proceed without service disruption. +- **Point-in-Time Recovery (PITR)**: Enabling recovery to any precise moment + after the earliest available base backup, using archived WAL files to replay + transactions up to the desired recovery point. + +!!!important + +WAL archives on their own are insufficient for disaster recovery. +A **physical base backup is required** to restore a PostgreSQL cluster. +!!! + +Using a WAL archive significantly enhances the resilience of a PostgreSQL +system. WAL files can be fetched by any PostgreSQL instance for replication or +recovery, with archives typically retaining WAL segments longer than local +retention policies, ensuring historical data is preserved for PITR and disaster +recovery workflows. + +Klio receives WAL content from a PostgreSQL primary via streaming replication. + +* * * + +## Physical base backups + +PostgreSQL supports **physical base backups** as the cornerstone of its +disaster recovery and PITR strategies. A base backup is a **consistent, file +system-level copy** of all data files used by a PostgreSQL cluster, including +the `PGDATA` directory and any additional tablespaces. + +Key properties of PostgreSQL base backups: + +- **Online (Hot) Backups**: Base backups can be taken while the database is + online, avoiding downtime. PostgreSQL maintains consistency during an online + backup by coordinating with its write-ahead logging system, ensuring a valid + restore point. +- **Foundation for PITR**: A base backup provides the starting point for + point-in-time recovery. After restoring the base backup, archived WAL files + are replayed to advance the system to a specific recovery target, allowing + precise restoration following accidental data loss or corruption. +- **Efficient Storage and Transport**: Base backups can be compressed and + streamed to external or object storage, supporting offsite and cloud-based + disaster recovery workflows. + +Klio leverages CNPG-I to coordinate the hot backup procedure, using +PostgreSQL’s `pg_backup_start` and `pg_backup_stop` concurrent API to ensure +consistency. It uses [Kopia](https://github.com/kopia/kopia/) to efficiently +transfer backup data across locations, ensuring backups are portable, +secure, and space-efficient. + +* * * + +## Recovery + +In PostgreSQL, **recovery** is the process of restoring a database cluster from +a **physical base backup**, bringing it to a consistent state by replaying +**write-ahead log (WAL)** files, which contain the necessary *redo* information +for all changes made after the backup. + +PostgreSQL’s recovery system supports [Point-in-Time Recovery (PITR)](https://www.postgresql.org/docs/current/continuous-archiving.html#BACKUP-PITR-RECOVERY), +enabling you to restore a cluster to **any precise moment** between your +earliest base backup and the latest available WAL segment. To perform recovery, +a **valid WAL archive is required alongside the physical base backup**. + +Klio follows the approach of CloudNativePG and implements the recovery part of +CNPG-I. It **does not perform in-place recovery on an existing cluster**; +instead, recovery is used to **bootstrap a new cluster** from a base backup and +replay WAL files to reach a desired state. + +Recovery can operate in two primary modes: full recovery (replaying WAL files +to the latest available segment) or **Point-in-Time Recovery (PITR)**, allowing +restoration to a chosen state before an incident such as accidental data +deletion. Klio supports all PITR targets provided by CloudNativePG, including +time, restore point, and transaction. diff --git a/product_docs/docs/klio/0/managing_storage.mdx b/product_docs/docs/klio/0/managing_storage.mdx new file mode 100644 index 00000000000..1ccc8179b77 --- /dev/null +++ b/product_docs/docs/klio/0/managing_storage.mdx @@ -0,0 +1,305 @@ +--- +title: Managing Storage +originalFilePath: >- + https://github.com/EnterpriseDB/klio/blob/main/documentation/web/versioned_docs/version-0.0.15/user/managing_storage.md +sidebar_position: 8 + +--- + +This guide explains how to manage storage on your Klio server, prevent +disk full scenarios, and recover when storage is exhausted. + +The Klio server uses persistent storage for backup data, WAL archives, cache, +and the work queue. When the data PVC approaches capacity, backup and WAL +archival operations may fail. + +## How Disk Space Is Freed + +Deleting a backup does **not** immediately free disk space. Klio is built +on top of [Kopia](https://kopia.io), which uses a two-phase approach: + +1. **Deletion** logically deletes backups +2. **Maintenance** actually removes deleted data, if the data is older + than 24 hours and unused by any existing backup + +This design prevents accidental data loss from concurrent operations. +However, it means that space is not freed until maintenance runs and the +24-hour safety window has passed. + +Maintenance runs automatically in the background. Klio does not currently +provide a way to trigger it on demand, but it can be started manually +by opening a shell on the Klio server pod and running: + +```bash +kopia maintenance set --owner=me \ + --config-file=/tmp/$KOPIACONFIG_TIER1_CONF \ + --disable-file-logging +kopia maintenance run \ + --config-file=/tmp/$KOPIACONFIG_TIER1_CONF \ + --full \ + --disable-file-logging +``` + +## When the Disk Is Full + +When the Klio data PVC is completely full: + +- All backup operations block (new backups, deletions, maintenance) +- WAL streaming to Klio stops +- PostgreSQL accumulates WAL files on its own PVC +- No backup corruption occurs, even when backups fail mid-operation +- No orphan or incomplete snapshots are left behind +- Existing backups remain intact and restorable + +All operations resume automatically when space is freed. + +!!!warning + +While the Klio disk is full, WAL files build up on the PostgreSQL PVC. +If this condition persists, it can lead to disk pressure on the database +side as well. Resolve Klio storage issues promptly to avoid cascading +failures. +!!! + +## Resolving Storage Issues + +### Expand the PVC + +The simplest option is to expand the PVC. The Klio operator supports +expansion of PersistentVolumeClaims (PVCs) for all storage components: +data, cache (Tier 1 and Tier 2), and queue. + +#### Prerequisites + +PVC expansion requires a StorageClass with `allowVolumeExpansion: true`. + +!!!warning User Responsibility + +Before attempting to resize PVCs, **you must verify** that your +StorageClass supports volume expansion. The operator will attempt the +resize operation directly—if the StorageClass does not support +expansion, the Kubernetes API will reject the request and the operator +will log an error. +!!! + +To check if your StorageClass supports expansion: + +```bash +kubectl get storageclass -o jsonpath='{.allowVolumeExpansion}' +``` + +If the output is not `true`, you need to either: + +1. Update the StorageClass to enable volume expansion (if the underlying + storage provisioner supports it) +2. Use a different StorageClass that supports volume expansion +3. Migrate to a new PVC (see [Limitations](#limitations) for options) + +#### Expanding PVC Size + +To expand a PVC, update the corresponding +`pvcTemplate.resources.requests.storage` field in the Server spec with +a larger value: + +```yaml +apiVersion: klio.enterprisedb.io/v1alpha1 +kind: Server +metadata: + name: my-server +spec: + tier1: + data: + pvcTemplate: + resources: + requests: + storage: 200Gi # Increased from 100Gi + cache: + pvcTemplate: + resources: + requests: + storage: 20Gi # Increased from 10Gi + queue: + pvcTemplate: + resources: + requests: + storage: 20Gi # Increased from 10Gi +``` + +Apply the updated Server resource: + +```bash +kubectl apply -f klio-server.yaml +``` + +#### What Happens During Resize + +When you update the Server spec with larger PVC sizes, the following +occurs: + +1. **PVC expansion**: The operator patches PVCs directly to the new + size. This modifies the PVC resources but does **not** update the + StatefulSet—the StatefulSet's VolumeClaimTemplates remain unchanged + at this point. +2. **Temporary misalignment**: After the PVC patch, there is a brief + period where the PVCs have the new size but the StatefulSet + VolumeClaimTemplates still reflect the old size. +3. **StatefulSet recreation**: The operator detects that the expected + StatefulSet (with new VolumeClaimTemplates) differs from the current + one. Since VolumeClaimTemplates are immutable in Kubernetes, the + StatefulSet is deleted and recreated to align with the new spec. +4. **Pod restart**: The Klio server pod restarts and mounts the + already-expanded PVCs. + +!!!note Why explicit PVC patching is necessary + +VolumeClaimTemplates only define specs for *new* PVCs—they do not resize +existing ones. Without explicit PVC patching by the operator, the +StatefulSet would be recreated but the PVCs would remain at their +original size, creating a permanent mismatch between the Server spec +and actual storage. +!!! + +#### StatefulSet and PVC Alignment + +After the full resize operation completes: + +- The **PVCs** have the new expanded size +- The **StatefulSet VolumeClaimTemplates** match the new size (after + recreation) +- The **Server spec** is consistent with both + +This ensures no drift between the desired state and actual resources. + +#### Monitoring Resize Progress + +The operator emits a `PVCExpanded` Kubernetes event on the Server +resource when a PVC is successfully expanded. You can view these events +with: + +```bash +kubectl describe server my-server +``` + +Check the PVC status to monitor the resize operation: + +```bash +kubectl get pvc -l klio.enterprisedb.io/klio-server=my-server +``` + +The PVC will show the new requested size in +`spec.resources.requests.storage`. The actual capacity is reflected in +`status.capacity.storage` once the resize completes. + +For detailed status, including any resize conditions: + +```bash +kubectl describe pvc data-my-server-klio-0 +``` + +#### Limitations + +- **Expansion only**: PVC shrinking is not supported by Kubernetes. + Attempting to reduce the storage size will be ignored and logged as + a warning. +- **StorageClass support**: The StorageClass must have + `allowVolumeExpansion: true`. If the StorageClass does not support + expansion, the resize will fail and an error will be logged. +- **Pod restart required**: Due to StatefulSet VolumeClaimTemplates + being immutable, PVC expansion causes a brief pod restart. +- **Filesystem resize**: After the volume is expanded, the filesystem + must also be resized. Most modern storage providers handle this + automatically. + +!!!warning No Automatic Fallback + +If your StorageClass does not support volume expansion, there is **no +automatic fallback**. The operator will not delete and recreate PVCs to +achieve a larger size, as this would result in **permanent data loss**. +The only options in this case are: + +1. Migrate to a StorageClass that supports volume expansion +2. Create a new Klio server with larger PVCs and restore from backup +3. Manually migrate data (requires downtime and careful planning) +!!! + +### Delete Backups and Run Maintenance + +!!!warning + +Maintenance requires some free disk space to run. If the disk is +completely full, maintenance itself may fail. In that case, expand +the PVC first or contact EDB support. +!!! + +If PVC expansion is not available, free space by deleting old backups +and running maintenance manually. + +1. **Delete old backups:** + + ```bash + kubectl exec -it my-server-klio-0 -- \ + klio admin delete-backup \ + --cluster my-cluster --tier1 + ``` + + To delete from both tiers, add `--tier2`. + + !!!note + + The actual space freed depends on how much data is shared with + other backups through deduplication. Deleting a backup only + reclaims space for data blocks that are not referenced by any + remaining backup. + !!! + + !!!warning + + Deleting a backup removes the ability to restore to that point + in time. Ensure you have adequate backups remaining before + deletion. + !!! + +2. **Run maintenance** to reclaim space from deleted backups by opening + a shell on the Klio server pod and running: + + ```bash + kopia maintenance set --owner=me \ + --config-file=/tmp/$KOPIACONFIG_TIER1_CONF \ + --disable-file-logging + kopia maintenance run \ + --config-file=/tmp/$KOPIACONFIG_TIER1_CONF \ + --full \ + --disable-file-logging + ``` + +### Contact EDB Support + +If the above options are not viable or maintenance fails due to +insufficient disk space, contact EDB support for assistance. + +## Best Practices + +1. **Configure retention policies**: The most effective way to control + storage growth is through properly configured retention policies, which + automatically delete old backups and WAL files no longer needed for + recovery. See + [Retention Policies](plugin_configuration.mdx#retention-policies) for + configuration details. + +2. **Monitor storage usage**: Klio does not provide built-in storage + alerts. Set up monitoring and alerting on your PVC usage to detect + capacity issues before they cause failures. + +3. **Size Tier 1 storage appropriately**: Account for your backup + frequency, database size, change rate, and retention requirements when + provisioning the data PVC. Include buffer for the 24-hour window + during which deleted backup data is not yet eligible for garbage + collection. + +4. **Use Tier 2 for long-term retention**: Object storage (S3, etc.) is + more cost-effective and scales easily for long-term backup retention. + Keep Tier 1 lean for fast recovery of recent backups. + +5. **Use expandable StorageClasses**: When possible, use StorageClasses + with `allowVolumeExpansion: true` to enable online PVC expansion as a + recovery option. diff --git a/product_docs/docs/klio/0/opentelemetry.mdx b/product_docs/docs/klio/0/opentelemetry.mdx new file mode 100644 index 00000000000..4982906f076 --- /dev/null +++ b/product_docs/docs/klio/0/opentelemetry.mdx @@ -0,0 +1,444 @@ +--- +title: OpenTelemetry Observability +originalFilePath: >- + https://github.com/EnterpriseDB/klio/blob/main/documentation/web/versioned_docs/version-0.0.15/user/opentelemetry.md +sidebar_position: 8 + +--- + +Klio provides built-in support for [OpenTelemetry](https://opentelemetry.io/), +enabling comprehensive observability through distributed tracing and metrics +collection. This allows you to monitor backup operations, performance +characteristics, and system health across your Klio deployment. + +## Available Telemetry + +Klio automatically collects the following: + +- Traces + - Distributed WAL streaming and processing + - Backup lifecycle (backup, backup run, verification, maintenance) +- Metrics + - Server + - Backup operation metrics + - Number of snapshots + - Number of files in the latest snapshot + - Number of directories in the latest snapshot + - Size of the latest snapshot + - Age of the latest snapshot + - Age of the oldest snapshot + - WAL processing metrics + - Number of WAL files written + - Bytes written + - Timestamp of the most recently written WAL file + - Queue metrics + - Number of messages in the queue + - Number of bytes in the queue + - [GRPC metrics](https://opentelemetry.io/docs/specs/semconv/rpc/rpc-metrics/) + - [Go runtime statistics](https://pkg.go.dev/go.opentelemetry.io/contrib/instrumentation/runtime) + - [Host metrics](https://pkg.go.dev/go.opentelemetry.io/contrib/instrumentation/host) + - [Controller runtime metrics](https://book.kubebuilder.io/reference/metrics-reference) + - Sidecar + - Backup lifecycle metrics + - Whether a backup is currently running + - Timestamp of the most recent backup start + - Timestamp of the most recent successful completion + - Timestamp of the most recent failure + - Duration of the most recent backup + - Total number of successful backups + - Total number of failed backups + - Backup verification metrics + - [GRPC metrics](https://opentelemetry.io/docs/specs/semconv/rpc/rpc-metrics/) + - [Go runtime statistics](https://pkg.go.dev/go.opentelemetry.io/contrib/instrumentation/runtime) + - [Host metrics](https://pkg.go.dev/go.opentelemetry.io/contrib/instrumentation/host) + - [Controller runtime metrics](https://book.kubebuilder.io/reference/metrics-reference) + +!!!note + +Log exporters are not currently supported. +!!! + +## Traces Reference + +### Backup lifecycle spans + +When a backup is triggered through CNPG-I, Klio creates +the following spans under the `klio.backup` tracer: + +| Span Name | Description | +| -------------------- | --------------------------------------------------------------------------- | +| `backup` | Root span covering the entire backup operation (run + verify + maintenance) | +| `backup_run` | Child span for the actual data backup execution | +| `backup_verify` | Child span for post-backup verification | +| `backup_maintenance` | Child span for post-backup maintenance | + +The `backup` span includes the following attributes: + +| Attribute | Type | Description | +| ------------- | ------ | --------------------------- | +| `backup.name` | string | Name assigned to the backup | + +On failure, the span records the error and sets its status to +`ERROR`. + +## Metrics Reference + +### Backup lifecycle metrics (sidecar) + +These metrics are emitted by the sidecar and track backup +operations on each PostgreSQL instance: + +| Metric Name | Type | Unit | Description | +| ------------------------------------- | ------- | ---- | ----------------------------------------------------------------------- | +| `klio.backup.running` | Gauge | - | Whether a backup is currently running (1) or not (0) | +| `klio.backup.latest_start_time` | Gauge | s | Unix epoch timestamp when the most recent backup started | +| `klio.backup.latest_completion_time` | Gauge | s | Unix epoch timestamp when the most recent backup completed successfully | +| `klio.backup.latest_failure_time` | Gauge | s | Unix epoch timestamp when the most recent backup failed | +| `klio.backup.latest_duration_seconds` | Gauge | s | Duration of the most recent backup in seconds | +| `klio.backup.successes` | Counter | - | Total number of successful backups | +| `klio.backup.failures` | Counter | - | Total number of failed backups | +| `klio.backup.verifications` | Counter | - | Total number of backup verification attempts | +| `klio.backup.verification_failures` | Counter | - | Total number of backup verification failures | + +### WAL server metrics (server) + +These metrics are emitted by the Klio server WAL component and track +WAL file reception from PostgreSQL instances: + +| Metric Name | Type | Unit | Description | +| ------------------------------ | ------- | ---- | ------------------------------------------------------------------ | +| `klio.wal.written_size` | Counter | By | Number of bytes written to disk for WAL files | +| `klio.wal.written` | Counter | - | Number of WAL files written | +| `klio.wal.latest_written_time` | Gauge | s | Unix epoch timestamp of the most recently written WAL file to disk | + +### WAL consumer metrics (server) + +These metrics are emitted by the Klio server WAL consumer and track +WAL archival to Tier 2 storage: + +| Metric Name | Type | Unit | Description | +| ------------------------------------------- | ------- | ---- | -------------------------------------------------------------------- | +| `klio.consumer.written_size` | Counter | By | Number of bytes written to Tier 2 for WAL files | +| `klio.consumer.written` | Counter | - | Number of WAL files written to Tier 2 | +| `klio.consumer.latest_written_time` | Gauge | s | Unix epoch timestamp of the most recently written WAL file to Tier 2 | +| `klio.consumer.backup_verification_success` | Counter | - | Number of successful backup verifications | +| `klio.consumer.backup_verification_failure` | Counter | - | Number of failed backup verifications (corruption detected) | + +### Alerting on stalled WAL processing + +Despite sharing a similar name, `klio.wal.latest_written_time` and +`klio.consumer.latest_written_time` track two distinct stages of the +WAL pipeline and signal different failure scenarios: + +- **`klio.wal.latest_written_time`** reflects when the Klio server + last received a WAL file from PostgreSQL streaming replication + (Tier 1). A stale value means PostgreSQL is no longer shipping + WALs to Klio, which may indicate a replication problem. + +- **`klio.consumer.latest_written_time`** reflects when the WAL + consumer last archived a WAL file to Tier 2 object storage (S3). + A stale value means the S3 backend is no longer receiving WALs, + even though PostgreSQL replication may still be working. + +Both metrics carry a `cluster_name` attribute label identifying the +PostgreSQL cluster the WAL event belongs to. + +### Base backup metrics (server) + +These metrics are emitted by the Klio server base backup component +and track Kopia snapshot statistics: + +| Metric Name | Type | Unit | Description | +| --------------------------------- | ----- | ---- | ------------------------------------------------------------------------------ | +| `klio.base.snapshots` | Gauge | - | Total number of base snapshots | +| `klio.base.latest_snapshot_size` | Gauge | By | Size of latest base snapshot in bytes (ignoring compression and deduplication) | +| `klio.base.latest_snapshot_files` | Gauge | - | Number of files in latest base snapshot | +| `klio.base.latest_snapshot_dirs` | Gauge | - | Number of directories in latest base snapshot | +| `klio.base.latest_snapshot_age` | Gauge | s | Age of latest base snapshot in seconds | +| `klio.base.oldest_snapshot_age` | Gauge | s | Age of oldest base snapshot in seconds | + +### Queue metrics (server) + +These metrics are emitted by the Klio server and track the state of +the embedded NATS JetStream queue used for asynchronous Tier 2 +offloading of WAL files and backups: + +| Metric Name | Type | Unit | Description | +| --------------------- | ----- | ---- | ------------------------------------------------------------------------ | +| `klio.queue.messages` | Gauge | - | Number of messages currently stored in the embedded NATS JetStream queue | +| `klio.queue.bytes` | Gauge | By | Number of bytes currently stored in the embedded NATS JetStream queue | + +## Configuration + +Klio automatically detects OpenTelemetry configuration through standard +environment variables. If no OpenTelemetry environment variables are present, +Klio will use no-op providers that don't collect any telemetry data. + +Traces and metrics exporters can be configured independently through the +[`autoexport`](https://go.opentelemetry.io/contrib/exporters/autoexport) package. + +### General Settings + +The following environment variables are used to configure OpenTelemetry: + +- `OTEL_SERVICE_NAME`: (required) Name of the service, e.g., `klio-server` +- `OTEL_RESOURCE_ATTRIBUTES`: Comma-separated list of resource attributes + (e.g., `deployment.environment=production,service.namespace=klio-system`) +- `OTEL_RESOURCE_DETECTORS`: Comma-separated list of resource detectors + from the [`autodetect`](https://pkg.go.dev/go.opentelemetry.io/contrib/detectors/autodetect) + package, used to automatically populate resource attributes + +### Traces exporter + +To enable the traces exporter, set the `OTEL_TRACES_EXPORTER` environment +variable to one of the supported exporters: + +- `otlp`: OpenTelemetry Protocol (OTLP) exporter +- `console`: Console exporter (useful for debugging) +- `none`: No-op exporter (disables tracing) + +You can define the OTLP protocol using the `OTEL_EXPORTER_OTLP_TRACES_PROTOCOL` +variable, or the general `OTEL_EXPORTER_OTLP_PROTOCOL`. Supported protocols +include: + +- `http/protobuf` (default) +- `grpc` + +Additional configuration options for trace exporters can be found in the +documentation of the respective exporters: + +- [OTLP Trace gRPC Exporter](https://pkg.go.dev/go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc) +- [OTLP Trace HTTP Exporter](https://pkg.go.dev/go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp) + +### Metrics Exporter + +To enable the metrics exporter, set the `OTEL_METRICS_EXPORTER` environment +variable to one of the supported exporters: + +- `otlp`: OpenTelemetry Protocol (OTLP) exporter +- `prometheus`: Prometheus exporter + HTTP server +- `console`: Console exporter (useful for debugging) +- `none`: No-op exporter (disables metrics) + +You can define the OTLP protocol using the `OTEL_EXPORTER_OTLP_METRICS_PROTOCOL` +variable, or the general `OTEL_EXPORTER_OTLP_PROTOCOL`. Supported protocols +include: + +- `http/protobuf` (default) +- `grpc` + +Additional configuration options for metrics exporters can be found in the +documentation of the respective exporters: + +- [OTLP Metric gRPC Exporter](https://pkg.go.dev/go.opentelemetry.io/otel/exporters/otlp/otlpmetric/otlpmetricgrpc) +- [OTLP Metric HTTP Exporter](https://pkg.go.dev/go.opentelemetry.io/otel/exporters/otlp/otlpmetric/otlpmetrichttp) + +For the Prometheus exporter, you can configure the host and port of the HTTP +server using the following environment variables: + +- `OTEL_EXPORTER_PROMETHEUS_HOST` (default: `localhost`) +- `OTEL_EXPORTER_PROMETHEUS_PORT` (default: `9464`) + +### Exporters and receivers + +The OTLP exporter pushes telemetry to any OTLP-compatible receiver. Common +options include: + +- An [OpenTelemetry Collector](https://opentelemetry.io/docs/collector/), + which can receive OTLP data and fan it out to multiple backends + (Prometheus, Jaeger, Grafana, etc.). In Kubernetes, the + [OpenTelemetry Operator](https://opentelemetry.io/docs/platforms/kubernetes/operator/) + manages collectors via the `OpenTelemetryCollector` CRD and can expose + a stable in-cluster OTLP endpoint for Klio to target. +- Any backend with native OTLP support. + +The Prometheus exporter starts a local HTTP server that Prometheus scrapes +directly, with no intermediate collector required. + +## Configuring Klio with OpenTelemetry in Kubernetes + +When running in a Kubernetes environment, Klio will automatically define +`CONTAINER_NAME`, `POD_NAME` and `NAMESPACE_NAME` environment variables. +When any of these environment variables are set, Klio will automatically add +the corresponding resource attributes (`k8s.container.name`, `k8s.pod.name`, +`k8s.namespace.name`) to all telemetry data. Each attribute is added +independently - you don't need all three environment variables to be present. + +!!!important + +If you have already defined any of these attributes in +`OTEL_RESOURCE_ATTRIBUTES`, Klio will **not override** them. Only missing +attributes will be added from the environment variables. This allows you to +customize the values while still benefiting from automatic defaults for any +attributes you don't explicitly set. +!!! + +### Klio server with OpenTelemetry + +When deploying a Klio `Server`, you can configure OpenTelemetry by specifying +the necessary settings in the `template` section of the `Server` spec: + +1. Set the required environment variables for OpenTelemetry configuration in + the `server` container. +2. Mount any necessary TLS certificates for secure communication with the + OpenTelemetry Collector. + +For simpler management, use a `ConfigMap` to store the OpenTelemetry configuration: + +```yaml +apiVersion: v1 +kind: ConfigMap +metadata: + name: klio-otel-config +data: + OTEL_SERVICE_NAME: "klio-server" + OTEL_RESOURCE_DETECTORS: "telemetry.sdk,host,os.type,process.executable.name" + OTEL_TRACES_EXPORTER: "otlp" + OTEL_EXPORTER_OTLP_TRACES_PROTOCOL: "grpc" + OTEL_EXPORTER_OTLP_TRACES_ENDPOINT: "https://otel-collector:4317" + OTEL_EXPORTER_OTLP_TRACES_COMPRESSION: "gzip" + OTEL_EXPORTER_OTLP_TRACES_TIMEOUT: "10000" + OTEL_EXPORTER_OTLP_TRACES_INSECURE: "false" + OTEL_EXPORTER_OTLP_TRACES_CERTIFICATE: "/otel/ca.crt" + OTEL_EXPORTER_OTLP_TRACES_CLIENT_CERTIFICATE: "/otel/tls.crt" + OTEL_EXPORTER_OTLP_TRACES_CLIENT_KEY: "/otel/tls.key" + OTEL_METRICS_EXPORTER: "otlp" + OTEL_METRIC_EXPORT_INTERVAL: "60000" + OTEL_EXPORTER_OTLP_METRICS_PROTOCOL: "grpc" + OTEL_EXPORTER_OTLP_METRICS_ENDPOINT: "https://otel-collector:4317" + OTEL_EXPORTER_OTLP_METRICS_TIMEOUT: "60000" + OTEL_EXPORTER_OTLP_METRICS_INSECURE: "false" + OTEL_EXPORTER_OTLP_METRICS_CERTIFICATE: "/otel/ca.crt" + OTEL_EXPORTER_OTLP_METRICS_CLIENT_CERTIFICATE: "/otel/tls.crt" + OTEL_EXPORTER_OTLP_METRICS_CLIENT_KEY: "/otel/tls.key" +--- +apiVersion: klio.enterprisedb.io/v1alpha1 +kind: Server +metadata: + name: my-klio-server +spec: + # ... other configuration ... + template: + spec: + containers: + - name: server + envFrom: + - configMapRef: + name: klio-otel-config + volumeMounts: + - mountPath: /otel + name: otel + volumes: + - name: otel + projected: + sources: + - secret: + name: otel-collector-tls + items: + - key: ca.crt + path: ca.crt + - secret: + name: otel-client-cert + items: + - key: tls.crt + path: tls.crt + - key: tls.key + path: tls.key +``` + +### Klio plugins with OpenTelemetry + +When deploying Klio as a CNPG Cluster plugin, configure OpenTelemetry by +specifying the necessary environment variables in the `containers` section of +the `PluginConfiguration` spec. The available container names are: + +- `klio-plugin`: Main plugin sidecar for backup management +- `klio-restore`: Restore operations sidecar + +Create a `ConfigMap` for the shared OpenTelemetry configuration: + +```yaml +apiVersion: v1 +kind: ConfigMap +metadata: + name: cluster-klio-otel-config +data: + OTEL_RESOURCE_DETECTORS: "telemetry.sdk,host,os.type,process.executable.name" + OTEL_TRACES_EXPORTER: "otlp" + OTEL_METRICS_EXPORTER: "otlp" + OTEL_EXPORTER_OTLP_PROTOCOL: "grpc" + OTEL_EXPORTER_OTLP_ENDPOINT: "https://otel-collector:4317" + OTEL_EXPORTER_OTLP_COMPRESSION: "gzip" + OTEL_EXPORTER_OTLP_TIMEOUT: "10000" + OTEL_EXPORTER_OTLP_INSECURE: "false" + OTEL_EXPORTER_OTLP_CERTIFICATE: "/projected/ca.crt" + OTEL_EXPORTER_OTLP_CLIENT_CERTIFICATE: "/projected/tls.crt" + OTEL_EXPORTER_OTLP_CLIENT_KEY: "/projected/tls.key" +``` + +Configure the `PluginConfiguration` to inject the environment variables into +each sidecar container: + +```yaml +apiVersion: klio.enterprisedb.io/v1alpha1 +kind: PluginConfiguration +metadata: + name: client-config-cluster-example +spec: + serverAddress: klio.default + clientSecretName: cluster-example-klio-user + serverSecretName: klio-server-tls + clusterName: cluster-example + containers: + - name: klio-plugin + env: + - name: OTEL_SERVICE_NAME + value: "klio-plugin" + envFrom: + - configMapRef: + name: cluster-klio-otel-config + - name: klio-restore + env: + - name: OTEL_SERVICE_NAME + value: "klio-restore" + envFrom: + - configMapRef: + name: cluster-klio-otel-config +``` + +Mount the OpenTelemetry certificates using the Cluster's `projectedVolumeTemplate`. +The projected volume is mounted at `/projected/` and is accessible to all +sidecar containers: + +```yaml +apiVersion: postgresql.cnpg.io/v1 +kind: Cluster +metadata: + name: cluster-example +spec: + instances: 3 + + projectedVolumeTemplate: + sources: + - secret: + name: otel-collector-tls + items: + - key: ca.crt + path: ca.crt + - secret: + name: otel-client-cert + items: + - key: tls.crt + path: tls.crt + - key: tls.key + path: tls.key + + plugins: + - name: klio.enterprisedb.io + enabled: true + parameters: + pluginConfigurationRef: client-config-cluster-example + + storage: + size: 10Gi +``` diff --git a/product_docs/docs/klio/0/plugin_configuration.mdx b/product_docs/docs/klio/0/plugin_configuration.mdx new file mode 100644 index 00000000000..36abcf7b4bc --- /dev/null +++ b/product_docs/docs/klio/0/plugin_configuration.mdx @@ -0,0 +1,555 @@ +--- +title: The Klio Plugin +originalFilePath: >- + https://github.com/EnterpriseDB/klio/blob/main/documentation/web/versioned_docs/version-0.0.15/user/plugin_configuration.md +sidebar_position: 6 + +--- + +The Klio plugin for CloudNativePG allows you to leverage the backup and WAL +streaming capabilities of Klio for your PostgreSQL clusters managed by +CloudNativePG. It will add two containers to each PostgreSQL instance pod: + +- A `klio-plugin` container that handles backup creation and management +- A `klio-wal` container that streams WAL files to the Klio server in real-time + +## Configuration + +The Klio plugin integrates with CloudNativePG through the CNPG-I (CloudNativePG +Interface) specification, enabling Klio to manage backups and WAL streaming for +your PostgreSQL clusters. To use Klio with a CloudNativePG cluster, you need to: + +1. Create a `PluginConfiguration` resource that defines how to connect to the + Klio server +2. Reference the plugin in your `Cluster` resource specification + +## Prerequisites + +Before configuring a cluster to use the Klio plugin, ensure you have: + +- A running Klio `Server` resource deployed in your namespace +- Client credentials (username and password) stored in a Kubernetes Secret +- The server's TLS certificate available in a Secret + +## Creating a PluginConfiguration resource + +The `PluginConfiguration` custom resource defines how the Klio plugin connects +to and communicates with the Klio server. This resource contains connection +details, authentication credentials, and optional configuration for metrics, +profiling, and backup retention policies. + +### Basic example + +Here's a minimal `PluginConfiguration` example: + +```yaml +apiVersion: klio.enterprisedb.io/v1alpha1 +kind: PluginConfiguration +metadata: + name: klio-plugin-config + namespace: default +spec: + serverAddress: klio-server.default + clientSecretName: client-sample-tls + serverSecretName: klio-server-tls + # mode: standard # Optional: standard (default) or read-only +``` + +### Client credentials secret + +The client credentials must be stored in a Kubernetes Secret of type +`kubernetes.io/tls`, containing a secret to be presented to the Klio server. + +This secret can be generated with cert-manager by following the [documentation +in the Klio server page](klio_server.mdx#creating-a-client-side-certificate), +or be provided by the user. + +### Server Address + +The `serverAddress` field specifies where the Klio server can be reached. This +can be: + +- A Kubernetes service name: `klio-server.default` (within the same namespace) +- A fully qualified domain name: `klio-server.default.svc.cluster.local` +- An external address: `klio.example.com` + +Connections will be done using the default ports of the Klio base and WAL +servers, respectively 51515 and 52000. + +### TLS configuration + +The `serverSecretName` field references a Secret containing the TLS certificate +used to secure communication with the Klio server. This is the same +certificate configured on the `Server` resource. + +## Configuring a Cluster to use the Klio plugin + +Once you have created a `PluginConfiguration`, reference it in your CloudNativePG +`Cluster` resource: + +```yaml +apiVersion: postgresql.cnpg.io/v1 +kind: Cluster +metadata: + name: my-postgres-cluster + namespace: default +spec: + instances: 3 + + postgresql: + pg_hba: + - local replication all peer map=local # Allow replication connections locally + + plugins: + - name: klio.enterprisedb.io + enabled: true # Activate the Klio plugin (default) + parameters: + pluginConfigurationRef: klio-plugin-config + + storage: + size: 10Gi +``` + +To be able to stream WAL files, ensure that your PostgreSQL configuration +allows local replication connections. You can do this by adding an entry to the +`pg_hba` section, as shown in the example above. + +### Plugin parameters + +The `plugins` section in the `Cluster` specification requires: + +- **name**: Must be set to `klio.enterprisedb.io` to identify the Klio plugin +- **enabled**: Set to `true` to activate the plugin. This is the default value. +- **parameters.pluginConfigurationRef**: The name of your `PluginConfiguration` resource + +!!!note + +Even though the Klio plugin is used to archive WAL files on the Klio server, +it does not use the `archiveCommand` parameter in the PostgreSQL configuration, +as the WAL are streamed directly to the Klio server. Thus, you must not set +`isWALArchiver: true` in the plugin configuration. +!!! + +!!!important + +If you add the Klio plugin to an **existing** cluster, you must +restart the cluster to inject the sidecar containers. Use +[`kubectl cnpg restart`][cnpg-restart] or set the +`kubectl.kubernetes.io/restartedAt` annotation on the cluster. + +[cnpg-restart]: https://cloudnative-pg.io/docs/current/kubectl-plugin/#restart +!!! + +!!!warning + +The `PluginConfiguration` resource referenced in the `Cluster` should exist +before creating or updating the cluster. If it doesn't exist, the Klio plugin +uses the PreReconcile hook to gate reconciliation, causing the cluster to wait +at the start of the reconciliation loop (before any object creation or status +changes) until the `PluginConfiguration` is created. This avoids unrecoverable +error states, but the cluster will not progress until the dependency is +satisfied. Ensure the `PluginConfiguration` is created with the correct name. +!!! + +## Applying configuration changes + +Most changes to the `PluginConfiguration` resource are applied +automatically. When you update a `PluginConfiguration`, the Klio +operator detects the change and updates the corresponding +`klio-config` Secret. The Klio sidecar containers monitor their +configuration file for changes and **restart automatically** to apply +the new configuration. This restart is intentional and expected. + +**What to expect during configuration updates:** + +- The `klio-plugin`, `klio-wal`, and `klio-restore` sidecar containers + will restart to pick up the new configuration +- Container restart counts will increment - this is normal behavior and + indicates the configuration was successfully applied +- Restarts are graceful and brief (typically 5-10 seconds) +- No data loss occurs - PostgreSQL continues running and WAL streaming + resumes automatically after restart +- You can verify the configuration was applied by checking the + `ConfigurationApplied` condition in the PluginConfiguration status + +This automatic propagation applies to all configuration fields +stored in the config file, including: + +- Server address +- Tier 1 and Tier 2 settings (backup, recovery, retention) +- Operation mode (`standard` or `read-only`) +- Cluster name override +- WAL prefetch configuration + +!!!note + +Changes to container customizations (such as `image`, +`resources`, or `securityContext`) and the `pprof` setting are +not applied automatically. These fields affect the pod spec, +which is managed by CloudNativePG. To apply these changes, use +`kubectl cnpg restart` to roll the cluster pods. +!!! + +## Advanced configuration options + +The `PluginConfiguration` resource supports several advanced options to +customize the plugin's behavior. + +### Retention policies + +Define how long backups should be retained by configuring retention policies +for Tier 1 and Tier 2 storage. Retention policies can be configured +independently for each tier: + +```yaml +apiVersion: klio.enterprisedb.io/v1alpha1 +kind: PluginConfiguration +metadata: + name: klio-plugin-config +spec: + serverAddress: klio-server.default + clientSecretName: klio-client-credentials + serverSecretName: klio-server-tls + tier1: + retention: + keepLatest: 5 + keepHourly: 12 + keepDaily: 7 + keepWeekly: 4 + keepMonthly: 6 + keepAnnual: 2 + tier2: + enableBackup: true + enableRecovery: true + retention: + keepLatest: 10 + keepDaily: 30 + keepMonthly: 12 + keepAnnual: 5 +``` + +Except for `keepLatest`, each option defines how many backups to retain +for the specified time period. For example, `keepDaily: 7` means that we should +retain at most one backup for each of the past 7 days. + +If multiple backups exist within the same time bucket, the most recent one is +kept, unless preserved by a different *keep* rule. Backups that are not +retained by any rule are deleted. Rule evaluation is done when a new backup is +taken. + +The Klio server will automatically delete WAL files that are no longer needed +for recovery by any retained backup. + +All retention settings are optional. For each unspecified retention level, +the default Kopia value is applied: + +```yaml +keepLatest: 10 +keepHourly: 48 +keepDaily: 7 +keepWeekly: 4 +keepMonthly: 24 +keepAnnual: 1 +``` + +Set a rule to `0` to disable that retention level. + +### Operation Mode + +The `mode` field controls whether the plugin can perform both backup and +restore operations (`standard`) or only restore operations (`read-only`). + +```yaml +spec: + mode: standard # or read-only +``` + +#### Standard Mode (default) + +In standard mode, the plugin can: + +- Create backups to Tier 1 (and optionally Tier 2) +- Stream WAL files to the server +- Restore from both Tier 1 and Tier 2 + +This is the default mode and suitable for most deployments. + +#### Read-Only Mode + +Use read-only mode when connecting to a read-only Klio server for recovery +operations only. This is useful for disaster recovery scenarios where you want +to restore from a read-only server in a secondary region or datacenter. + +```yaml +apiVersion: klio.enterprisedb.io/v1alpha1 +kind: PluginConfiguration +metadata: + name: dr-restore-config +spec: + serverAddress: dr-server.default + clientSecretName: dr-client-credentials + serverSecretName: dr-server-tls + mode: read-only + + # Read-only mode requires: + # - tier2 configuration with enableRecovery: true + # - NO tier1 configuration + tier2: + enableRecovery: true + # enableBackup must be false or omitted +``` + +**Restrictions in read-only mode:** + +- Tier 2 must be configured with `enableRecovery: true` +- Tier 2 `enableBackup` must be `false` or omitted +- Tier 1 configuration is not allowed +- No backup or WAL streaming operations are performed + +See the [Read-Only Server Mode](klio_server.mdx#read-only-mode) documentation +for details on setting up a read-only Klio server. + +### Cluster name override + +By default, the plugin uses the name of the CloudNativePG `Cluster` resource. +You can override this if needed: + +```yaml +spec: + clusterName: my-custom-cluster-name +``` + +This can be useful working with backups from different clusters, for example +when restoring clusters or configuring replica clusters. + +### Tier 2 configuration + +Tier 2 provides secondary storage (typically object storage like S3) for +long-term backup retention and disaster recovery. Configure Tier 2 using the +`tier2` section: + +```yaml +spec: + tier2: + enableBackup: true + enableRecovery: true + retention: + keepDaily: 30 + keepMonthly: 12 +``` + +#### Options + +- **`enableBackup`**: When set to `true`, backups and WAL files are + automatically synchronized to Tier 2 storage after being stored in Tier 1. + This ensures your backups are available in long-term storage. + +- **`enableRecovery`**: When set to `true`, Klio will look for backups and + WAL files in both Tier 1 and Tier 2 during restore operations. If a backup + is available in both tiers, Tier 1 takes precedence as restore from it will + be faster. + +- **`retention`**: Configure a separate retention policy for Tier 2. + Typically, you would configure longer retention periods for Tier 2 since + object storage is more cost-effective for long-term storage. + +See the [Architecture documentation](architectures.mdx#tier-2-secondary-storage-object-storage) +for more details on Tier 2 storage. + +### WAL Prefetch Configuration + +During recovery operations, Klio can prefetch WAL files ahead of PostgreSQL's +requests to speed up recovery. Configure prefetching using the `walPrefetch` +section: + +```yaml +spec: + walPrefetch: + count: 8 + maxConcurrentDownloads: 16 +``` + +#### Options + +- **`count`**: The number of WAL files to prefetch ahead during recovery. + Set to `0` to disable prefetching. Default is `2`. + +- **`maxConcurrentDownloads`**: The maximum number of concurrent WAL + downloads. Higher values can improve recovery speed on high-bandwidth + connections but use more resources. Default is `4`. + +### Observability + +See the [OpenTelemetry observability](opentelemetry.mdx) section for more +details on how to monitor the Klio plugin using OpenTelemetry. + +### Performance profiling + +Enable the pprof HTTP endpoint for performance profiling and troubleshooting: + +```yaml +spec: + pprof: true +``` + +When enabled, the pprof endpoint is exposed and can be used with Go's profiling +tools to analyze CPU usage, memory allocation, goroutines, and other runtime +metrics. + +!!!warning + +Only enable pprof in development or testing environments, or when actively +troubleshooting performance issues. It should not be enabled in production +unless necessary. +!!! + +## Container customization + +The `PluginConfiguration` resource allows you to customize the Klio sidecar +containers by providing base container specifications that are used as the +foundation for the sidecars. This feature enables you to add custom environment +variables, volume mounts, resource limits, and other container settings without +modifying the PostgreSQL container environment. + +### Basic example + +```yaml +apiVersion: klio.enterprisedb.io/v1alpha1 +kind: PluginConfiguration +metadata: + name: klio-plugin-config +spec: + serverAddress: klio-server.default + clientSecretName: klio-client-credentials + serverSecretName: klio-server-tls + containers: + - name: klio-plugin + env: + - name: CUSTOM_ENV_VAR + value: "my-value" + - name: DEBUG_LEVEL + value: "info" + - name: klio-wal + env: + - name: WAL_BUFFER_SIZE + value: "8192" +``` + +### How container merging works + +The containers you define serve as the base for the Klio sidecars, with the +following merge behavior: + +1. **Your container is the base**: When you define a container + (e.g., `klio-plugin`), your specification serves as the starting point +2. **Klio enforces required values**: Klio sets its essential configuration: + - Container `name` (klio-plugin, klio-wal, or klio-restore) + - Container `args` (the command arguments needed for operation) + - `CONTAINER_NAME` environment variable +3. **Your customizations are preserved**: All other fields you define remain + intact +4. **Template defaults fill gaps**: For fields you don't specify, Klio applies + sensible defaults (image, security context, standard volume mounts, etc.) + +!!!important + +Klio's required values (name, args, `CONTAINER_NAME` env var) will +always override any conflicting values you set. All other customizations are +respected. +!!! + +### Plugin configuration selection in replica clusters + +When a CloudNativePG `Cluster` has multiple `PluginConfiguration` +resources — one for archiving and one or more for external clusters — +Klio selects which configuration to apply to the sidecar containers +using the following logic: + +1. **Archive plugin takes precedence**: if the `Cluster` has a Klio + plugin declared in `.spec.plugins` (the archive plugin), its + `PluginConfiguration` is used for the sidecar containers on every + pod. +2. **Fallback to replica source**: if no archive plugin is configured + and the cluster is a replica (`.spec.replica` is set), the + designated primary pod uses the `PluginConfiguration` referenced + by the external cluster defined as the replica source + (`.spec.replica.source`). Non-primary pods do not receive a Klio + sidecar in this case. + +For example, consider a replica cluster that does not archive locally +but restores WALs from an external source managed by Klio: + +```yaml +apiVersion: postgresql.cnpg.io/v1 +kind: Cluster +metadata: + name: cluster-dc-b +spec: + instances: 3 + # No archive plugin in .spec.plugins + + replica: + self: cluster-dc-b + primary: cluster-dc-a + source: cluster-dc-a + + externalClusters: + - name: cluster-dc-a + plugin: + name: klio.enterprisedb.io + parameters: + pluginConfigurationRef: source-plugin-config +``` + +In this setup, only the designated primary of `cluster-dc-b` gets a +Klio sidecar, configured from the `source-plugin-config` +`PluginConfiguration`. The container customizations defined in that +`PluginConfiguration` (image, resources, environment variables, etc.) +are applied to the sidecar following the same merging rules described +above. + +### Available sidecar containers + +The following containers can be customized: + +- **`klio-plugin`**: Handles backup creation and management in PostgreSQL pods +- **`klio-wal`**: Streams WAL files to the Klio server in PostgreSQL pods +- **`klio-restore`**: Restores backups during recovery jobs + +### Example: Resource limits and environment variables + +```yaml +apiVersion: klio.enterprisedb.io/v1alpha1 +kind: PluginConfiguration +metadata: + name: klio-plugin-config +spec: + serverAddress: klio-server.default + clientSecretName: klio-client-credentials + serverSecretName: klio-server-tls + containers: + - name: klio-plugin + env: + - name: LOG_LEVEL + value: "debug" + - name: OTEL_EXPORTER_OTLP_ENDPOINT + value: "http://otel-collector:4317" + resources: + limits: + memory: "512Mi" + cpu: "1" + requests: + memory: "256Mi" + cpu: "500m" + - name: klio-wal + env: + - name: WAL_STREAM_TIMEOUT + value: "30s" + resources: + limits: + memory: "256Mi" + cpu: "500m" + requests: + memory: "128Mi" + cpu: "250m" +``` diff --git a/product_docs/docs/klio/0/upgrade_notes.mdx b/product_docs/docs/klio/0/upgrade_notes.mdx new file mode 100644 index 00000000000..eb08811e497 --- /dev/null +++ b/product_docs/docs/klio/0/upgrade_notes.mdx @@ -0,0 +1,198 @@ +--- +title: Upgrade Notes +originalFilePath: >- + https://github.com/EnterpriseDB/klio/blob/main/documentation/web/versioned_docs/version-0.0.15/user/upgrade_notes.md +sidebar_position: 91 + +--- + +This page lists version-specific changes that may require +manual action when upgrading Klio. For the upgrade procedure, +see the [Helm chart page](helm_chart.mdx#upgrades). + +## Upgrading to 0.0.15 + +The `--custom-cnpg-group` and `--custom-cnpg-version` flags have been +removed from the operator manager arguments. The operator now derives the CNPG +API group and version from the cluster's metadata at runtime. + +In the Helm chart, `--custom-cnpg-group` was previously set in the default +`controllerManager.manager.args` list, and has now been removed. + +No action is needed in most cases, unless one of the following applies: + +1. You are setting these flags in your Helm values or `--set` overrides + explicitly +2. You are using `--reuse-values` when upgrading, which would preserve the old + flags in the new deployment. + +In any of these cases, ensure that the `controllerManager.manager.args` is +overridden to define the parameter list. + +The default arguments are shown in the +[Helm chart page](helm_chart.mdx#configuration-reference). + +## Upgrading to 0.0.14 + +### Encryption key management (breaking change) + +!!!Warning + +You should complete the first four steps in this section +before proceeding with the Klio upgrade with Helm. +!!! + +Previous versions of Klio stored the encryption key as a +plaintext value in a Kubernetes Secret, referenced via the +`encryptionKey` field (a `SecretKeySelector`). This field has +been replaced by `encryptionKeyFile` and `identityFile`, which +use [Age encryption](klio_server.mdx#age-encryption) to protect +the key at rest. + +!!!warning + +This is a **breaking API change**. Existing `Server` resources +using `encryptionKey` must be updated after upgrading the CRD. +The underlying encryption key (used by Kopia) does **not** +change — only how it is stored and delivered to Klio. +!!! + +The steps below show the migration for `tier1`. If your +Server also has `tier2` configured, repeat the same steps +for `tier2` (replacing `.spec.tier1` with `.spec.tier2` in +the commands, and updating the `tier2` section in the Server +spec). Tier1 and tier2 may use different encryption keys and +identity files. + +To migrate an existing deployment: + +!!!Warning + +Complete steps from 1. to 4. before upgrading Klio. +!!! + +1. Extract the secret name and key from the Server resource: + + ```bash + SECRET_NAME=$(kubectl get server my-server \ + -o jsonpath='{.spec.tier1.encryptionKey.name}') + SECRET_KEY=$(kubectl get server my-server \ + -o jsonpath='{.spec.tier1.encryptionKey.key}') + ``` + +2. Retrieve the current encryption key from the secret: + + ```bash + ENCRYPTION_KEY=$(kubectl get secret "$SECRET_NAME" \ + -o jsonpath="{.data.${SECRET_KEY}}" | base64 -d) + ``` + +3. Create the `values.yaml` file from the existing Helm chart: + + ```bash + helm get values -n cnpg-system > values.yaml + ``` + +4. Edit the `values.yaml` file updating the Klio version with + the new release tag: + + ```bash + controllerManager: + manager: + env: + SIDECAR_IMAGE: ghcr.io/enterprisedb/klio:v0.0.14 + [...] + image: + tag: v0.0.14 + [...] + ``` + + Now proceed with the Klio upgrade following the + [Helm chart page](helm_chart.mdx#upgrades), + until the "Upgrade Klio Server" section included. + But first, please, complete reading this section. + + !!!Warning + + The command to verify that the Server is running the + latest version will continue showing the old version. + This is normal, as the operator can not reconcile yet. + !!! + + You can use the `values.yaml` file created in the previous + step when requested. + + !!!Warning + + Do not delete the Klio Server's Pod yet, nor the + StatefulSet. The situation will settle after you + perform the following steps in this section. + !!! + +5. Generate an Age key pair: + + ```bash + age-keygen -o identity.txt + # Note the public key from the output + ``` + +6. Encrypt the existing key with Age: + + ```bash + echo -n "$ENCRYPTION_KEY" | age \ + -r \ + -o encryption-key.age --armor + ``` + +7. Create new Kubernetes Secrets: + + ```bash + kubectl create secret generic my-server-encryption-key \ + --from-file=encryption-key.age + kubectl create secret generic my-server-age-identity \ + --from-file=identity.txt + ``` + +8. Update the `tier1` section of the `Server` resource, + replacing the old `encryptionKey` field with the new + fields: + + ```yaml + # Before (remove this): + # encryptionKey: + # name: my-server-encryption + # key: encryptionKey + + # After: + encryptionKeyFile: + fileReference: + volume: + secret: + secretName: my-server-encryption-key + path: encryption-key.age + identityFile: + fileReference: + volume: + secret: + secretName: my-server-age-identity + path: identity.txt + ``` + + !!!Note + + Add the same sections in `tier2`, in case it is enabled. + !!! + +9. Apply the updated `Server` resource, then verify the Klio + server pod restarts successfully. + + In case the Server's Pod is stuck in `CrashLoopBackOff` state, + please delete it, then check again. + +10. Once verified, delete the old plaintext secret and the + local `identity.txt` file: + + ```bash + kubectl delete secret my-server-encryption + rm identity.txt + ``` diff --git a/product_docs/docs/klio/0/wal_streaming.mdx b/product_docs/docs/klio/0/wal_streaming.mdx new file mode 100644 index 00000000000..4d93e145438 --- /dev/null +++ b/product_docs/docs/klio/0/wal_streaming.mdx @@ -0,0 +1,122 @@ +--- +title: WAL Streaming +originalFilePath: >- + https://github.com/EnterpriseDB/klio/blob/main/documentation/web/versioned_docs/version-0.0.15/user/wal_streaming.md +sidebar_position: 4 + +--- + +A standout feature of Klio is its native, cloud-first implementation of WAL +streaming for PostgreSQL. This architecture enables: + +- Partial WAL segment streaming, ensuring real-time data transfer +- Built-in compression and encryption using user-provided keys +- Controlled replication slot advancement, protecting against WAL loss +- Optional synchronous replication, offering zero RPO when enabled + +## Architecture + +WAL streaming in Klio is built around two components: a client and a server. + +- The client, invoked using the `klio send-wal` command, typically runs + alongside PostgreSQL but does not have to. +- The server, started with the `klio server start-wal` command, runs as a + dedicated process on the Klio server. + +In Kubernetes environments, as illustrated in the diagram above, Klio streams +WAL records directly from the PostgreSQL primary over a local Unix domain +socket. The WAL streamer runs as a lightweight sidecar container within the +same pod as the primary instance and is managed by the CNPG-I–compliant plugin. +It continuously pushes data to a remote Klio WAL server (Tier 1), which handles +partial WAL file synchronization and archives completed segments into the +central WAL archive for the PostgreSQL cluster. + +![WAL streaming architectural overview](images/wal-streaming.png) + +## Moving Beyond `archive_command` + +Klio replaces the traditional PostgreSQL `archive_command` method for WAL +handling in CloudNativePG clusters, providing improved reliability, efficiency, +security, and observability. + +PostgreSQL’s `archive_command` is a shell command executed when a WAL segment +is complete—either because the segment reached its size limit (typically 16MB) +or the `archive_timeout` elapsed (5 minutes by default in CloudNativePG). + +The streaming model provided by Klio offers several key advantages over this +approach: + +- **Near-zero RPO:** WAL changes are streamed incrementally in near real-time, + reducing the worst-case recovery point objective (RPO) from 5 minutes to + near-zero, or even zero in synchronous mode. + +- **Improved efficiency and scalability:** A single, continuously running WAL + streamer process replaces the need to spawn a new process for each WAL + segment, resulting in lower CPU and I/O usage and better scalability during + periods of high WAL volume. + +- **Enhanced security:** WAL data is encrypted end-to-end, both in transit and + at rest, providing protection not available with the traditional + `archive_command`. + +- **Comprehensive observability:** Native metrics and structured logging + provide full visibility into WAL streaming operations, simplifying + monitoring, anomaly detection, and troubleshooting compared to the opaque + nature of `archive_command`. + +## Monitoring Klio WAL Streamer in PostgreSQL + +The Klio WAL streamer is a PostgreSQL streaming replication client and, +as such, can be monitored using the standard `pg_stat_replication` +system view in the PostgreSQL catalog. + +The WAL streamer identifies itself with `application_name` set to `klio`. + +To verify whether any Klio WAL streamer is connected to an instance (in +Kubernetes deployments, this will always be the primary), run the following +query: + +```sql +SELECT * FROM pg_stat_replication WHERE application_name = 'klio'; +``` + +An example output might look like this: + +The following excerpt is an a example: + +```console +-[ RECORD 1 ]----+------------------------------ +pid | 1070 +usesysid | 10 +usename | postgres +application_name | klio +client_addr | +client_hostname | +client_port | -1 +backend_start | 2025-08-07 01:14:39.619662+00 +backend_xmin | +state | streaming +sent_lsn | 2/C765A000 +write_lsn | 2/C75FA000 +flush_lsn | 2/C741A000 +replay_lsn | 2/C741A000 +write_lag | 00:00:00.919907 +flush_lag | 00:00:00.923556 +replay_lag | 00:00:00.923556 +sync_priority | 0 +sync_state | async +reply_time | 2025-08-07 01:54:44.756306+00 +``` + +As you can see, Klio provides relevant feedback to PostgreSQL. Here is a brief +explanation of the key fields: + +- `state`: The replication connection status (`streaming` indicates active + streaming). +- `sent_lsn`, `write_lsn`, `flush_lsn`, `replay_lsn`: Positions in the WAL + indicating how far data has been sent, written, flushed, and replayed on the + Klio server (replayed and flushed are always identical). +- `write_lag`, `flush_lag`, `replay_lag`: Delays between WAL positions + indicating replication latency. +- `sync_state`: The synchronization state of this standby (e.g., `async`, + `sync`, `potential`, `quorum`). diff --git a/product_docs/docs/klio/0/walplayer.mdx b/product_docs/docs/klio/0/walplayer.mdx new file mode 100644 index 00000000000..a82a5227472 --- /dev/null +++ b/product_docs/docs/klio/0/walplayer.mdx @@ -0,0 +1,338 @@ +--- +title: WAL Player +originalFilePath: >- + https://github.com/EnterpriseDB/klio/blob/main/documentation/web/versioned_docs/version-0.0.15/user/walplayer.md +sidebar_position: 80 + +--- + +The WAL Player is a command-line tool designed to benchmark the performance of +your Klio servers by simulating PostgreSQL Write-Ahead Log (WAL) file streaming +workloads. It is an essential tool for ensuring your Klio servers can handle +your production workloads efficiently. Use it regularly to validate performance +and capacity planning decisions. + +## Overview + +WAL Player provides two main commands: + +- **`generate`** - Creates synthetic WAL files for testing +- **`play`** - Sends WAL files to a Klio server and measures performance + +This tool is essential for: + +- Performance testing and benchmarking Klio servers +- Validating server capacity under different workloads +- Measuring throughput and latency characteristics +- Load testing before production deployment + +## Prerequisites + +- Klio binary installed and accessible +- A running Klio server to test against +- Sufficient disk space for generating test WAL files + +## Commands + +### `klio wal-player generate` + +Generates synthetic WAL files for testing purposes. + +#### Usage + +```bash +klio wal-player generate [output-directory] [flags] +``` + +#### Parameters + +- `output-directory` - Directory where WAL files will be created (defaults to + current directory) + +#### Flags + +- `--wal-size` - Size of each WAL file in MB (default: 16) +- `--length` - Number of WAL files to generate (required) + +#### Examples + +```bash +# Generate 10 WAL files of 16MB each in the current directory +klio wal-player generate --length 10 + +# Generate 50 WAL files of 32MB each in a specific directory +klio wal-player generate /tmp/test-wals --wal-size 32 --length 50 +``` + +### `klio wal-player play` + +Sends WAL files to a Klio server and measures performance metrics. + +#### Usage + +```bash +klio wal-player play [directory] [flags] +``` + +#### Parameters + +- `directory` - Directory containing WAL files to send (required). This + directory should contain PostgreSQL WAL files in the standard format (e.g., + `000000010000000000000001`). It also supports files compressed with gzip, + provided they have the `.gz` extension. + +#### Flags + +- `--jobs, -j` - Number of parallel jobs for concurrent uploads (default: 1). + Can be used to simulate multiple Klio clients sending data simultaneously. +- `--block-size` - Block size in KB for streaming (default: 2048). This controls + how much data is sent in each request. + +#### Configuration + +The play command requires client configuration to connect to your Klio server. +This can be provided via: + +- Configuration file +- Environment variables +- Command-line flags + +Example configuration: + +```yaml +# klio-config.yaml +client: + cluster_name: walplayer + wal: + address: localhost:52000 + server_cert_path: "/path/to/server.crt" + client_cert_path: "/path/to/client/tls.crt" + client_key_path: "/path/to/client/tls.key" +``` + +#### Examples + +```bash +# Send WAL files using single connection +klio wal-player play ./test-wals + +# Send WAL files using 4 workers for parallel uploads +klio wal-player play ./test-wals --jobs 4 + +# Benchmark with different block sizes +klio wal-player play ./test-wals --jobs 2 --block-size 1024 +``` + +## Performance Metrics + +The `play` command outputs detailed performance metrics in JSON format for each +WAL file: + +```json +{ + "walFullPath": "/path/to/000000010000000000000001", + "startTime": "2025-01-15T10:30:00Z", + "endTime": "2025-01-15T10:30:02Z", + "elapsedTime": "7651680", + "error": "" +} +``` + +### Metrics Explained + +- **`walFullPath`** - Full path to the WAL file that was sent +- **`startTime`** - When the upload started +- **`endTime`** - When the upload completed +- **`elapsedTime`** - Total time taken for the upload in nanoseconds +- **`error`** - Error message if the upload failed (empty on success) + +## Benchmarking Example + +The following Kubernetes Job definition demonstrates how to use +the WAL Player to benchmark a Klio server. This example covers generating +WAL files and then playing them back to the server. + + + +```yaml +--- +# PVC for storing generated WAL files +apiVersion: v1 +kind: PersistentVolumeClaim +metadata: + name: walplayer-data +spec: + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 2Gi # Enough space to hold the generated amount of WAL files +--- +# Client certificate for authenticating with the Klio server +apiVersion: cert-manager.io/v1 +kind: Certificate +metadata: + name: walplayer-client-cert +spec: + commonName: klio@walplayer + secretName: walplayer-client-cert + duration: 2160h # 90d + renewBefore: 360h # 15d + isCA: false + usages: + - client auth + issuerRef: + name: server-sample-ca + kind: Issuer + group: cert-manager.io +--- +# ConfigMap with klio client configuration +apiVersion: v1 +kind: ConfigMap +metadata: + name: walplayer-config +data: + # Address your klio server + klio-config.yaml: | + client: + cluster_name: walplayer + wal: + address: server-sample.default:52000 + server_cert_path: /certs/server/ca.crt + client_cert_path: /certs/client/tls.crt + client_key_path: /certs/client/tls.key +--- +# Job to generate and play WAL files +apiVersion: batch/v1 +kind: Job +metadata: + name: walplayer-benchmark +spec: + template: + metadata: + labels: + app: walplayer + spec: + restartPolicy: Never + initContainers: + # Generate synthetic WAL files + - name: generate-wals + image: docker.enterprisedb.com/k8s/klio:v0.0.15 + imagePullPolicy: Always + command: + - /usr/bin/klio + - wal-player + - generate + - /data + - --wal-size=16 + - --length=100 + volumeMounts: + - name: data + mountPath: /data + containers: + # Play WAL files to the Klio server + - name: play-wals + image: docker.enterprisedb.com/k8s/klio:v0.0.15 + imagePullPolicy: Always + command: + - /usr/bin/klio + - wal-player + - play + - /data + - --config=/config/klio-config.yaml + - --jobs=4 + - --block-size=2048 + volumeMounts: + - name: data + mountPath: /data + - name: config + mountPath: /config + readOnly: true + - name: server-cert + mountPath: /certs/server + readOnly: true + - name: client-cert + mountPath: /certs/client + readOnly: true + volumes: + - name: data + persistentVolumeClaim: + claimName: walplayer-data + - name: config + configMap: + name: walplayer-config + - name: server-cert + secret: + secretName: server-sample-tls + - name: client-cert + secret: + secretName: walplayer-client-cert +``` + + + +### Customizing the Benchmark + +You can adjust the following parameters to simulate different workload scenarios: + +#### WAL Generation Parameters + +Modify the `generate-wals` init container to create different test workloads: + +- Many small files: + + ```yaml + - --wal-size=16 + - --length=1000 + ``` + +- Less large files: + + ```yaml + - --wal-size=256 + - --length=100 + ``` + +Match actual production for better results. + +#### WAL Playback Parameters + +Modify the `play-wals` container to test different upload patterns: + +- **Jobs** (`--jobs`): Number of parallel upload workers + - Start with `--jobs=1` to establish baseline performance + - Increase to `--jobs=2`, `--jobs=4`, `--jobs=8` to find optimal concurrency + - Performance typically plateaus at some point +- **Block Size** (`--block-size`): Size of each streaming chunk in KB + - Default is `--block-size=2048` + - Maximum is 8192 + +### Analyzing Results + +View the job logs to see the JSON performance metrics: + +```bash +kubectl logs job/walplayer-benchmark -c play-wals +``` + +You can analyze the output using `jq`: + +```bash +# Get all results +kubectl logs job/walplayer-benchmark -c play-wals > results.json + +# Calculate total successful uploads +jq -s '[.[] | select(.error == "")] | length' results.json + +# Calculate average upload time (in nanoseconds) +jq -s '[.[] | select(.error == "") | .elapsedTime | tonumber] | add / length' results.json + +# Find any failed uploads +jq -s '.[] | select(has("error") and .error != "")' results.json +``` + +## Performance Optimization Tips + +1. **Resource Monitoring**: Monitor CPU, memory, and disk I/O on the Klio server +2. **Network Bandwidth**: Ensure sufficient bandwidth between client and server +3. **Storage Performance**: Verify storage can handle the write throughput diff --git a/src/constants/products.js b/src/constants/products.js index c840f5ad400..816a6bf0007 100644 --- a/src/constants/products.js +++ b/src/constants/products.js @@ -63,6 +63,11 @@ const products = { alteruser_utility: { name: "alteruser", iconName: IconNames.TOOLS }, edb_sqlpatch: { name: "EDB SQL Patch", iconName: IconNames.TOOLS }, language_pack: { name: "Language Pack", iconName: IconNames.TOOLS }, + klio: { + name: "Enterprise Data Protection for CloudNativePG™", + shortName: "Klio", + iconName: IconNames.BACKUP, + }, lasso: { name: "Lasso" }, livecompare: { name: "LiveCompare", iconName: IconNames.INTEGRATION }, "Migration Handbook": { name: "Migration Handbook" }, diff --git a/src/styles/_admonitions.scss b/src/styles/_admonitions.scss index 07ece9ae5e0..98d0f962f43 100644 --- a/src/styles/_admonitions.scss +++ b/src/styles/_admonitions.scss @@ -10,7 +10,7 @@ .admonition-info { @extend .alert-secondary; } -.admonition-warning { +.admonition-warning, .admonition-caution { @extend .alert-warning; } .admonition-danger { @@ -89,7 +89,7 @@ } } -.admonition-warning { +.admonition-warning, .admonition-caution { > .admonition-heading h5:before { mask-image: url('data:image/svg+xml;utf8,'); }