Introduction

Kubernetes assigns a unique UID to every object, but kubectl does not support getting or deleting resources directly by UID. The API and CLI are designed around namespace, resource type, and name. To operate on a resource by UID, you first query for the resource whose .metadata.uid matches, then use its name. This is an extra step but ensures correctness, especially when multiple objects share similar names across namespaces.

Why kubectl Does Not Support UID Directly

Kubernetes resources are identified by the tuple (apiVersion, kind, namespace, name). UIDs are internal identifiers used for ownership references (ownerReferences), garbage collection, and conflict detection. The API server indexes resources by name, not UID, so there is no efficient single-call lookup by UID.

Get a Pod by UID

Use kubectl get with JSONPath or jq to filter by UID.

1# Find a pod by UID in a specific namespace
2TARGET_UID="d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f9a"
3
4kubectl get pods -n default -o json | \
5  jq -r ".items[] | select(.metadata.uid == \"$TARGET_UID\") | .metadata.name"

Or using kubectl with JSONPath:

kubectl get pods -n default -o jsonpath='{range .items[?(@.metadata.uid=="d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f9a")]}{.metadata.name}{"\n"}{end}'

Search Across All Namespaces

1TARGET_UID="d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f9a"
2
3kubectl get pods --all-namespaces -o json | \
4  jq -r ".items[] | select(.metadata.uid == \"$TARGET_UID\") | \"\(.metadata.namespace)/\(.metadata.name)\""

Delete a Pod by UID

Since kubectl delete requires a name, find the name first, then delete.

1TARGET_UID="d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f9a"
2NAMESPACE="default"
3
4POD_NAME=$(kubectl get pods -n "$NAMESPACE" -o json | \
5  jq -r ".items[] | select(.metadata.uid == \"$TARGET_UID\") | .metadata.name")
6
7if [ -n "$POD_NAME" ]; then
8  kubectl delete pod "$POD_NAME" -n "$NAMESPACE"
9  echo "Deleted pod: $POD_NAME"
10else
11  echo "No pod found with UID: $TARGET_UID"
12fi

Get Any Resource by UID

The same pattern works for any Kubernetes resource type.

1# Find a deployment by UID
2TARGET_UID="a1b2c3d4-e5f6-7890-abcd-ef1234567890"
3
4kubectl get deployments -n default -o json | \
5  jq -r ".items[] | select(.metadata.uid == \"$TARGET_UID\") | .metadata.name"
6
7# Find a service by UID
8kubectl get services --all-namespaces -o json | \
9  jq -r ".items[] | select(.metadata.uid == \"$TARGET_UID\") | \"\(.metadata.namespace)/\(.metadata.name)\""

Using the Kubernetes API Directly

The Kubernetes API supports field selectors, but metadata.uid is not a supported field selector for most resources. You must list and filter client-side.

1from kubernetes import client, config
2
3config.load_kube_config()
4v1 = client.CoreV1Api()
5
6target_uid = "d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f9a"
7
8pods = v1.list_namespaced_pod(namespace="default")
9for pod in pods.items:
10    if pod.metadata.uid == target_uid:
11        print(f"Found: {pod.metadata.name}")
12        # Delete if needed
13        v1.delete_namespaced_pod(name=pod.metadata.name, namespace="default")
14        break

When UIDs Are Useful

UIDs are primarily used for:

• Owner references: Garbage collection uses UIDs to track parent-child relationships between resources.
• Conflict detection: The API server uses UIDs to ensure you are updating the correct revision of a resource.
• Audit logging: UIDs uniquely identify a specific incarnation of a resource, even if the name is reused after deletion.

# Check ownerReferences to see which UID owns a pod
kubectl get pod my-pod -o jsonpath='{.metadata.ownerReferences[*].uid}'

Common Pitfalls

• Expecting kubectl get pod --uid=xxx to work — kubectl has no --uid flag. You must filter JSON output client-side.
• Searching only in one namespace when the resource could be in any namespace — use --all-namespaces when the namespace is unknown.
• Assuming UIDs are reused after deletion — UIDs are unique within the cluster lifetime. A new pod with the same name gets a different UID.
• Using UIDs for human communication — UIDs are long and hard to read. Use resource names and namespaces for day-to-day operations, and UIDs only for programmatic correlation.
• Not handling the case where no resource matches the UID — always check for empty results before attempting delete operations.

Summary

• Kubernetes does not support direct get/delete by UID through kubectl.
• Use kubectl get -o json | jq to filter resources by .metadata.uid, then operate by name.
• UIDs are unique per resource incarnation and useful for ownership references, garbage collection, and audit trails.
• For programmatic access, list resources and filter by UID in client libraries (Python, Go, etc.).
• Always search across all namespaces when the resource location is unknown.