fdai-deployment-cli 0.1.2__py3-none-any.whl

fdai_deployment_cli/hub_workload_handoff.py

@@ -0,0 +1,264 @@
+"""Exact Terraform import, state-release, and rollback contract for Hub workload handoff."""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Mapping, Sequence
+from pathlib import Path
+from typing import Any
+
+from fdai_deployment_cli.contracts import canonical_bytes, canonical_digest
+from fdai_deployment_cli.hub_workload_handoff_inputs import (
+    INVENTORY_SCHEMA,
+    WorkloadStateObject,
+    build_handoff_inventory,
+    read_handoff_inventory,
+    write_handoff_operator_inputs,
+)
+from fdai_deployment_cli.private_output import write_private_bytes
+
+TRANSITION_SCHEMA = "fdai.hub-workload-state-transition.v1"
+RECEIPT_SCHEMA = "fdai.hub-workload-state-transition-receipt.v1"
+ADOPTION_RELEASE_SCHEMA = "fdai.runtime-adoption-release.v1"
+PLAN_RECEIPT_SCHEMA = "fdai.hub-workload-plan-verification.v1"
+_DIGEST = re.compile(r"sha256:[0-9a-f]{64}\Z", re.ASCII)
+
+__all__ = [
+    "WorkloadStateObject",
+    "build_handoff_inventory",
+    "read_handoff_inventory",
+    "verify_handoff_plan",
+    "verify_handoff_plans",
+    "write_handoff_operator_inputs",
+    "write_handoff_terraform_files",
+]
+
+
+def verify_handoff_plan(
+    plan: Mapping[str, object],
+    objects: Sequence[WorkloadStateObject],
+    *,
+    phase: str,
+    inventory_digest: str,
+) -> dict[str, object]:
+    """Verify an exact import, forget-only release, or post-import zero-change plan."""
+
+    if (
+        phase not in {"import", "release", "zero-change"}
+        or _DIGEST.fullmatch(inventory_digest) is None
+    ):
+        raise ValueError("Hub handoff plan verification inputs are invalid")
+    expected = {item.address: item for item in objects}
+    if not expected or len(expected) != len(objects):
+        raise ValueError("Hub handoff plan objects must be unique")
+    _plan_header(plan, applyable=phase != "zero-change")
+    changes = _plan_changes(plan)
+    if set(changes) != set(expected):
+        raise ValueError(f"Hub handoff {phase} plan inventory differs")
+    for address, change in changes.items():
+        actions = change.get("actions")
+        importing = change.get("importing")
+        if phase == "import":
+            before = change.get("before")
+            if (
+                actions != ["no-op"]
+                or not isinstance(importing, Mapping)
+                or importing.get("id") != expected[address].import_id
+                or (before is not None and before != change.get("after"))
+            ):
+                raise ValueError("Hub handoff import plan is not exact import-only")
+        elif phase == "release":
+            if (
+                actions != ["forget"]
+                or importing is not None
+                or change.get("before") is None
+                or change.get("after") is not None
+            ):
+                raise ValueError("Hub handoff release plan is not exact forget-only")
+        elif (
+            actions != ["no-op"]
+            or importing is not None
+            or "before" not in change
+            or change.get("before") != change.get("after")
+        ):
+            raise ValueError("Hub handoff plan is not zero-change")
+    body: dict[str, object] = {
+        "schema_version": PLAN_RECEIPT_SCHEMA,
+        "phase": phase,
+        "inventory_digest": inventory_digest,
+        "plan_digest": "sha256:" + canonical_digest(plan),
+        "object_count": len(expected),
+        "live_mutation_authorized": False,
+        "state_effect": {
+            "import": "import-only",
+            "release": "forgotten-without-destroy",
+            "zero-change": "zero-change",
+        }[phase],
+    }
+    return body | {"receipt_digest": "sha256:" + canonical_digest(body)}
+
+
+def write_handoff_terraform_files(
+    destination: Path,
+    objects: Sequence[WorkloadStateObject],
+) -> tuple[Path, Path]:
+    """Write exact removed/import blocks into a fresh private execution directory."""
+
+    if destination.exists() or destination.is_symlink():
+        raise ValueError("Hub handoff Terraform destination already exists")
+    by_address = {item.address: item for item in objects}
+    if not by_address or len(by_address) != len(objects):
+        raise ValueError("Hub handoff Terraform objects must be unique")
+    destination.mkdir(mode=0o700, parents=True)
+    release_path = destination / "hub-release.tf.json"
+    rollback_path = destination / "hub-rollback.tf.json"
+    write_private_bytes(
+        release_path,
+        canonical_bytes(
+            {
+                "removed": [
+                    {
+                        "from": f"${{{address}}}",
+                        "lifecycle": {"destroy": False},
+                    }
+                    for address in sorted(by_address)
+                ]
+            }
+        )
+        + b"\n",
+    )
+    write_private_bytes(
+        rollback_path,
+        canonical_bytes(
+            {
+                "import": [
+                    {
+                        "to": f"${{{address}}}",
+                        "id": by_address[address].import_id,
+                    }
+                    for address in sorted(by_address)
+                ]
+            }
+        )
+        + b"\n",
+    )
+    return release_path, rollback_path
+
+
+def verify_handoff_plans(
+    release_plan: Mapping[str, object],
+    rollback_plan: Mapping[str, object],
+    objects: Sequence[WorkloadStateObject],
+    *,
+    adoption_release: Mapping[str, object],
+) -> dict[str, object]:
+    """Require exact forget-only release and zero-change rollback plans."""
+
+    adoption_release_digest = _adoption_release_digest(adoption_release)
+    inventory_body = {
+        "schema_version": INVENTORY_SCHEMA,
+        "objects": [
+            {
+                "address": item.address,
+                "import_id": item.import_id,
+                "render_digest": item.render_digest,
+            }
+            for item in sorted(objects, key=lambda value: value.address)
+        ],
+    }
+    inventory_digest = "sha256:" + canonical_digest(inventory_body)
+    release_verification = verify_handoff_plan(
+        release_plan,
+        objects,
+        phase="release",
+        inventory_digest=inventory_digest,
+    )
+    rollback_verification = verify_handoff_plan(
+        rollback_plan,
+        objects,
+        phase="zero-change",
+        inventory_digest=inventory_digest,
+    )
+    body: dict[str, object] = {
+        "schema_version": RECEIPT_SCHEMA,
+        "objects": [
+            {
+                "address": item.address,
+                "import_id": item.import_id,
+                "render_digest": item.render_digest,
+            }
+            for item in sorted(objects, key=lambda value: value.address)
+        ],
+        "release_plan_digest": "sha256:" + canonical_digest(release_plan),
+        "rollback_plan_digest": "sha256:" + canonical_digest(rollback_plan),
+        "release_verification_digest": release_verification["receipt_digest"],
+        "rollback_verification_digest": rollback_verification["receipt_digest"],
+        "adoption_release_receipt_digest": adoption_release_digest,
+        "release_state": "forgotten-without-destroy",
+        "rollback_state": "zero-change",
+    }
+    return body | {"receipt_digest": "sha256:" + canonical_digest(body)}
+
+
+def _adoption_release_digest(receipt: Mapping[str, object]) -> str:
+    digest = receipt.get("receipt_digest")
+    body = {key: value for key, value in receipt.items() if key != "receipt_digest"}
+    if (
+        body.get("schema_version") != ADOPTION_RELEASE_SCHEMA
+        or body.get("reconciliation_released") is not True
+        or not isinstance(body.get("installation_id"), str)
+        or not isinstance(body.get("release_id"), str)
+        or _DIGEST.fullmatch(str(body.get("adoption_receipt_digest"))) is None
+        or not isinstance(digest, str)
+        or digest != "sha256:" + canonical_digest(body)
+    ):
+        raise ValueError("Agent reconciliation release receipt is invalid")
+    return digest
+
+
+def _plan_header(plan: Mapping[str, object], *, applyable: bool) -> None:
+    if (
+        plan.get("format_version") not in {"1.1", "1.2"}
+        or plan.get("complete") is not True
+        or plan.get("errored") is not False
+        or plan.get("applyable") is not applyable
+        or plan.get("resource_drift", []) != []
+        or plan.get("deferred_changes", []) != []
+    ):
+        raise ValueError("Hub handoff plan metadata is invalid")
+    output_changes = plan.get("output_changes", {})
+    if not isinstance(output_changes, Mapping):
+        raise ValueError(  # noqa: TRY004 - normalize untrusted plan JSON
+            "Hub handoff plan outputs are invalid"
+        )
+    if phase_changes := [
+        value
+        for value in output_changes.values()
+        if not isinstance(value, Mapping) or value.get("actions") != ["no-op"]
+    ]:
+        raise ValueError(f"Hub handoff plan contains {len(phase_changes)} output changes")
+    checks = plan.get("checks", [])
+    if not isinstance(checks, list) or any(
+        not isinstance(check, Mapping) or check.get("status") != "pass" for check in checks
+    ):
+        raise ValueError("Hub handoff plan checks must pass")
+
+
+def _plan_changes(plan: Mapping[str, object]) -> dict[str, dict[str, Any]]:
+    changes = plan.get("resource_changes")
+    if not isinstance(changes, list):
+        raise ValueError(  # noqa: TRY004 - normalize untrusted plan JSON
+            "Terraform plan resource changes are invalid"
+        )
+    result: dict[str, dict[str, Any]] = {}
+    for item in changes:
+        if (
+            not isinstance(item, Mapping)
+            or not isinstance(address := item.get("address"), str)
+            or item.get("previous_address") is not None
+            or not isinstance(change := item.get("change"), Mapping)
+            or address in result
+        ):
+            raise ValueError("Terraform plan resource change is invalid")
+        result[address] = dict(change)
+    return result

