6.4 Kubernetes Manifest Resource Identity

Kubernetes Manifest Resource Identity is the specific combination of fields within a manifest, namely its kind, API version, namespace, and name, that a client uses to determine which existing cluster object, if any, a given manifest corresponds to when it is submitted, forming the matching key that governs whether an apply operation creates a new object or updates an already-existing one.

The Identity Tuple

Kind and API Version

A manifest's kind and apiVersion together identify the type of object being described, determining which resource endpoint the manifest will be submitted against and which schema it will be validated against, functioning as the type component of the manifest's overall identity.

Namespace and Name

For namespaced resources, the combination of metadata.namespace and metadata.name identifies the specific instance within that type, while cluster-scoped resources rely on metadata.name alone; together with kind, this forms the complete addressable identity that determines exactly which object on the cluster, if any, the manifest refers to.

Identity Does Not Include UID

Notably, a manifest's identity for matching purposes is based on this human-assigned tuple, not on the system-assigned uid, since a manifest authored before an object exists cannot possibly know its future uid; the API server resolves identity based on kind, namespace, and name, and only afterward does the resulting object carry a uid for finer-grained, collision-proof tracking.

Identity's Role in Apply Operations

Determining Create Versus Update

When a manifest is applied, whether through kubectl apply or programmatically through server-side apply, the client or server first checks whether an object matching the manifest's identity tuple already exists; if not, a new object is created, and if one is found, the existing object is updated according to the fields present in the manifest.

Idempotent Reapplication

Because identity is derived from stable, human-chosen fields rather than a generated identifier, reapplying the same manifest repeatedly is idempotent with respect to identity resolution: the same manifest will always resolve to the same target object as long as its kind, namespace, and name remain unchanged, a property essential to the reliability of declarative, repeatable deployment workflows.

Identity Changes Across Manifest Revisions

Renaming Implies a New Identity

If a manifest's metadata.name is changed between applications, the new manifest resolves to a different identity entirely, meaning the API server treats it as describing an entirely new object rather than a rename of the previous one; the original object, if no longer referenced by any manifest, is left behind unless something else explicitly removes it.

Namespace Changes Behave Similarly

Changing a manifest's namespace has the same effect as changing its name: because namespace is part of the identity tuple, the manifest now targets a different object entirely, and Kubernetes has no native concept of moving an existing object between namespaces through a manifest update alone.

Implications for Manifest Management Practices

Avoiding Orphaned Objects

Because renaming or re-namespacing a manifest creates a new object rather than modifying the old one in place, teams practicing GitOps or manifest-driven deployment need explicit cleanup steps, such as pruning, to remove objects whose corresponding manifest has since been renamed or deleted from the source repository, since identity resolution alone will not detect or clean up the orphaned original.

Pruning and Identity Tracking

Tools that support pruning, removing cluster objects that no longer correspond to any manifest in the current source set, typically track the identity tuples of previously applied manifests, often using a tracking label or annotation, so that objects whose identity no longer appears in the latest manifest set can be correctly identified as candidates for removal.

Distinguishing Manifest Identity From generateName

generateName as an Exception

Manifests using generateName instead of a fixed name deliberately opt out of a stable, predictable identity, since the actual name is only assigned at creation time by the API server; such manifests are inherently non-idempotent to reapply in the usual sense, since each submission using generateName produces a distinct new object rather than updating a previously created one.