Kubernetes 中的对象

Kubernetes 对象是 Kubernetes 系统中的持久实体。Kubernetes 使用这些实体来表示集群的状态。了解 Kubernetes 对象模型以及如何使用这些对象。

本页面介绍了 Kubernetes 对象如何在 Kubernetes API 中表示，以及如何以 .yaml 格式表达它们。

理解 Kubernetes 对象

Kubernetes 对象 是 Kubernetes 系统中的持久实体。Kubernetes 使用这些实体来表示集群的状态。具体来说，它们可以描述：

哪些容器化应用正在运行（以及在哪些节点上）
这些应用可用的资源
关于这些应用行为的策略，例如重启策略、升级和容错

Kubernetes 对象是一个“意图记录”——一旦你创建了该对象，Kubernetes 系统将不断努力确保该对象存在。通过创建一个对象，你实际上是在告诉 Kubernetes 系统你希望集群的工作负载呈现什么样；这就是集群的期望状态。

要使用 Kubernetes 对象——无论是创建、修改还是删除它们——你都需要使用 Kubernetes API。例如，当你使用 kubectl 命令行界面时，CLI 会为你调用必要的 Kubernetes API。你也可以使用其中一种客户端库直接在自己的程序中使用 Kubernetes API。

对象规约（spec）与状态（status）

几乎每个 Kubernetes 对象都包含两个嵌套的对象字段，用于管理对象的配置：对象 spec 和对象 status。对于有 spec 的对象，你必须在创建对象时设置它，提供你希望资源具有的特征描述：即期望状态。

status 描述了对象的当前状态，由 Kubernetes 系统及其组件提供和更新。Kubernetes 控制平面持续且主动地管理每个对象的实际状态，以匹配你提供的期望状态。

例如：在 Kubernetes 中，Deployment 是一个可以表示在集群上运行的应用的对象。当你创建 Deployment 时，你可能会设置 Deployment spec，指定你希望运行该应用的三个副本。Kubernetes 系统读取 Deployment 规约并启动你所期望应用的三个实例——更新状态以匹配你的规约。如果其中任何实例发生故障（状态更改），Kubernetes 系统会通过进行修正来响应规约和状态之间的差异——在这种情况下，即启动一个替换实例。

有关对象规约、状态和元数据的更多信息，请参阅 Kubernetes API 约定。

描述 Kubernetes 对象

当你创建一个 Kubernetes 对象时，必须提供描述其期望状态的对象规约，以及关于该对象的一些基本信息（如名称）。当你使用 Kubernetes API 创建对象（直接或通过 kubectl）时，该 API 请求必须在请求体中包含这些 JSON 格式的信息。通常，你以清单（manifest）文件的形式向 kubectl 提供这些信息。按照惯例，清单是 YAML 格式的（也可以使用 JSON 格式）。当通过 HTTP 发起 API 请求时，kubectl 等工具会将清单中的信息转换为 JSON 或其他受支持的序列化格式。

这是一个示例清单，显示了 Kubernetes Deployment 所需的字段和对象规约：

application/deployment.yaml

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deployment
spec:
  selector:
    matchLabels:
      app: nginx
  replicas: 2 # tells deployment to run 2 pods matching the template
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx:1.14.2
        ports:
        - containerPort: 80

使用如上清单文件创建 Deployment 的一种方法是使用 kubectl 命令行界面中的 kubectl apply 命令，并将 .yaml 文件作为参数传递。示例如下：

kubectl apply -f https://k8s.io/examples/application/deployment.yaml

输出类似于此

deployment.apps/nginx-deployment created

必要字段

在要创建的 Kubernetes 对象的清单（YAML 或 JSON 文件）中，你需要为以下字段设置值：

apiVersion - 你正在使用哪个版本的 Kubernetes API 来创建此对象
kind - 你想要创建的对象种类
metadata - 帮助唯一标识对象的数据，包括 name 字符串、UID 和可选的 namespace
spec - 你期望该对象处于什么状态

对象 spec 的精确格式因每个 Kubernetes 对象而异，并包含特定于该对象的嵌套字段。Kubernetes API 参考可以帮助你找到所有可以使用 Kubernetes 创建的对象的规约格式。

例如，请参阅 Pod API 参考中的 spec 字段。对于每个 Pod，.spec 字段指定了 Pod 及其期望状态（例如该 Pod 内每个容器的容器镜像名称）。对象规范的另一个例子是 StatefulSet API 的 spec 字段。对于 StatefulSet，.spec 字段指定了 StatefulSet 及其期望状态。在 StatefulSet 的 .spec 中，有一个 Pod 对象的模板。该模板描述了 StatefulSet 控制器为了满足 StatefulSet 规范而将要创建的 Pod。不同类型的对象也可以具有不同的 .status；同样，API 参考页面详细介绍了该 .status 字段的结构，及其针对每种不同类型对象的内容。

有关编写 YAML 配置文件的更多信息，请参阅 Kubernetes 配置最佳实践。

服务端字段验证

从 Kubernetes v1.25 开始，API 服务器提供服务端字段验证，用于检测对象中无法识别或重复的字段。它在服务端提供了 kubectl --validate 的所有功能。

kubectl 工具使用 --validate 标志来设置字段验证级别。它接受 ignore、warn 和 strict 值，同时也接受 true（等同于 strict）和 false（等同于 ignore）。kubectl 的默认验证设置为 --validate=true。

Strict: 严格字段验证，验证失败时报错
Warn: 执行字段验证，但错误以警告形式暴露，而不是导致请求失败
Ignore: 不执行服务端字段验证

当 kubectl 无法连接到支持字段验证的 API 服务器时，它将回退到使用客户端验证。Kubernetes 1.27 及更高版本始终提供字段验证；较旧的 Kubernetes 版本可能不提供。如果你的集群版本低于 v1.27，请查看你所用 Kubernetes 版本的文档。

接下来

如果你是 Kubernetes 新手，请阅读以下内容：

Pods，这是最基础、最重要的 Kubernetes 对象。
Deployment 对象。
Kubernetes 中的 Controllers。
kubectl 和 kubectl 命令。

Kubernetes 对象管理解释了如何使用 kubectl 管理对象。如果你还没有安装 kubectl，你可能需要安装它。

要全面了解 Kubernetes API，请访问：

Kubernetes API 概述

要更深入地了解 Kubernetes 中的对象，请阅读本章节中的其他页面：

最后修改于 2025 年 11 月 24 日太平洋标准时间晚上 9:22：将 K8s 配置最佳实践迁移至博客 (b90c59015c)