fdai_deployment_cli/hub_workload_handoff_inputs.py

@@ -0,0 +1,227 @@
+"""Private full-topology inputs for the Hub workload Terraform state handoff."""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass
+from pathlib import Path
+
+from fdai_deployment_cli.contracts import canonical_bytes, canonical_digest
+from fdai_deployment_cli.private_output import write_private_bytes
+
+INVENTORY_SCHEMA = "fdai.hub-workload-state-inventory.v1"
+_ADDRESS = re.compile(
+    r"kubernetes_(?:deployment_v1|service_v1|cron_job_v1|horizontal_pod_autoscaler_v2)"
+    r"\.[a-z][a-z0-9_]*(?:\[[\"'][a-z0-9](?:[-a-z0-9]{0,61}[a-z0-9])?[\"']\])?\Z",
+    re.ASCII,
+)
+_IMPORT_ID = re.compile(r"[a-z0-9](?:[-a-z0-9]{0,61}[a-z0-9])?/[A-Za-z0-9._/-]{1,253}\Z")
+_DIGEST = re.compile(r"sha256:[0-9a-f]{64}\Z", re.ASCII)
+_KIND_RESOURCES = {
+    "Deployment": ("kubernetes_deployment_v1", "workload", "deployments"),
+    "Service": ("kubernetes_service_v1", "workload", "services"),
+    "CronJob": ("kubernetes_cron_job_v1", "job", "cron_jobs"),
+    "HorizontalPodAutoscaler": (
+        "kubernetes_horizontal_pod_autoscaler_v2",
+        "workload",
+        "horizontal_pod_autoscalers",
+    ),
+}
+
+
+@dataclass(frozen=True, slots=True)
+class WorkloadStateObject:
+    address: str
+    import_id: str
+    render_digest: str
+
+    def __post_init__(self) -> None:
+        if (
+            _ADDRESS.fullmatch(self.address) is None
+            or _IMPORT_ID.fullmatch(self.import_id) is None
+            or _DIGEST.fullmatch(self.render_digest) is None
+        ):
+            raise ValueError("Hub workload state object is invalid")
+
+
+def build_handoff_inventory(
+    native_scope: Mapping[str, object],
+    rendered_manifests: Sequence[Mapping[str, object]],
+) -> dict[str, object]:
+    """Bind one exact native scope to Terraform addresses, import IDs, and render digests."""
+
+    namespace = native_scope.get("namespace")
+    if not isinstance(namespace, str):
+        raise ValueError(  # noqa: TRY004 - normalize untrusted JSON into one operator error
+            "Hub workload native scope namespace is invalid"
+        )
+    expected = _native_resources(native_scope)
+    objects: list[WorkloadStateObject] = []
+    actual: set[tuple[str, str]] = set()
+    tfvars: dict[str, dict[str, str]] = {
+        "deployments": {},
+        "services": {},
+        "cron_jobs": {},
+        "horizontal_pod_autoscalers": {},
+    }
+    for manifest in rendered_manifests:
+        kind = manifest.get("kind")
+        metadata = manifest.get("metadata")
+        if (
+            not isinstance(kind, str)
+            or kind not in _KIND_RESOURCES
+            or not isinstance(metadata, Mapping)
+            or not isinstance(name := metadata.get("name"), str)
+            or metadata.get("namespace") != namespace
+        ):
+            raise ValueError("Hub workload rendered manifest is invalid")
+        key = (kind, name)
+        if key in actual:
+            raise ValueError("Hub workload rendered manifests must be unique")
+        actual.add(key)
+        resource_type, resource_name, variable_name = _KIND_RESOURCES[kind]
+        address = f'{resource_type}.{resource_name}["{name}"]'
+        import_id = f"{namespace}/{name}"
+        objects.append(
+            WorkloadStateObject(
+                address=address,
+                import_id=import_id,
+                render_digest="sha256:" + canonical_digest(manifest),
+            )
+        )
+        tfvars[variable_name][name] = import_id
+    if actual != expected:
+        raise ValueError("Hub workload rendered inventory differs from the native scope")
+    ordered = sorted(objects, key=lambda item: item.address)
+    body: dict[str, object] = {
+        "schema_version": INVENTORY_SCHEMA,
+        "namespace": namespace,
+        "objects": [
+            {
+                "address": item.address,
+                "import_id": item.import_id,
+                "render_digest": item.render_digest,
+            }
+            for item in ordered
+        ],
+        "terraform_variables": {
+            "namespace": namespace,
+            **{key: dict(sorted(value.items())) for key, value in tfvars.items()},
+        },
+    }
+    return body | {"inventory_digest": "sha256:" + canonical_digest(body)}
+
+
+def write_handoff_operator_inputs(
+    destination: Path,
+    native_scope: Mapping[str, object],
+    rendered_manifests: Sequence[Mapping[str, object]],
+) -> tuple[Path, Path, Path]:
+    """Write exact Terraform variables, verified inventory, and phase commands."""
+
+    inventory = build_handoff_inventory(native_scope, rendered_manifests)
+    inventory_path = destination / "workload-handoff-inventory.json"
+    tfvars_path = destination / "workload-handoff.tfvars.json"
+    commands_path = destination / "workload-handoff-commands.txt"
+    write_private_bytes(inventory_path, canonical_bytes(inventory) + b"\n")
+    write_private_bytes(
+        tfvars_path,
+        canonical_bytes(inventory["terraform_variables"]) + b"\n",
+    )
+    write_private_bytes(commands_path, _commands().encode())
+    return inventory_path, tfvars_path, commands_path
+
+
+def read_handoff_inventory(document: Mapping[str, object]) -> tuple[WorkloadStateObject, ...]:
+    """Verify and load a generated handoff inventory without trusting its Terraform variables."""
+
+    digest = document.get("inventory_digest")
+    body = {key: value for key, value in document.items() if key != "inventory_digest"}
+    objects = body.get("objects")
+    if (
+        body.get("schema_version") != INVENTORY_SCHEMA
+        or not isinstance(body.get("namespace"), str)
+        or not isinstance(objects, list)
+        or not objects
+        or not isinstance(digest, str)
+        or digest != "sha256:" + canonical_digest(body)
+    ):
+        raise ValueError("Hub workload state inventory is invalid")
+    result: list[WorkloadStateObject] = []
+    for item in objects:
+        if not isinstance(item, Mapping):
+            raise ValueError(  # noqa: TRY004 - normalize untrusted JSON into one operator error
+                "Hub workload state inventory is invalid"
+            )
+        result.append(
+            WorkloadStateObject(
+                address=str(item.get("address", "")),
+                import_id=str(item.get("import_id", "")),
+                render_digest=str(item.get("render_digest", "")),
+            )
+        )
+    if len({item.address for item in result}) != len(result):
+        raise ValueError("Hub workload state inventory is invalid")
+    return tuple(result)
+
+
+def _native_resources(scope: Mapping[str, object]) -> set[tuple[str, str]]:
+    components = _names(scope.get("components"), required=True)
+    services = _names(scope.get("service_components"), required=False)
+    schedules = _names(scope.get("scheduled_components"), required=False)
+    autoscalers = _names(scope.get("autoscaled_components"), required=False)
+    if not services and scope.get("service_components") is None:
+        services = components
+    if not services <= components or not autoscalers <= components or components & schedules:
+        raise ValueError("Hub workload native scope is invalid")
+    return (
+        {("Deployment", name) for name in components}
+        | {("Service", name) for name in services}
+        | {("CronJob", name) for name in schedules}
+        | {("HorizontalPodAutoscaler", name) for name in autoscalers}
+    )
+
+
+def _names(value: object, *, required: bool) -> set[str]:
+    if value is None and not required:
+        return set()
+    if (
+        not isinstance(value, (list, tuple))
+        or (required and not value)
+        or any(not isinstance(item, str) for item in value)
+        or len(set(value)) != len(value)
+    ):
+        raise ValueError("Hub workload native scope is invalid")
+    return set(value)
+
+
+def _commands() -> str:
+    return """\
+# Replace angle-bracket values with private operator paths. Reuse one absolute backend path.
+umask 077
+terraform -chdir=infra/hub-workload-state-handoff/import init -reconfigure -backend-config=path=<absolute-private-state-path>
+terraform -chdir=infra/hub-workload-state-handoff/import plan -var-file=<workload-handoff.tfvars.json> -var=kubeconfig_path=<private-kubeconfig> -var=kubeconfig_context=<kube-context> -out=<import-plan>
+terraform show -json <import-plan> > <import-plan.json>
+fdai-lifecycle-manager verify-workload-handoff-plan --phase import --inventory <workload-handoff-inventory.json> --plan-json <import-plan.json> --destination <import-verification.json>
+terraform -chdir=infra/hub-workload-state-handoff/import apply <import-plan>
+terraform -chdir=infra/hub-workload-state-handoff/import plan -detailed-exitcode -var-file=<workload-handoff.tfvars.json> -var=kubeconfig_path=<private-kubeconfig> -var=kubeconfig_context=<kube-context> -out=<import-zero-plan>
+terraform show -json <import-zero-plan> > <import-zero-plan.json>
+fdai-lifecycle-manager verify-workload-handoff-plan --phase zero-change --inventory <workload-handoff-inventory.json> --plan-json <import-zero-plan.json> --destination <import-zero-verification.json>
+
+terraform -chdir=infra/hub-workload-state-handoff/release init -reconfigure -backend-config=path=<absolute-private-state-path>
+terraform -chdir=infra/hub-workload-state-handoff/release plan -var-file=<workload-handoff.tfvars.json> -var=kubeconfig_path=<private-kubeconfig> -var=kubeconfig_context=<kube-context> -out=<release-plan>
+terraform show -json <release-plan> > <release-plan.json>
+fdai-lifecycle-manager verify-workload-handoff-plan --phase release --inventory <workload-handoff-inventory.json> --plan-json <release-plan.json> --destination <release-verification.json>
+terraform -chdir=infra/hub-workload-state-handoff/release apply <release-plan>
+
+# Rollback only after the Agent reconciliation-release receipt is retained.
+terraform -chdir=infra/hub-workload-state-handoff/import init -reconfigure -backend-config=path=<absolute-private-state-path>
+terraform -chdir=infra/hub-workload-state-handoff/import plan -var-file=<workload-handoff.tfvars.json> -var=kubeconfig_path=<private-kubeconfig> -var=kubeconfig_context=<kube-context> -out=<rollback-import-plan>
+terraform show -json <rollback-import-plan> > <rollback-import-plan.json>
+fdai-lifecycle-manager verify-workload-handoff-plan --phase import --inventory <workload-handoff-inventory.json> --plan-json <rollback-import-plan.json> --destination <rollback-import-verification.json>
+terraform -chdir=infra/hub-workload-state-handoff/import apply <rollback-import-plan>
+terraform -chdir=infra/hub-workload-state-handoff/import plan -detailed-exitcode -var-file=<workload-handoff.tfvars.json> -var=kubeconfig_path=<private-kubeconfig> -var=kubeconfig_context=<kube-context> -out=<rollback-zero-plan>
+terraform show -json <rollback-zero-plan> > <rollback-zero-plan.json>
+fdai-lifecycle-manager verify-workload-handoff-plan --phase zero-change --inventory <workload-handoff-inventory.json> --plan-json <rollback-zero-plan.json> --destination <rollback-zero-verification.json>
+"""