Kubernetes Manifest Resource Identity

Kubernetes Manifest Resource Identity is the combination of fields within a manifest — apiVersion, kind, name, and namespace — that together determine exactly which object in the cluster a given manifest refers to, and it is this identity, not the manifest file's own filename or location on disk, that the API server uses to decide whether an apply operation is creating a brand-new object or updating one that already exists. Understanding how identity is derived from manifest content, independent of anything about the file itself, is essential to predicting what a given apply or create operation will actually do.

The Identity-Determining Fields

apiVersion and kind Establish Type

apiVersion and kind together determine which resource type, and therefore which specific collection of objects, a manifest belongs to; two manifests with identical metadata.name but different kind values refer to entirely distinct objects (a ConfigMap named config and a Secret named config coexist without conflict), since object identity within the API is always scoped to a specific resource type.

name and namespace Establish the Specific Instance

Within a given resource type, metadata.name (combined with metadata.namespace for namespaced types) pins down exactly which instance the manifest describes; changing a manifest's name field between applies does not update an existing object under a new name, it creates an entirely separate object, since the API server has no way to infer that two differently named manifests were "meant" to refer to the same conceptual entity.

Identity Is Independent of File Location

The Filename Carries No Meaning to the API

Nothing about a manifest's filename, its directory, or the order it appears in a multi-document file has any bearing on the object identity the API server derives from it; renaming deployment.yaml to app.yaml, or moving it to a different directory, has zero effect on which live object kubectl apply -f will target, since the API server only ever sees the parsed content, never the originating file's path.

Implications for Reorganizing Manifest Files

This independence means manifest files can be freely reorganized, renamed, split, or merged for project organization purposes without any risk of accidentally creating duplicate objects or losing track of an existing one, as long as the identity-determining fields within the content itself remain unchanged.

Identity and the apply Workflow

How apply Determines Create Versus Update

When kubectl apply (or any declarative apply-style client) submits a manifest, it first attempts to determine whether an object with the manifest's derived identity already exists by querying the API server; if it does, the operation proceeds as a patch against the existing object, and if not, the operation proceeds as a creation, meaning the exact same manifest content, applied at different points in time, can result in either behavior purely depending on whether a matching object currently exists.

Renaming as Delete-and-Recreate

Because name is part of an object's identity and, for most types, is immutable once set, a manifest edit that changes metadata.name does not rename the existing object; from the API's perspective it declares an entirely new object, meaning true "renaming" of a running resource generally requires explicitly deleting the old-named object and creating a new one under the new name, with whatever downtime or reference-updating that transition implies.

Namespace as Part of Identity

Namespace Determined by Manifest or Context

A namespaced manifest's effective namespace comes either from an explicit metadata.namespace field within the manifest itself, or, if omitted, from the namespace specified by the applying client's context (such as kubectl's current context namespace or an explicit -n flag); the same manifest content applied against two different target namespaces produces two entirely independent objects, since namespace is as much a part of identity as name is for namespaced types.

Risk of Namespace Mismatch

Because namespace can be supplied outside the manifest itself, a manifest lacking an explicit namespace field carries an implicit dependency on whatever context it happens to be applied under, which is a common source of accidental cross-environment deployment when the same manifest is applied without realizing the active context has changed since it was last used.