Great question. Here’s how to use the prefect-kubernetes integration to call

read_namespaced_pod

with

KubernetesCredentials

in Prefect 3.4.25. First, make sure the integration is installed: -

pip install "prefect[kubernetes]"

(installs the

prefect-kubernetes

package and Kubernetes client) Key pieces you’ll use: -

prefect_kubernetes.credentials.KubernetesCredentials

-

prefect_kubernetes.credentials.KubernetesClusterConfig

(optional, if you want to load from a kubeconfig) -

prefect_kubernetes.pods.read_namespaced_pod

Function signature (for reference):

read_namespaced_pod(
    kubernetes_credentials: KubernetesCredentials,
    pod_name: str,
    namespace: str = "default",
    **kube_kwargs
) -> V1Pod

Option A — In-cluster (recommended when your flow runs in a Kubernetes pod) - If you instantiate

KubernetesCredentials()

with no args, it will try in-cluster auth first and fall back to local kubeconfig.

from prefect import flow
from prefect_kubernetes.credentials import KubernetesCredentials
from prefect_kubernetes.pods import read_namespaced_pod

@flow
def get_pod_info():
    creds = KubernetesCredentials()  # auto-detect in-cluster or fall back to kubeconfig
    pod = read_namespaced_pod(
        kubernetes_credentials=creds,
        pod_name="my-pod",
        namespace="default"
    )
    print(f"Pod phase: {pod.status.phase}")
    print(f"Labels: {pod.metadata.labels or {}}")
    return pod

get_pod_info()

Option B — From a kubeconfig file/context (e.g., running locally)

from prefect_kubernetes.credentials import KubernetesClusterConfig, KubernetesCredentials
from prefect_kubernetes.pods import read_namespaced_pod

cluster_config = KubernetesClusterConfig.from_file(
    path="~/.kube/config",
    context_name="my-context"  # optional; uses current context if omitted
)
creds = KubernetesCredentials(cluster_config=cluster_config)

pod = read_namespaced_pod(
    kubernetes_credentials=creds,
    pod_name="my-pod",
    namespace="default"
)
print(pod.status.phase, pod.metadata.labels)

Option C — Save/load as a Prefect block

from prefect_kubernetes.credentials import KubernetesClusterConfig, KubernetesCredentials

# Create and save once
cluster_config = KubernetesClusterConfig.from_file(path="~/.kube/config", context_name="my-context")
KubernetesCredentials(cluster_config=cluster_config).save("my-k8s-creds", overwrite=True)

# Later, load and use
from prefect_kubernetes.pods import read_namespaced_pod
creds = KubernetesCredentials.load("my-k8s-creds")
pod = read_namespaced_pod(kubernetes_credentials=creds, pod_name="my-pod", namespace="default")

Accessing common pod fields

print(pod.metadata.name)          # name
print(pod.metadata.namespace)     # namespace
print(pod.metadata.labels or {})  # dict of labels
print(pod.status.phase)           # Pending | Running | Succeeded | Failed | Unknown

RBAC reminder (in-cluster) - The service account your flow runs as must be allowed to get pods in the target namespace. Example Role/RoleBinding:

apiVersion: <http://rbac.authorization.k8s.io/v1|rbac.authorization.k8s.io/v1>
kind: Role
metadata:
  name: pod-reader
  namespace: default
rules:
- apiGroups: [""]
  resources: ["pods"]
  verbs: ["get", "list"]
---
apiVersion: <http://rbac.authorization.k8s.io/v1|rbac.authorization.k8s.io/v1>
kind: RoleBinding
metadata:
  name: pod-reader-binding
  namespace: default
subjects:
- kind: ServiceAccount
  name: <your-service-account>
  namespace: default
roleRef:
  kind: Role
  name: pod-reader
  apiGroup: <http://rbac.authorization.k8s.io|rbac.authorization.k8s.io>

Docs and API references - prefect-kubernetes integration guide - KubernetesCredentials API - Pods helpers API

If you prefer to work with the raw Kubernetes client, you can also drop down to the client via

KubernetesCredentials.get_client("core")

and call the Kubernetes API directly. Would you like to run this inside a cluster (in which case Option A + RBAC is ideal), or from your local machine using a kubeconfig? Which namespace are you targeting?