codecraftai-interop-kubernetes 1.2.0__py3-none-any.whl

ccai/interop/kubernetes/__init__.py

@@ -0,0 +1,41 @@
+"""
+    .. module:: kubernetes
+    :platform: Darwin, Linux, Unix, Windows
+    :synopsis: The ``codecraftai-interop-kubernetes`` package — the Kubernetes
+        interop client for the ccai suite.
+
+    Transport note
+    --------------
+    This package wraps the official ``kubernetes`` Python SDK. That SDK is
+    the correct, supported transport for the Kubernetes API server, so this
+    package is deliberately *not* a ``RestClientBase`` codegen package and
+    introduces no parallel REST client. All public APIs normalise the SDK's
+    behaviour to the ccai ``Aspects`` pattern — callers control
+    timeouts, polling and logging; no ``@retry``-style decorators are used.
+
+    .. moduleauthor:: Myron Walker <myron.walker@gmail.com>
+"""
+
+__author__ = "Myron Walker"
+__copyright__ = "Copyright 2025, Code Craft AI LLC"
+__credits__ = []
+
+
+from ccai.interop.kubernetes.aspectskubernetes import (
+    AspectsKubernetes,
+    DEFAULT_KUBERNETES_ASPECTS,
+)
+from ccai.interop.kubernetes.kubernetesclient import (
+    KubernetesClient,
+    DEFAULT_NAMESPACE,
+)
+from ccai.interop.kubernetes.kuberneteshealth import KubernetesHealth
+
+
+__all__ = [
+    "AspectsKubernetes",
+    "DEFAULT_KUBERNETES_ASPECTS",
+    "DEFAULT_NAMESPACE",
+    "KubernetesClient",
+    "KubernetesHealth",
+]

ccai/interop/kubernetes/aspectskubernetes.py

@@ -0,0 +1,89 @@
+"""
+    .. module:: aspectskubernetes
+    :platform: Darwin, Linux, Unix, Windows
+    :synopsis: Provides :class:`AspectsKubernetes` and the
+        ``DEFAULT_KUBERNETES_ASPECTS`` instance applied to every public
+        method on :class:`KubernetesClient` and the workload primitives.
+
+    .. moduleauthor:: Myron Walker <myron.walker@gmail.com>
+"""
+
+__author__ = "Myron Walker"
+__copyright__ = "Copyright 2025, Code Craft AI LLC"
+__credits__ = []
+
+
+import logging
+
+from typing import Optional
+
+from ccai.aspects.aspects import Aspects
+
+
+class AspectsKubernetes(Aspects):
+    """
+        Kubernetes-specialised :class:`Aspects` carrier.
+
+        The class exists so that callers can write
+        ``aspects: AspectsKubernetes`` for clarity at call sites and so
+        that Kubernetes-specific behaviour parameters (the request timeout
+        forwarded to the SDK, the waiter poll interval, and the structured
+        logging level) carry sensible defaults without churning the public
+        type signature on every primitive method.
+
+        :ivar timeout_seconds: Per-request timeout forwarded to the SDK.
+        :ivar poll_interval: Seconds between iterations of a waiter loop.
+        :ivar logging_level: Standard ``logging`` level for structured logs.
+    """
+
+    def __init__(
+        self,
+        *,
+        completion_interval: float = 2.0,
+        completion_timeout: float = 600.0,
+        connection_timeout: float = 30.0,
+        max_attempts: int = 1,
+        logger_name: Optional[str] = None,
+        timeout_seconds: float = 30.0,
+        poll_interval: float = 2.0,
+        logging_level: int = logging.INFO,
+    ) -> None:
+        """
+            Initialise a Kubernetes-flavoured aspects bundle.
+
+            :param completion_interval: Seconds between completion-poll
+                iterations for callers that drive a synchronous wait loop.
+            :param completion_timeout: Maximum seconds to wait for
+                completion before raising :class:`TimeoutError`.
+            :param connection_timeout: Maximum seconds to wait for a single
+                network attempt before reclassifying.
+            :param max_attempts: Maximum number of attempts a caller is
+                allowed to perform when reconciling against a cluster.
+            :param logger_name: Optional logger name a caller can route
+                logs into.
+            :param timeout_seconds: Per-request timeout forwarded to the
+                underlying ``kubernetes`` SDK call.
+            :param poll_interval: Seconds between iterations of a waiter
+                sub-loop.
+            :param logging_level: Standard ``logging`` level used for the
+                structured logging emitted by primitive methods.
+
+            :returns: ``None``
+        """
+        super().__init__(
+            completion_interval=completion_interval,
+            completion_timeout=completion_timeout,
+            connection_timeout=connection_timeout,
+            max_attempts=max_attempts,
+            logger_name=logger_name,
+        )
+        self.timeout_seconds = timeout_seconds
+        self.poll_interval = poll_interval
+        self.logging_level = logging_level
+        return
+
+
+DEFAULT_KUBERNETES_ASPECTS = AspectsKubernetes()
+
+
+__all__ = ["AspectsKubernetes", "DEFAULT_KUBERNETES_ASPECTS"]

