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

fdai_deployment_cli/standalone_host_rebind.py

@@ -0,0 +1,226 @@
+"""Retained managed-host input rebind operations."""
+
+from __future__ import annotations
+
+import argparse
+import copy
+import re
+from collections.abc import Callable
+from pathlib import Path
+
+from fdai_deployment_cli import standalone_planned_outputs, standalone_terraform_environment
+from fdai_deployment_cli.contracts import canonical_digest
+from fdai_deployment_cli.standalone_host_state import private_json, replace_private_json
+from fdai_deployment_cli.standalone_license_installation import aks_license_environment
+from fdai_deployment_cli.standalone_stage_targets import (
+    focused_private_access,
+    reconcile_retained_private_access,
+)
+
+ManagedIdentityLogin = Callable[[dict[str, object], Path], None]
+
+
+def reconcile_retained_aks_license_binding(
+    retained_values: dict[str, object],
+    current_values: dict[str, object],
+) -> bool:
+    """Admit only the first verified license binding into a retained Core workload."""
+    retained_workloads = retained_values.get("workloads")
+    current_workloads = current_values.get("workloads")
+    if not isinstance(retained_workloads, dict) or not isinstance(current_workloads, dict):
+        raise TypeError("retained AKS workload inventory is invalid")
+    retained_core = retained_workloads.get("core-control-plane")
+    current_core = current_workloads.get("core-control-plane")
+    if not isinstance(retained_core, dict) or not isinstance(current_core, dict):
+        raise TypeError("retained Core workload is invalid")
+    environment_keys = {"FDAI_LICENSE_IMAGE_DIGEST", "FDAI_LICENSE_TOKEN_REVISION"}
+    secret_keys = {"FDAI_LICENSE_TOKEN"}
+    changed = False
+    for field, allowed in (
+        ("environment", environment_keys),
+        ("secret_environment", secret_keys),
+    ):
+        retained = retained_core.get(field)
+        current = current_core.get(field)
+        if not isinstance(retained, dict) or not isinstance(current, dict):
+            raise TypeError("retained Core license binding is invalid")
+        previous = {key: retained.get(key) for key in allowed if key in retained}
+        selected = {key: current.get(key) for key in allowed if key in current}
+        if previous and previous != selected:
+            raise ValueError("retained Core license binding differs")
+        if not previous and selected:
+            retained.update(selected)
+            changed = True
+    if changed:
+        image_digest = retained_core["environment"].get("FDAI_LICENSE_IMAGE_DIGEST")
+        revision = retained_core["environment"].get("FDAI_LICENSE_TOKEN_REVISION")
+        token_secret = retained_core["secret_environment"].get("FDAI_LICENSE_TOKEN")
+        if (
+            not isinstance(image_digest, str)
+            or re.fullmatch(r"[0-9a-f]{64}", image_digest) is None
+            or not isinstance(revision, str)
+            or re.fullmatch(r"[0-9a-f]{64}", revision) is None
+            or token_secret != "fdai-capability-license"
+        ):
+            raise ValueError("new Core license binding is invalid")
+    return changed
+
+
+def bind_installed_license(
+    _args: argparse.Namespace,
+    work_dir: Path,
+) -> dict[str, object]:
+    """Bind an already verified entitlement to the retained Core workload contract."""
+    application_values = private_json(
+        work_dir / "application.auto.tfvars.json",
+        "application variables",
+    )
+    environment, secrets = aks_license_environment(application_values)
+    if not environment or secrets != {"FDAI_LICENSE_TOKEN": "fdai-capability-license"}:
+        raise ValueError("verified installed license binding is unavailable")
+    workloads_path = work_dir / "workloads.auto.tfvars.json"
+    context_path = work_dir / "context.json"
+    retained_values = private_json(workloads_path, "AKS workload variables")
+    current_values = copy.deepcopy(retained_values)
+    current_workloads = current_values.get("workloads")
+    if not isinstance(current_workloads, dict):
+        raise TypeError("AKS workload inventory is invalid")
+    current_core = current_workloads.get("core-control-plane")
+    if not isinstance(current_core, dict):
+        raise TypeError("Core workload is invalid")
+    current_environment = current_core.get("environment")
+    current_secrets = current_core.get("secret_environment")
+    if not isinstance(current_environment, dict) or not isinstance(current_secrets, dict):
+        raise TypeError("Core workload environment is invalid")
+    current_environment.update(environment)
+    current_secrets.update(secrets)
+    changed = reconcile_retained_aks_license_binding(retained_values, current_values)
+
+    context = private_json(context_path, "standalone host context")
+    expected = context.get("expected_workloads")
+    if not isinstance(expected, dict):
+        raise TypeError("expected AKS workload inventory is invalid")
+    expected_core = expected.get("core-control-plane")
+    if not isinstance(expected_core, dict):
+        raise TypeError("expected Core workload is invalid")
+    expected_secrets = expected_core.get("secret_environment")
+    if not isinstance(expected_secrets, dict):
+        raise TypeError("expected Core secret environment is invalid")
+    retained_secret = expected_secrets.get("FDAI_LICENSE_TOKEN")
+    if retained_secret not in {None, secrets["FDAI_LICENSE_TOKEN"]}:
+        raise ValueError("expected Core license binding differs")
+    expected_secrets.update(secrets)
+
+    if changed:
+        replace_private_json(workloads_path, retained_values)
+    replace_private_json(context_path, context)
+    receipt: dict[str, object] = {
+        "schema_version": "fdai.aks-license-workload-binding.v1",
+        "state": "bound",
+        "workloads_digest": canonical_digest(retained_values),
+        "expected_workloads_digest": canonical_digest(expected),
+        "mutation_performed": changed,
+        "subscription_ready": False,
+    }
+    receipt["receipt_digest"] = canonical_digest(receipt)
+    replace_private_json(work_dir / "license-workload-binding-receipt.json", receipt)
+    return receipt
+
+
+def refresh_private_access(
+    _args: argparse.Namespace,
+    work_dir: Path,
+    *,
+    login: ManagedIdentityLogin,
+) -> dict[str, object]:
+    """Refresh only policy-forced private-access selectors after a claimed substrate failure."""
+    context_path = work_dir / "context.json"
+    variables_path = work_dir / "application.auto.tfvars.json"
+    context = private_json(context_path, "standalone host context")
+    variables = private_json(variables_path, "standalone host Terraform variables")
+    login(context, work_dir)
+    key_vault_private_access = (
+        standalone_terraform_environment.requires_aks_key_vault_private_access(
+            subscription_id=str(context["subscription_id"]),
+            resource_group_name=str(context["resource_group_name"]),
+            vault_name=str(context["key_vault_name"]),
+            work_dir=work_dir,
+        )
+    )
+    document_storage_private_access = (
+        standalone_terraform_environment.requires_aks_document_storage_private_access(
+            subscription_id=str(context["subscription_id"]),
+            resource_group_name=str(context["resource_group_name"]),
+            account_name=str(context["document_storage_account_name"]),
+            work_dir=work_dir,
+        )
+    )
+    changed = reconcile_retained_private_access(
+        context,
+        variables,
+        key_vault_private_access,
+        document_storage_private_access,
+    )
+    if changed:
+        replace_private_json(context_path, context)
+        replace_private_json(variables_path, variables)
+    return {
+        "schema_version": "fdai.standalone-private-access-refresh.v1",
+        "state": "refreshed",
+        "focused_private_access": focused_private_access(context),
+        "mutation_performed": False,
+        "subscription_ready": False,
+    }
+
+
+def prepare_managed_identity_login(
+    context: dict[str, object],
+    work_dir: Path,
+    *,
+    login: Callable[[str, str, str, str, Path], None],
+) -> None:
+    standalone_terraform_environment.configure_terraform(context)
+    standalone_planned_outputs.bind(
+        Path(str(context["infra"])),
+        variables=work_dir / "application.auto.tfvars.json",
+        data_dir=Path(str(context.get("terraform_data", work_dir / "terraform-data"))),
+    )
+    login(
+        str(context["subscription_id"]),
+        str(context["tenant_id"]),
+        str(context["client_id"]),
+        str(context["principal_id"]),
+        work_dir,
+    )
+
+
+def pending_application_operation(
+    context: dict[str, object],
+    work_dir: Path,
+    *,
+    input_rebind_pending: bool,
+) -> str | None:
+    if (
+        input_rebind_pending
+        and not (work_dir / "application-input-rebind-update-receipt.json").is_file()
+    ):
+        return "application-input-rebind-update"
+    if (work_dir / "license-application-update-receipt.json").is_file():
+        return None
+    path = work_dir / "license-workload-binding-receipt.json"
+    if not path.is_file() or path.is_symlink():
+        return None
+    receipt = private_json(path, "license workload binding receipt")
+    digest = receipt.pop("receipt_digest", None)
+    expected = context.get("expected_workloads")
+    workloads = private_json(work_dir / "workloads.auto.tfvars.json", "AKS workload variables")
+    if (
+        canonical_digest(receipt) != digest
+        or receipt.get("schema_version") != "fdai.aks-license-workload-binding.v1"
+        or receipt.get("state") != "bound"
+        or receipt.get("workloads_digest") != canonical_digest(workloads)
+        or not isinstance(expected, dict)
+        or receipt.get("expected_workloads_digest") != canonical_digest(expected)
+    ):
+        raise ValueError("license workload binding receipt is invalid")
+    return "license-application-update"

