localargo 0.1.0__py3-none-any.whl

localargo/manager.py

@@ -0,0 +1,232 @@
+# SPDX-FileCopyrightText: 2025-present William Born <william.born.git@gmail.com>
+#
+# SPDX-License-Identifier: MIT
+"""Declarative cluster lifecycle management."""
+
+from __future__ import annotations
+
+import json
+import subprocess
+import time
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+from localargo.config.manifest import load_manifest
+from localargo.logging import logger
+from localargo.providers.base import ProviderError
+from localargo.providers.registry import get_provider
+
+if TYPE_CHECKING:
+    from localargo.providers.base import ClusterProvider
+
+
+class ClusterManagerError(Exception):
+    """Base exception for cluster manager errors."""
+
+
+class ClusterManager:
+    """
+    Declarative cluster lifecycle manager.
+
+    Provides unified orchestration for creating, deleting, and managing
+    clusters defined in YAML manifests using dynamic provider selection.
+
+    Args:
+        manifest_path (str | Path): Path to cluster manifest file
+
+    Raises:
+        ClusterManagerError: If manifest cannot be loaded
+    """
+
+    def __init__(self, manifest_path: str | Path):
+        try:
+            self.manifest = load_manifest(manifest_path)
+        except Exception as e:
+            msg = f"Failed to load manifest: {e}"
+            raise ClusterManagerError(msg) from e
+
+        # Create provider instances for each cluster
+        self.providers: dict[str, ClusterProvider] = {}
+        for cluster_config in self.manifest.clusters:
+            provider_class = get_provider(cluster_config.provider)
+            provider_instance = provider_class(name=cluster_config.name)
+            self.providers[cluster_config.name] = provider_instance
+
+    def apply(self) -> dict[str, bool]:
+        """
+        Create all clusters defined in the manifest.
+
+        Returns:
+            dict[str, bool]: Dictionary mapping cluster names to success status
+        """
+        logger.info("Applying cluster manifest...")
+        results = {}
+
+        for cluster_config in self.manifest.clusters:
+            cluster_name = cluster_config.name
+            logger.info(
+                "Creating cluster '%s' with provider '%s'",
+                cluster_name,
+                cluster_config.provider,
+            )
+
+            try:
+                provider = self.providers[cluster_name]
+                success = provider.create_cluster(**cluster_config.kwargs)
+                results[cluster_name] = success
+
+                if success:
+                    logger.info("✅ Cluster '%s' created successfully", cluster_name)
+                    self._update_state_file(cluster_name, "created", cluster_config.provider)
+                else:
+                    logger.error("❌ Failed to create cluster '%s'", cluster_name)
+
+            except ProviderError as e:
+                logger.error("❌ Error creating cluster '%s': %s", cluster_name, e)
+                results[cluster_name] = False
+            except (OSError, subprocess.SubprocessError, RuntimeError, ValueError) as e:
+                logger.error("❌ System error creating cluster '%s': %s", cluster_name, e)
+                results[cluster_name] = False
+
+        return results
+
+    def delete(self) -> dict[str, bool]:
+        """
+        Delete all clusters defined in the manifest.
+
+        Returns:
+            dict[str, bool]: Dictionary mapping cluster names to success status
+        """
+        logger.info("Deleting clusters from manifest...")
+        results = {}
+
+        for cluster_config in self.manifest.clusters:
+            cluster_name = cluster_config.name
+            logger.info("Deleting cluster '%s'", cluster_name)
+
+            try:
+                provider = self.providers[cluster_name]
+                success = provider.delete_cluster()
+                results[cluster_name] = success
+
+                if success:
+                    logger.info("✅ Cluster '%s' deleted successfully", cluster_name)
+                    self._update_state_file(cluster_name, "deleted", cluster_config.provider)
+                else:
+                    logger.error("❌ Failed to delete cluster '%s'", cluster_name)
+
+            except ProviderError as e:
+                logger.error("❌ Error deleting cluster '%s': %s", cluster_name, e)
+                results[cluster_name] = False
+            except (OSError, subprocess.SubprocessError, RuntimeError, ValueError) as e:
+                logger.error("❌ System error deleting cluster '%s': %s", cluster_name, e)
+                results[cluster_name] = False
+
+        return results
+
+    def status(self) -> dict[str, dict[str, Any]]:
+        """
+        Get status of all clusters defined in the manifest.
+
+        Returns:
+            dict[str, dict[str, Any]]: Dictionary mapping cluster names to status information
+        """
+        logger.info("Getting cluster status...")
+        results = {}
+
+        for cluster_config in self.manifest.clusters:
+            cluster_name = cluster_config.name
+
+            try:
+                provider = self.providers[cluster_name]
+                status_info = provider.get_cluster_status()
+                results[cluster_name] = status_info
+
+                if status_info.get("ready", False):
+                    logger.info("✅ Cluster '%s': ready", cluster_name)
+                elif status_info.get("exists", False):
+                    logger.warning("⚠️  Cluster '%s': exists but not ready", cluster_name)
+                else:
+                    logger.warning("❌ Cluster '%s': does not exist", cluster_name)
+
+            except ProviderError as e:
+                logger.error("❌ Error getting status for cluster '%s': %s", cluster_name, e)
+                results[cluster_name] = {
+                    "error": str(e),
+                    "exists": False,
+                    "ready": False,
+                }
+            except (OSError, subprocess.SubprocessError, RuntimeError, ValueError) as e:
+                logger.error(
+                    "❌ System error getting status for cluster '%s': %s", cluster_name, e
+                )
+                results[cluster_name] = {
+                    "error": str(e),
+                    "exists": False,
+                    "ready": False,
+                }
+
+        return results
+
+    def _update_state_file(self, cluster_name: str, action: str, provider: str) -> None:
+        """
+        Update persistent state file with cluster information.
+
+        Args:
+            cluster_name (str): Name of the cluster
+            action (str): Action performed ('created' or 'deleted')
+            provider (str): Provider name used
+        """
+        state_file = Path(".localargo") / "state.json"
+        state = _load_state_file(state_file)
+        cluster_entry = _find_or_create_cluster_entry(state, cluster_name, provider)
+        _update_cluster_entry(cluster_entry, action)
+        _save_state_file(state, state_file)
+
+
+def _load_state_file(state_file: Path) -> dict[str, Any]:
+    """Load state from file, handling corruption gracefully."""
+    state: dict[str, Any] = {"clusters": []}
+    if state_file.exists():
+        try:
+            with open(state_file, encoding="utf-8") as f:
+                state = json.load(f)
+        except (json.JSONDecodeError, FileNotFoundError):
+            # Reset to empty state if file is corrupted
+            state = {"clusters": []}
+    return state
+
+
+def _find_or_create_cluster_entry(
+    state: dict[str, Any], cluster_name: str, provider: str
+) -> Any:
+    """Find existing cluster entry or create a new one."""
+    for cluster in state["clusters"]:
+        if cluster["name"] == cluster_name:
+            return cluster
+
+    # Create new cluster entry
+    cluster_entry = {
+        "name": cluster_name,
+        "provider": provider,
+        "created": None,
+        "last_action": None,
+    }
+    state["clusters"].append(cluster_entry)
+    return cluster_entry
+
+
+def _update_cluster_entry(cluster_entry: dict[str, Any], action: str) -> None:
+    """Update cluster entry with action and timestamp."""
+    timestamp = int(time.time())
+    if action == "created":
+        cluster_entry["created"] = timestamp
+    cluster_entry["last_action"] = action
+    cluster_entry["last_updated"] = timestamp
+
+
+def _save_state_file(state: dict[str, Any], state_file: Path) -> None:
+    """Save state to file, ensuring directory exists."""
+    state_file.parent.mkdir(exist_ok=True)
+    with open(state_file, "w", encoding="utf-8") as f:
+        json.dump(state, f, indent=2)