ccai/interop/kubernetes/exceptionmapping.py

@@ -0,0 +1,106 @@
+"""
+    .. module:: exceptionmapping
+    :platform: Darwin, Linux, Unix, Windows
+    :synopsis: Provides the :func:`reclassify_api_exception` helper which
+        translates a ``kubernetes`` SDK ``ApiException`` into the ccai
+        typed exception hierarchy.
+
+    .. moduleauthor:: Myron Walker <myron.walker@gmail.com>
+"""
+
+__author__ = "Myron Walker"
+__copyright__ = "Copyright 2025, Code Craft AI LLC"
+__credits__ = []
+
+
+import os
+
+from ccai.interop.kubernetes.exceptions.kuberneteserrors import (
+    KubernetesApiError,
+    KubernetesConflictError,
+    KubernetesForbiddenError,
+    KubernetesResourceNotFoundError,
+    KubernetesUnauthorizedError,
+)
+
+
+STATUS_TO_EXCEPTION = {
+    401: KubernetesUnauthorizedError,
+    403: KubernetesForbiddenError,
+    404: KubernetesResourceNotFoundError,
+    409: KubernetesConflictError,
+}
+
+
+def is_api_exception(error: BaseException) -> bool:
+    """
+        Decide whether ``error`` is a ``kubernetes`` SDK ``ApiException``
+        (or a test double that mimics it) and is therefore safe to
+        reclassify into the ccai typed exception hierarchy.
+
+        Anything else — ``SemanticError``, ``TypeError``, ``ValueError`` and
+        other programming-defect errors — must NOT be reclassified; it has
+        to bubble untouched so callers and the audit can see the real fault.
+
+        The check is structural: the SDK ``ApiException`` is identified by a
+        class name ending in ``ApiException`` together with the ``status``
+        attribute it always carries. This avoids a hard import of the SDK
+        at module-import time.
+
+        :param error: The caught exception instance to classify.
+
+        :returns: ``True`` when ``error`` is an SDK API exception.
+    """
+    type_name = type(error).__name__
+    is_named_api_exception = type_name.endswith("ApiException")
+    has_status_attribute = hasattr(error, "status")
+
+    rtnval = is_named_api_exception and has_status_attribute
+    return rtnval
+
+
+def reclassify_api_exception(api_exception: Exception) -> KubernetesApiError:
+    """
+        Translate a ``kubernetes`` SDK ``ApiException`` into the matching
+        ccai typed exception so callers never have to inspect HTTP
+        status codes.
+
+        :param api_exception: The SDK ``ApiException`` instance to translate.
+
+        :returns: A :class:`KubernetesApiError` (or one of its subclasses)
+            that should be raised ``from api_exception`` by the caller.
+    """
+    status_code = getattr(api_exception, "status", None)
+
+    if status_code is None:
+        status_code = 0
+
+    detail = getattr(api_exception, "reason", None)
+
+    if detail is None:
+        detail = str(api_exception)
+
+    body = getattr(api_exception, "body", None)
+
+    err_msg_lines = ["Kubernetes API request failed."]
+    err_msg_lines.append("STATUS: {}".format(status_code))
+    err_msg_lines.append("REASON: {}".format(detail))
+
+    if body is not None:
+        err_msg_lines.append("BODY:")
+        err_msg_lines.append("    {}".format(body))
+
+    err_msg = os.linesep.join(err_msg_lines)
+
+    exception_type = STATUS_TO_EXCEPTION.get(status_code, KubernetesApiError)
+
+    reclassified = exception_type(
+        err_msg,
+        status_code=status_code,
+        detail=str(detail),
+    )
+
+    return reclassified
+
+
+__all__ = ["is_api_exception", "reclassify_api_exception", "STATUS_TO_EXCEPTION"]