fdai_deployment_cli/standalone_host_residual.py

@@ -0,0 +1,104 @@
+"""Dispatch managed-host residual and residual-successor applies."""
+
+from __future__ import annotations
+
+import argparse
+from collections.abc import Callable
+from pathlib import Path
+
+from fdai_deployment_cli.standalone_residual_apply import apply_residual_plan
+from fdai_deployment_cli.standalone_residual_successor import apply_residual_successor
+
+
+def _original_operation(stage: str, work_dir: Path) -> str:
+    """Name the claimed apply a residual review extends.
+
+    A fresh AKS runtime is applied as ``runtime-cluster`` before the ordinary ``runtime``
+    operation, so its retained review and claim carry that name until it receives a receipt.
+    """
+
+    if (
+        stage == "runtime"
+        and (work_dir / "runtime-cluster-claim.json").exists()
+        and not (work_dir / "runtime-cluster-receipt.json").exists()
+    ):
+        return "runtime-cluster"
+    return stage
+
+
+def apply_residual_checkpoint(
+    args: argparse.Namespace,
+    work_dir: Path,
+    *,
+    private_json: Callable[[Path, str], dict[str, object]],
+    validate_approval: Callable[..., None],
+    managed_identity_login: Callable[[dict[str, object], Path], None],
+    stage_paths: Callable[[str, dict[str, object], Path], tuple[Path, Path]],
+    activate_stage: Callable[[str, dict[str, object], Path], None],
+    stage_targets: Callable[[str, dict[str, object]], tuple[str, ...]],
+    guard_runtime: Callable[[dict[str, object], Path], None],
+    readback_stage: Callable[[str, dict[str, object]], bool],
+    absolute_path: Callable[[Path], Path],
+) -> dict[str, object]:
+    """Apply the one current residual review under the shared host boundary."""
+
+    stage = str(args.stage)
+    context = private_json(work_dir / "context.json", "standalone host context")
+    receipt_path = work_dir / f"{stage}-receipt.json"
+    residual_review_path = work_dir / f"{stage}-residual-review.json"
+    if receipt_path.exists() and not residual_review_path.exists():
+        return private_json(receipt_path, "standalone residual apply receipt")
+    original = _original_operation(stage, work_dir)
+    original_review = private_json(
+        work_dir / f"{original}-review.json", "standalone original plan review"
+    )
+    original_claim = private_json(
+        work_dir / f"{original}-claim.json", "standalone original apply claim"
+    )
+    residual_review = private_json(residual_review_path, "standalone residual plan review")
+    approval = private_json(absolute_path(args.approval), "standalone residual plan approval")
+    successor_path = work_dir / f"{stage}-residual-successor-review.json"
+    validate_approval(
+        private_json(successor_path, "standalone residual successor review")
+        if successor_path.exists()
+        else residual_review,
+        approval,
+        context=context,
+    )
+    managed_identity_login(context, work_dir)
+    infra, variables = stage_paths(stage, context, work_dir)
+    activate_stage(stage, context, work_dir)
+    targets = stage_targets(stage, context)
+    if stage == "runtime":
+        guard_runtime(context, work_dir)
+    if successor_path.exists():
+        return apply_residual_successor(
+            work_dir=work_dir,
+            stage=stage,
+            context=context,
+            infra=infra,
+            variables=variables,
+            targets=targets,
+            original_review=original_review,
+            original_claim=original_claim,
+            residual_review=residual_review,
+            residual_claim=private_json(
+                work_dir / f"{stage}-residual-claim.json", "standalone residual claim"
+            ),
+            successor_review=private_json(successor_path, "standalone residual successor review"),
+            approval=approval,
+            effect_readback=lambda: readback_stage(stage, context),
+        )
+    return apply_residual_plan(
+        work_dir=work_dir,
+        stage=stage,
+        context=context,
+        infra=infra,
+        variables=variables,
+        targets=targets,
+        original_review=original_review,
+        original_claim=original_claim,
+        residual_review=residual_review,
+        approval=approval,
+        effect_readback=lambda: readback_stage(stage, context),
+    )

