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

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 字段的结构及其针对不同类型对象的内容。

服务端字段校验

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

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

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

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

下一步

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

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

要全面了解 Kubernetes API,请访问:

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

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