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 spec 并启动三个所需应用实例——更新 status 以与您的 spec 匹配。如果其中任何实例失败（状态更改），Kubernetes 系统会通过进行纠正来响应 spec 和 status 之间的差异——在本例中，是启动一个替换实例。

有关对象 spec、status 和 metadata 的更多信息，请参阅Kubernetes API 约定。

描述 Kubernetes 对象

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

以下是一个示例清单，展示了 Kubernetes Deployment 所需的字段和对象 spec

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 创建的所有对象的 spec 格式。

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

注意

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

服务端字段校验

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

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

严格: 严格字段校验，校验失败时报错
警告: 执行字段校验，但将错误暴露为警告而非导致请求失败
忽略: 不执行服务端字段校验

当 kubectl 无法连接到支持字段校验的 API Server 时，它将回退到使用客户端校验。Kubernetes 1.27 及更高版本总是提供字段校验；旧版本的 Kubernetes 可能不支持。如果您的集群版本低于 v1.27，请查阅您版本对应的 Kubernetes 文档。

下一步

如果您是 Kubernetes 新手，请进一步阅读以下内容：

Pod 是最重要的基础 Kubernetes 对象。
Deployment 对象。
Kubernetes 中的控制器。
kubectl 和 kubectl 命令。

Kubernetes 对象管理解释了如何使用 kubectl 管理对象。如果您尚未安装 kubectl，可能需要安装 kubectl。

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

Kubernetes API 概述

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

上次修改时间：2024 年 8 月 25 日下午 8:24 PST：重新排序概述页面 (42da717f16)