# Object Names and IDs

LLMS index: [llms.txt](/llms.txt)

---

<!-- overview -->

Each <a class='glossary-tooltip' title='An entity in the Kubernetes system, representing part of the state of your cluster.' data-bs-toggle='tooltip' data-bs-placement='top' href='/docs/concepts/overview/working-with-objects/#kubernetes-objects' target='_blank' aria-label='object'>object</a> in your cluster has a [_Name_](#names) that is unique for that type of resource.
Every Kubernetes object also has a [_UID_](#uids) that is unique across your whole cluster.

For example, you can only have one Pod named `myapp-1234` within the same [namespace](/docs/concepts/overview/working-with-objects/namespaces/), but you can have one Pod and one Deployment that are each named `myapp-1234`.

For non-unique user-provided attributes, Kubernetes provides [labels](/docs/concepts/overview/working-with-objects/labels/) and [annotations](/docs/concepts/overview/working-with-objects/annotations/).



<!-- body -->

## Names

<p>A client-provided string that refers to an object in a <a class='glossary-tooltip' title='A Kubernetes entity, representing an endpoint on the Kubernetes API server.' data-bs-toggle='tooltip' data-bs-placement='top' href='/docs/reference/using-api/api-concepts/#standard-api-terminology' target='_blank' aria-label='resource'>resource</a>
URL, such as <code>/api/v1/pods/some-name</code>.</p>
<p>Only one object of a given kind can have a given name at a time. However, if you delete the object, you can make a new object with the same name.</p>

Names must be unique across all [API versions](/docs/concepts/overview/kubernetes-api/#api-groups-and-versioning) of the same resource. 

Kubernetes uniquely identifies objects using a combination of four attributes:
* **API group** (e.g., `apps`)
* **Resource type** (e.g., `deployments`)
* **Namespace** (for namespaced resources)
* **Name**

While you can access a resource through different API versions (such as `v1` or `v1beta1`), the version is simply a different representation of the same underlying object. Because the version is not part of the unique identification, you cannot create two objects with the same name and resource type in the same namespace by using different API versions.


<div class="alert alert-info" role="note"><h4 class="alert-heading">Note:</h4>In cases when objects represent a physical entity, like a Node representing a physical host, when the host is re-created under the same name without deleting and re-creating the Node, Kubernetes treats the new host as the old one, which may lead to inconsistencies.</div>


The server may generate a name when `generateName` is provided instead of `name` in a resource create request.
When `generateName` is used, the provided value is used as a name prefix, which server appends a generated suffix
to. Even though the name is generated, it may conflict with existing names resulting in an HTTP 409 response. This
became far less likely to happen in Kubernetes v1.31 and later, since the server will make up to 8 attempts to generate a
unique name before returning an HTTP 409 response.

Below are four types of commonly used name constraints for resources.

### DNS Subdomain Names

Most resource types require a name that can be used as a DNS subdomain name
as defined in [RFC 1123](https://tools.ietf.org/html/rfc1123).
This means the name must:

- contain no more than 253 characters
- contain only lowercase alphanumeric characters, '-' or '.'
- start with an alphanumeric character
- end with an alphanumeric character

### RFC 1123 Label Names {#dns-label-names}

Some resource types require their names to follow the DNS
label standard as defined in [RFC 1123](https://tools.ietf.org/html/rfc1123).
This means the name must:

- contain at most 63 characters
- contain only lowercase alphanumeric characters or '-'
- start with an alphabetic character
- end with an alphanumeric character


<div class="alert alert-info" role="note"><h4 class="alert-heading">Note:</h4>When the <code>RelaxedServiceNameValidation</code> feature gate is enabled,
Service object names are allowed to start with a digit.</div>


### RFC 1035 Label Names

Some resource types require their names to follow the DNS
label standard as defined in [RFC 1035](https://tools.ietf.org/html/rfc1035).
This means the name must:

- contain at most 63 characters
- contain only lowercase alphanumeric characters or '-'
- start with an alphabetic character
- end with an alphanumeric character


<div class="alert alert-info" role="note"><h4 class="alert-heading">Note:</h4>While RFC 1123 technically allows labels to start with digits, the current
Kubernetes implementation requires both RFC 1035 and RFC 1123 labels to start
with an alphabetic character. The exception is when the <code>RelaxedServiceNameValidation</code>
feature gate is enabled for Service objects, which allows Service names to start with digits.</div>


### Path Segment Names

Some resource types require their names to be able to be safely encoded as a
path segment. In other words, the name may not be "." or ".." and the name may
not contain "/" or "%".

Here's an example manifest for a Pod named `nginx-demo`.

```yaml
apiVersion: v1
kind: Pod
metadata:
  name: nginx-demo
spec:
  containers:
  - name: nginx
    image: nginx:1.14.2
    ports:
    - containerPort: 80
```



<div class="alert alert-info" role="note"><h4 class="alert-heading">Note:</h4>Some resource types have additional restrictions on their names.</div>


## UIDs

<p>A Kubernetes systems-generated string to uniquely identify objects.</p>
<p>Every object created over the whole lifetime of a Kubernetes cluster has a distinct UID. It is intended to distinguish between historical occurrences of similar entities.</p>

Kubernetes UIDs are universally unique identifiers (also known as UUIDs).
UUIDs are standardized as ISO/IEC 9834-8 and as ITU-T X.667.


## What's next

* Read about [labels](/docs/concepts/overview/working-with-objects/labels/) and [annotations](/docs/concepts/overview/working-with-objects/annotations/) in Kubernetes.
* See the [Identifiers and Names in Kubernetes](https://git.k8s.io/design-proposals-archive/architecture/identifiers.md) design document.