The binding is made once (at server startup, or on the first tool call) and
shared by every tool, so all tools answer from this cluster.

Parameters
----------
None
    This function does not take any parameters.

Returns
-------
ClusterInfo
    An object with the following fields:

    source : str
        "kubeconfig" (bound through a kubeconfig context), "in-cluster" (the
        service account of the pod the server runs in), or "capture" (a
        recorded snapshot of a cluster being replayed, not a live cluster).
    context : Optional[str]
        The kubeconfig context name. None for in-cluster config, and for a
        capture that did not record one.
    server : Optional[str]
        URL of the cluster's API server.
    kubeconfig : Optional[str]
        Path of the kubeconfig file (or ``:``-separated list of files) the
        binding was read from. None unless source is "kubeconfig".
    server_version : Optional[str]
        Kubernetes version reported by the API server, e.g. "v1.31.2". None if
        the server could not be reached, or the capture did not record it.
    captured_at : Optional[datetime.datetime]
        For a capture, when it was taken; every age and timestamp the tools
        return is relative to that moment. None for a live cluster.

Raises
------
K8sConfigError
    If no cluster configuration can be loaded.

WARNING: ConfigMaps can contain secret-shaped values (e.g. credentials stored
as plain config). When this tool is served through the k8stools MCP server, the
output passes through a redaction step by default (see the `redaction` module
and the server's `--no-redact` flag). Callers using this function directly get
the raw values and are responsible for their own redaction.

Parameters
----------
name : str
    Name of the ConfigMap.
namespace : str, optional
    Namespace of the ConfigMap (default is "default").

Returns
-------
dict[str, Any]
    A dictionary describing the ConfigMap with the following keys:

    name : str
        Name of the ConfigMap.
    namespace : str
        Namespace of the ConfigMap.
    data : dict[str, str]
        The string key/value data map (empty dict if none).
    binary_data_keys : list[str]
        Names of any binary keys. The binary values themselves are not
        returned.

Raises
------
K8sConfigError
    If unable to initialize the K8S API.
K8sApiError
    If the ConfigMap is not found or the API call fails.

Note that this returns only summary metadata (not the ConfigMap contents); use
`get_configmap` to read the actual data map.

Parameters
----------
namespace : Optional[str], default=None
    The specific namespace to list ConfigMaps from. If None, lists ConfigMaps from
    all namespaces.

Returns
-------
list of ConfigMapSummary
    A list of ConfigMapSummary objects, each with the following fields:

    name : str
        Name of the ConfigMap.
    namespace : str
        Namespace in which the ConfigMap lives.
    key_count : int
        Number of keys across `data` and `binary_data`.
    data_size : int
        Approximate total size in bytes of all values.
    age : datetime.timedelta
        Age of the ConfigMap (current time minus creation timestamp).

Raises
------
K8sConfigError
    If unable to initialize the K8S API.
K8sApiError
    If the API call to list ConfigMaps fails.

Parameters
----------
namespace : Optional[str], default=None
    The specific namespace to list CronJobs from. If None, lists from all
    namespaces.

Returns
-------
list of CronJobSummary
    A list of CronJobSummary objects, each with the following fields:

    name : str
        Name of the CronJob.
    namespace : str
        Namespace of the CronJob.
    schedule : str
        Cron schedule expression.
    suspend : bool
        Whether the CronJob is suspended.
    active : int
        Number of currently active (running) jobs.
    last_schedule_time : Optional[datetime.timedelta]
        Time since the CronJob was last scheduled (None if never).
    last_successful_time : Optional[datetime.timedelta]
        Time since the CronJob last completed successfully (None if never).
    age : datetime.timedelta
        Age of the CronJob (current time minus creation timestamp).
    containers : list[ContainerTemplateSummary]
        The job pod template's containers, each with name, image, and literal
        environment values.

Raises
------
K8sConfigError
    If unable to initialize the K8S API.
K8sApiError
    If the API call to list CronJobs fails.

A DaemonSet runs one pod on each node it targets; its pods are named
"<daemonset>-<5 characters>" and have `owner` "DaemonSet/<daemonset>" in
`get_pod_summaries`. A shortfall between the counts below ("desired 5,
ready 4") is often the first sign of a problem with a particular node.

Parameters
----------
namespace : Optional[str], default=None
    The specific namespace to list DaemonSets from. If None, lists from all
    namespaces.

Returns
-------
list of DaemonSetSummary
    A list of DaemonSetSummary objects, each with the following fields:

    name : str
        Name of the DaemonSet.
    namespace : str
        Namespace in which the DaemonSet runs.
    desired_number_scheduled : int
        Number of nodes that should be running the DaemonSet's pod - the
        actual number of nodes it targets.
    current_number_scheduled : int
        Number of nodes running at least one of its pods that should.
    number_ready : int
        Number of nodes whose pod is ready.
    updated_number_scheduled : int
        Number of nodes running a pod from the current pod template. Less
        than desired means a rollout is in progress or stuck.
    number_available : int
        Number of nodes whose pod has been ready for at least minReadySeconds.
    number_misscheduled : int
        Number of nodes running its pod that should not be.
    node_selector : dict[str, str]
        The pod template's nodeSelector (kubectl's NODE SELECTOR column).
        Many DaemonSets choose their nodes with node affinity and
        tolerations instead, which this does not show, so an empty selector
        does not mean "every node"; desired_number_scheduled is the count.
    update_strategy : str
        Update strategy type ("RollingUpdate" or "OnDelete").
    images : list[str]
        Container images of the current pod template, in container order. A
        pod running a different image is from an earlier revision.
    age : datetime.timedelta
        Age of the DaemonSet (current time minus creation timestamp).

Raises
------
K8sConfigError
    If unable to initialize the K8S API.
K8sApiError
    If the API call to list DaemonSets fails.

Retrieves a list of DeploymentSummary objects for deployments in a given namespace or all namespaces.
Similar to `kubectl get deployements`.

Parameters
----------
namespace : Optional[str], default=None
    The specific namespace to list deployments from. If None, lists deployments from all namespaces.

Returns
-------
list of DeploymentSummary
    A list of DeploymentSummary objects, each providing a summary of a deployment's status with the following fields:

    name : str
        Name of the deployment.
    namespace : str
        Namespace in which the deployment is running.
    total_replicas : int
        Total number of replicas desired for this deployment.
    ready_replicas : int
        Number of replicas that are currently ready.
    up_to_date_replicas : int
        Number of replicas that are up to date.
    available_replicas : int
        Number of replicas that are available.
    age : datetime.timedelta
        Age of the deployment (current time minus creation timestamp).

Raises
------
K8sConfigError
    If unable to initialize the K8S API.
K8sApiError
    If the API call to list deployments fails.

Unlike `get_pod_events` (which is scoped to a single named pod), this supports
the sweep queries common in capacity/storage runbooks — e.g. all "Evicted"
events, or all "FailedScheduling" events — where the affected pods often have no
stable name to look up. Note Kubernetes expires an event record about an hour
(by default) after its last occurrence, so events that stopped repeating
earlier than that are gone.

Parameters
----------
namespace : Optional[str], default=None
    Namespace to list events from. If None, lists across all namespaces.
reason : Optional[str], default=None
    If set, only return events with this reason (e.g. "Evicted",
    "FailedScheduling", "BackOff").
involved_kind : Optional[str], default=None
    If set, only return events whose involved object is of this kind (e.g.
    "Pod", "Node", "PersistentVolumeClaim").
involved_name : Optional[str], default=None
    If set, only return events whose involved object has this name.
event_type : Optional[str], default=None
    If set, only return events of this type ("Normal" or "Warning").

Returns
-------
list of EventSummary
    Matching events. Each EventSummary has the following fields:

    last_seen : Optional[datetime.timedelta]
        Time since the event was last seen (if available).
    first_seen : Optional[datetime.timedelta]
        Time since the first occurrence combined into this record (if
        available).
    count : Optional[int]
        How many occurrences Kubernetes combined into this record: repeats
        of the same event on the same object are counted in one record
        rather than listed separately. The count covers first_seen to
        last_seen, not the object's lifetime - a record that stops repeating
        expires (after 1h by default), and a later repeat starts a new one.
        For a crash-looping container, count the "Created" or "Started"
        events to get restarts. "BackOff" is emitted repeatedly while the
        kubelet waits to restart, so its count is several times the number
        of restarts. count divided by (first_seen - last_seen) is the
        average rate over that window, not the current back-off.

        A record can lag behind what it counts. By default the kubelet
        writes at most one event update per object and event type
        ("Normal" or "Warning") every 5 minutes, once a burst of 25 is
        used up; occurrences in between are counted but only written with
        the next update, which then jumps by several at once. So count and
        last_seen describe the most recent *written* occurrence and can
        trail reality by several occurrences and tens of minutes. They lag
        together, so the rate above still holds, but last_seen is not the
        time of the last restart: for that, use the container status
        (last_state.finished_at, state.started_at from
        get_pod_container_statuses) or PodSummary.last_restart, which come
        from the kubelet's status rather than from events. "Pulled",
        "Created" and "Started" share one write budget, so their counts for
        the same restarts can differ by a few; don't compare counts across
        reasons.
    type : str
        Type of the event ("Normal" or "Warning").
    reason : str
        Reason for the event.
    object : str
        The involved object as "Kind/name" (or just the name when the kind is
        unavailable).
    message : str
        Message describing the event.

Raises
------
K8sConfigError
    If unable to initialize the K8S API.
K8sApiError
    If the API call to list events fails.

Parameters
----------
namespace : Optional[str], default=None
    The specific namespace to list Jobs from. If None, lists from all namespaces.

Returns
-------
list of JobSummary
    A list of JobSummary objects, each with the following fields:

    name : str
        Name of the Job.
    namespace : str
        Namespace of the Job.
    owner : Optional[str]
        Name of the owning CronJob, if this Job was created by one.
    active : int
        Number of actively running pods.
    succeeded : int
        Number of pods that completed successfully.
    failed : int
        Number of pods that terminated in failure.
    start_time : Optional[datetime.timedelta]
        Time since the Job started (None if not started).
    completion_time : Optional[datetime.timedelta]
        Time since the Job completed (None if not complete).
    conditions : list[str]
        Status condition types currently True (e.g. ["Complete"], ["Failed"]).
    age : datetime.timedelta
        Age of the Job (current time minus creation timestamp).
    containers : list[ContainerTemplateSummary]
        The Job pod template's containers, each with name, image, and literal
        environment values.

Raises
------
K8sConfigError
    If unable to initialize the K8S API.
K8sApiError
    If the API call to list Jobs fails.

Finds the newest Job owned by the CronJob, then returns the logs of that Job's
most-recently-created pod. Removes the need to manually locate the right
short-lived pod for a CronJob's last tick.

Parameters
----------
cronjob_name : str
    Name of the CronJob.
namespace : str, optional
    Namespace of the CronJob (default is "default").
container_name : str, optional
    Container within the pod. If None, defaults to the first container.
tail : int, optional
    Number of lines from the end of the log (default: last 1000).
since_seconds : int, optional
    If set, only return logs newer than this many seconds.
previous : bool, default False
    If True, return logs from the previous terminated container instance.
    See `get_logs_for_pod_and_container` for the cases - CrashLoopBackOff, a
    restart racing the call, a reclaimed log file - where that legitimately
    returns the same text as `previous=False`, or a 200 whose body is an
    error message.

Returns
-------
str, optional
    Log content, or None if the CronJob has no jobs/pods yet.

Raises
------
K8sConfigError
    If unable to initialize the K8S API.
K8sApiError
    If the API call fails.

Job pods are short-lived, so this convenience finds the newest pod belonging to
the Job (via its `job-name` label) and returns its logs, saving the caller from
listing pods and sorting by creation time.

Parameters
----------
job_name : str
    Name of the Job.
namespace : str, optional
    Namespace of the Job (default is "default").
container_name : str, optional
    Container within the pod. If None, defaults to the first container.
tail : int, optional
    Number of lines from the end of the log (default: last 1000).
since_seconds : int, optional
    If set, only return logs newer than this many seconds.
previous : bool, default False
    If True, return logs from the previous terminated container instance.
    See `get_logs_for_pod_and_container` for the cases - CrashLoopBackOff, a
    restart racing the call, a reclaimed log file - where that legitimately
    returns the same text as `previous=False`, or a 200 whose body is an
    error message.

Returns
-------
str, optional
    Log content, or None if the Job has no pods.

Raises
------
K8sConfigError
    If unable to initialize the K8S API.
K8sApiError
    If the API call fails.

Retrieves logs from a Kubernetes pod and container.

Args:
    pod_name (str): The name of the pod.
    namespace (str): The namespace of the pod.
    container_name (str, optional): The name of the container within the pod.
                                    If None, defaults to the first container.
    tail (int, optional): Number of lines to return from the end of the log.
                          If None, defaults to the last 1000 lines. Pass a
                          larger value to retrieve more history, or a small
                          value for a bounded recent slice.
    since_seconds (int, optional): If set, only return logs newer than this
                          many seconds. Combines with `tail` (both limits
                          apply).
    previous (bool, default False): If True, return logs from the *previous*
                          terminated instance of the container instead of the
                          current one. Indispensable for crashloop analysis,
                          where the current instance's logs are empty or
                          post-restart. Fails if there is no previous instance.

                          Three Kubernetes behaviors make `previous=True`
                          look as though it were ignored or broken; none is a
                          fault in this tool, and all are worth knowing before
                          drawing a conclusion from the output:

                          * While a container sits in CrashLoopBackOff there
                            is no running instance, so the kubelet serves the
                            most recently *terminated* one for `previous=False`
                            as well - both calls then return the same text.
                            Check the container's state with
                            `get_pod_container_statuses` before concluding the
                            flag had no effect.
                          * A restart between two calls shifts the window: the
                            instance that was current becomes the previous one,
                            so a container crash-looping every few seconds can
                            legitimately return identical bytes for both.
                            Compare the log timestamps, not just the flag.
                          * Once the previous instance's log file has been
                            reclaimed, the API answers 200 with the text
                            `unable to retrieve container logs for <id>` -
                            a successful call whose body is an error message,
                            not a raised error.

                          Only the single most recent terminated instance is
                          retained by the kubelet; there is no way to reach
                          further back than one.

Returns:
    str: The log content as text, with real newlines. An empty string if the
         container has produced no log output (never None).

Raises
------
K8sConfigError
    If unable to initialize the K8S API.
K8sApiError
    If the API call to fetch logs fails or an unexpected error occurs.

Parameters
----------
None
    This function does not take any parameters.

Returns
-------
list of NamespaceSummary
    List of namespace summary objects. Each NamespaceSummary has the following fields:

    name : str
        Name of the namespace.
    status : str
        Status phase of the namespace.
    age : datetime.timedelta
        Age of the namespace (current time minus creation timestamp).
Raises
------
K8sConfigError
    If unable to initialize the K8S API.
K8sApiError
    If the API call to list namespaces fails.

Parameters
----------
None
    This function does not take any parameters.

Returns
-------
list of NodeSummary
    List of node summary objects. Each NodeSummary has the following fields:

    name : str
        Name of the node.
    status : str
        Status of the node (Ready, NotReady, etc.).
    roles : list[str]
        List of roles for the node (e.g., ['control-plane', 'master']).
    age : datetime.timedelta
        Age of the node (current time minus creation timestamp).
    version : str
        Kubernetes version running on the node.
    internal_ip : Optional[str]
        Internal IP address of the node.
    external_ip : Optional[str]
        External IP address of the node (if available).
    os_image : Optional[str]
        Operating system image running on the node.
    kernel_version : Optional[str]
        Kernel version of the node.
    container_runtime : Optional[str]
        Container runtime version on the node.
    capacity : dict[str, str]
        Total capacity of the node keyed by resource name (e.g. "cpu",
        "memory", "ephemeral-storage", "pods"). Empty if unavailable.
    allocatable : dict[str, str]
        Resources allocatable to pods (capacity minus system-reserved),
        keyed by resource name. Empty if unavailable.
    conditions : dict[str, str]
        Node conditions keyed by type with their status, e.g.
        {"Ready": "True", "MemoryPressure": "False", "DiskPressure": "False"}.
    conditions_since : dict[str, datetime.timedelta]
        For each condition in `conditions`, the time since its status last
        changed (the API's lastTransitionTime), e.g. how long the node has
        been Ready, or how long ago a MemoryPressure episode ended. A
        condition with no transition time is left out.

        It changes only when the status does. A node or kubelet restart in
        which the node comes back Ready without having been marked NotReady
        or Unknown in between does not reset it: on a minikube cluster
        stopped and started together with its control plane, Ready stayed
        "True since the node was created" across a reboot. So a long Ready
        age does not mean the node or its pods have been running that long,
        and a short one can come from a brief NotReady flap rather than a
        reboot. To date a node's last start, use its "Starting" or
        "Rebooted" events (`get_events(involved_kind="Node")`, while they
        last - events usually expire after an hour), or the `started_at` of
        containers that start with the node, such as kube-proxy and the
        kube-system control-plane containers (`get_pod_container_statuses`).
    taints : list[str]
        Taints on the node formatted as "key=value:effect" (value omitted
        when empty).
    labels : dict[str, str]
        All labels on the node. Useful for identifying node pool / instance
        type and spotting version skew across pools.

Raises
------
K8sConfigError
    If unable to initialize the K8S API.
K8sApiError
    If the API call to list nodes fails.

Get the status for all containers in a specified Kubernetes pod.

Parameters
----------
pod_name : str
    Name of the pod to retrieve container statuses for.
namespace : str, optional
    Namespace of the pod (default is "default").

Returns
-------
list of ContainerStatus
    List of container status objects for the specified pod. Each ContainerStatus has the following fields:

    pod_name : str
        Name of the pod.
    namespace : str
        Namespace of the pod.
    container_name : str
        Name of the container.
    image : str
        Image name.
    ready : bool
        Whether the container is currently passing its readiness check.
        The value will change as readiness probes keep executing.
    restart_count : int
        Number of times the container has restarted.
    started : Optional[bool]
        Started indicates whether the container has finished its postStart
        lifecycle hook and passed its startup probe.
    stop_signal : Optional[str]
        Stop signal for the container.
    state : Optional[ContainerState]
        Current state of the container.
    last_state : Optional[ContainerState]
        Last state of the container. When Terminated, ``ran_for`` is how long
        that instance ran (``finished_at - started_at``). It is not the
        restart interval, which adds the back-off named in a Waiting
        ``state``'s message, and it is not how much time the container's log
        covers: a process can stop logging long before it is killed.
    volume_mounts : list[VolumeMountStatus]
        Status of volume mounts for the container
    resource_requests : dict[str, str]
        Describes the minimum amount of compute resources required. If Requests
        is omitted for a container, it defaults to Limits if that is explicitly specified,
        otherwise to an implementation-defined value. Requests cannot exceed Limits. 
    resource_limits : dict[str, str]
        Describes the maximum amount of compute resources allowed.
    allocated_resources : dict[str, str]
        Compute resources allocated for this container by the node.

Raises
------
K8sConfigError
    If unable to initialize the K8S API.
K8sApiError
    If the API call to read the pod fails.

Get events for a specific Kubernetes pod. This is equivalent to the kubectl command:
`kubectl get events -n NAMESPACE --field-selector involvedObject.name=POD_NAME,involvedObject.kind=Pod`

Parameters
----------
pod_name : str
    Name of the pod to retrieve events for.
namespace : str, optional
    Namespace of the pod (default is "default").

Returns
-------
list of EventSummary
    List of events associated with the specified pod. Each EventSummary has the following fields:

    last_seen : Optional[datetime.timedelta]
        Time since the most recent occurrence of the event (if available).
    first_seen : Optional[datetime.timedelta]
        Time since the first occurrence combined into this record (if
        available).
    count : Optional[int]
        How many occurrences Kubernetes combined into this record: repeats
        of the same event on the same object are counted in one record
        rather than listed separately. The count covers first_seen to
        last_seen, not the object's lifetime - a record that stops repeating
        expires (after 1h by default), and a later repeat starts a new one.
        For a crash-looping container, count the "Created" or "Started"
        events to get restarts. "BackOff" is emitted repeatedly while the
        kubelet waits to restart, so its count is several times the number
        of restarts. count divided by (first_seen - last_seen) is the
        average rate over that window, not the current back-off.

        A record can lag behind what it counts. By default the kubelet
        writes at most one event update per object and event type
        ("Normal" or "Warning") every 5 minutes, once a burst of 25 is
        used up; occurrences in between are counted but only written with
        the next update, which then jumps by several at once. So count and
        last_seen describe the most recent *written* occurrence and can
        trail reality by several occurrences and tens of minutes. They lag
        together, so the rate above still holds, but last_seen is not the
        time of the last restart: for that, use the container status
        (last_state.finished_at, state.started_at from
        get_pod_container_statuses) or PodSummary.last_restart, which come
        from the kubelet's status rather than from events. "Pulled",
        "Created" and "Started" share one write budget, so their counts for
        the same restarts can differ by a few; don't compare counts across
        reasons.
    type : str
        Type of the event.
    reason : str
        Reason for the event.
    object : str
        The object this event applies to.
    message : str
        Message describing the event.
Raises
------
K8sConfigError
    If unable to initialize the K8S API.
K8sApiError
    If the API call to list events fails.

Retrieves the spec for a given pod in a specific namespace.

Args:
    pod_name (str): The name of the pod.
    namespace (str): The namespace the pod belongs to (defaults to "default").

Returns
-------
dict[str, Any]
    The pod's spec object, containing its desired state. It is converted
    from a V1PodSpec to a dictionary. Key fields include:

    containers : list of kubernetes.client.V1Container
        List of containers belonging to the pod. Each container defines its image,
        ports, environment variables, resource requests/limits, etc.
    init_containers : list of kubernetes.client.V1Container, optional
        List of initialization containers belonging to the pod.
    volumes : list of kubernetes.client.V1Volume, optional
        List of volumes mounted in the pod and the sources available for
        the containers.
    node_selector : dict, optional
        A selector which must be true for the pod to fit on a node.
        Keys and values are strings.
    restart_policy : str
        Restart policy for all containers within the pod.
        Common values are "Always", "OnFailure", "Never".
    service_account_name : str, optional
        Service account name in the namespace that the pod will use to
        access the Kubernetes API.
    dns_policy : str
        DNS policy for the pod. Common values are "ClusterFirst", "Default".
    priority_class_name : str, optional
        If specified, indicates the pod's priority_class via its name.
    node_name : str, optional
        NodeName is a request to schedule this pod onto a specific node.

Raises
------
K8SConfigError
    If unable to initialize the K8S API
K8sApiError
    If the pod is not found, configuration fails, or any other API error occurs.

Retrieves a list of PodSummary objects for pods in a given namespace or all namespaces.

Parameters
----------
namespace : Optional[str], default=None
    The specific namespace to list pods from. If None, lists pods from all namespaces.

Returns
-------
list of PodSummary
    A list of PodSummary objects, each providing a summary of a pod's status with the following fields:

    name : str
        Name of the pod.
    namespace : str
        Namespace in which the pod is running.
    total_containers : int
        Total number of containers in the pod.
    ready_containers : int
        Number of containers currently in ready state.
    restarts : int
        Total number of restarts for all containers in the pod.
    last_restart : Optional[datetime.timedelta]
        Time since a container of this pod last terminated - the most
        recent last_state.finished_at across its containers - or None if
        none has. For a container waiting in CrashLoopBackOff this is its
        last crash, not a restart: it has not been started again yet. Taken
        from the kubelet's status, so it is current, unlike event records.
    age : datetime.timedelta
        Age of the pod (current time minus creation timestamp).
    ip : Optional[str]
        Pod IP address (None if not assigned).
    node : Optional[str]
        Name of the node where the pod is running (None if not scheduled).
    owner : Optional[str]
        The pod's controlling owner, as "Kind/name" - the object that
        created and manages it, e.g. "DaemonSet/otel-collector-agent",
        "StatefulSet/valkey-cart", "Job/backup-29318400". None for a bare
        pod nobody manages. This is the direct owner only: a Deployment's
        pods are owned by one of its replica sets ("ReplicaSet/ad-7d9f8c6b5"),
        whose `owner_deployment` (`get_replicaset_summaries`) names the
        Deployment; likewise a Job's `owner` names its CronJob. Static
        (mirror) pods such as the control plane's report "Node/<node name>".
        Group pods into workloads by this field rather than by stripping
        name suffixes.
Raises
------
K8sConfigError
    If unable to initialize the K8S API.
K8sApiError
    If the API call to list pods fails.

For each PVC, this also resolves which pods currently mount it (by scanning pod
volumes in the same scope), which is useful for spotting orphaned PVCs — claims
with an empty `mounted_by` and no owning pod.

Parameters
----------
namespace : Optional[str], default=None
    The specific namespace to list PVCs from. If None, lists from all namespaces.

Returns
-------
list of PVCSummary
    A list of PVCSummary objects, each with the following fields:

    name : str
        Name of the PVC.
    namespace : str
        Namespace of the PVC.
    status : str
        Phase of the PVC ("Bound", "Pending", or "Lost").
    volume_name : Optional[str]
        Name of the bound PersistentVolume (None if unbound).
    capacity : Optional[str]
        Storage capacity (e.g. "10Gi"); falls back to the requested size when
        the claim is not yet bound.
    access_modes : list[str]
        Access modes (e.g. ["ReadWriteOnce"]).
    storage_class : Optional[str]
        StorageClass backing the claim.
    mounted_by : list[str]
        Names of pods (in the same scope) currently mounting this PVC. Empty
        for orphaned/unmounted claims.
    age : datetime.timedelta
        Age of the PVC (current time minus creation timestamp).

Raises
------
K8sConfigError
    If unable to initialize the K8S API.
K8sApiError
    If the API call to list PVCs fails.

Retrieves a list of ReplicaSetSummary objects, similar to `kubectl get replicasets`
but including each replica set's deployment revision and container images.

A Deployment's replica sets are its revision history: every update to a Deployment
creates a new replica set carrying that revision's pod template, and older replica
sets are retained (scaled to zero). Listing them for one deployment therefore shows
when it last changed and what its image was at each revision - which is how you
answer "did something change recently?" without access to deployment tooling or
version control.

Results are grouped by namespace and owning deployment, and within each
deployment sorted by revision, oldest first. So when filtered to a single
deployment, the last entry is that deployment's current revision.

Replica sets with no revision (see `revision` below) sort *first*, ahead of
revision 1, rather than being dropped. They have no place in any deployment's
history, so they are listed before it rather than appended to it. In practice
they are only visible in an unfiltered listing: a replica set without a
revision has no owning deployment either, so passing `deployment` filters them
out, and the "last entry is the current revision" guarantee above is unaffected.

Parameters
----------
namespace : Optional[str], default=None
    The specific namespace to list replica sets from. If None, lists from all namespaces.
deployment : Optional[str], default=None
    If given, return only replica sets owned by this deployment. This is the common
    case: one deployment's revision history.

Returns
-------
list of ReplicaSetSummary
    A list of ReplicaSetSummary objects with the following fields:

    name : str
        Name of the replica set.
    namespace : str
        Namespace in which the replica set is defined.
    owner_deployment : Optional[str]
        Name of the Deployment that owns this replica set, or None if it is
        standalone (not managed by a Deployment).
    revision : Optional[int]
        The deployment revision this replica set represents, taken from the
        `deployment.kubernetes.io/revision` annotation. None when that
        annotation is absent, which means no Deployment created this replica
        set - only the Deployment controller writes it. A hand-written replica
        set, or one created by another controller, therefore has no revision
        (and no `owner_deployment`), and appears in neither `kubectl rollout
        history` nor a `deployment`-filtered call here. Also None if the
        annotation is present but not an integer.
    desired_replicas : int
        Replicas desired for this replica set. Old revisions are scaled to 0.
    current_replicas : int
        Replicas currently running.
    ready_replicas : int
        Replicas currently ready.
    images : list[str]
        Container images in this revision's pod template, in container order.
        Comparing this across revisions shows what an upgrade changed.
    age : datetime.timedelta
        Age of the replica set (current time minus creation timestamp). For the
        newest revision this is how long ago the deployment last changed.

Raises
------
K8sConfigError
    If unable to initialize the K8S API.
K8sApiError
    If the API call to list replica sets fails.

Parameters
----------
namespace : Optional[str], default=None
    The specific namespace to list services from. If None, lists services from all namespaces.

Returns
-------
list of ServiceSummary
    A list of ServiceSummary objects, each providing a summary of a service's status with the following fields:

    name : str
        Name of the service.
    namespace : str
        Namespace in which the service is running.
    type : str
        Type of the service (ClusterIP, NodePort, LoadBalancer, ExternalName).
    cluster_ip : Optional[str]
        Cluster IP address assigned to the service (None for ExternalName services).
    external_ip : Optional[str]
        External IP address if applicable (for LoadBalancer services).
    ports : list[PortInfo]
        List of ports (and their protocols) exposed by the service.
    age : datetime.timedelta
        Age of the service (current time minus creation timestamp).
    selector : dict[str, str]
        The label selector the service uses to choose backing pods. Empty
        for services without a selector (e.g. ExternalName, or manually
        managed Endpoints).
    labels : dict[str, str]
        Labels on the service object.
    annotations : dict[str, str]
        Annotations on the service object.

Raises
------
K8sConfigError
    If unable to initialize the K8S API.
K8sApiError
    If the API call to list services fails.

Parameters
----------
namespace : Optional[str], default=None
    The specific namespace to list StatefulSets from. If None, lists from all
    namespaces.

Returns
-------
list of StatefulSetSummary
    A list of StatefulSetSummary objects, each with the following fields:

    name : str
        Name of the StatefulSet.
    namespace : str
        Namespace in which the StatefulSet runs.
    total_replicas : int
        Desired number of replicas.
    ready_replicas : int
        Number of replicas currently ready.
    current_replicas : int
        Number of replicas created by the current revision.
    update_strategy : str
        Update strategy type (e.g. "RollingUpdate", "OnDelete").
    service_name : Optional[str]
        Name of the governing (headless) service.
    age : datetime.timedelta
        Age of the StatefulSet (current time minus creation timestamp).

Raises
------
K8sConfigError
    If unable to initialize the K8S API.
K8sApiError
    If the API call to list StatefulSets fails.