charmlibs-interfaces-k8s-backup-target 0.1.0__tar.gz

charmlibs_interfaces_k8s_backup_target-0.1.0/.gitignore

@@ -0,0 +1,184 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.coverage-*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+.report/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/latest/usage/project/#working-with-version-control
+.pdm.toml
+.pdm-python
+.pdm-build/
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+.idea/
+
+# PyPI configuration file
+.pypirc
+
+# packed charms
+.packed
+
+# temporary directory for packing charms
+.tmp
+
+# uv.lock from example libraries as we don't commit these
+.example/**/uv.lock
+.tutorial/**/uv.lock
+interfaces/.example/**/uv.lock

charmlibs_interfaces_k8s_backup_target-0.1.0/CHANGELOG.md

@@ -0,0 +1,3 @@
+# 0.1.0 - 5 March 2026
+
+Initial release of the `k8s_backup_target` interface library.

charmlibs_interfaces_k8s_backup_target-0.1.0/PKG-INFO

@@ -0,0 +1,28 @@
+Metadata-Version: 2.4
+Name: charmlibs-interfaces-k8s-backup-target
+Version: 0.1.0
+Summary: The charmlibs.interfaces.k8s-backup-target package.
+Project-URL: Repository, https://github.com/canonical/charmlibs
+Project-URL: Issues, https://github.com/canonical/charmlibs/issues
+Author: The Charm Tech team at Canonical
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.10
+Requires-Dist: ops
+Requires-Dist: pydantic
+Description-Content-Type: text/markdown
+
+# charmlibs.interfaces.k8s_backup_target
+
+The `k8s_backup_target` interface library.
+
+To install, add `charmlibs-interfaces-k8s-backup-target` to your Python dependencies. Then in your Python code, import as:
+
+```py
+from charmlibs.interfaces import k8s_backup_target
+```
+
+See the [reference documentation](https://documentation.ubuntu.com/charmlibs/reference/charmlibs/interfaces/k8s_backup_target).

charmlibs_interfaces_k8s_backup_target-0.1.0/README.md

@@ -0,0 +1,11 @@
+# charmlibs.interfaces.k8s_backup_target
+
+The `k8s_backup_target` interface library.
+
+To install, add `charmlibs-interfaces-k8s-backup-target` to your Python dependencies. Then in your Python code, import as:
+
+```py
+from charmlibs.interfaces import k8s_backup_target
+```
+
+See the [reference documentation](https://documentation.ubuntu.com/charmlibs/reference/charmlibs/interfaces/k8s_backup_target).

charmlibs_interfaces_k8s_backup_target-0.1.0/interface/v0/README.md

@@ -0,0 +1,60 @@
+# `k8s_backup_target/v0`
+
+## Overview
+
+The `k8s_backup_target` interface enables a **client charm** to specify what Kubernetes data should be backed up by relating to a **backup charm or backup integrator charm**. In practice, a client charm declares the namespaces and resource types to include or exclude in backups, and the backup charm or integrator uses this specification to forward backup requests to a backup operator. This design lets the client define backup requirements **without direct cluster elevated permissions**, delegating the backup execution to the backup operator charm.
+
+## Direction
+
+This is a unidirectional interface where the provider (client) sends data and the requirer (backup charm or backup integrator) only receives data. There is no data sent back from the requirer side.
+
+```mermaid
+flowchart TD
+    Provider -- endpoint, app_name, model, spec --> Requirer
+```
+
+## Behavior
+
+- **Provider (Client Charm)**: Provides the backup specification via its application relation data. Typically, a client charm will set this data as soon as the relation is formed.
+- **Requirer (Backup Charm or Backup Integrator Charm)**: Consumes the spec. It does not send any data over the relation. If the requirer is an integrator charm, it should listens for changes to the relation data and forward the received spec to the backup operator it is related to.
+
+## Relation Data
+
+[\[Pydantic Schema\]](./schema.py)
+
+On the provider side, the application data bag must contain structure with the following fields:
+
+- `app` (string, required): Name of the client application that requires backups.
+- `relation_name` (string, required): Name of the relation on the client side through which this spec is sent (from metadata.yaml).
+- `model` (string, required): Name of the model where the client application is deployed.
+- `spec` (dict, required): A dictionary defining what to back up. The spec structure is based on [Velero's resource filtering model](https://velero.io/docs/main/resource-filtering/) but is designed to be generic enough for alternative backup providers in future. This includes the following keys:
+  - `include_namespaces` (list of str, optional): Specific Kubernetes namespaces to include in the backup. If not provided (None), all namespaces are included.
+  - `include_resources` (list of str, optional): Specific Kubernetes resource kinds to include in the backup. If not provided (None), all resource types are included.
+  - `exclude_namespaces` (list of str, optional): Namespaces to exclude from the backup.
+  - `exclude_resources` (list of str, optional): Resource kinds to exclude from the backup.
+  - `include_cluster_resources` (bool, optional): Whether to include cluster-scoped resources in the backup.
+  - `label_selector` (dict, optional): A label selector to filter resources for backup.
+  - `ttl` (string, optional): Time-to-live duration for the backup (e.g., "72h", "30d").
+
+### Provider
+
+#### Example
+
+```yaml
+  application-data:
+    app: my-app
+    relation_name: backup
+    model: my-model
+    spec:
+        include_namespaces: ["my-namespace"]
+        include_resources: ["persistentvolumeclaims", "services", "deployments"]
+        exclude_resources: null
+        exclude_namespaces: null
+        label_selector: {"app": "my-app"}
+        include_cluster_resources: false
+        ttl: "24h"
+```
+
+### Requirer
+
+N/A

charmlibs_interfaces_k8s_backup_target-0.1.0/interface/v0/interface.yaml

@@ -0,0 +1,16 @@
+name: k8s_backup_target
+version: 0
+status: draft
+lib: charmlibs.interfaces.k8s_backup_target
+summary: Configure Kubernetes backup target specifications.
+description: |
+  The `k8s_backup_target` interface allows client charms to specify Kubernetes backup requirements to a backup integrator charm.
+  The provider charm (client) provides backup specifications including namespaces, resource types, and retention policies, while the requirer charm (backup integrator) receives these specifications and forwards them to a backup operator.
+
+requirers:
+  - name: velero-integrator-operator
+    url: https://github.com/canonical/velero-integrator-operator
+
+providers: []
+
+maintainer: analytics

charmlibs_interfaces_k8s_backup_target-0.1.0/interface/v0/schema.py

@@ -0,0 +1 @@
+../../src/charmlibs/interfaces/k8s_backup_target/_schema.py

charmlibs_interfaces_k8s_backup_target-0.1.0/pyproject.toml

@@ -0,0 +1,76 @@
+[project]
+name = "charmlibs-interfaces-k8s-backup-target"
+description = "The charmlibs.interfaces.k8s-backup-target package."
+readme = "README.md"
+requires-python = ">=3.10"
+authors = [
+    {name="The Charm Tech team at Canonical"},
+]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: Apache Software License",
+    "Intended Audience :: Developers",
+    "Operating System :: POSIX :: Linux",
+    "Development Status :: 4 - Beta",
+]
+dynamic = ["version"]
+dependencies = [
+    "ops",
+    "pydantic",
+]
+
+[dependency-groups]
+lint = [
+]
+unit = [
+    "ops[testing]",
+    "pytest",
+]
+functional = [
+]
+integration = [
+]
+
+[project.urls]
+"Repository" = "https://github.com/canonical/charmlibs"
+"Issues" = "https://github.com/canonical/charmlibs/issues"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/charmlibs"]
+
+[tool.hatch.version]
+path = "src/charmlibs/interfaces/k8s_backup_target/_version.py"
+
+[tool.ruff]
+extend = "../../pyproject.toml"
+src = ["src", "tests/unit", "tests/functional", "tests/integration"]
+
+[tool.ruff.format]
+quote-style = "preserve"
+
+[tool.ruff.lint.extend-per-file-ignores]
+"./**/schema.py" = [
+    "CPY",  # copyright
+    "D",  # docs
+    "E501",  # line too long
+]
+"tests/**/*" = [
+    "E501",
+]
+
+[tool.pyright]
+extends = "../../pyproject.toml"
+include = ["src", "tests"]
+pythonVersion = "3.10"
+
+[tool.charmlibs.functional]
+ubuntu = []
+pebble = []
+sudo = false
+
+[tool.charmlibs.integration]
+tags = []

charmlibs_interfaces_k8s_backup_target-0.1.0/ruff.toml

@@ -0,0 +1,18 @@
+extend = "../../pyproject.toml"
+
+[format]
+quote-style = "preserve"
+
+[lint.extend-per-file-ignores]
+"./**/schema.py" = [
+    "CPY",  # copyright
+    "D",  # docs
+    "E501",  # line too long
+]
+"./interface/v*/tests/*.py" = [
+    "CPY",  # copyright
+    "D",  # docs
+    "S",  # security
+    "E501",  # line too long
+    "F841",  # assignment to unused variable
+]

charmlibs_interfaces_k8s_backup_target-0.1.0/src/charmlibs/interfaces/k8s_backup_target/__init__.py

@@ -0,0 +1,89 @@
+# Copyright 2026 Canonical Ltd.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""K8s Backup Target library.
+
+This library implements the Requirer and Provider roles for the ``k8s_backup_target`` relation
+interface. It is used by client charms to declare backup specifications, and by backup charms or
+backup integrator charms to consume them and forward to backup operators.
+
+The ``k8s_backup_target`` interface allows a charm (the provider) to provide a declarative
+description of what Kubernetes resources should be included in a backup. These specifications are
+sent to the backup charm or backup integrator charm (the requirer), which merges them with schedule
+configuration and forwards to the backup operator.
+
+This interface follows a least-privilege model: client charms do not manipulate cluster resources
+themselves. Instead, they define what should be backed up and leave execution to the backup
+operator.
+
+Provider Example
+================
+
+::
+
+    from charmlibs.interfaces.k8s_backup_target import (
+        K8sBackupTargetProvider,
+        K8sBackupTargetSpec,
+    )
+
+    class SomeCharm(CharmBase):
+        def __init__(self, *args):
+            # ...
+            self.backup = K8sBackupTargetProvider(
+                self,
+                relation_name="backup",
+                spec=K8sBackupTargetSpec(
+                    include_namespaces=["my-namespace"],
+                    include_resources=["persistentvolumeclaims", "services", "deployments"],
+                    ttl=str(self.config["ttl"]),
+                ),
+                # Optional: refresh the data on custom events
+                refresh_event=[self.on.config_changed],
+            )
+
+Requirer Example
+================
+
+::
+
+    from charmlibs.interfaces.k8s_backup_target import (
+        K8sBackupTargetRequirer,
+    )
+
+    class BackupIntegratorCharm(CharmBase):
+        def __init__(self, *args):
+            # ...
+            self.backup_requirer = K8sBackupTargetRequirer(self, relation_name="k8s-backup-target")
+
+        def _on_backup_action(self, event):
+            spec = self.backup_requirer.get_backup_spec(
+                app_name=event.params["app"],
+                endpoint=event.params["endpoint"],
+                model=event.params["model"],
+            )
+            ...
+"""
+
+from ._backup_target import (
+    K8sBackupTargetProvider,
+    K8sBackupTargetRequirer,
+)
+from ._schema import K8sBackupTargetSpec
+from ._version import __version__ as __version__
+
+__all__ = [
+    "K8sBackupTargetProvider",
+    "K8sBackupTargetRequirer",
+    "K8sBackupTargetSpec",
+]

charmlibs_interfaces_k8s_backup_target-0.1.0/src/charmlibs/interfaces/k8s_backup_target/_backup_target.py

@@ -0,0 +1,162 @@
+# Copyright 2026 Canonical Ltd.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""K8s Backup Target library implementation."""
+
+import logging
+
+import ops
+from ops import BoundEvent, EventBase
+from ops.charm import CharmBase
+from ops.framework import Object
+
+from ._schema import BackupTargetEntry, K8sBackupTargetSpec, ProviderAppData
+
+logger = logging.getLogger(__name__)
+
+
+class K8sBackupTargetRequirer:
+    """Requirer class for the backup target configuration relation."""
+
+    def __init__(self, charm: CharmBase, relation_name: str):
+        """Initialize the requirer.
+
+        Args:
+            charm: The charm instance that requires backup configuration.
+            relation_name: The name of the relation (from metadata.yaml).
+        """
+        self._charm = charm
+        self._relation_name = relation_name
+
+    @staticmethod
+    def _load_provider_data(relation: ops.Relation) -> ProviderAppData | None:
+        """Load and validate provider app data from a relation."""
+        try:
+            return relation.load(ProviderAppData, relation.app)
+        except (ops.RelationDataError, ValueError):
+            return None
+
+    @property
+    def is_ready(self) -> bool:
+        """Check if the relation has valid backup target data.
+
+        Returns:
+            True if at least one relation has parseable backup_targets data.
+        """
+        relations = self._charm.model.relations[self._relation_name]
+        for relation in relations:
+            data = self._load_provider_data(relation)
+            if data and data.backup_targets:
+                return True
+        return False
+
+    def get_backup_spec(
+        self, app_name: str, endpoint: str, model: str
+    ) -> K8sBackupTargetSpec | None:
+        """Get a K8sBackupTargetSpec for a given (app, endpoint, model).
+
+        Args:
+            app_name: The name of the application for which the backup is configured.
+            endpoint: The name of the relation (from metadata.yaml).
+            model: The model name of the application.
+
+        Returns:
+            The backup specification if available, otherwise None.
+        """
+        relations = self._charm.model.relations[self._relation_name]
+
+        for relation in relations:
+            data = self._load_provider_data(relation)
+            if not data:
+                continue
+            for entry in data.backup_targets:
+                if (
+                    entry.app == app_name
+                    and entry.model == model
+                    and entry.relation_name == endpoint
+                ):
+                    return entry.spec
+
+        logger.warning("No backup spec found for app '%s' and endpoint '%s'", app_name, endpoint)
+        return None
+
+
+class K8sBackupTargetProvider(Object):
+    """Provider class for the backup target configuration relation."""
+
+    def __init__(
+        self,
+        charm: CharmBase,
+        relation_name: str,
+        spec: K8sBackupTargetSpec,
+        refresh_event: BoundEvent | list[BoundEvent] | None = None,
+    ):
+        """Initialize the provider with the specified backup configuration.
+
+        Args:
+            charm: The charm instance that provides backup.
+            relation_name: The name of the relation (from metadata.yaml).
+            spec: The backup specification to be used.
+            refresh_event: Optional event(s) to trigger data sending.
+        """
+        super().__init__(charm, relation_name)
+        self._charm = charm
+        self._app_name = self._charm.app.name
+        self._model = self._charm.model.name
+        self._relation_name = relation_name
+        self._spec = spec
+
+        self.framework.observe(self._charm.on.leader_elected, self._send_data)
+        self.framework.observe(
+            self._charm.on[self._relation_name].relation_created, self._send_data
+        )
+        self.framework.observe(self._charm.on.upgrade_charm, self._send_data)
+
+        if refresh_event:
+            if not isinstance(refresh_event, tuple | list):
+                refresh_event = [refresh_event]
+            for event in refresh_event:
+                self.framework.observe(event, self._send_data)
+
+    def _send_data(self, event: EventBase):
+        """Handle any event where we should send data to the relation."""
+        if not self._charm.model.unit.is_leader():
+            logger.debug(
+                "K8sBackupTargetProvider handled send_data event when it is not a leader. "
+                "Skipping event - no data sent"
+            )
+            return
+
+        relations = self._charm.model.relations.get(self._relation_name)
+
+        if not relations:
+            logger.warning(
+                "K8sBackupTargetProvider handled send_data event but no relation '%s' found. "
+                "Skipping event - no data sent",
+                self._relation_name,
+            )
+            return
+
+        entry = BackupTargetEntry(
+            app=self._app_name,
+            relation_name=self._relation_name,
+            model=self._model,
+            spec=self._spec,
+        )
+        provider_data = ProviderAppData(
+            backup_targets=[entry],
+        )
+
+        for relation in relations:
+            relation.save(provider_data, self._charm.app)