localargo/providers/__init__.py

@@ -0,0 +1,6 @@
+# SPDX-FileCopyrightText: 2025-present William Born <william.born.git@gmail.com>
+#
+# SPDX-License-Identifier: MIT
+"""Cluster provider implementations."""
+
+from __future__ import annotations

localargo/providers/base.py

@@ -0,0 +1,146 @@
+# SPDX-FileCopyrightText: 2025-present William Born <william.born.git@gmail.com>
+#
+# SPDX-License-Identifier: MIT
+"""Base classes and interfaces for cluster providers."""
+
+from __future__ import annotations
+
+import abc
+import subprocess
+import time
+from typing import Any
+
+from localargo.utils.cli import check_cli_availability, run_subprocess
+
+
+def check_process_exited_with_error(
+    process: subprocess.Popen, error_msg: str = "Process failed"
+) -> None:
+    """Check if a process has exited and raise error if it failed.
+
+    Args:
+        process (subprocess.Popen): The subprocess.Popen object to check
+        error_msg (str): Error message to raise if process exited with non-zero code
+
+    Raises:
+        ClusterCreationError: If process has exited with non-zero return code
+    """
+    if process.poll() is not None and process.returncode != 0:
+        raise ClusterCreationError(error_msg)
+
+
+class ClusterProvider(abc.ABC):
+    """Abstract base class for Kubernetes cluster providers."""
+
+    def __init__(self, name: str = "localargo"):
+        self.name = name
+
+    @property
+    @abc.abstractmethod
+    def provider_name(self) -> str:
+        """Name of the provider (e.g., 'kind', 'k3s')."""
+
+    @abc.abstractmethod
+    def is_available(self) -> bool:
+        """Check if the provider is installed and available."""
+
+    @abc.abstractmethod
+    def create_cluster(self, **kwargs: Any) -> bool:
+        """Create a new cluster with the provider."""
+
+    @abc.abstractmethod
+    def delete_cluster(self, name: str | None = None) -> bool:
+        """Delete a cluster."""
+
+    @abc.abstractmethod
+    def get_cluster_status(self, name: str | None = None) -> dict[str, Any]:
+        """Get cluster status information."""
+
+    def get_context_name(self, cluster_name: str | None = None) -> str:
+        """Get the kubectl context name for this cluster."""
+        cluster_name = cluster_name or self.name
+        return f"{self.provider_name}-{cluster_name}"
+
+    def _ensure_kubectl_available(self) -> str:
+        """Ensure kubectl is available and return its path.
+
+        Returns:
+            str: Path to kubectl executable
+
+        Raises:
+            FileNotFoundError: If kubectl is not found in PATH
+        """
+        kubectl_path = check_cli_availability("kubectl", "kubectl not found in PATH")
+        if not kubectl_path:
+            msg = "kubectl not found in PATH"
+            raise FileNotFoundError(msg)
+        return kubectl_path
+
+    def _run_kubectl_command(
+        self, cmd: list[str], **kwargs: Any
+    ) -> subprocess.CompletedProcess[str]:
+        """Run a kubectl command with standardized error handling.
+
+        Args:
+            cmd (list[str]): kubectl command as list of strings
+            **kwargs (Any): Additional arguments for subprocess.run
+
+        Returns:
+            subprocess.CompletedProcess[str]: CompletedProcess from subprocess.run
+        """
+        kubectl_path = self._ensure_kubectl_available()
+        return run_subprocess([kubectl_path, *cmd], **kwargs)
+
+    def _wait_for_cluster_ready(
+        self, context_name: str | subprocess.Popen, timeout: int = 300
+    ) -> None:
+        """Wait for cluster to become ready by checking cluster-info.
+
+        Args:
+            context_name (str | subprocess.Popen): kubectl context name for the cluster
+                or process for k3s
+            timeout (int): Maximum time to wait in seconds
+
+        Raises:
+            ClusterCreationError: If cluster doesn't become ready within timeout
+        """
+        start_time = time.time()
+        while time.time() - start_time < timeout:
+            try:
+                if isinstance(context_name, str):
+                    # Standard kubectl-based wait
+                    self._run_kubectl_command(
+                        ["cluster-info", "--context", context_name],
+                        capture_output=True,
+                        check=True,
+                    )
+                    return
+
+                # k3s-specific process-based wait
+                check_process_exited_with_error(
+                    context_name, error_msg="k3s server process exited with error"
+                )
+            except subprocess.CalledProcessError:
+                if isinstance(context_name, str):
+                    time.sleep(2)
+                # For k3s, continue polling the process
+
+        if isinstance(context_name, str):
+            msg = f"Cluster '{self.name}' failed to become ready within {timeout} seconds"
+            raise ClusterCreationError(msg)
+
+
+class ProviderError(Exception):
+    """Base exception for provider-related errors."""
+
+
+class ProviderNotAvailableError(ProviderError):
+    """Raised when a provider is not available."""
+
+
+class ClusterCreationError(ProviderError):
+    """Raised when cluster creation fails."""
+
+
+class ClusterOperationError(ProviderError):
+    """Raised when a cluster operation fails."""

