localargo 0.1.0__py3-none-any.whl

localargo/providers/kind.py

@@ -0,0 +1,326 @@
+# SPDX-FileCopyrightText: 2025-present William Born <william.born.git@gmail.com>
+#
+# SPDX-License-Identifier: MIT
+"""KinD (Kubernetes in Docker) provider implementation."""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+import tempfile
+from pathlib import Path
+from typing import Any
+
+from localargo.providers.base import (
+    ClusterCreationError,
+    ClusterOperationError,
+    ClusterProvider,
+    ProviderNotAvailableError,
+)
+from localargo.utils.cli import check_cli_availability, run_subprocess
+
+
+class KindProvider(ClusterProvider):
+    """KinD (Kubernetes in Docker) cluster provider."""
+
+    @property
+    def provider_name(self) -> str:
+        return "kind"
+
+    def _create_kind_config(self) -> str:
+        """Create a kind cluster config with port mappings for ingress."""
+        return """kind: Cluster
+apiVersion: kind.x-k8s.io/v1alpha4
+nodes:
+- role: control-plane
+  extraPortMappings:
+  - containerPort: 80
+    hostPort: 80
+    protocol: TCP
+  - containerPort: 443
+    hostPort: 443
+    protocol: TCP
+"""
+
+    def is_available(self) -> bool:
+        """Check if KinD, kubectl, and helm are installed and available."""
+        try:
+            # Check kind
+            kind_path = check_cli_availability("kind")
+            if not kind_path:
+                return False
+            result = subprocess.run(
+                [kind_path, "version"], capture_output=True, text=True, check=True
+            )
+            if "kind" not in result.stdout.lower():
+                return False
+
+            # Check kubectl
+            kubectl_path = check_cli_availability("kubectl")
+            if not kubectl_path:
+                return False
+
+            # Check helm
+            helm_path = shutil.which("helm")
+            return bool(helm_path)
+        except (subprocess.CalledProcessError, FileNotFoundError, RuntimeError):
+            return False
+
+    def create_cluster(self, **kwargs: Any) -> bool:  # noqa: ARG002
+        """Create a KinD cluster and install ArgoCD with nginx-ingress."""
+        if not self.is_available():
+            msg = (
+                "KinD, kubectl, and helm are required. Install from: "
+                "https://kind.sigs.k8s.io/, https://kubernetes.io/docs/tasks/tools/, "
+                "and https://helm.sh/"
+            )
+            raise ProviderNotAvailableError(msg)
+
+        try:
+            # Create cluster with port mappings for direct access
+            config_content = self._create_kind_config()
+            with tempfile.NamedTemporaryFile(
+                mode="w", suffix=".yaml", delete=False
+            ) as config_file:
+                config_file.write(config_content)
+                config_file_path = config_file.name
+
+            cmd = [
+                "kind",
+                "create",
+                "cluster",
+                "--name",
+                self.name,
+                "--config",
+                config_file_path,
+            ]
+            subprocess.run(cmd, check=True)
+
+            # Clean up temporary config file
+            Path(config_file_path).unlink(missing_ok=True)
+
+            # Wait for cluster to be ready
+            self._wait_for_cluster_ready(f"kind-{self.name}")
+
+            # Install nginx-ingress
+            self._install_nginx_ingress()
+
+            # Install ArgoCD
+            self._install_argocd()
+
+        except subprocess.CalledProcessError as e:
+            msg = f"Failed to create KinD cluster: {e}"
+            raise ClusterCreationError(msg) from e
+
+        return True
+
+    def delete_cluster(self, name: str | None = None) -> bool:
+        """Delete a KinD cluster."""
+        cluster_name = name or self.name
+        try:
+            cmd = ["kind", "delete", "cluster", "--name", cluster_name]
+            subprocess.run(cmd, check=True)  # Show output for debugging
+        except subprocess.CalledProcessError as e:
+            msg = f"Failed to delete KinD cluster '{cluster_name}': {e}"
+            raise ClusterOperationError(msg) from e
+
+        return True
+
+    def get_cluster_status(self, name: str | None = None) -> dict[str, Any]:
+        """Get KinD cluster status information."""
+        cluster_name = name or self.name
+        context_name = f"kind-{cluster_name}"
+
+        try:
+            # Check if cluster exists
+            kind_path = shutil.which("kind")
+            if kind_path is None:
+                msg = "kind not found in PATH. Please ensure kind is installed and available."
+                raise RuntimeError(msg)
+            result = subprocess.run(
+                [kind_path, "get", "clusters"], capture_output=True, text=True, check=True
+            )
+            clusters = result.stdout.strip().split("\n")
+            exists = cluster_name in clusters
+
+            status = {
+                "provider": "kind",
+                "name": cluster_name,
+                "exists": exists,
+                "context": context_name,
+                "ready": False,
+            }
+
+            if exists:
+                # Check if context is accessible
+                try:
+                    run_subprocess(["kubectl", "cluster-info", "--context", context_name])
+                    status["ready"] = True
+                except subprocess.CalledProcessError:
+                    pass
+
+        except subprocess.CalledProcessError as e:
+            msg = f"Failed to get cluster status: {e}"
+            raise ClusterOperationError(msg) from e
+
+        return status
+
+    def _wait_for_cluster_ready(
+        self, context_name: str | subprocess.Popen, timeout: int = 60
+    ) -> None:
+        """Wait for the cluster to be ready."""
+        if isinstance(context_name, str) or context_name is None:
+            context_name = f"kind-{self.name}"
+        super()._wait_for_cluster_ready(context_name, timeout)
+
+    def _install_nginx_ingress(self) -> None:
+        """Install nginx-ingress controller."""
+        helm_path = shutil.which("helm")
+        kubectl_path = shutil.which("kubectl")
+        if helm_path is None:
+            msg = "helm not found in PATH. Please ensure helm is installed and available."
+            raise RuntimeError(msg)
+        if kubectl_path is None:
+            msg = (
+                "kubectl not found in PATH. Please ensure kubectl is installed and available."
+            )
+            raise RuntimeError(msg)
+
+        try:
+            # Add ingress-nginx helm repo
+            subprocess.run(
+                [
+                    helm_path,
+                    "repo",
+                    "add",
+                    "ingress-nginx",
+                    "https://kubernetes.github.io/ingress-nginx",
+                ],
+                check=False,  # Allow failure if repo already exists
+            )
+            subprocess.run([helm_path, "repo", "update"], check=True)
+
+            # Install nginx-ingress using helm with kind-specific configuration
+            subprocess.run(
+                [
+                    helm_path,
+                    "upgrade",
+                    "--install",
+                    "ingress-nginx",
+                    "ingress-nginx/ingress-nginx",
+                    "--namespace",
+                    "ingress-nginx",
+                    "--create-namespace",
+                    "--wait",
+                    "--wait-for-jobs",
+                    "--timeout=180s",
+                    "--set",
+                    "controller.hostNetwork=true",
+                    "--set",
+                    "controller.dnsPolicy=ClusterFirstWithHostNet",
+                    "--set",
+                    "controller.kind=DaemonSet",
+                    "--set",
+                    "controller.service.type=ClusterIP",
+                    "--set",
+                    "controller.extraArgs.enable-ssl-passthrough=true",
+                    "--set",
+                    "controller.extraArgs.enable-ssl-chain-completion=false",
+                    "--set",
+                    "controller.config.use-proxy-protocol=false",
+                    "--set",
+                    "controller.config.compute-full-forwarded-for=true",
+                    "--set",
+                    "controller.config.use-forwarded-headers=true",
+                    "--set",
+                    "controller.config.ssl-protocols=TLSv1.2 TLSv1.3",
+                    "--set",
+                    r"controller.nodeSelector.kubernetes\.io/os=linux",
+                    "--set",
+                    "controller.config.server-name-hash-bucket-size=256",
+                ],
+                check=True,
+            )
+
+            # Wait for controller to be ready
+            subprocess.run(
+                [
+                    kubectl_path,
+                    "-n",
+                    "ingress-nginx",
+                    "rollout",
+                    "status",
+                    "daemonset/ingress-nginx-controller",
+                    "--timeout=180s",
+                ],
+                check=True,
+            )
+
+        except subprocess.CalledProcessError as e:
+            msg = f"Failed to install nginx-ingress: {e}"
+            raise ClusterCreationError(msg) from e
+
+    def _install_argocd(self) -> None:
+        """Install ArgoCD using helm with ingress configuration."""
+        helm_path = shutil.which("helm")
+        if helm_path is None:
+            msg = "helm not found in PATH. Please ensure helm is installed and available."
+            raise RuntimeError(msg)
+
+        try:
+            # Add ArgoCD helm repo
+            subprocess.run(
+                [helm_path, "repo", "add", "argo", "https://argoproj.github.io/argo-helm"],
+                check=True,
+            )
+            subprocess.run([helm_path, "repo", "update"], check=True)
+
+            # Install ArgoCD with ingress enabled using proper SSL passthrough configuration
+            subprocess.run(
+                [
+                    helm_path,
+                    "upgrade",
+                    "--install",
+                    "argocd",
+                    "argo/argo-cd",
+                    "--namespace",
+                    "argocd",
+                    "--create-namespace",
+                    "--wait",
+                    "--wait-for-jobs",
+                    "--timeout=180s",
+                    "--set",
+                    "server.ingress.enabled=true",
+                    "--set",
+                    "server.ingress.ingressClassName=nginx",
+                    "--set",
+                    "server.ingress.hostname=argocd.localtest.me",
+                    "--set",
+                    "server.ingress.annotations.nginx\\.ingress\\.kubernetes\\.io/"
+                    "force-ssl-redirect=true",
+                    "--set",
+                    "server.ingress.annotations.nginx\\.ingress\\.kubernetes\\.io/"
+                    "ssl-passthrough=true",
+                    "--set",
+                    "server.ingress.paths[0]=/",
+                    "--set",
+                    "server.ingress.pathType=Prefix",
+                    "--set",
+                    "server.ingress.tls=false",
+                    "--set",
+                    "server.extraArgs[0]=--insecure=false",
+                    "--set",
+                    "configs.params.server.insecure=false",
+                    "--set",
+                    "configs.params.server.grpc.web=true",
+                    "--set",
+                    "global.domain=argocd.localtest.me",
+                    "--set",
+                    "configs.cm.url=https://argocd.localtest.me",
+                ],
+                check=True,
+            )
+
+        except subprocess.CalledProcessError as e:
+            msg = f"Failed to install ArgoCD: {e}"
+            raise ClusterCreationError(msg) from e

