对象名称和 ID

集群中的每个对象都有一个在该类资源中唯一的名称。每个 Kubernetes 对象还拥有一个在整个集群中唯一的UID

例如,在同一个 命名空间中,你只能拥有一个名为 myapp-1234 的 Pod,但你可以同时拥有一个名为 myapp-1234 的 Pod 和一个名为 myapp-1234 的 Deployment。

对于非唯一且由用户提供的属性,Kubernetes 提供了标签 (Labels)注解 (Annotations)

名称

这是客户端提供的字符串,用于在资源 URL 中引用对象,例如 /api/v1/pods/some-name

在同一时间,特定类型中只能有一个对象拥有给定的名称。不过,如果你删除了该对象,则可以创建一个拥有相同名称的新对象。

名称在同一资源的所有 API 版本中必须是唯一的。API 资源由其 API 组、资源类型、命名空间(对于命名空间范围内的资源)和名称来区分。换句话说,在此上下文中 API 版本无关紧要。

说明

当对象代表物理实体(例如代表物理主机的 Node)时,如果在不删除并重新创建 Node 的情况下以相同名称重新创建主机,Kubernetes 会将新主机视为旧主机,这可能会导致不一致。

当资源创建请求中提供 generateName 而非 name 时,服务器可能会生成一个名称。使用 generateName 时,提供的值将用作名称前缀,服务器会在其后追加一个生成的后缀。即使名称是生成的,它也可能与现有名称冲突,从而导致 HTTP 409 响应。在 Kubernetes v1.31 及更高版本中,这种情况发生的可能性大大降低,因为服务器会在返回 HTTP 409 响应之前尝试最多 8 次生成唯一的名称。

以下是四种常用的资源名称约束类型。

DNS 子域名

大多数资源类型要求名称必须符合 RFC 1123 定义的 DNS 子域名规范。这意味着名称必须:

  • 长度不超过 253 个字符
  • 仅包含小写字母数字字符、'-' 或 '.'
  • 以字母数字字符开头
  • 以字母数字字符结尾

RFC 1123 标签名称

某些资源类型要求其名称符合 RFC 1123 定义的 DNS 标签标准。这意味着名称必须:

  • 包含最多 63 个字符
  • 仅包含小写字母数字字符或 '-'
  • 以字母字符开头
  • 以字母数字字符结尾

说明

当启用 RelaxedServiceNameValidation 功能门控时,允许 Service 对象名称以数字开头。

RFC 1035 标签名称

某些资源类型要求其名称符合 RFC 1035 定义的 DNS 标签标准。这意味着名称必须:

  • 包含最多 63 个字符
  • 仅包含小写字母数字字符或 '-'
  • 以字母字符开头
  • 以字母数字字符结尾

说明

虽然 RFC 1123 在技术上允许标签以数字开头,但当前的 Kubernetes 实现要求 RFC 1035 和 RFC 1123 标签都必须以字母字符开头。例外情况是,当针对 Service 对象启用了 RelaxedServiceNameValidation 功能门控时,允许 Service 名称以数字开头。

路径段名称

某些资源类型要求其名称能够安全地编码为路径段。换句话说,名称不能是 "." 或 "..",且名称不能包含 "/" 或 "%"。

以下是一个名为 nginx-demo 的 Pod 的示例清单。

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

说明

某些资源类型对其名称有额外的限制。

UID

由 Kubernetes 系统生成的字符串,用于唯一标识对象。

在 Kubernetes 集群的整个生命周期中创建的每个对象都有一个不同的 UID。其目的是为了区分相似实体的历史记录。

Kubernetes UID 是通用唯一标识符(也称为 UUID)。UUID 遵循 ISO/IEC 9834-8 和 ITU-T X.667 标准。

接下来


最后修改于 2025 年 10 月 2 日下午 6:19 PST: docs: 修复 RFC 1123 标签名称文档 (0a5bab0183)