cnpg-drill 0.1.2__tar.gz

cnpg_drill-0.1.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 cnpg-drill contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

cnpg_drill-0.1.2/PKG-INFO

@@ -0,0 +1,131 @@
+Metadata-Version: 2.4
+Name: cnpg-drill
+Version: 0.1.2
+Summary: Prove CloudNativePG Barman backups restore into an isolated cluster
+Author: cnpg-drill contributors
+License: MIT License
+        
+        Copyright (c) 2026 cnpg-drill contributors
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Keywords: cloudnativepg,postgresql,kubernetes,backup,restore
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# cnpg-drill
+
+**Prove that a CloudNativePG backup can restore.** `cnpg-drill` creates a disposable CloudNativePG cluster from the source cluster's Barman Cloud object store, waits for PostgreSQL to become ready, runs read-only SQL assertions, emits a JSON result, and deletes the drill cluster. It can run locally or on a schedule as a Kubernetes CronJob.
+
+The core is free and works without an account or external service. It does not make backups or copy database contents to a vendor. The proposed hosted service in [RESEARCH.md](RESEARCH.md) is separate and has not been built.
+
+## Status
+
+**Early alpha.** Unit tests cover manifest safety and execution state. A disposable [local integration run](integration/local/README.md) on v0.1.0 proved full restore, PITR, read-only archive access, denied-WAL reporting, failed-check reporting, and Cluster/PVC cleanup on one version matrix. The v0.1.1 release archive and public chart 0.1.2 also restored a fresh backup and checked a row in an application database. A separate single-node pgEdge chart restore passed SQL checks in its `app` database. Validate against your operator, PostgreSQL image, storage, object store, and Barman plugin versions before treating a pass as disaster recovery assurance.
+
+The [v0.1.2 release](https://github.com/danielgaskins/cnpg-drill/releases/tag/v0.1.2) carries literal AWS checksum compatibility settings into recovery clusters without copying source credentials. It includes the MIT-licensed kubectl plugin archive and checksum. The [default Krew index submission](https://github.com/kubernetes-sigs/krew-index/pull/6373) and [custom Krew index submission](https://github.com/ishantanu/awesome-kubectl-plugins/pull/44) currently package v0.1.0 and are under review. [kubetools](https://github.com/collabnix/kubetools/pull/431) is reviewing a Backup Tools listing.
+
+The [Helm chart is listed on Artifact Hub](https://artifacthub.io/packages/helm/cnpg-drill/cnpg-drill) as a Verified Publisher package. Chart version `0.1.2` uses the v0.1.1 application image and includes the publisher's [website](https://danielgaskins.com/).
+
+## What it supports
+
+- One source CloudNativePG cluster with one enabled Barman Cloud plugin and a named `ObjectStore` in the same namespace.
+- An optional separate `recoveryObjectStore` with credentials limited to archive reads. Preflight checks that its destination and endpoint match the source store before creating a Cluster.
+- Full restore from the latest completed Barman plugin `Backup` resource, or PITR to an explicit RFC3339 `targetTime`. The selected backup ID is pinned and included in the report; a stale backup fails preflight.
+- Single-instance drill cluster using the source's PostgreSQL image, storage size/class, optional WAL storage, and resource requests.
+- Copies literal AWS checksum compatibility settings from the source Cluster for S3-compatible archive restores; it does not copy writer credentials or arbitrary environment variables.
+- Read-only SQL checks in `postgres` or a named application database. Exact expected values make reports easy to audit.
+- Optional timestamp freshness assertions (`maxAgeSeconds`) for an application-defined recovery point. This measures age of that application's data, not the database WAL RPO.
+- A JSON report on stdout and optionally in a local file. Query outputs are hashed rather than logged. Exit code 0 means all checks, Cluster deletion, and PVC cleanup passed; 1 means the drill failed; 2 means invalid input or a failed preflight.
+- Scheduled execution with the Helm CronJob in `deploy/helm/cnpg-drill`.
+
+The CLI refuses source clusters with tablespaces or recovery bootstrap because a naive clone could produce an incomplete or misleading pass. Volume snapshots, cross-namespace restores, cross-region recovery, custom Postgres extension image changes, and multi-cluster fleet management are future work.
+
+## Install and use
+
+For a first run on your own cluster, follow the [first-run guide](docs/FIRST-RUN.md).
+
+Requirements: Python 3.10+, `kubectl` in `PATH`, CloudNativePG and the Barman Cloud plugin installed in the target cluster, and Kubernetes access to read the source Cluster and ObjectStore, create/get/delete a drill Cluster, and exec into its PostgreSQL pod.
+
+```bash
+python3 -m pip install -e .
+cnpg-drill plan --config examples/drill.json
+cnpg-drill run --config examples/drill.json --report reports/latest.json
+```
+
+`plan` reads the source configuration and prints the exact Cluster manifest it would create. Review that manifest before running the first drill. The example's table-count assertion is illustrative; replace it with an invariant from your own application. A minimal check is `SELECT 1`, but it only proves connection to the recovered server, not useful application data.
+
+Example `drill.json`:
+
+```json
+{
+  "namespace": "production",
+  "cluster": "app-db",
+  "recoveryObjectStore": "app-db-recovery-readonly",
+  "timeoutSeconds": 1800,
+  "maxBackupAgeSeconds": 691200,
+  "checks": [
+    {"name": "postgres-ready", "query": "SELECT 1", "expected": "1"},
+    {"name": "orders-exist", "database": "app", "query": "SELECT count(*) > 0 FROM public.orders", "expected": "t"},
+    {"name": "recent-order", "database": "app", "query": "SELECT max(created_at)::timestamptz FROM public.orders", "maxAgeSeconds": 86400}
+  ]
+}
+```
+
+For PITR, add `"targetTime": "2026-09-29T10:00:00Z"`. Pick a time inside the backup and WAL retention window. A passing PITR check proves only that target; use a second drill for the latest recovery path.
+
+## Scheduled drill
+
+The Helm chart creates a namespace-scoped ServiceAccount, Role, RoleBinding, ConfigMap, and CronJob. Set `cluster`, `checks`, and the other settings in a values file and install it **in the same namespace as the source Cluster and ObjectStore**. The chart defaults to suspension so installation does not immediately start a restore.
+
+The example image build pins kubectl 1.36.4, suitable for Kubernetes 1.35–1.37 under the project's [version skew policy](https://kubernetes.io/releases/). Set `KUBECTL_VERSION` at image build time for another supported cluster version.
+
+```bash
+helm install cnpg-drill oci://ghcr.io/danielgaskins/charts/cnpg-drill \
+  --version 0.1.2 -n production -f drill-values.yaml
+```
+
+See the [first-run guide](docs/FIRST-RUN.md) and [chart values](deploy/helm/cnpg-drill/README.md) for a suspended first run with a separate read-only recovery ObjectStore. The chart pins a public multi-architecture image digest. The CronJob uses `concurrencyPolicy: Forbid` and a bounded job deadline. Its logs contain the JSON result; failed runs have nonzero exit status. **The chart does not yet provide durable report storage, missed-run alerts, or fleet policy.**
+
+## Safety boundary
+
+- The generated recovery Cluster never copies `spec.plugins`, so it is not configured to archive WAL back to the source bucket. Set `recoveryObjectStore` to a separately named `ObjectStore` with read-only archive credentials. The tool compares its destination and endpoint with the source store; it cannot verify credential permissions, so test that writes are denied before relying on this boundary. Omitting this field uses the source `ObjectStore` for compatibility.
+- A recovery timeout includes a machine-readable `failureReason` when the recovery Pod logs identify archive access denial or unavailable WAL. It does not copy raw logs into the report; inspect Pod and operator logs for detail.
+- The drill uses the same namespace because the plugin's `ObjectStore` and its credentials are namespace-scoped. The source Cluster object is never modified.
+- SQL checks run in a `BEGIN READ ONLY` transaction. Queries are limited to one `SELECT` or `WITH` statement without semicolons. Only provide trusted SQL; this is a guard against mistakes, not a security sandbox.
+- By default, the tool deletes the drill Cluster even when recovery or a check fails. `retainOnFailure` leaves it for investigation and can incur storage costs. Cleanup failures turn the result red.
+- The tool checks that PVCs labeled for the drill cluster disappear after Cluster deletion and fails the report if they remain. Kubernetes PersistentVolume cleanup depends on the storage class; inspect cloud volumes after a first drill.
+- The planned SaaS boundary is metadata only. This repository contains no telemetry upload or hosted service.
+
+## Contributing and upstream distribution
+
+Run `PYTHONPATH=src python3 -m unittest discover -s tests -v`. See [CONTRIBUTING.md](CONTRIBUTING.md) for how to add a recovery path, the live integration test gate, and the Krew package plan. We will submit only a tested, released package that stands on its own. Upstream acceptance is not assumed.
+
+[UPSTREAM.md](UPSTREAM.md) records the specific repositories, proposed contribution value, and submission gates.
+
+## Recovery references
+
+- [CloudNativePG backup guidance](https://cloudnative-pg.io/docs/devel/backup/)
+- [CloudNativePG recovery documentation](https://cloudnative-pg.io/docs/devel/recovery/)
+- [Barman Cloud recovery example](https://cloudnative-pg.io/plugin-barman-cloud/docs/next/concepts/)

cnpg_drill-0.1.2/README.md

@@ -0,0 +1,95 @@
+# cnpg-drill
+
+**Prove that a CloudNativePG backup can restore.** `cnpg-drill` creates a disposable CloudNativePG cluster from the source cluster's Barman Cloud object store, waits for PostgreSQL to become ready, runs read-only SQL assertions, emits a JSON result, and deletes the drill cluster. It can run locally or on a schedule as a Kubernetes CronJob.
+
+The core is free and works without an account or external service. It does not make backups or copy database contents to a vendor. The proposed hosted service in [RESEARCH.md](RESEARCH.md) is separate and has not been built.
+
+## Status
+
+**Early alpha.** Unit tests cover manifest safety and execution state. A disposable [local integration run](integration/local/README.md) on v0.1.0 proved full restore, PITR, read-only archive access, denied-WAL reporting, failed-check reporting, and Cluster/PVC cleanup on one version matrix. The v0.1.1 release archive and public chart 0.1.2 also restored a fresh backup and checked a row in an application database. A separate single-node pgEdge chart restore passed SQL checks in its `app` database. Validate against your operator, PostgreSQL image, storage, object store, and Barman plugin versions before treating a pass as disaster recovery assurance.
+
+The [v0.1.2 release](https://github.com/danielgaskins/cnpg-drill/releases/tag/v0.1.2) carries literal AWS checksum compatibility settings into recovery clusters without copying source credentials. It includes the MIT-licensed kubectl plugin archive and checksum. The [default Krew index submission](https://github.com/kubernetes-sigs/krew-index/pull/6373) and [custom Krew index submission](https://github.com/ishantanu/awesome-kubectl-plugins/pull/44) currently package v0.1.0 and are under review. [kubetools](https://github.com/collabnix/kubetools/pull/431) is reviewing a Backup Tools listing.
+
+The [Helm chart is listed on Artifact Hub](https://artifacthub.io/packages/helm/cnpg-drill/cnpg-drill) as a Verified Publisher package. Chart version `0.1.2` uses the v0.1.1 application image and includes the publisher's [website](https://danielgaskins.com/).
+
+## What it supports
+
+- One source CloudNativePG cluster with one enabled Barman Cloud plugin and a named `ObjectStore` in the same namespace.
+- An optional separate `recoveryObjectStore` with credentials limited to archive reads. Preflight checks that its destination and endpoint match the source store before creating a Cluster.
+- Full restore from the latest completed Barman plugin `Backup` resource, or PITR to an explicit RFC3339 `targetTime`. The selected backup ID is pinned and included in the report; a stale backup fails preflight.
+- Single-instance drill cluster using the source's PostgreSQL image, storage size/class, optional WAL storage, and resource requests.
+- Copies literal AWS checksum compatibility settings from the source Cluster for S3-compatible archive restores; it does not copy writer credentials or arbitrary environment variables.
+- Read-only SQL checks in `postgres` or a named application database. Exact expected values make reports easy to audit.
+- Optional timestamp freshness assertions (`maxAgeSeconds`) for an application-defined recovery point. This measures age of that application's data, not the database WAL RPO.
+- A JSON report on stdout and optionally in a local file. Query outputs are hashed rather than logged. Exit code 0 means all checks, Cluster deletion, and PVC cleanup passed; 1 means the drill failed; 2 means invalid input or a failed preflight.
+- Scheduled execution with the Helm CronJob in `deploy/helm/cnpg-drill`.
+
+The CLI refuses source clusters with tablespaces or recovery bootstrap because a naive clone could produce an incomplete or misleading pass. Volume snapshots, cross-namespace restores, cross-region recovery, custom Postgres extension image changes, and multi-cluster fleet management are future work.
+
+## Install and use
+
+For a first run on your own cluster, follow the [first-run guide](docs/FIRST-RUN.md).
+
+Requirements: Python 3.10+, `kubectl` in `PATH`, CloudNativePG and the Barman Cloud plugin installed in the target cluster, and Kubernetes access to read the source Cluster and ObjectStore, create/get/delete a drill Cluster, and exec into its PostgreSQL pod.
+
+```bash
+python3 -m pip install -e .
+cnpg-drill plan --config examples/drill.json
+cnpg-drill run --config examples/drill.json --report reports/latest.json
+```
+
+`plan` reads the source configuration and prints the exact Cluster manifest it would create. Review that manifest before running the first drill. The example's table-count assertion is illustrative; replace it with an invariant from your own application. A minimal check is `SELECT 1`, but it only proves connection to the recovered server, not useful application data.
+
+Example `drill.json`:
+
+```json
+{
+  "namespace": "production",
+  "cluster": "app-db",
+  "recoveryObjectStore": "app-db-recovery-readonly",
+  "timeoutSeconds": 1800,
+  "maxBackupAgeSeconds": 691200,
+  "checks": [
+    {"name": "postgres-ready", "query": "SELECT 1", "expected": "1"},
+    {"name": "orders-exist", "database": "app", "query": "SELECT count(*) > 0 FROM public.orders", "expected": "t"},
+    {"name": "recent-order", "database": "app", "query": "SELECT max(created_at)::timestamptz FROM public.orders", "maxAgeSeconds": 86400}
+  ]
+}
+```
+
+For PITR, add `"targetTime": "2026-09-29T10:00:00Z"`. Pick a time inside the backup and WAL retention window. A passing PITR check proves only that target; use a second drill for the latest recovery path.
+
+## Scheduled drill
+
+The Helm chart creates a namespace-scoped ServiceAccount, Role, RoleBinding, ConfigMap, and CronJob. Set `cluster`, `checks`, and the other settings in a values file and install it **in the same namespace as the source Cluster and ObjectStore**. The chart defaults to suspension so installation does not immediately start a restore.
+
+The example image build pins kubectl 1.36.4, suitable for Kubernetes 1.35–1.37 under the project's [version skew policy](https://kubernetes.io/releases/). Set `KUBECTL_VERSION` at image build time for another supported cluster version.
+
+```bash
+helm install cnpg-drill oci://ghcr.io/danielgaskins/charts/cnpg-drill \
+  --version 0.1.2 -n production -f drill-values.yaml
+```
+
+See the [first-run guide](docs/FIRST-RUN.md) and [chart values](deploy/helm/cnpg-drill/README.md) for a suspended first run with a separate read-only recovery ObjectStore. The chart pins a public multi-architecture image digest. The CronJob uses `concurrencyPolicy: Forbid` and a bounded job deadline. Its logs contain the JSON result; failed runs have nonzero exit status. **The chart does not yet provide durable report storage, missed-run alerts, or fleet policy.**
+
+## Safety boundary
+
+- The generated recovery Cluster never copies `spec.plugins`, so it is not configured to archive WAL back to the source bucket. Set `recoveryObjectStore` to a separately named `ObjectStore` with read-only archive credentials. The tool compares its destination and endpoint with the source store; it cannot verify credential permissions, so test that writes are denied before relying on this boundary. Omitting this field uses the source `ObjectStore` for compatibility.
+- A recovery timeout includes a machine-readable `failureReason` when the recovery Pod logs identify archive access denial or unavailable WAL. It does not copy raw logs into the report; inspect Pod and operator logs for detail.
+- The drill uses the same namespace because the plugin's `ObjectStore` and its credentials are namespace-scoped. The source Cluster object is never modified.
+- SQL checks run in a `BEGIN READ ONLY` transaction. Queries are limited to one `SELECT` or `WITH` statement without semicolons. Only provide trusted SQL; this is a guard against mistakes, not a security sandbox.
+- By default, the tool deletes the drill Cluster even when recovery or a check fails. `retainOnFailure` leaves it for investigation and can incur storage costs. Cleanup failures turn the result red.
+- The tool checks that PVCs labeled for the drill cluster disappear after Cluster deletion and fails the report if they remain. Kubernetes PersistentVolume cleanup depends on the storage class; inspect cloud volumes after a first drill.
+- The planned SaaS boundary is metadata only. This repository contains no telemetry upload or hosted service.
+
+## Contributing and upstream distribution
+
+Run `PYTHONPATH=src python3 -m unittest discover -s tests -v`. See [CONTRIBUTING.md](CONTRIBUTING.md) for how to add a recovery path, the live integration test gate, and the Krew package plan. We will submit only a tested, released package that stands on its own. Upstream acceptance is not assumed.
+
+[UPSTREAM.md](UPSTREAM.md) records the specific repositories, proposed contribution value, and submission gates.
+
+## Recovery references
+
+- [CloudNativePG backup guidance](https://cloudnative-pg.io/docs/devel/backup/)
+- [CloudNativePG recovery documentation](https://cloudnative-pg.io/docs/devel/recovery/)
+- [Barman Cloud recovery example](https://cloudnative-pg.io/plugin-barman-cloud/docs/next/concepts/)

cnpg_drill-0.1.2/pyproject.toml

@@ -0,0 +1,24 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "cnpg-drill"
+version = "0.1.2"
+description = "Prove CloudNativePG Barman backups restore into an isolated cluster"
+readme = "README.md"
+requires-python = ">=3.10"
+license = {file = "LICENSE"}
+authors = [{name = "cnpg-drill contributors"}]
+keywords = ["cloudnativepg", "postgresql", "kubernetes", "backup", "restore"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+]
+
+[project.scripts]
+cnpg-drill = "cnpg_drill.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]

cnpg_drill-0.1.2/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

cnpg_drill-0.1.2/src/cnpg_drill/__init__.py

@@ -0,0 +1,3 @@
+"""CloudNativePG recovery drill."""
+
+__version__ = "0.1.2"

cnpg_drill-0.1.2/src/cnpg_drill/cli.py

@@ -0,0 +1,43 @@
+"""Command-line interface for local use and Kubernetes CronJobs."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from . import __version__
+from .core import Config, DrillError, Kubectl, prepare, run_drill
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="cnpg-drill", description="Verify a CloudNativePG backup with a disposable recovery cluster")
+    parser.add_argument("--version", action="version", version=__version__)
+    parser.add_argument("--kubectl", default="kubectl", help="kubectl executable path")
+    sub = parser.add_subparsers(dest="command", required=True)
+    for command in ("plan", "run"):
+        item = sub.add_parser(command)
+        item.add_argument("--config", required=True, type=Path, help="JSON drill config")
+        if command == "run":
+            item.add_argument("--report", type=Path, help="write JSON report to this path")
+    args = parser.parse_args(argv)
+    try:
+        config = Config.from_dict(json.loads(args.config.read_text(encoding="utf-8")))
+        client = Kubectl(args.kubectl)
+        if args.command == "plan":
+            print(json.dumps(prepare(client, config), indent=2, sort_keys=True))
+            return 0
+        report = run_drill(client, config)
+        encoded = json.dumps(report, indent=2, sort_keys=True)
+        print(encoded)
+        if args.report:
+            args.report.write_text(encoded + "\n", encoding="utf-8")
+        return 0 if report["status"] == "passed" else (2 if report.get("phase") == "preflight" else 1)
+    except (DrillError, OSError, json.JSONDecodeError) as exc:
+        print(f"cnpg-drill: {exc}", file=sys.stderr)
+        return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

cnpg_drill-0.1.2/src/cnpg_drill/core.py

@@ -0,0 +1,393 @@
+"""Recovery planning and execution, with a deliberately small Kubernetes surface."""
+
+from __future__ import annotations
+
+import copy
+import datetime as dt
+import hashlib
+import json
+import re
+import secrets
+import subprocess
+import time
+from dataclasses import dataclass
+from typing import Any, Callable
+
+
+PLUGIN = "barman-cloud.cloudnative-pg.io"
+API = "clusters.postgresql.cnpg.io"
+DNS_NAME = re.compile(r"^[a-z0-9]([-a-z0-9]*[a-z0-9])?$")
+
+
+class DrillError(RuntimeError):
+    """A recoverable validation or drill failure."""
+
+
+@dataclass(frozen=True)
+class Check:
+    name: str
+    query: str
+    expected: str | None = None
+    max_age_seconds: int | None = None
+    database: str = "postgres"
+
+
+@dataclass(frozen=True)
+class Config:
+    namespace: str
+    cluster: str
+    recovery_object_store: str | None = None
+    timeout_seconds: int = 1800
+    poll_seconds: int = 5
+    max_backup_age_seconds: int = 691200
+    target_time: str | None = None
+    checks: tuple[Check, ...] = (Check("connection", "SELECT 1", "1"),)
+    retain_on_failure: bool = False
+
+    @classmethod
+    def from_dict(cls, raw: dict[str, Any]) -> Config:
+        if not isinstance(raw, dict):
+            raise DrillError("Config must be a JSON object")
+        allowed = {"namespace", "cluster", "recoveryObjectStore", "timeoutSeconds", "pollSeconds", "maxBackupAgeSeconds", "targetTime", "checks", "retainOnFailure"}
+        unknown = set(raw) - allowed
+        if unknown:
+            raise DrillError(f"Unknown config keys: {', '.join(sorted(unknown))}")
+        namespace, cluster = raw.get("namespace"), raw.get("cluster")
+        for label, value in (("namespace", namespace), ("cluster", cluster)):
+            if not isinstance(value, str) or not DNS_NAME.fullmatch(value) or len(value) > 63:
+                raise DrillError(f"{label} must be a Kubernetes DNS label")
+        recovery_object_store = raw.get("recoveryObjectStore")
+        if recovery_object_store is not None and (not isinstance(recovery_object_store, str) or not DNS_NAME.fullmatch(recovery_object_store) or len(recovery_object_store) > 63):
+            raise DrillError("recoveryObjectStore must be a Kubernetes DNS label")
+        timeout = raw.get("timeoutSeconds", 1800)
+        poll = raw.get("pollSeconds", 5)
+        max_backup_age = raw.get("maxBackupAgeSeconds", 691200)
+        if type(timeout) is not int or not 30 <= timeout <= 86400:
+            raise DrillError("timeoutSeconds must be 30..86400")
+        if type(poll) is not int or not 1 <= poll <= 60:
+            raise DrillError("pollSeconds must be 1..60")
+        if type(max_backup_age) is not int or not 1 <= max_backup_age <= 31536000:
+            raise DrillError("maxBackupAgeSeconds must be 1..31536000")
+        target = raw.get("targetTime")
+        if target is not None:
+            if not isinstance(target, str):
+                raise DrillError("targetTime must be an RFC3339 timestamp")
+            try:
+                parsed = dt.datetime.fromisoformat(target.replace("Z", "+00:00"))
+            except ValueError as exc:
+                raise DrillError("targetTime must be an RFC3339 timestamp") from exc
+            if parsed.tzinfo is None:
+                raise DrillError("targetTime must include a timezone")
+            if parsed > dt.datetime.now(dt.timezone.utc):
+                raise DrillError("targetTime cannot be in the future")
+        checks_raw = raw.get("checks", [{"name": "connection", "query": "SELECT 1", "expected": "1"}])
+        if not isinstance(checks_raw, list) or not 1 <= len(checks_raw) <= 50:
+            raise DrillError("checks must be a list of 1..50 checks")
+        checks: list[Check] = []
+        for item in checks_raw:
+            if not isinstance(item, dict) or not {"name", "query"} <= set(item) or set(item) - {"name", "query", "expected", "maxAgeSeconds", "database"}:
+                raise DrillError("Each check needs name, query, and one comparison")
+            if ("expected" in item) == ("maxAgeSeconds" in item):
+                raise DrillError("Each check needs exactly one of expected or maxAgeSeconds")
+            name, query, expected = item["name"], item["query"], item.get("expected")
+            max_age = item.get("maxAgeSeconds")
+            database = item.get("database", "postgres")
+            if not isinstance(name, str) or not name or len(name) > 80:
+                raise DrillError("Check name must be 1..80 characters")
+            if "expected" in item and (not isinstance(expected, str) or len(expected) > 4096):
+                raise DrillError("Check expected must be a string up to 4096 characters")
+            if "maxAgeSeconds" in item and (type(max_age) is not int or not 1 <= max_age <= 31536000):
+                raise DrillError("maxAgeSeconds must be 1..31536000")
+            if not isinstance(query, str) or len(query) > 8192 or not re.match(r"^\s*(SELECT|WITH)\b", query, re.I) or ";" in query:
+                raise DrillError(f"Check {name}: query must be one SELECT/WITH statement without semicolons")
+            if not isinstance(database, str) or not re.fullmatch(r"[A-Za-z_][A-Za-z0-9_-]{0,62}", database):
+                raise DrillError(f"Check {name}: database must be a simple PostgreSQL database name")
+            checks.append(Check(name, query.strip(), expected, max_age, database))
+        retained = raw.get("retainOnFailure", False)
+        if type(retained) is not bool:
+            raise DrillError("retainOnFailure must be boolean")
+        return cls(namespace, cluster, recovery_object_store, timeout, poll, max_backup_age, target, tuple(checks), retained)
+
+
+class Kubectl:
+    def __init__(self, executable: str = "kubectl", invoke: Callable[..., subprocess.CompletedProcess[str]] = subprocess.run):
+        self.executable = executable
+        self.invoke = invoke
+
+    def call(self, args: list[str], *, input_text: str | None = None, timeout: int = 60) -> str:
+        try:
+            result = self.invoke([self.executable, *args], input=input_text, text=True, capture_output=True, timeout=timeout, check=False)
+        except (FileNotFoundError, subprocess.TimeoutExpired) as exc:
+            raise DrillError(f"kubectl unavailable or timed out: {exc}") from exc
+        if result.returncode:
+            raise DrillError(f"kubectl {' '.join(args[:4])} failed: {result.stderr.strip()[:1000]}")
+        return result.stdout
+
+    def get(self, resource: str, name: str, namespace: str) -> dict[str, Any]:
+        return json.loads(self.call(["-n", namespace, "get", resource, name, "-o", "json"]))
+
+    def list_pvcs(self, cluster: str, namespace: str) -> list[str]:
+        data = json.loads(self.call(["-n", namespace, "get", "pvc", "-l", f"cnpg.io/cluster={cluster}", "-o", "json"]))
+        return [item["metadata"]["name"] for item in data.get("items", [])]
+
+    def recovery_logs(self, cluster: str, namespace: str) -> list[str]:
+        data = json.loads(self.call(["-n", namespace, "get", "pods", "-l", f"cnpg.io/cluster={cluster}", "-o", "json"]))
+        logs = []
+        pods = sorted(data.get("items", []), key=lambda p: p.get("metadata", {}).get("creationTimestamp", ""), reverse=True)
+        for pod in pods[:5]:
+            name = pod.get("metadata", {}).get("name", "")
+            if "full-recovery" not in name:
+                continue
+            for container in ("plugin-barman-cloud", "full-recovery"):
+                try:
+                    logs.append(self.call(["-n", namespace, "logs", name, "-c", container, "--tail=200"], timeout=20))
+                except DrillError:
+                    continue
+        return logs
+
+    def list_backups(self, namespace: str) -> list[dict[str, Any]]:
+        data = json.loads(self.call(["-n", namespace, "get", "backups.postgresql.cnpg.io", "-o", "json"]))
+        return data.get("items", [])
+
+    def create(self, manifest: dict[str, Any], namespace: str) -> None:
+        self.call(["-n", namespace, "create", "-f", "-"], input_text=json.dumps(manifest))
+
+    def delete(self, resource: str, name: str, namespace: str, *, timeout: int = 120) -> None:
+        self.call(["-n", namespace, "delete", resource, name, "--ignore-not-found=true", "--wait=true", f"--timeout={timeout}s"], timeout=timeout + 15)
+
+    def exec_query(self, pod: str, namespace: str, query: str, database: str = "postgres") -> str:
+        # One read-only transaction. The config parser rejects semicolons in query.
+        sql = f"BEGIN READ ONLY; {query}; COMMIT;"
+        return self.call(["-n", namespace, "exec", pod, "-c", "postgres", "--", "psql", "-X", "-qAt", "-v", "ON_ERROR_STOP=1", "-U", "postgres", "-d", database, "-c", sql], timeout=60).strip()
+
+
+def choose_backup(backups: list[dict[str, Any]], config: Config, object_name: str | None = None) -> tuple[dict[str, Any], int]:
+    now = dt.datetime.now(dt.timezone.utc)
+    target = dt.datetime.fromisoformat(config.target_time.replace("Z", "+00:00")) if config.target_time else now
+    candidates: list[tuple[dt.datetime, dict[str, Any]]] = []
+    for backup in backups:
+        if backup.get("spec", {}).get("cluster", {}).get("name") != config.cluster:
+            continue
+        status = backup.get("status", {})
+        if status.get("phase") != "completed" or not status.get("backupId"):
+            continue
+        if (status.get("method") or backup.get("spec", {}).get("method")) != "plugin":
+            continue
+        if backup.get("spec", {}).get("pluginConfiguration", {}).get("name") not in (None, PLUGIN):
+            continue
+        backup_object = backup.get("spec", {}).get("pluginConfiguration", {}).get("parameters", {}).get("barmanObjectName")
+        if object_name and backup_object and backup_object != object_name:
+            continue
+        try:
+            stopped = dt.datetime.fromisoformat(status["stoppedAt"].replace("Z", "+00:00"))
+        except (KeyError, TypeError, ValueError):
+            continue
+        if stopped.tzinfo and stopped <= target:
+            candidates.append((stopped, backup))
+    if not candidates:
+        raise DrillError("No completed Barman plugin Backup with an ID exists before the recovery target")
+    stopped, chosen = max(candidates, key=lambda item: item[0])
+    age = int((now - stopped).total_seconds())
+    if age > config.max_backup_age_seconds:
+        raise DrillError(f"Latest eligible Backup is {age}s old, above maxBackupAgeSeconds={config.max_backup_age_seconds}")
+    return chosen, age
+
+
+def build_manifest(source: dict[str, Any], config: Config, *, name: str, backup: dict[str, Any] | None = None) -> dict[str, Any]:
+    spec = source.get("spec", {})
+    if spec.get("tablespaces"):
+        raise DrillError("Tablespace clusters are not supported in v0.1; refusing incomplete restore")
+    bootstrap = spec.get("bootstrap") or {}
+    if bootstrap.get("recovery") or bootstrap.get("pg_basebackup"):
+        raise DrillError("Replica or recovery-source clusters are not supported in v0.1")
+    if bootstrap and "initdb" not in bootstrap:
+        raise DrillError("Only default or initdb bootstrap sources are supported in v0.1")
+    plugins = [p for p in spec.get("plugins", []) if p.get("name") == PLUGIN and p.get("enabled", True)]
+    if len(plugins) != 1:
+        raise DrillError("Source needs one enabled Barman Cloud plugin")
+    params = plugins[0].get("parameters", {})
+    object_name = params.get("barmanObjectName")
+    if not isinstance(object_name, str) or not DNS_NAME.fullmatch(object_name):
+        raise DrillError("Barman plugin needs a valid barmanObjectName")
+    storage = spec.get("storage")
+    if not isinstance(storage, dict) or not storage.get("size"):
+        raise DrillError("Source Cluster needs storage.size")
+    if len(name) > 63 or not DNS_NAME.fullmatch(name) or name == config.cluster:
+        raise DrillError("Invalid or unsafe drill cluster name")
+    recovery: dict[str, Any] = {"source": "backup-source"}
+    if backup:
+        recovery["recoveryTarget"] = {"backupID": backup["status"]["backupId"]}
+    initdb = bootstrap.get("initdb") or {}
+    for key in ("database", "owner", "secret"):
+        if key in initdb:
+            recovery[key] = copy.deepcopy(initdb[key])
+    if config.target_time:
+        recovery.setdefault("recoveryTarget", {})["targetTime"] = config.target_time
+    external = {"name": "backup-source", "plugin": {"name": PLUGIN, "enabled": True, "parameters": {"barmanObjectName": config.recovery_object_store or object_name, "serverName": params.get("serverName") or config.cluster}}}
+    output: dict[str, Any] = {
+        "apiVersion": "postgresql.cnpg.io/v1", "kind": "Cluster",
+        "metadata": {"name": name, "namespace": config.namespace, "labels": {"app.kubernetes.io/managed-by": "cnpg-drill", "cnpg-drill.dev/source": config.cluster}, "annotations": {"cnpg-drill.dev/source-uid": source.get("metadata", {}).get("uid", ""), "cnpg-drill.dev/backup-name": backup.get("metadata", {}).get("name", "") if backup else ""}},
+        "spec": {"instances": 1, "storage": copy.deepcopy(storage), "bootstrap": {"recovery": recovery}, "externalClusters": [external]},
+    }
+    for key in ("imageName", "imageCatalogRef", "walStorage", "resources"):
+        if key in spec:
+            output["spec"][key] = copy.deepcopy(spec[key])
+    # S3-compatible stores may need these boto3 settings during recovery too.
+    # Never copy arbitrary source env: it can contain writer credentials.
+    recovery_env = [
+        {"name": item["name"], "value": item["value"]} for item in spec.get("env", [])
+        if isinstance(item, dict)
+        and item.get("name") in {"AWS_REQUEST_CHECKSUM_CALCULATION", "AWS_RESPONSE_CHECKSUM_VALIDATION", "AWS_NO_CHUNKED_ENCODING"}
+        and isinstance(item.get("value"), str)
+        and "valueFrom" not in item
+    ]
+    if recovery_env:
+        output["spec"]["env"] = recovery_env
+    # Deliberately do not copy spec.plugins: the recovered cluster must not archive to source.
+    return output
+
+
+def new_name(source_name: str) -> str:
+    suffix = dt.datetime.now(dt.timezone.utc).strftime("%m%d%H%M") + "-" + secrets.token_hex(3)
+    return f"drill-{source_name[:48-len(suffix)]}-{suffix}"
+
+
+def recovery_failure_reason(logs: list[str]) -> str | None:
+    """Classify recovery logs without exposing archive paths, credentials, or SQL."""
+    messages = []
+    for log in logs:
+        for line in log.splitlines()[-200:]:
+            try:
+                entry = json.loads(line)
+            except json.JSONDecodeError:
+                continue
+            if not isinstance(entry, dict):
+                continue
+            record = entry.get("record")
+            if isinstance(record, dict):
+                messages.append(str(record.get("message", "")))
+            messages.append(str(entry.get("error", "")))
+            messages.append(str(entry.get("msg", "")))
+    combined = "\n".join(messages).lower()
+    if re.search(r"access.?denied|permission.?denied|forbidden|\b403\b", combined):
+        return "archive_access_denied"
+    if re.search(r"(wal|archive).{0,100}(not found|no such key|missing|unavailable|does not exist)|requested wal segment.{0,100}removed", combined):
+        return "wal_unavailable"
+    if re.search(r"restore error|error while restoring a backup|fatal", combined):
+        return "recovery_process_failed"
+    return None
+
+
+def prepare(client: Kubectl, config: Config, name: str | None = None) -> dict[str, Any]:
+    source = client.get(API, config.cluster, config.namespace)
+    if source.get("metadata", {}).get("deletionTimestamp"):
+        raise DrillError("Source Cluster is being deleted")
+    source_plugins = [p for p in source.get("spec", {}).get("plugins", []) if p.get("name") == PLUGIN and p.get("enabled", True)]
+    object_name = source_plugins[0].get("parameters", {}).get("barmanObjectName") if len(source_plugins) == 1 else None
+    backup, age = choose_backup(client.list_backups(config.namespace), config, object_name)
+    manifest = build_manifest(source, config, name=name or new_name(config.cluster), backup=backup)
+    manifest["metadata"]["annotations"]["cnpg-drill.dev/backup-age-seconds"] = str(age)
+    if not object_name:
+        raise DrillError("Source needs one enabled Barman Cloud plugin")
+    source_store = client.get("objectstores.barmancloud.cnpg.io", object_name, config.namespace)
+    recovery_name = config.recovery_object_store or object_name
+    if recovery_name != object_name:
+        recovery_store = client.get("objectstores.barmancloud.cnpg.io", recovery_name, config.namespace)
+        source_config = source_store.get("spec", {}).get("configuration", {})
+        recovery_config = recovery_store.get("spec", {}).get("configuration", {})
+        for field in ("destinationPath", "endpointURL"):
+            if not source_config.get(field) or source_config.get(field) != recovery_config.get(field):
+                raise DrillError(f"Recovery ObjectStore {field} must match source ObjectStore")
+    return manifest
+
+
+def run_drill(client: Kubectl, config: Config, *, sleep: Callable[[float], None] = time.sleep, monotonic: Callable[[], float] = time.monotonic) -> dict[str, Any]:
+    started_at = dt.datetime.now(dt.timezone.utc)
+    started = monotonic()
+    result: dict[str, Any] = {"schemaVersion": 1, "source": f"{config.namespace}/{config.cluster}", "startedAt": started_at.isoformat(), "targetTime": config.target_time, "checks": [], "status": "error"}
+    name: str | None = None
+    created = False
+    try:
+        manifest = prepare(client, config)
+        name = manifest["metadata"]["name"]
+        result["drillCluster"] = name
+        result["sourceClusterUID"] = manifest["metadata"]["annotations"]["cnpg-drill.dev/source-uid"]
+        result["backupName"] = manifest["metadata"]["annotations"]["cnpg-drill.dev/backup-name"]
+        result["backupID"] = manifest["spec"]["bootstrap"]["recovery"]["recoveryTarget"]["backupID"]
+        result["backupAgeSeconds"] = int(manifest["metadata"]["annotations"]["cnpg-drill.dev/backup-age-seconds"])
+        created = True
+        # A create request can reach the API even if the client loses its response.
+        # In that case, still try to remove the uniquely named drill Cluster.
+        client.create(manifest, config.namespace)
+        recovery_started = monotonic()
+        deadline = started + config.timeout_seconds
+        primary = None
+        while monotonic() < deadline:
+            cluster = client.get(API, name, config.namespace)
+            status = cluster.get("status", {})
+            if status.get("readyInstances", 0) >= 1 and status.get("currentPrimary"):
+                primary = status["currentPrimary"]
+                break
+            sleep(config.poll_seconds)
+        if not primary:
+            try:
+                reason = recovery_failure_reason(client.recovery_logs(name, config.namespace))
+            except DrillError:
+                reason = None
+            result["failureReason"] = reason or "recovery_timeout"
+            hints = {
+                "archive_access_denied": "Check recovery ObjectStore permissions to read both base backup and WAL objects.",
+                "wal_unavailable": "Check that the required WAL segment exists and is readable in the recovery archive.",
+                "recovery_process_failed": "Inspect the drill recovery Pod and operator logs for the underlying restore error.",
+                "recovery_timeout": "Inspect the drill recovery Pod and operator logs for the cause.",
+            }
+            raise DrillError(f"Recovery did not become ready within {config.timeout_seconds}s. {hints[result['failureReason']]}")
+        result["recoverySeconds"] = round(monotonic() - recovery_started, 2)
+        for check in config.checks:
+            observed = client.exec_query(primary, config.namespace, check.query, check.database)
+            check_result: dict[str, Any] = {"name": check.name, "database": check.database, "observedSha256": hashlib.sha256(observed.encode()).hexdigest()}
+            if check.max_age_seconds is not None:
+                try:
+                    observed_time = dt.datetime.fromisoformat(observed.replace("Z", "+00:00"))
+                    if observed_time.tzinfo is None:
+                        raise ValueError("timestamp lacks timezone")
+                    age = (dt.datetime.now(dt.timezone.utc) - observed_time).total_seconds()
+                    check_result["ageSeconds"] = round(age, 2)
+                    check_result["maxAgeSeconds"] = check.max_age_seconds
+                    passed = 0 <= age <= check.max_age_seconds
+                except ValueError:
+                    passed = False
+                    check_result["error"] = "query did not return a timestamp with timezone"
+            else:
+                passed = observed == check.expected
+            check_result["passed"] = passed
+            result["checks"].append(check_result)
+            if not passed:
+                raise DrillError(f"Check {check.name!r} did not meet its assertion")
+        result["status"] = "passed"
+    except (DrillError, ValueError, KeyError) as exc:
+        result["error"] = str(exc)
+        result["status"] = "failed"
+        if not created:
+            result["phase"] = "preflight"
+    finally:
+        if created and name and not (result["status"] == "failed" and config.retain_on_failure):
+            try:
+                client.delete(API, name, config.namespace)
+                cleanup_deadline = monotonic() + 60
+                remaining = client.list_pvcs(name, config.namespace)
+                while remaining and monotonic() < cleanup_deadline:
+                    sleep(2)
+                    remaining = client.list_pvcs(name, config.namespace)
+                if remaining:
+                    raise DrillError(f"Drill PVCs still exist after Cluster deletion: {', '.join(remaining)}")
+                result["cleanup"] = "cluster-and-pvcs-deleted"
+            except DrillError as exc:
+                result["cleanup"] = "failed"
+                result["cleanupError"] = str(exc)
+                result["status"] = "failed"
+        elif created:
+            result["cleanup"] = "retained-for-investigation"
+        result["finishedAt"] = dt.datetime.now(dt.timezone.utc).isoformat()
+        result["durationSeconds"] = round(monotonic() - started, 2)
+    return result

cnpg_drill-0.1.2/src/cnpg_drill.egg-info/PKG-INFO

@@ -0,0 +1,131 @@
+Metadata-Version: 2.4
+Name: cnpg-drill
+Version: 0.1.2
+Summary: Prove CloudNativePG Barman backups restore into an isolated cluster
+Author: cnpg-drill contributors
+License: MIT License
+        
+        Copyright (c) 2026 cnpg-drill contributors
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Keywords: cloudnativepg,postgresql,kubernetes,backup,restore
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# cnpg-drill
+
+**Prove that a CloudNativePG backup can restore.** `cnpg-drill` creates a disposable CloudNativePG cluster from the source cluster's Barman Cloud object store, waits for PostgreSQL to become ready, runs read-only SQL assertions, emits a JSON result, and deletes the drill cluster. It can run locally or on a schedule as a Kubernetes CronJob.
+
+The core is free and works without an account or external service. It does not make backups or copy database contents to a vendor. The proposed hosted service in [RESEARCH.md](RESEARCH.md) is separate and has not been built.
+
+## Status
+
+**Early alpha.** Unit tests cover manifest safety and execution state. A disposable [local integration run](integration/local/README.md) on v0.1.0 proved full restore, PITR, read-only archive access, denied-WAL reporting, failed-check reporting, and Cluster/PVC cleanup on one version matrix. The v0.1.1 release archive and public chart 0.1.2 also restored a fresh backup and checked a row in an application database. A separate single-node pgEdge chart restore passed SQL checks in its `app` database. Validate against your operator, PostgreSQL image, storage, object store, and Barman plugin versions before treating a pass as disaster recovery assurance.
+
+The [v0.1.2 release](https://github.com/danielgaskins/cnpg-drill/releases/tag/v0.1.2) carries literal AWS checksum compatibility settings into recovery clusters without copying source credentials. It includes the MIT-licensed kubectl plugin archive and checksum. The [default Krew index submission](https://github.com/kubernetes-sigs/krew-index/pull/6373) and [custom Krew index submission](https://github.com/ishantanu/awesome-kubectl-plugins/pull/44) currently package v0.1.0 and are under review. [kubetools](https://github.com/collabnix/kubetools/pull/431) is reviewing a Backup Tools listing.
+
+The [Helm chart is listed on Artifact Hub](https://artifacthub.io/packages/helm/cnpg-drill/cnpg-drill) as a Verified Publisher package. Chart version `0.1.2` uses the v0.1.1 application image and includes the publisher's [website](https://danielgaskins.com/).
+
+## What it supports
+
+- One source CloudNativePG cluster with one enabled Barman Cloud plugin and a named `ObjectStore` in the same namespace.
+- An optional separate `recoveryObjectStore` with credentials limited to archive reads. Preflight checks that its destination and endpoint match the source store before creating a Cluster.
+- Full restore from the latest completed Barman plugin `Backup` resource, or PITR to an explicit RFC3339 `targetTime`. The selected backup ID is pinned and included in the report; a stale backup fails preflight.
+- Single-instance drill cluster using the source's PostgreSQL image, storage size/class, optional WAL storage, and resource requests.
+- Copies literal AWS checksum compatibility settings from the source Cluster for S3-compatible archive restores; it does not copy writer credentials or arbitrary environment variables.
+- Read-only SQL checks in `postgres` or a named application database. Exact expected values make reports easy to audit.
+- Optional timestamp freshness assertions (`maxAgeSeconds`) for an application-defined recovery point. This measures age of that application's data, not the database WAL RPO.
+- A JSON report on stdout and optionally in a local file. Query outputs are hashed rather than logged. Exit code 0 means all checks, Cluster deletion, and PVC cleanup passed; 1 means the drill failed; 2 means invalid input or a failed preflight.
+- Scheduled execution with the Helm CronJob in `deploy/helm/cnpg-drill`.
+
+The CLI refuses source clusters with tablespaces or recovery bootstrap because a naive clone could produce an incomplete or misleading pass. Volume snapshots, cross-namespace restores, cross-region recovery, custom Postgres extension image changes, and multi-cluster fleet management are future work.
+
+## Install and use
+
+For a first run on your own cluster, follow the [first-run guide](docs/FIRST-RUN.md).
+
+Requirements: Python 3.10+, `kubectl` in `PATH`, CloudNativePG and the Barman Cloud plugin installed in the target cluster, and Kubernetes access to read the source Cluster and ObjectStore, create/get/delete a drill Cluster, and exec into its PostgreSQL pod.
+
+```bash
+python3 -m pip install -e .
+cnpg-drill plan --config examples/drill.json
+cnpg-drill run --config examples/drill.json --report reports/latest.json
+```
+
+`plan` reads the source configuration and prints the exact Cluster manifest it would create. Review that manifest before running the first drill. The example's table-count assertion is illustrative; replace it with an invariant from your own application. A minimal check is `SELECT 1`, but it only proves connection to the recovered server, not useful application data.
+
+Example `drill.json`:
+
+```json
+{
+  "namespace": "production",
+  "cluster": "app-db",
+  "recoveryObjectStore": "app-db-recovery-readonly",
+  "timeoutSeconds": 1800,
+  "maxBackupAgeSeconds": 691200,
+  "checks": [
+    {"name": "postgres-ready", "query": "SELECT 1", "expected": "1"},
+    {"name": "orders-exist", "database": "app", "query": "SELECT count(*) > 0 FROM public.orders", "expected": "t"},
+    {"name": "recent-order", "database": "app", "query": "SELECT max(created_at)::timestamptz FROM public.orders", "maxAgeSeconds": 86400}
+  ]
+}
+```
+
+For PITR, add `"targetTime": "2026-09-29T10:00:00Z"`. Pick a time inside the backup and WAL retention window. A passing PITR check proves only that target; use a second drill for the latest recovery path.
+
+## Scheduled drill
+
+The Helm chart creates a namespace-scoped ServiceAccount, Role, RoleBinding, ConfigMap, and CronJob. Set `cluster`, `checks`, and the other settings in a values file and install it **in the same namespace as the source Cluster and ObjectStore**. The chart defaults to suspension so installation does not immediately start a restore.
+
+The example image build pins kubectl 1.36.4, suitable for Kubernetes 1.35–1.37 under the project's [version skew policy](https://kubernetes.io/releases/). Set `KUBECTL_VERSION` at image build time for another supported cluster version.
+
+```bash
+helm install cnpg-drill oci://ghcr.io/danielgaskins/charts/cnpg-drill \
+  --version 0.1.2 -n production -f drill-values.yaml
+```
+
+See the [first-run guide](docs/FIRST-RUN.md) and [chart values](deploy/helm/cnpg-drill/README.md) for a suspended first run with a separate read-only recovery ObjectStore. The chart pins a public multi-architecture image digest. The CronJob uses `concurrencyPolicy: Forbid` and a bounded job deadline. Its logs contain the JSON result; failed runs have nonzero exit status. **The chart does not yet provide durable report storage, missed-run alerts, or fleet policy.**
+
+## Safety boundary
+
+- The generated recovery Cluster never copies `spec.plugins`, so it is not configured to archive WAL back to the source bucket. Set `recoveryObjectStore` to a separately named `ObjectStore` with read-only archive credentials. The tool compares its destination and endpoint with the source store; it cannot verify credential permissions, so test that writes are denied before relying on this boundary. Omitting this field uses the source `ObjectStore` for compatibility.
+- A recovery timeout includes a machine-readable `failureReason` when the recovery Pod logs identify archive access denial or unavailable WAL. It does not copy raw logs into the report; inspect Pod and operator logs for detail.
+- The drill uses the same namespace because the plugin's `ObjectStore` and its credentials are namespace-scoped. The source Cluster object is never modified.
+- SQL checks run in a `BEGIN READ ONLY` transaction. Queries are limited to one `SELECT` or `WITH` statement without semicolons. Only provide trusted SQL; this is a guard against mistakes, not a security sandbox.
+- By default, the tool deletes the drill Cluster even when recovery or a check fails. `retainOnFailure` leaves it for investigation and can incur storage costs. Cleanup failures turn the result red.
+- The tool checks that PVCs labeled for the drill cluster disappear after Cluster deletion and fails the report if they remain. Kubernetes PersistentVolume cleanup depends on the storage class; inspect cloud volumes after a first drill.
+- The planned SaaS boundary is metadata only. This repository contains no telemetry upload or hosted service.
+
+## Contributing and upstream distribution
+
+Run `PYTHONPATH=src python3 -m unittest discover -s tests -v`. See [CONTRIBUTING.md](CONTRIBUTING.md) for how to add a recovery path, the live integration test gate, and the Krew package plan. We will submit only a tested, released package that stands on its own. Upstream acceptance is not assumed.
+
+[UPSTREAM.md](UPSTREAM.md) records the specific repositories, proposed contribution value, and submission gates.
+
+## Recovery references
+
+- [CloudNativePG backup guidance](https://cloudnative-pg.io/docs/devel/backup/)
+- [CloudNativePG recovery documentation](https://cloudnative-pg.io/docs/devel/recovery/)
+- [Barman Cloud recovery example](https://cloudnative-pg.io/plugin-barman-cloud/docs/next/concepts/)

cnpg_drill-0.1.2/src/cnpg_drill.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+LICENSE
+README.md
+pyproject.toml
+src/cnpg_drill/__init__.py
+src/cnpg_drill/cli.py
+src/cnpg_drill/core.py
+src/cnpg_drill.egg-info/PKG-INFO
+src/cnpg_drill.egg-info/SOURCES.txt
+src/cnpg_drill.egg-info/dependency_links.txt
+src/cnpg_drill.egg-info/entry_points.txt
+src/cnpg_drill.egg-info/top_level.txt
+tests/test_cli.py
+tests/test_core.py

cnpg_drill-0.1.2/src/cnpg_drill.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

cnpg_drill-0.1.2/src/cnpg_drill.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+cnpg-drill = cnpg_drill.cli:main

cnpg_drill-0.1.2/src/cnpg_drill.egg-info/top_level.txt

@@ -0,0 +1 @@
+cnpg_drill

cnpg_drill-0.1.2/tests/test_cli.py

@@ -0,0 +1,52 @@
+import contextlib
+import io
+import json
+import tempfile
+import unittest
+from pathlib import Path
+from unittest.mock import patch
+
+from cnpg_drill import cli
+
+from test_core import FakeClient
+
+
+class CliTest(unittest.TestCase):
+    def test_plan_outputs_manifest_without_creating_cluster(self):
+        fake = FakeClient()
+        with tempfile.TemporaryDirectory() as folder:
+            config = Path(folder) / "config.json"
+            config.write_text(json.dumps({"namespace": "production", "cluster": "app-db"}))
+            output = io.StringIO()
+            with patch.object(cli, "Kubectl", return_value=fake), contextlib.redirect_stdout(output):
+                code = cli.main(["plan", "--config", str(config)])
+        self.assertEqual(code, 0)
+        self.assertIsNone(fake.created)
+        self.assertEqual(json.loads(output.getvalue())["kind"], "Cluster")
+
+    def test_run_writes_machine_readable_failure_report(self):
+        fake = FakeClient(check_result="0")
+        with tempfile.TemporaryDirectory() as folder:
+            config = Path(folder) / "config.json"
+            report = Path(folder) / "report.json"
+            config.write_text(json.dumps({"namespace": "production", "cluster": "app-db"}))
+            with patch.object(cli, "Kubectl", return_value=fake), contextlib.redirect_stdout(io.StringIO()):
+                code = cli.main(["run", "--config", str(config), "--report", str(report)])
+            result = json.loads(report.read_text())
+        self.assertEqual(code, 1)
+        self.assertEqual(result["status"], "failed")
+        self.assertEqual(result["checks"][0]["passed"], False)
+
+    def test_run_returns_code_two_for_preflight_failure(self):
+        fake = FakeClient()
+        with tempfile.TemporaryDirectory() as folder:
+            config = Path(folder) / "config.json"
+            config.write_text(json.dumps({"namespace": "production", "cluster": "app-db", "maxBackupAgeSeconds": 1}))
+            with patch.object(cli, "Kubectl", return_value=fake), contextlib.redirect_stdout(io.StringIO()):
+                code = cli.main(["run", "--config", str(config)])
+        self.assertEqual(code, 2)
+        self.assertIsNone(fake.created)
+
+
+if __name__ == "__main__":
+    unittest.main()

cnpg_drill-0.1.2/tests/test_core.py

@@ -0,0 +1,267 @@
+import copy
+import datetime as dt
+import hashlib
+import json
+import unittest
+
+from cnpg_drill.core import Config, DrillError, Kubectl, build_manifest, choose_backup, prepare, recovery_failure_reason, run_drill
+
+
+SOURCE = {
+    "metadata": {"name": "app-db", "namespace": "production", "uid": "source-uid-123"},
+    "spec": {
+        "instances": 3,
+        "imageName": "ghcr.io/cloudnative-pg/postgresql:17",
+        "storage": {"size": "10Gi", "storageClass": "fast"},
+        "walStorage": {"size": "2Gi"},
+        "plugins": [{"name": "barman-cloud.cloudnative-pg.io", "enabled": True, "isWALArchiver": True, "parameters": {"barmanObjectName": "app-store"}}],
+    },
+}
+
+
+class FakeClient:
+    def __init__(self, *, ready=True, check_result="1", cleanup_error=False, create_error=False, remaining_pvcs=None):
+        self.ready = ready
+        self.check_result = check_result
+        self.cleanup_error = cleanup_error
+        self.create_error = create_error
+        self.created = None
+        self.deleted = None
+        self.queries = []
+        self.remaining_pvcs = remaining_pvcs or []
+
+    def get(self, resource, name, namespace):
+        if name == "app-db":
+            return copy.deepcopy(SOURCE)
+        if name in ("app-store", "recovery-store", "wrong-store"):
+            destination = "s3://other/" if name == "wrong-store" else "s3://backups/"
+            return {"metadata": {"name": name}, "spec": {"configuration": {"destinationPath": destination, "endpointURL": "https://s3.example.test"}}}
+        return {"status": {"readyInstances": 1 if self.ready else 0, "currentPrimary": f"{name}-1" if self.ready else ""}}
+
+    def create(self, manifest, namespace):
+        self.created = manifest
+        if self.create_error:
+            raise DrillError("create response lost")
+
+    def delete(self, resource, name, namespace):
+        if self.cleanup_error:
+            raise DrillError("delete denied")
+        self.deleted = name
+
+    def exec_query(self, pod, namespace, query, database="postgres"):
+        self.queries.append((pod, database, query))
+        return self.check_result
+
+    def list_pvcs(self, cluster, namespace):
+        return self.remaining_pvcs
+
+    def recovery_logs(self, cluster, namespace):
+        return []
+
+    def list_backups(self, namespace):
+        stopped = (dt.datetime.now(dt.timezone.utc) - dt.timedelta(hours=1)).isoformat()
+        return [{"metadata": {"name": "app-db-backup"}, "spec": {"cluster": {"name": "app-db"}, "method": "plugin", "pluginConfiguration": {"name": "barman-cloud.cloudnative-pg.io"}}, "status": {"phase": "completed", "backupId": "20260929T120000", "stoppedAt": stopped, "method": "plugin"}}]
+
+
+class ConfigTest(unittest.TestCase):
+    def test_recovery_store_name_is_validated(self):
+        with self.assertRaisesRegex(DrillError, "recoveryObjectStore"):
+            Config.from_dict({"namespace": "production", "cluster": "app-db", "recoveryObjectStore": "Other/namespace"})
+
+    def test_rejects_mutating_or_multiple_statements(self):
+        for query in ("DELETE FROM users", "SELECT 1; DROP TABLE users", "  INSERT INTO x VALUES (1)"):
+            with self.subTest(query=query), self.assertRaises(DrillError):
+                Config.from_dict({"namespace": "production", "cluster": "app-db", "checks": [{"name": "unsafe", "query": query, "expected": "1"}]})
+
+    def test_requires_timezone_for_pitr(self):
+        with self.assertRaises(DrillError):
+            Config.from_dict({"namespace": "production", "cluster": "app-db", "targetTime": "2026-01-01T00:00:00"})
+
+    def test_database_name_rejects_connection_strings(self):
+        for database in ("host=elsewhere", "postgresql://elsewhere/db", "-h", "app db"):
+            with self.subTest(database=database), self.assertRaisesRegex(DrillError, "database"):
+                Config.from_dict({"namespace": "production", "cluster": "app-db", "checks": [{"name": "app-data", "database": database, "query": "SELECT 1", "expected": "1"}]})
+
+    def test_exec_uses_selected_database_in_read_only_transaction(self):
+        calls = []
+
+        def invoke(argv, **kwargs):
+            calls.append(argv)
+            return type("Result", (), {"returncode": 0, "stdout": "1\n", "stderr": ""})()
+
+        observed = Kubectl(invoke=invoke).exec_query("drill-1", "production", "SELECT 1", "app")
+        self.assertEqual(observed, "1")
+        self.assertEqual(calls[0][calls[0].index("-d") + 1], "app")
+        self.assertIn("BEGIN READ ONLY; SELECT 1; COMMIT;", calls[0])
+
+
+class ManifestTest(unittest.TestCase):
+    def setUp(self):
+        self.config = Config.from_dict({"namespace": "production", "cluster": "app-db", "targetTime": "2026-01-01T00:00:00Z"})
+
+    def test_recovery_uses_source_archive_but_does_not_archive(self):
+        manifest = build_manifest(SOURCE, self.config, name="drill-app-db-test")
+        spec = manifest["spec"]
+        self.assertNotIn("plugins", spec)
+        self.assertNotIn("backup", spec)
+        self.assertEqual(spec["bootstrap"]["recovery"]["recoveryTarget"]["targetTime"], "2026-01-01T00:00:00Z")
+        self.assertEqual(spec["externalClusters"][0]["plugin"]["parameters"], {"barmanObjectName": "app-store", "serverName": "app-db"})
+        self.assertEqual(spec["storage"]["size"], "10Gi")
+        self.assertEqual(spec["walStorage"]["size"], "2Gi")
+
+    def test_separate_recovery_store_preserves_source_backup_selection(self):
+        config = Config.from_dict({"namespace": "production", "cluster": "app-db", "recoveryObjectStore": "recovery-store"})
+        manifest = prepare(FakeClient(), config, name="drill-app-db-test")
+        self.assertEqual(manifest["spec"]["externalClusters"][0]["plugin"]["parameters"]["barmanObjectName"], "recovery-store")
+        self.assertEqual(manifest["metadata"]["annotations"]["cnpg-drill.dev/backup-name"], "app-db-backup")
+        self.assertNotIn("plugins", manifest["spec"])
+
+    def test_rejects_recovery_store_pointing_elsewhere(self):
+        config = Config.from_dict({"namespace": "production", "cluster": "app-db", "recoveryObjectStore": "wrong-store"})
+        with self.assertRaisesRegex(DrillError, "destinationPath must match"):
+            prepare(FakeClient(), config, name="drill-app-db-test")
+
+    def test_fails_closed_on_tablespaces(self):
+        source = copy.deepcopy(SOURCE)
+        source["spec"]["tablespaces"] = [{"name": "data"}]
+        with self.assertRaises(DrillError):
+            build_manifest(source, self.config, name="drill-app-db-test")
+
+    def test_preserves_custom_application_database_identity(self):
+        source = copy.deepcopy(SOURCE)
+        source["spec"]["bootstrap"] = {"initdb": {"database": "orders", "owner": "orders_user", "secret": {"name": "orders-owner"}}}
+        recovery = build_manifest(source, self.config, name="drill-app-db-test")["spec"]["bootstrap"]["recovery"]
+        self.assertEqual(recovery["database"], "orders")
+        self.assertEqual(recovery["owner"], "orders_user")
+        self.assertEqual(recovery["secret"], {"name": "orders-owner"})
+
+    def test_copies_s3_compatibility_env_without_writer_credentials(self):
+        source = copy.deepcopy(SOURCE)
+        source["spec"]["env"] = [
+            {"name": "AWS_REQUEST_CHECKSUM_CALCULATION", "value": "when_required"},
+            {"name": "AWS_RESPONSE_CHECKSUM_VALIDATION", "value": "when_required"},
+            {"name": "AWS_ACCESS_KEY_ID", "valueFrom": {"secretKeyRef": {"name": "writer", "key": "access"}}},
+            {"name": "AWS_NO_CHUNKED_ENCODING", "valueFrom": {"secretKeyRef": {"name": "writer", "key": "flag"}}},
+        ]
+        env = build_manifest(source, self.config, name="drill-app-db-test")["spec"]["env"]
+        self.assertEqual(env, [
+            {"name": "AWS_REQUEST_CHECKSUM_CALCULATION", "value": "when_required"},
+            {"name": "AWS_RESPONSE_CHECKSUM_VALIDATION", "value": "when_required"},
+        ])
+
+
+class BackupSelectionTest(unittest.TestCase):
+    def setUp(self):
+        self.config = Config.from_dict({"namespace": "production", "cluster": "app-db"})
+
+    def test_chooses_latest_completed_plugin_backup(self):
+        fake = FakeClient()
+        eligible = fake.list_backups("production")[0]
+        older = copy.deepcopy(eligible)
+        older["status"]["backupId"] = "older"
+        older["status"]["stoppedAt"] = (dt.datetime.now(dt.timezone.utc) - dt.timedelta(days=1)).isoformat()
+        failed = copy.deepcopy(eligible)
+        failed["status"]["phase"] = "failed"
+        chosen, age = choose_backup([older, failed, eligible], self.config)
+        self.assertEqual(chosen["status"]["backupId"], "20260929T120000")
+        self.assertLess(age, 7200)
+
+    def test_rejects_stale_backup(self):
+        config = Config.from_dict({"namespace": "production", "cluster": "app-db", "maxBackupAgeSeconds": 30})
+        with self.assertRaisesRegex(DrillError, "above maxBackupAgeSeconds"):
+            choose_backup(FakeClient().list_backups("production"), config)
+
+    def test_pitr_requires_backup_before_target(self):
+        config = Config.from_dict({"namespace": "production", "cluster": "app-db", "targetTime": "2020-01-01T00:00:00Z"})
+        with self.assertRaisesRegex(DrillError, "No completed"):
+            choose_backup(FakeClient().list_backups("production"), config)
+
+
+class RunTest(unittest.TestCase):
+    def setUp(self):
+        self.config = Config.from_dict({"namespace": "production", "cluster": "app-db"})
+
+    def test_success_reports_check_and_cleans_up(self):
+        client = FakeClient()
+        report = run_drill(client, self.config)
+        self.assertEqual(report["status"], "passed")
+        self.assertEqual(report["backupID"], "20260929T120000")
+        self.assertLess(report["backupAgeSeconds"], 7200)
+        self.assertEqual(report["cleanup"], "cluster-and-pvcs-deleted")
+        self.assertEqual(client.deleted, report["drillCluster"])
+        self.assertEqual(report["checks"], [{"name": "connection", "database": "postgres", "passed": True, "observedSha256": hashlib.sha256(b"1").hexdigest()}])
+
+    def test_check_can_query_application_database(self):
+        config = Config.from_dict({"namespace": "production", "cluster": "app-db", "checks": [{"name": "app-data", "database": "app", "query": "SELECT 1", "expected": "1"}]})
+        client = FakeClient()
+        report = run_drill(client, config)
+        self.assertEqual(report["status"], "passed")
+        self.assertEqual(client.queries[0][1], "app")
+        self.assertEqual(report["checks"][0]["database"], "app")
+
+    def test_failed_check_still_cleans_up(self):
+        client = FakeClient(check_result="0")
+        report = run_drill(client, self.config)
+        self.assertEqual(report["status"], "failed")
+        self.assertEqual(report["cleanup"], "cluster-and-pvcs-deleted")
+        self.assertNotIn("got '0'", report["error"])
+
+    def test_cleanup_failure_fails_drill(self):
+        client = FakeClient(cleanup_error=True)
+        report = run_drill(client, self.config)
+        self.assertEqual(report["status"], "failed")
+        self.assertEqual(report["cleanup"], "failed")
+
+    def test_attempts_cleanup_after_ambiguous_create_failure(self):
+        client = FakeClient(create_error=True)
+        report = run_drill(client, self.config)
+        self.assertEqual(report["status"], "failed")
+        self.assertEqual(client.deleted, client.created["metadata"]["name"])
+        self.assertNotEqual(report.get("phase"), "preflight")
+
+    def test_stale_backup_is_preflight_failure(self):
+        client = FakeClient()
+        config = Config.from_dict({"namespace": "production", "cluster": "app-db", "maxBackupAgeSeconds": 1})
+        report = run_drill(client, config)
+        self.assertEqual(report["phase"], "preflight")
+        self.assertIsNone(client.created)
+
+    def test_retention_only_on_failure(self):
+        client = FakeClient(check_result="0")
+        config = Config.from_dict({"namespace": "production", "cluster": "app-db", "retainOnFailure": True})
+        report = run_drill(client, config)
+        self.assertEqual(report["cleanup"], "retained-for-investigation")
+        self.assertIsNone(client.deleted)
+
+    def test_freshness_check_passes_without_logging_timestamp(self):
+        import datetime as dt
+        observed = (dt.datetime.now(dt.timezone.utc) - dt.timedelta(seconds=10)).isoformat()
+        client = FakeClient(check_result=observed)
+        config = Config.from_dict({"namespace": "production", "cluster": "app-db", "checks": [{"name": "recent-order", "query": "SELECT now()", "maxAgeSeconds": 60}]})
+        report = run_drill(client, config)
+        self.assertEqual(report["status"], "passed")
+        self.assertNotIn(observed, str(report))
+        self.assertLess(report["checks"][0]["ageSeconds"], 60)
+
+    def test_recovery_diagnostic_classifies_without_leaking_logs(self):
+        logs = ['{"error":"WAL file 000000010000000000000005 not found in archive s3://private/"}']
+        self.assertEqual(recovery_failure_reason(logs), "wal_unavailable")
+        self.assertEqual(recovery_failure_reason(['{"error":"AccessDenied: secret-bucket"}']), "archive_access_denied")
+        self.assertIsNone(recovery_failure_reason(['{"msg":"restored log file from archive"}']))
+
+    def test_timeout_reports_safe_reason_and_cleans_up(self):
+        class FailedRecovery(FakeClient):
+            def recovery_logs(self, cluster, namespace):
+                return ['{"error":"AccessDenied for s3://secret-path/"}']
+
+        client = FailedRecovery(ready=False)
+        times = iter([0, 1, 31, 32, 33])
+        config = Config.from_dict({"namespace": "production", "cluster": "app-db", "timeoutSeconds": 30})
+        report = run_drill(client, config, sleep=lambda _: None, monotonic=lambda: next(times))
+        self.assertEqual(report["failureReason"], "archive_access_denied")
+        self.assertNotIn("secret-path", str(report))
+        self.assertEqual(report["cleanup"], "cluster-and-pvcs-deleted")
+
+
+if __name__ == "__main__":
+    unittest.main()