localargo/providers/registry.py

@@ -0,0 +1,52 @@
+# SPDX-FileCopyrightText: 2025-present William Born <william.born.git@gmail.com>
+#
+# SPDX-License-Identifier: MIT
+"""Provider registry for cluster management."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from localargo.providers.k3s import K3sProvider
+from localargo.providers.kind import KindProvider
+
+if TYPE_CHECKING:
+    from localargo.providers.base import ClusterProvider
+
+
+# Registry of available providers
+PROVIDERS: dict[str, type[ClusterProvider]] = {
+    "kind": KindProvider,
+    "k3s": K3sProvider,
+}
+
+
+def get_provider(name: str) -> type[ClusterProvider]:
+    """
+    Get a provider class by name.
+
+    Args:
+        name (str): Name of the provider (e.g., 'kind', 'k3s')
+
+    Returns:
+        type[ClusterProvider]: Provider class
+
+    Raises:
+        ValueError: If provider name is unknown
+    """
+    try:
+        return PROVIDERS[name]
+    except KeyError as err:
+        available = ", ".join(PROVIDERS.keys())
+        msg = f"Unknown provider: {name}. Available providers: {available}"
+        raise ValueError(msg) from err
+
+
+def list_available_providers() -> list[str]:
+    """
+    List names of all available providers.
+
+    Returns:
+        list[str]: List of provider names
+    """
+    return list(PROVIDERS.keys())

localargo/utils/__init__.py

@@ -0,0 +1,4 @@
+# SPDX-FileCopyrightText: 2025-present William Born <william.born.git@gmail.com>
+#
+# SPDX-License-Identifier: MIT
+"""Utility functions and helpers."""

localargo/utils/cli.py

@@ -0,0 +1,231 @@
+# SPDX-FileCopyrightText: 2025-present William Born <william.born.git@gmail.com>
+#
+# SPDX-License-Identifier: MIT
+"""CLI validation and execution utilities."""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+from typing import Any
+
+from localargo.logging import logger
+
+
+def check_cli_availability(cli_name: str, error_msg: str | None = None) -> str | None:
+    """Check if a CLI tool is available in PATH.
+
+    Args:
+        cli_name (str): Name of the CLI tool to check
+        error_msg (str | None): Optional error message to raise if CLI not found
+
+    Returns:
+        str | None: Path to the CLI executable if found, None otherwise
+
+    Raises:
+        FileNotFoundError: If error_msg is provided and CLI is not found
+    """
+    path = shutil.which(cli_name)
+    if not path and error_msg:
+        raise FileNotFoundError(error_msg)
+    return path
+
+
+def ensure_argocd_available() -> str:
+    """Ensure argocd CLI is available and return its path.
+
+    Returns:
+        str: Path to the argocd CLI executable
+
+    Raises:
+        FileNotFoundError: If argocd CLI is not found
+    """
+    argocd_path = check_cli_availability("argocd", "argocd CLI not found")
+    if not argocd_path:
+        msg = "argocd CLI not found"
+        raise FileNotFoundError(msg)
+    return argocd_path
+
+
+def ensure_kubectl_available() -> str:
+    """Ensure kubectl CLI is available and return its path.
+
+    Returns:
+        str: Path to the kubectl CLI executable
+
+    Raises:
+        FileNotFoundError: If kubectl CLI is not found
+    """
+    kubectl_path = check_cli_availability("kubectl", "kubectl not found")
+    if not kubectl_path:
+        msg = "kubectl not found"
+        raise FileNotFoundError(msg)
+    return kubectl_path
+
+
+def ensure_helm_available() -> str:
+    """Ensure helm CLI is available and return its path."""
+    path = check_cli_availability("helm", "helm not found")
+    if not path:
+        msg = "helm not found"
+        raise FileNotFoundError(msg)
+    return path
+
+
+def ensure_kind_available() -> str:
+    """Ensure kind CLI is available and return its path."""
+    path = check_cli_availability("kind", "kind not found")
+    if not path:
+        msg = "kind not found"
+        raise FileNotFoundError(msg)
+    return path
+
+
+def ensure_core_tools_available() -> None:
+    """Ensure kubectl, helm, argocd, and kind are available.
+
+    Raises FileNotFoundError if any are missing.
+    """
+    ensure_kubectl_available()
+    ensure_helm_available()
+    ensure_argocd_available()
+    ensure_kind_available()
+
+
+def build_kubectl_get_pods_cmd(
+    kubectl_path: str, namespace: str, label_selector: str
+) -> list[str]:
+    """Build kubectl command to get pod names with label selector.
+
+    Args:
+        kubectl_path (str): Path to kubectl executable
+        namespace (str): Kubernetes namespace
+        label_selector (str): Label selector for pods
+
+    Returns:
+        list[str]: kubectl command as list of strings
+    """
+    return [
+        kubectl_path,
+        "get",
+        "pods",
+        "-n",
+        namespace,
+        "-l",
+        label_selector,
+        "-o",
+        "jsonpath={.items[*].metadata.name}",
+    ]
+
+
+def build_kubectl_get_cmd(
+    kubectl_path: str,
+    resource: str,
+    namespace: str,
+    label_selector: str | None = None,
+    output_format: str | None = None,
+    **kwargs: str,
+) -> list[str]:
+    """Build a generic kubectl get command.
+
+    Args:
+        kubectl_path (str): Path to kubectl executable
+        resource (str): Kubernetes resource type (e.g., 'pods', 'deployments')
+        namespace (str): Kubernetes namespace
+        label_selector (str | None): Label selector (optional)
+        output_format (str | None): Output format (e.g., 'json', 'yaml', 'custom-columns=...')
+        **kwargs (str): Additional kubectl arguments
+
+    Returns:
+        list[str]: kubectl command as list of strings
+    """
+    cmd = [kubectl_path, "get", resource, "-n", namespace]
+
+    if label_selector:
+        cmd.extend(["-l", label_selector])
+
+    if output_format:
+        cmd.extend(["-o", output_format])
+
+    # Add any additional arguments
+    for key, value in kwargs.items():
+        cmd.extend([f"--{key}", value])
+
+    return cmd
+
+
+def build_kubectl_logs_cmd(
+    kubectl_path: str, namespace: str, pod_name: str, tail: int | None = None
+) -> list[str]:
+    """Build kubectl command to get logs from a pod.
+
+    Args:
+        kubectl_path (str): Path to kubectl executable
+        namespace (str): Kubernetes namespace
+        pod_name (str): Name of the pod
+        tail (int | None): Number of lines to show from the end (optional)
+
+    Returns:
+        list[str]: kubectl command as list of strings
+    """
+    cmd = [kubectl_path, "logs", "-n", namespace, pod_name]
+    if tail is not None:
+        cmd.extend(["--tail", str(tail)])
+    return cmd
+
+
+def run_subprocess(
+    cmd: list[str],
+    *,
+    capture_output: bool = True,
+    text: bool = True,
+    check: bool = True,
+    **kwargs: Any,
+) -> subprocess.CompletedProcess[str]:
+    """Run a subprocess command with standardized error handling.
+
+    Args:
+        cmd (list[str]): Command to run as a list of strings
+        capture_output (bool): Whether to capture stdout/stderr
+        text (bool): Whether to decode output as text
+        check (bool): Whether to raise CalledProcessError on non-zero exit
+        **kwargs (Any): Additional arguments to pass to subprocess.run
+
+    Returns:
+        subprocess.CompletedProcess[str]: CompletedProcess instance
+
+    Raises:
+        subprocess.CalledProcessError: If check=True and command fails
+    """
+    # Extract CLI name from command for validation
+    if cmd:
+        cli_name = cmd[0]
+        # Check if it's a common CLI tool that should be validated
+        if cli_name in ("kubectl", "argocd", "k3s", "kind", "docker"):
+            check_cli_availability(cli_name)
+
+    try:
+        return subprocess.run(
+            cmd,
+            capture_output=capture_output,
+            text=text,
+            check=check,
+            **kwargs,
+        )
+    except subprocess.CalledProcessError as e:
+        logger.debug("Command failed: %s", " ".join(cmd))
+        logger.debug("Return code: %s", e.returncode)
+        if e.stdout:
+            logger.debug("Stdout: %s", e.stdout)
+        if e.stderr:
+            logger.debug("Stderr: %s", e.stderr)
+        raise
+
+
+def log_subprocess_error(error: subprocess.CalledProcessError) -> None:
+    """Log a subprocess error in a standardized format.
+
+    Args:
+        error (subprocess.CalledProcessError): The subprocess error to log
+    """
+    logger.info("❌ Error: %s", error)