| get_cluster_infoA | Report which Kubernetes cluster these tools are bound to. Call this first
when more than one cluster could be involved, and before drawing conclusions
that depend on which cluster the data came from. 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.
|
| get_namespacesA | Return a summary of the namespaces for this Kubernetes cluster, similar to that
returned by kubectl get namespace. 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.
|
| get_node_summariesA | Return a summary of the nodes for this Kubernetes cluster, similar to that
returned by kubectl get nodes -o wide. 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_pod_summariesA | 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.
|
| get_pod_container_statusesA | 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_pod_eventsA | 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.
|
| get_pod_specA | 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.
|
| get_logs_for_pod_and_containerA | 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.
|
| get_deployment_summariesA | 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.
|
| get_replicaset_summariesA | 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.
|
| get_service_summariesA | Retrieves a list of ServiceSummary objects for services in a given namespace or all namespaces.
Similar to kubectl get services. 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.
|
| get_configmap_summariesA | Retrieves a list of ConfigMapSummary objects for ConfigMaps in a given namespace
or all namespaces, similar to kubectl get configmaps. 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.
|
| get_configmapA | Retrieves the full contents of a single ConfigMap. 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.
|
| get_statefulset_summariesA | Retrieves a list of StatefulSetSummary objects for StatefulSets in a given
namespace or all namespaces, similar to kubectl get statefulsets. 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.
|
| get_daemonset_summariesA | Retrieves a list of DaemonSetSummary objects for DaemonSets in a given
namespace or all namespaces, similar to kubectl get daemonsets -o wide. 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.
|
| get_cronjob_summariesA | Retrieves a list of CronJobSummary objects for CronJobs in a given namespace
or all namespaces, similar to kubectl get cronjobs. 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.
|
| get_job_summariesA | Retrieves a list of JobSummary objects for Jobs in a given namespace or all
namespaces, similar to kubectl get jobs. 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.
|
| get_logs_for_jobA | Retrieves logs from the most-recently-created pod of a Job. 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.
|
| get_logs_for_cronjobA | Retrieves logs from the most-recent run of a CronJob. 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.
|
| get_pvc_summariesA | Retrieves a list of PVCSummary objects for PersistentVolumeClaims in a given
namespace or all namespaces, similar to kubectl get pvc. 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.
|
| get_eventsA | Lists cluster- or namespace-wide events with optional server-side filtering. 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.
|
