cnpg-drill 0.1.2__py3-none-any.whl

cnpg_drill/__init__.py

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

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/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.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,9 @@
+cnpg_drill/__init__.py,sha256=bsuuJxSuvjphv2BC76ueuv60gNLgX98OvIBvJhBN1iE,59
+cnpg_drill/cli.py,sha256=Gq9kprNdYsyq7TQoDF8nGme3Iyg-MqJ0bPTwCbrfJSc,1784
+cnpg_drill/core.py,sha256=6kf97ZtiTogYg2g8N6FdOrY59GTfYTpYtaIGQOqr1jM,22322
+cnpg_drill-0.1.2.dist-info/licenses/LICENSE,sha256=tp91pBoNJGc9mfBSenjbIuE4t_TAji0ohKLZ9kq3yek,1080
+cnpg_drill-0.1.2.dist-info/METADATA,sha256=AX4vSljB5aPQ6b4HPc8QMGci4O9zAp_TlRw6r9Y1FfE,10869
+cnpg_drill-0.1.2.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+cnpg_drill-0.1.2.dist-info/entry_points.txt,sha256=4JZjskQhNDiOSIp92Ac4ogdr2oYbjlq-Vv7oqy16CXs,51
+cnpg_drill-0.1.2.dist-info/top_level.txt,sha256=qy7X-k6OPJbOMahO_v-WvV_LUkFBmPFkIVaownyDXBo,11
+cnpg_drill-0.1.2.dist-info/RECORD,,

cnpg_drill-0.1.2.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

cnpg_drill-0.1.2.dist-info/entry_points.txt

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

cnpg_drill-0.1.2.dist-info/licenses/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.dist-info/top_level.txt

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