ccai/interop/kubernetes/exceptions/__init__.py

@@ -0,0 +1,35 @@
+"""
+    .. module:: exceptions
+    :platform: Darwin, Linux, Unix, Windows
+    :synopsis: Exception hierarchy for the ``codecraftai-interop-kubernetes``
+        package. Re-exports the named exception types so callers can import
+        them from a single location.
+
+    .. moduleauthor:: Myron Walker <myron.walker@gmail.com>
+"""
+
+__author__ = "Myron Walker"
+__copyright__ = "Copyright 2025, Code Craft AI LLC"
+__credits__ = []
+
+
+from ccai.interop.kubernetes.exceptions.kuberneteserrors import (
+    KubernetesApiError,
+    KubernetesConflictError,
+    KubernetesForbiddenError,
+    KubernetesJobFailedError,
+    KubernetesResourceNotFoundError,
+    KubernetesUnauthorizedError,
+    KubernetesWaitTimeoutError,
+)
+
+
+__all__ = [
+    "KubernetesApiError",
+    "KubernetesConflictError",
+    "KubernetesForbiddenError",
+    "KubernetesJobFailedError",
+    "KubernetesResourceNotFoundError",
+    "KubernetesUnauthorizedError",
+    "KubernetesWaitTimeoutError",
+]

ccai/interop/kubernetes/exceptions/kuberneteserrors.py