fdai_deployment_cli/standalone_host_state.py

@@ -0,0 +1,145 @@
+"""Private filesystem state primitives for standalone deployment checkpoints."""
+
+from __future__ import annotations
+
+import fcntl
+import hashlib
+import json
+import os
+import secrets
+import stat
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+
+from fdai_deployment_cli.private_output import read_private_bytes, write_private_output
+
+
+def private_json(path: Path, label: str) -> dict[str, Any]:
+    """Read one bounded private JSON object through descriptor-safe I/O."""
+    try:
+        value = json.loads(read_private_bytes(path, max_bytes=4 * 1024 * 1024))
+    except json.JSONDecodeError as exc:
+        raise ValueError(f"{label} is invalid") from exc
+    if not isinstance(value, dict):
+        raise ValueError(  # noqa: TRY004 - normalize untrusted JSON into a stable CLI error
+            f"{label} is invalid"
+        )
+    return {str(key): item for key, item in value.items()}
+
+
+def replace_private_json(path: Path, value: dict[str, object]) -> None:
+    """Atomically replace one private JSON object without reusing a temporary path."""
+    temporary = path.parent / f".{path.name}.tmp-{os.getpid()}-{secrets.token_hex(8)}"
+    published = False
+    try:
+        write_private_output(
+            temporary,
+            json.dumps(value, sort_keys=True, separators=(",", ":")) + "\n",
+        )
+        os.replace(temporary, path)
+        path.chmod(0o600)
+        published = True
+    finally:
+        if not published:
+            temporary.unlink(missing_ok=True)
+
+
+def replace_or_verify_private_json(path: Path, value: dict[str, object]) -> None:
+    """Create one private JSON object or verify its exact retained value."""
+    if path.exists():
+        if private_json(path, path.name) != value:
+            raise ValueError(f"retained {path.name} differs")
+        return
+    replace_private_json(path, value)
+
+
+def file_digest(path: Path) -> str:
+    """Hash one bounded private artifact without following symlinks."""
+    return hashlib.sha256(read_private_bytes(path, max_bytes=512 * 1024 * 1024)).hexdigest()
+
+
+def executable_digest(path: Path) -> str:
+    """Hash one current-UID immutable executable through a held descriptor."""
+    descriptor = os.open(path, os.O_RDONLY | os.O_NOFOLLOW | os.O_NONBLOCK)
+    try:
+        details = os.fstat(descriptor)
+        mode = stat.S_IMODE(details.st_mode)
+        if (
+            not stat.S_ISREG(details.st_mode)
+            or details.st_uid != os.geteuid()
+            or details.st_nlink != 1
+            or not mode & stat.S_IXUSR
+            or mode & 0o022
+            or details.st_size > 512 * 1024 * 1024
+        ):
+            raise PermissionError("verified executable permissions are invalid")
+        digest = hashlib.sha256()
+        while chunk := os.read(descriptor, 1024 * 1024):
+            digest.update(chunk)
+        return digest.hexdigest()
+    finally:
+        os.close(descriptor)
+
+
+def private_directory(path: Path) -> None:
+    """Require one absolute current-UID mode-0700 directory."""
+    path.mkdir(parents=True, mode=0o700, exist_ok=True)
+    details = path.lstat()
+    if (
+        not path.is_absolute()
+        or not stat.S_ISDIR(details.st_mode)
+        or stat.S_IMODE(details.st_mode) != 0o700
+        or details.st_uid != os.geteuid()
+    ):
+        raise PermissionError("standalone host work directory must be current-UID mode 0700")
+
+
+def acquire_checkpoint_lock(work_dir: Path) -> int:
+    """Acquire one nonblocking lock for all stateful managed-host checkpoints."""
+    directory = os.open(work_dir, os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW)
+    try:
+        descriptor = os.open(
+            ".checkpoint.lock",
+            os.O_RDWR | os.O_CREAT | os.O_NOFOLLOW,
+            0o600,
+            dir_fd=directory,
+        )
+    finally:
+        os.close(directory)
+    details = os.fstat(descriptor)
+    if (
+        not stat.S_ISREG(details.st_mode)
+        or stat.S_IMODE(details.st_mode) != 0o600
+        or details.st_uid != os.geteuid()
+        or details.st_nlink != 1
+    ):
+        os.close(descriptor)
+        raise PermissionError("standalone checkpoint lock is not a private regular file")
+    try:
+        fcntl.flock(descriptor, fcntl.LOCK_EX | fcntl.LOCK_NB)
+    except BlockingIOError as exc:
+        os.close(descriptor)
+        raise ValueError("another standalone checkpoint is already running") from exc
+    return descriptor
+
+
+def absolute(path: Path) -> Path:
+    """Resolve a CLI path relative to the current working directory without dereferencing it."""
+    return path if path.is_absolute() else Path.cwd() / path
+
+
+def moment(value: datetime) -> str:
+    """Render one UTC instant in the stable machine format."""
+    return value.astimezone(UTC).isoformat().replace("+00:00", "Z")
+
+
+def parse_moment(value: str) -> datetime:
+    """Parse one timezone-aware approval instant and normalize it to UTC."""
+    try:
+        result = datetime.fromisoformat(value)
+    except ValueError as exc:
+        raise ValueError("approval expiry is invalid") from exc
+    if result.tzinfo is None:
+        raise ValueError("approval expiry is invalid")
+    return result.astimezone(UTC)