Skip to content

feat(compression): allow configuring the Kopia compression policy - #189

Open
gabriele-wolfox wants to merge 3 commits into
mainfrom
dev/126
Open

feat(compression): allow configuring the Kopia compression policy#189
gabriele-wolfox wants to merge 3 commits into
mainfrom
dev/126

Conversation

@gabriele-wolfox

Copy link
Copy Markdown
Contributor

What

Kopia repositories were created without a compression policy, so base backup
data was stored uncompressed. This lets users configure Kopia compression for
base backups, both globally and per cluster.

Configuration

Compression can be set at two levels, following Kopia's policy inheritance
(a per-cluster policy overrides the global one for that cluster's source):

  • Global (repository-wide) on the Server, under spec.tier1.compression
    and spec.tier2.compression. Applied to Kopia's global policy when the
    server starts.
  • Per cluster on the PluginConfiguration, under spec.tier1.compression
    and spec.tier2.compression. Applied to the cluster's own source.

Each policy exposes:

  • algorithm: any Kopia compressor (e.g. zstd, s2-default, gzip) or
    none to disable compression.
  • minSize / maxSize (optional, bytes): restrict compression to files within
    a size range.

Both tier1 and tier2 are covered. Compression takes effect on the next backup;
existing backups are not recompressed.

Example:

apiVersion: klio.cnpg.io/v1alpha1
kind: PluginConfiguration
spec:
  clusterName: cluster-example
  tier1:
    compression:
      algorithm: zstd
      minSize: 4096
  tier2:
    enableBackup: true
    compression:
      algorithm: zstd-better-compression
      minSize: 4096

Out of scope

Kopia's only-compress / never-compress extension lists are not exposed:
they select files by extension, which does not fit a PostgreSQL data directory
(relation files are numeric), and WAL files are compressed separately.

Testing

A new e2e (compression_test.go) sets a global policy on the Server and a
different per-cluster policy on the PluginConfiguration, runs a backup, and
asserts via kopia policy show that both the --global and user@host
policies carry the expected algorithm and minSize on tier1 and tier2. Docs,
CRDs, Helm chart, and generated API reference are updated.

Closes #126

Assisted-by: Claude

gabriele-wolfox and others added 3 commits September 2, 2026 13:07
Kopia repositories were created without a compression policy, so base
backup data was stored uncompressed. Allow users to configure a
compression policy repository-wide on the Server (applied to the global
Kopia policy at server start) and per-cluster on the PluginConfiguration
(applied to the cluster's own source, overriding the global policy).
Both tier1 and tier2 are covered: tier1 is set through the Kopia server
during the backup, while tier2 travels over gRPC and is applied by the
backup consumer before the relay.

The policy exposes the compression algorithm plus the optional minSize
and maxSize bounds (in bytes) that restrict which files are compressed.
Kopia's only-compress and never-compress extension lists are left out on
purpose: they select files by extension, which does not fit a PostgreSQL
data directory (relation files are numeric and carry no meaningful
extension), and WAL files are compressed on a separate path regardless.

Closes #126

Assisted-by: Claude

Signed-off-by: Gabriele Quaresima <gabriele.quaresima@enterprisedb.com>
The policy builder emitted `--compression-min-size` and
`--compression-max-size` only for non-zero values, so a bound written to
the Kopia repository could never be removed: no value of the
configuration field produced a flag that reset it, and files outside the
stale range silently stayed uncompressed.

Both bounds are now always emitted, with zero rendered as `inherit`,
which Kopia resets to the value inherited from the parent policy.

Document that removing the whole `compression` section still leaves the
stored policy in place, and that `algorithm: none` is the way to stop
compressing.

Refs #126

Signed-off-by: Armando Ruocco <armando.ruocco@enterprisedb.com>
A `minSize` above a non-zero `maxSize` matches no file at all: Kopia
accepts the policy and then skips compression for every file, so the
resource reported compression as enabled while nothing was compressed.

The range is now validated in the client policy, in the tier1 and tier2
server configuration, and through a CEL rule on the shared CRD type, so
an inconsistent range is refused at admission. The check runs even when
no algorithm is set, because the size bounds are applied independently
of it.

Refs #126

Signed-off-by: Armando Ruocco <armando.ruocco@enterprisedb.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Support configuring Kopia compression policy

2 participants