@@ -0,0 +1,125 @@
+"""
+    .. module:: kuberneteserrors
+    :platform: Darwin, Linux, Unix, Windows
+    :synopsis: Defines the typed exception hierarchy raised by
+        :class:`KubernetesClient` and the workload primitives. The hierarchy
+        shields callers from the underlying SDK's ``ApiException`` status
+        codes.
+
+    .. moduleauthor:: Myron Walker <myron.walker@gmail.com>
+"""
+
+__author__ = "Myron Walker"
+__copyright__ = "Copyright 2025, Code Craft AI LLC"
+__credits__ = []
+
+
+from typing import Optional
+
+
+class KubernetesApiError(Exception):
+    """
+        Base error for every failure reclassified from the underlying
+        ``kubernetes`` SDK ``ApiException``.
+
+        :ivar status_code: The HTTP status code reported by the API server.
+        :ivar detail: The human readable detail message from the API server.
+    """
+
+    def __init__(self, message: str, *, status_code: int, detail: str) -> None:
+        """
+            Initialise a :class:`KubernetesApiError`.
+
+            :param message: The summary message describing the failure.
+            :param status_code: The HTTP status code reported by the API
+                server.
+            :param detail: The detail message reported by the API server.
+
+            :returns: ``None``
+        """
+        super().__init__(message)
+        self.status_code = status_code
+        self.detail = detail
+        return
+
+
+class KubernetesUnauthorizedError(KubernetesApiError):
+    """
+        Raised when the API server reports a 401 (authentication failure).
+    """
+
+
+class KubernetesForbiddenError(KubernetesApiError):
+    """
+        Raised when the API server reports a 403 (authorisation failure).
+    """
+
+
+class KubernetesResourceNotFoundError(KubernetesApiError):
+    """
+        Raised when the API server reports a 404 (resource absent).
+    """
+
+
+class KubernetesConflictError(KubernetesApiError):
+    """
+        Raised when the API server reports a 409 (resource conflict). Also
+        raised by the workload primitives when an ``apply`` would adopt a
+        foreign, non-codecraftai-managed resource.
+    """
+
+
+class KubernetesJobFailedError(Exception):
+    """
+        Raised by :meth:`JobPrimitive.wait_for_completion` when the observed
+        Job transitions to a ``Failed`` state.
+
+        :ivar info: The :class:`JobInfo` DTO observed at the time of failure.
+    """
+
+    def __init__(self, message: str, *, info: object) -> None:
+        """
+            Initialise a :class:`KubernetesJobFailedError`.
+
+            :param message: The summary message describing the failure.
+            :param info: The :class:`JobInfo` DTO observed at failure time.
+
+            :returns: ``None``
+        """
+        super().__init__(message)
+        self.info = info
+        return
+
+
+class KubernetesWaitTimeoutError(TimeoutError):
+    """
+        Raised by a workload primitive waiter when the resource does not
+        reach the awaited state within ``aspects.completion_timeout``.
+
+        :ivar observed: The last observed DTO or status object, retained for
+            debuggability.
+    """
+
+    def __init__(self, message: str, *, observed: Optional[object] = None) -> None:
+        """
+            Initialise a :class:`KubernetesWaitTimeoutError`.
+
+            :param message: The summary message describing the timeout.
+            :param observed: The last observed status object.
+
+            :returns: ``None``
+        """
+        super().__init__(message)
+        self.observed = observed
+        return
+
+
+__all__ = [
+    "KubernetesApiError",
+    "KubernetesConflictError",
+    "KubernetesForbiddenError",
+    "KubernetesJobFailedError",
+    "KubernetesResourceNotFoundError",
+    "KubernetesUnauthorizedError",
+    "KubernetesWaitTimeoutError",
+]

ccai/interop/kubernetes/kubeconfigloader.py