localargo/providers/k3s.py

@@ -0,0 +1,206 @@
+# SPDX-FileCopyrightText: 2025-present William Born <william.born.git@gmail.com>
+#
+# SPDX-License-Identifier: MIT
+"""k3s provider implementation."""
+
+from __future__ import annotations
+
+import os
+import subprocess
+import tempfile
+import time
+from pathlib import Path
+from typing import Any
+
+from localargo.providers.base import (
+    ClusterCreationError,
+    ClusterOperationError,
+    ClusterProvider,
+    ProviderNotAvailableError,
+    check_process_exited_with_error,
+)
+from localargo.utils.cli import check_cli_availability, run_subprocess
+
+
+def build_k3s_server_command(kubeconfig_path: str) -> list[str]:
+    """Build the k3s server command with standard options.
+
+    Args:
+        kubeconfig_path (str): Path where kubeconfig should be written
+
+    Returns:
+        list[str]: k3s server command as list of strings
+    """
+    return [
+        "k3s",
+        "server",
+        "--cluster-init",  # Enable clustering
+        "--disable",
+        "traefik",  # Disable default ingress
+        "--disable",
+        "servicelb",  # Disable service load balancer
+        "--write-kubeconfig",
+        kubeconfig_path,
+    ]
+
+
+class K3sProvider(ClusterProvider):
+    """k3s (lightweight Kubernetes) cluster provider."""
+
+    def __init__(self, name: str = "localargo"):
+        super().__init__(name)
+        # Use secure temp file for kubeconfig
+        _, temp_path = tempfile.mkstemp(suffix=".yaml")
+        self._kubeconfig_path = temp_path
+
+    @property
+    def provider_name(self) -> str:
+        return "k3s"
+
+    def is_available(self) -> bool:
+        """Check if k3s is installed and available."""
+        try:
+            k3s_path = check_cli_availability("k3s")
+            if not k3s_path:
+                return False
+            result = subprocess.run(
+                [k3s_path, "--version"], capture_output=True, text=True, check=True
+            )
+            return "k3s" in result.stdout.lower()
+        except (subprocess.CalledProcessError, FileNotFoundError, RuntimeError):
+            return False
+
+    def create_cluster(self, **kwargs: Any) -> bool:  # noqa: ARG002
+        """Create a k3s cluster with ArgoCD-friendly configuration."""
+        if not self.is_available():
+            msg = "k3s is not installed. Install with: curl -sfL https://get.k3s.io | sh -"
+            raise ProviderNotAvailableError(msg)
+
+        try:
+            # Set up environment for k3s
+            env = os.environ.copy()
+            env["K3S_KUBECONFIG_OUTPUT"] = self._kubeconfig_path
+            env["K3S_CLUSTER_NAME"] = self.name
+
+            # Start k3s server in background
+            cmd = build_k3s_server_command(self._kubeconfig_path)
+
+            # Start k3s server in background - process must persist beyond this method
+            process = subprocess.Popen(  # pylint: disable=consider-using-with
+                cmd, env=env, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL
+            )
+
+            # Wait for cluster to be ready
+            self._wait_for_cluster_ready(process)
+
+            # Set up kubectl context
+            self._configure_kubectl_context()
+
+        except subprocess.CalledProcessError as e:
+            msg = f"Failed to create k3s cluster: {e}"
+            raise ClusterCreationError(msg) from e
+        except Exception as e:
+            msg = f"Unexpected error creating k3s cluster: {e}"
+            raise ClusterCreationError(msg) from e
+
+        return True
+
+    def delete_cluster(self, name: str | None = None) -> bool:
+        """Delete a k3s cluster."""
+        # k3s clusters are typically managed as system services
+        # For now, we'll provide guidance rather than automated deletion
+        cluster_name = name or self.name
+        msg = (
+            f"k3s cluster '{cluster_name}' deletion must be done manually. "
+            "Typically: sudo systemctl stop k3s && sudo k3s-uninstall.sh"
+        )
+        raise ClusterOperationError(msg)
+
+    def get_cluster_status(self, name: str | None = None) -> dict[str, Any]:
+        """Get k3s cluster status information."""
+        cluster_name = name or self.name
+
+        status = {
+            "provider": "k3s",
+            "name": cluster_name,
+            "exists": False,
+            "context": cluster_name,
+            "ready": False,
+            "kubeconfig": self._kubeconfig_path,
+        }
+
+        # Check if kubeconfig exists and is valid
+        kubeconfig = Path(self._kubeconfig_path)
+        if kubeconfig.exists():
+            status["exists"] = True
+
+            # Check if cluster is accessible
+            try:
+                run_subprocess(["kubectl", "--kubeconfig", str(kubeconfig), "cluster-info"])
+                status["ready"] = True
+            except subprocess.CalledProcessError:
+                pass
+
+        return status
+
+    def _wait_for_cluster_ready(
+        self, context_name: str | subprocess.Popen, timeout: int = 60
+    ) -> None:
+        """Wait for the k3s cluster to be ready."""
+        # k3s implementation expects a process, not a context name
+        if isinstance(context_name, str):
+            msg = "k3s provider expects a process object, not a context name"
+            raise TypeError(msg)
+
+        start_time = time.time()
+
+        while time.time() - start_time < timeout:
+            check_process_exited_with_error(
+                context_name, error_msg="k3s server process exited with error"
+            )
+            if context_name.poll() is not None:
+                # Process has exited successfully
+                break
+
+            # Check if kubeconfig is ready and cluster is accessible
+            if self._is_kubeconfig_ready():
+                return
+
+            time.sleep(2)
+
+        if context_name.poll() is None:
+            context_name.terminate()
+        msg = f"k3s cluster '{self.name}' failed to become ready within {timeout} seconds"
+        raise ClusterCreationError(msg)
+
+    def _is_kubeconfig_ready(self) -> bool:
+        """Return True if kubeconfig exists and cluster is accessible."""
+        kubeconfig = Path(self._kubeconfig_path)
+        if not kubeconfig.exists():
+            return False
+        try:
+            run_subprocess(["kubectl", "--kubeconfig", str(kubeconfig), "cluster-info"])
+        except subprocess.CalledProcessError:
+            return False
+        return True
+
+    def _configure_kubectl_context(self) -> None:
+        """Configure kubectl context for the k3s cluster."""
+        try:
+            # Rename the default context to our cluster name
+            self._run_kubectl_command(
+                [
+                    "config",
+                    "--kubeconfig",
+                    self._kubeconfig_path,
+                    "rename-context",
+                    "default",
+                    self.name,
+                ],
+                check=True,
+                capture_output=True,
+            )
+
+        except subprocess.CalledProcessError as e:
+            msg = f"Failed to configure kubectl context: {e}"
+            raise ClusterOperationError(msg) from e