@@ -0,0 +1,163 @@
+"""
+    .. module:: kubeconfigloader
+    :platform: Darwin, Linux, Unix, Windows
+    :synopsis: Provides :class:`KubeConfigLoader`, the helper that resolves a
+        kubeconfig from a path, an in-memory dict, or an in-cluster
+        service-account context into a :class:`KubernetesRestClient`.
+
+    .. moduleauthor:: Myron Walker <myron.walker@gmail.com>
+"""
+
+__author__ = "Myron Walker"
+__copyright__ = "Copyright 2025, Code Craft AI LLC"
+__credits__ = []
+
+
+import os
+
+from typing import Dict, List, Optional
+
+from ccai.errors.exceptions import SemanticError
+
+from ccai.restclient.kubernetes.kubeconfigresolver import (
+    KubeConfigResolver
+)
+from ccai.restclient.kubernetes.kubernetesrestclient import (
+    KubernetesRestClient
+)
+
+
+class KubeConfigLoader:
+    """
+        Resolves a kubeconfig source into a
+        :class:`ccai.restclient.kubernetes.kubernetesrestclient.KubernetesRestClient`.
+
+        Exactly one of ``kubeconfig_path``, ``kubeconfig_dict`` or
+        ``in_cluster`` must be supplied. The loader keeps the resolved
+        in-memory dict (when one was supplied) so callers may later switch
+        contexts without re-reading the source.
+
+        :ivar kubeconfig_path: The path the kubeconfig was loaded from, or
+            ``None``.
+        :ivar kubeconfig_dict: The in-memory kubeconfig dict, or ``None``.
+        :ivar in_cluster: ``True`` when the in-cluster context is in use.
+        :ivar context: The active context name, or ``None`` for in-cluster.
+    """
+
+    def __init__(
+        self,
+        *,
+        kubeconfig_path: Optional[str] = None,
+        kubeconfig_dict: Optional[Dict[str, object]] = None,
+        in_cluster: bool = False,
+        context: Optional[str] = None,
+    ) -> None:
+        """
+            Initialise a :class:`KubeConfigLoader`.
+
+            :param kubeconfig_path: Filesystem path of a kubeconfig file.
+            :param kubeconfig_dict: An in-memory kubeconfig dict.
+            :param in_cluster: When ``True`` use the in-cluster
+                service-account context.
+            :param context: The named context to activate. Ignored when
+                ``in_cluster`` is ``True``.
+
+            :returns: ``None``
+            :raises: SemanticError
+        """
+        sources_supplied = []
+
+        if kubeconfig_path is not None:
+            sources_supplied.append("kubeconfig_path")
+
+        if kubeconfig_dict is not None:
+            sources_supplied.append("kubeconfig_dict")
+
+        if in_cluster is True:
+            sources_supplied.append("in_cluster")
+
+        if len(sources_supplied) == 0:
+            err_msg_lines = [
+                "A kubeconfig source must be supplied.",
+                ("Provide exactly one of 'kubeconfig_path', "
+                 "'kubeconfig_dict' or 'in_cluster=True'."),
+            ]
+            err_msg = os.linesep.join(err_msg_lines)
+            raise SemanticError(err_msg) from None
+
+        if len(sources_supplied) > 1:
+            err_msg_lines = [
+                "Only one kubeconfig source may be supplied.",
+                "SUPPLIED: ({})".format(len(sources_supplied)),
+            ]
+            for source_name in sources_supplied:
+                err_msg_lines.append("    {}".format(source_name))
+
+            err_msg = os.linesep.join(err_msg_lines)
+            raise SemanticError(err_msg) from None
+
+        self.kubeconfig_path = kubeconfig_path
+        self.kubeconfig_dict = kubeconfig_dict
+        self.in_cluster = in_cluster
+        self.context = context
+        return
+
+    def available_contexts(self) -> List[str]:
+        """
+            Enumerate the context names available in the resolved kubeconfig.
+
+            :returns: The list of context names. An in-cluster loader yields
+                an empty list because in-cluster operation has no contexts.
+        """
+        context_names: List[str] = []
+
+        if self.in_cluster is True:
+            return context_names
+
+        config_dict = self.kubeconfig_dict
+
+        if config_dict is None and self.kubeconfig_path is not None:
+            import yaml
+
+            with open(self.kubeconfig_path, "r") as config_handle:
+                config_dict = yaml.safe_load(config_handle)
+
+        if config_dict is None:
+            return context_names
+
+        contexts = config_dict.get("contexts", None)
+
+        if contexts is None:
+            return context_names
+
+        for context_entry in contexts:
+            entry_name = context_entry.get("name", None)
+            if entry_name is not None:
+                context_names.append(entry_name)
+
+        return context_names
+
+    def build_api_client(self) -> object:
+        """
+            Resolve the kubeconfig source and build a configured
+            :class:`KubernetesRestClient`.
+
+            The name is retained from when this returned an SDK
+            ``ApiClient``; the returned object now carries the api groups
+            directly (``core_v1``, ``apps_v1``, ``batch_v1``,
+            ``networking_v1``, ``version``).
+
+            :returns: A configured :class:`KubernetesRestClient`.
+        """
+        resolver = KubeConfigResolver(
+            kubeconfig_path=self.kubeconfig_path,
+            kubeconfig_dict=self.kubeconfig_dict,
+            in_cluster=self.in_cluster,
+            context=self.context,
+        )
+        resolution = resolver.resolve()
+        api_client = KubernetesRestClient(resolution=resolution)
+        return api_client
+
+
+__all__ = ["KubeConfigLoader"]