扩展 Kubernetes

• 1: Operator 模式
• 2: 计算、存储和网络扩展
• 2.1: 网络插件
• 2.2: 设备插件
• 3: 扩展 Kubernetes API
• 3.1: 定制资源
• 3.2: Kubernetes API 聚合层

Kubernetes 是高度可配置且可扩展的。因此，大多数情况下， 你不需要派生自己的 Kubernetes 副本或者向项目代码提交补丁。

本指南描述定制 Kubernetes 的可选方式。主要针对的读者是希望了解如何针对自身工作环境需要来调整 Kubernetes 的集群管理者。 对于那些充当平台开发人员的开发人员或 Kubernetes 项目的贡献者而言， 他们也会在本指南中找到有用的介绍信息，了解系统中存在哪些扩展点和扩展模式， 以及它们所附带的各种权衡和约束等等。

定制化的方法主要可分为配置和扩展两种。 前者主要涉及更改命令行参数、本地配置文件或者 API 资源； 后者则需要额外运行一些程序、网络服务或两者。 本文主要关注扩展。

配置

配置文件和命令参数的说明位于在线文档的参考一节， 每个可执行文件一个页面：

• kube-apiserver
• kube-controller-manager
• kube-scheduler
• kubelet
• kube-proxy

在托管的 Kubernetes 服务中或者受控安装的发行版本中，命令参数和配置文件不总是可以修改的。 即使它们是可修改的，通常其修改权限也仅限于集群操作员。 此外，这些内容在将来的 Kubernetes 版本中很可能发生变化，设置新参数或配置文件可能需要重启进程。 有鉴于此，应该在没有其他替代方案时才会使用这些命令参数和配置文件。

诸如 ResourceQuota、 NetworkPolicy 和基于角色的访问控制（RBAC） 等内置策略 API 都是以声明方式配置策略选项的内置 Kubernetes API。 即使在托管的 Kubernetes 服务和受控的 Kubernetes 安装环境中，API 通常也是可用的。 内置策略 API 遵循与 Pod 这类其他 Kubernetes 资源相同的约定。 当你使用稳定版本的策略 API， 它们与其他 Kubernetes API 一样，采纳的是一种预定义的支持策略。 出于以上原因，在条件允许的情况下，基于策略 API 的方案应该优先于配置文件和命令参数。

扩展

扩展（Extensions）是一些扩充 Kubernetes 能力并与之深度集成的软件组件。 它们调整 Kubernetes 的工作方式使之支持新的类型和新的硬件种类。

大多数集群管理员会使用一种托管的 Kubernetes 服务或者其某种发行版本。 这类集群通常都预先安装了扩展。因此，大多数 Kubernetes 用户不需要安装扩展， 至于需要自己编写新的扩展的情况就更少了。

扩展模式

Kubernetes 从设计上即支持通过编写客户端程序来将其操作自动化。 任何能够对 Kubernetes API 发出读写指令的程序都可以提供有用的自动化能力。 自动化组件可以运行在集群上，也可以运行在集群之外。 通过遵从本文中的指南，你可以编写高度可用的、运行稳定的自动化组件。 自动化组件通常可以用于所有 Kubernetes 集群，包括托管的集群和受控的安装环境。

编写客户端程序有一种特殊的控制器（Controller）模式， 能够与 Kubernetes 很好地协同工作。控制器通常会读取某个对象的 .spec，或许还会执行一些操作， 之后更新对象的 .status。

控制器是 Kubernetes API 的客户端。当 Kubernetes 充当客户端且调用某远程服务时， Kubernetes 将此称作 Webhook。该远程服务称作 Webhook 后端。 与定制的控制器相似，Webhook 也会引入失效点（Point of Failure）。

说明：

在 Kubernetes 之外，“Webhook” 这个词通常是指一种异步通知机制， 其中 Webhook 调用将用作对另一个系统或组件的单向通知。 在 Kubernetes 生态系统中，甚至同步的 HTTP 调用也经常被描述为 “Webhook”。

在 Webhook 模型中，Kubernetes 向远程服务发起网络请求。 在另一种称作可执行文件插件（Binary Plugin） 模型中，Kubernetes 执行某个可执行文件（程序）。 这些可执行文件插件由 kubelet（例如，CSI 存储插件和 CNI 网络插件） 和 kubectl 使用。

扩展点

下图展示了 Kubernetes 集群中的这些扩展点及其访问集群的客户端。

图示要点

1. 用户通常使用 kubectl 与 Kubernetes API 交互。 插件定制客户端的行为。 有一些通用的扩展可以应用到不同的客户端，还有一些特定的方式可以扩展 kubectl。

2. API 服务器处理所有请求。API 服务器中的几种扩展点能够使用户对请求执行身份认证、 基于其内容阻止请求、编辑请求内容、处理删除操作等等。 这些扩展点在 API 访问扩展节详述。

3. API 服务器能提供各种类型的资源（Resources） 服务。 诸如 pods 的内置资源类型是由 Kubernetes 项目所定义的，无法改变。 请查阅 API 扩展了解如何扩展 Kubernetes API。

4. Kubernetes 调度器负责决定 Pod 要放置到哪些节点上执行。有几种方式来扩展调度行为，这些方法将在调度器扩展节中展开说明。

5. Kubernetes 中的很多行为都是通过称为控制器（Controller）的程序来实现的， 这些程序也都是 API 服务器的客户端。控制器常常与定制资源结合使用。 进一步了解请查阅结合使用新的 API 与自动化组件和更改内置资源。

6. Kubelet 运行在各个服务器（节点）上，帮助 Pod 展现为虚拟的服务器并在集群网络中拥有自己的 IP。 网络插件使得 Kubernetes 能够采用不同实现技术来连接 Pod 网络。

7. 你可以使用设备插件集成定制硬件或其他专用的节点本地设施， 使得这些设施可用于集群中运行的 Pod。Kubelet 包括了对使用设备插件的支持。

   kubelet 也会为 Pod 及其容器增加或解除卷的挂载。 你可以使用存储插件增加对新存储类别和其他卷类型的支持。

扩展点选择流程图

如果你无法确定从何处入手，下面的流程图可能对你有些帮助。 注意，某些方案可能需要同时采用几种类型的扩展。

---

客户端扩展

kubectl 所用的插件是单独的二进制文件，用于添加或替换特定子命令的行为。 kubectl 工具还可以与凭据插件集成。 这些扩展只影响单个用户的本地环境，因此不能强制执行站点范围的策略。

如果你要扩展 kubectl 工具，请阅读用插件扩展 kubectl。

API 扩展

定制资源对象

如果你想要定义新的控制器、应用配置对象或者其他声明式 API，并且使用 Kubernetes 工具（如 kubectl）来管理它们，可以考虑向 Kubernetes 添加定制资源。

关于定制资源的更多信息，可参见定制资源概念指南。

API 聚合层

你可以使用 Kubernetes 的 API 聚合层将 Kubernetes API 与其他服务集成，例如指标。

结合使用新 API 与自动化组件

定制资源 API 与控制回路的组合称作控制器模式。 如果你的控制器代替人工操作员根据所需状态部署基础设施，那么控制器也可以遵循 Operator 模式。 Operator 模式用于管理特定的应用；通常，这些应用需要维护状态并需要仔细考虑状态的管理方式。

你还可以创建自己的定制 API 和控制回路来管理其他资源（例如存储）或定义策略（例如访问控制限制）。

更改内置资源

当你通过添加定制资源来扩展 Kubernetes 时，所添加的资源总是会被放在一个新的 API 组中。 你不可以替换或更改现有的 API 组。添加新的 API 不会直接让你影响现有 API（如 Pod）的行为，不过 API 访问扩展能够实现这点。

API 访问扩展

当请求到达 Kubernetes API 服务器时，首先要经过身份认证，之后是鉴权操作， 再之后要经过若干类型的准入控制（某些请求实际上未通过身份认证，需要特殊处理）。 参见控制 Kubernetes API 访问以了解此流程的细节。

Kubernetes 身份认证/授权流程中的每个步骤都提供了扩展点。

身份认证

身份认证负责将所有请求中的头部或证书映射到发出该请求的客户端的用户名。

Kubernetes 提供若干内置的身份认证方法。它也可以运行在某种身份认证代理的后面， 并且可以将来自 Authorization: 头部的令牌发送到某个远程服务 （认证 Webhook 来执行验证操作，以备内置方法无法满足你的要求。

鉴权

鉴权操作负责确定特定的用户是否可以读、写 API 资源或对其执行其他操作。此操作仅在整个资源集合的层面进行。 换言之，它不会基于对象的特定字段作出不同的判决。

如果内置的鉴权选项无法满足你的需要， 你可以使用鉴权 Webhook 来调用用户提供的代码，执行定制的鉴权决定。

动态准入控制

请求的鉴权操作结束之后，如果请求的是写操作， 还会经过准入控制处理步骤。 除了内置的处理步骤，还存在一些扩展点：

• 镜像策略 Webhook 能够限制容器中可以运行哪些镜像。
• 为了执行任意的准入控制决定， 可以使用一种通用的准入 Webhook 机制。这类准入 Webhook 可以拒绝创建或更新请求。 一些准入 Webhook 会先修改传入的请求数据，才会由 Kubernetes 进一步处理这些传入请求数据。

基础设施扩展

设备插件

设备插件允许一个节点通过设备插件发现新的 Node 资源（除了内置的类似 CPU 和内存这类资源之外）。

存储插件

容器存储接口 (CSI) 插件提供了一种扩展 Kubernetes 的方式使其支持新类别的卷。 这些卷可以由持久的外部存储提供支持，可以提供临时存储，还可以使用文件系统范型为信息提供只读接口。

Kubernetes 还包括对 FlexVolume 插件的支持，该插件自 Kubernetes v1.23 起被弃用（被 CSI 替代）。

FlexVolume 插件允许用户挂载 Kubernetes 本身不支持的卷类型。 当你运行依赖于 FlexVolume 存储的 Pod 时，kubelet 会调用一个二进制插件来挂载该卷。 归档的 FlexVolume 设计提案对此方法有更多详细说明。

Kubernetes 存储供应商的卷插件 FAQ 包含了有关存储插件的通用信息。

网络插件

你的 Kubernetes 集群需要一个网络插件才能拥有一个正常工作的 Pod 网络， 才能支持 Kubernetes 网络模型的其他方面。

网络插件可以让 Kubernetes 使用不同的网络拓扑和技术。

Kubelet 镜像凭据提供程序插件

特性状态： Kubernetes v1.26 [stable]

Kubelet 镜像凭据提供程序是 Kubelet 动态检索镜像仓库凭据的插件。 当你从与配置匹配的容器镜像仓库中拉取镜像时，这些凭据将被使用。

这些插件可以与外部服务通信或使用本地文件来获取凭据。这样，kubelet 就不需要为每个仓库都设置静态凭据，并且可以支持各种身份验证方法和协议。

有关插件配置的详细信息，请参阅 配置 kubelet 镜像凭据提供程序。

调度扩展

调度器是一种特殊的控制器，负责监视 Pod 变化并将 Pod 分派给节点。 默认的调度器可以被整体替换掉，同时继续使用其他 Kubernetes 组件。 或者也可以在同一时刻使用多个调度器。

这是一项非同小可的任务，几乎绝大多数 Kubernetes 用户都会发现其实他们不需要修改调度器。

你可以控制哪些调度插件处于激活状态， 或将插件集关联到名字不同的调度器配置文件上。 你还可以编写自己的插件，与一个或多个 kube-scheduler 的扩展点集成。

最后，内置的 kube-scheduler 组件支持 Webhook， 从而允许远程 HTTP 后端（调度器扩展）来为 kube-scheduler 选择的 Pod 所在节点执行过滤和优先排序操作。

说明：

你只能使用调度器扩展程序 Webhook 来影响节点过滤和节点优先排序； 其他扩展点无法通过集成 Webhook 获得。

接下来

• 进一步了解基础设施扩展
  • 设备插件
  • 网络插件
  • CSI 存储插件
• 进一步了解 kubectl 插件
• 进一步了解定制资源
• 进一步了解扩展 API 服务器
• 进一步了解动态准入控制
• 进一步了解 Operator 模式

1 - Operator 模式

Operator 是 Kubernetes 的扩展软件， 它利用定制资源管理应用及其组件。 Operator 遵循 Kubernetes 的理念，特别是在控制器方面。

初衷

Operator 模式 旨在记述（正在管理一个或一组服务的）运维人员的关键目标。 这些运维人员负责一些特定的应用和 Service，他们需要清楚地知道系统应该如何运行、如何部署以及出现问题时如何处理。

在 Kubernetes 上运行工作负载的人们都喜欢通过自动化来处理重复的任务。 Operator 模式会封装你编写的（Kubernetes 本身提供功能以外的）任务自动化代码。

Kubernetes 上的 Operator

Kubernetes 为自动化而生。无需任何修改，你即可以从 Kubernetes 核心中获得许多内置的自动化功能。 你可以使用 Kubernetes 自动化部署和运行工作负载，甚至 可以自动化 Kubernetes 自身。

Kubernetes 的 Operator 模式概念允许你在不修改 Kubernetes 自身代码的情况下， 通过为一个或多个自定义资源关联控制器来扩展集群的能力。 Operator 是 Kubernetes API 的客户端， 充当自定义资源的控制器。

Operator 示例

使用 Operator 可以自动化的事情包括：

• 按需部署应用
• 获取/还原应用状态的备份
• 处理应用代码的升级以及相关改动。例如数据库 Schema 或额外的配置设置
• 发布一个 Service，要求不支持 Kubernetes API 的应用也能发现它
• 模拟整个或部分集群中的故障以测试其稳定性
• 在没有内部成员选举程序的情况下，为分布式应用选择首领角色

想要更详细的了解 Operator？下面是一个示例：

1. 有一个名为 SampleDB 的自定义资源，你可以将其配置到集群中。
2. 一个包含 Operator 控制器部分的 Deployment，用来确保 Pod 处于运行状态。
3. Operator 代码的容器镜像。
4. 控制器代码，负责查询控制平面以找出已配置的 SampleDB 资源。
5. Operator 的核心是告诉 API 服务器，如何使现实与代码里配置的资源匹配。
   • 如果添加新的 SampleDB，Operator 将设置 PersistentVolumeClaims 以提供持久化的数据库存储， 设置 StatefulSet 以运行 SampleDB，并设置 Job 来处理初始配置。
   • 如果你删除它，Operator 将建立快照，然后确保 StatefulSet 和 Volume 已被删除。
6. Operator 也可以管理常规数据库的备份。对于每个 SampleDB 资源，Operator 会确定何时创建（可以连接到数据库并进行备份的）Pod。这些 Pod 将依赖于 ConfigMap 和/或具有数据库连接详细信息和凭据的 Secret。
7. 由于 Operator 旨在为其管理的资源提供强大的自动化功能，因此它还需要一些额外的支持性代码。 在这个示例中，代码将检查数据库是否正运行在旧版本上， 如果是，则创建 Job 对象为你升级数据库。

部署 Operator

部署 Operator 最常见的方法是将自定义资源及其关联的控制器添加到你的集群中。 跟运行容器化应用一样，控制器通常会运行在控制平面之外。 例如，你可以在集群中将控制器作为 Deployment 运行。

使用 Operator

部署 Operator 后，你可以对 Operator 所使用的资源执行添加、修改或删除操作。 按照上面的示例，你将为 Operator 本身建立一个 Deployment，然后：

kubectl get SampleDB                   # 查找所配置的数据库

kubectl edit SampleDB/example-database # 手动修改某些配置

可以了！Operator 会负责应用所作的更改并保持现有服务处于良好的状态。

编写你自己的 Operator

如果生态系统中没有可以实现你目标的 Operator，你可以自己编写代码。

你还可以使用任何支持 Kubernetes API 客户端的语言或运行时来实现 Operator（即控制器）。

以下是一些库和工具，你可用于编写自己的云原生 Operator。

• Charmed Operator Framework
• Java Operator SDK
• Kopf (Kubernetes Operator Pythonic Framework)
• kube-rs (Rust)
• kubebuilder
• KubeOps (.NET operator SDK)
• KUDO（Kubernetes 通用声明式 Operator）
• Mast
• Metacontroller，可与 Webhook 结合使用，以实现自己的功能。
• Operator Framework
• shell-operator

接下来

• 阅读 CNCF Operator 白皮书。
• 详细了解定制资源
• 在 OperatorHub.io 上找到现成的、适合你的 Operator
• 发布你的 Operator，让别人也可以使用
• 阅读 CoreOS 原始文章，它介绍了 Operator 模式（这是一个存档版本的原始文章）。
• 阅读这篇来自谷歌云的关于构建 Operator 最佳实践的文章

2 - 计算、存储和网络扩展

本节介绍不属于 Kubernetes 本身组成部分的一些集群扩展。 你可以使用这些扩展来增强集群中的节点，或者提供将 Pod 关联在一起的网络结构。

• CSI 和 FlexVolume 存储插件

  容器存储接口 (CSI) 插件提供了一种扩展 Kubernetes 的方式使其支持新类别的卷。 这些卷可以由持久的外部存储提供支持，可以提供临时存储，还可以使用文件系统范型为信息提供只读接口。

  Kubernetes 还包括对 FlexVolume 插件的扩展支持，该插件自 Kubernetes v1.23 起被弃用（被 CSI 替代）。

  FlexVolume 插件允许用户挂载 Kubernetes 本身不支持的卷类型。 当你运行依赖于 FlexVolume 存储的 Pod 时，kubelet 会调用一个二进制插件来挂载该卷。 归档的 FlexVolume 设计提案对此方法有更多详细说明。

  Kubernetes 存储供应商的卷插件 FAQ 包含了有关存储插件的通用信息。

• 设备插件

  设备插件允许一个节点发现新的 Node 设施（除了 cpu 和 memory 等内置的节点资源之外）， 并向请求资源的 Pod 提供了这些自定义的节点本地设施。

• 网络插件

  网络插件可以让 Kubernetes 使用不同的网络拓扑和技术。 你的 Kubernetes 集群需要一个 网络插件 才能拥有一个正常工作的 Pod 网络， 才能支持 Kubernetes 网络模型的其他方面。

  Kubernetes 1.29 兼容 CNI 网络插件。

2.1 - 网络插件

Kubernetes 1.29 支持用于集群联网的容器网络接口 (CNI) 插件。 你必须使用和你的集群相兼容并且满足你的需求的 CNI 插件。 在更广泛的 Kubernetes 生态系统中你可以使用不同的插件（开源和闭源）。

要实现 Kubernetes 网络模型，你需要一个 CNI 插件。

你必须使用与 v0.4.0 或更高版本的 CNI 规范相符合的 CNI 插件。 Kubernetes 推荐使用一个兼容 v1.0.0 CNI 规范的插件（插件可以兼容多个规范版本）。

安装

在网络语境中，容器运行时（Container Runtime）是在节点上的守护进程， 被配置用来为 kubelet 提供 CRI 服务。具体而言，容器运行时必须配置为加载所需的 CNI 插件，从而实现 Kubernetes 网络模型。

要了解容器运行时如何管理 CNI 插件的具体信息，可参见对应容器运行时的文档，例如：

• containerd
• CRI-O

要了解如何安装和管理 CNI 插件的具体信息，可参阅对应的插件或 网络驱动（Networking Provider） 的文档。

网络插件要求

对于插件开发人员以及时常会构建并部署 Kubernetes 的用户而言， 插件可能也需要特定的配置来支持 kube-proxy。 iptables 代理依赖于 iptables，插件可能需要确保 iptables 能够监控容器的网络通信。 例如，如果插件将容器连接到 Linux 网桥，插件必须将 net/bridge/bridge-nf-call-iptables sysctl 参数设置为 1，以确保 iptables 代理正常工作。 如果插件不使用 Linux 网桥，而是使用类似于 Open vSwitch 或者其它一些机制， 它应该确保为代理对容器通信执行正确的路由。

默认情况下，如果未指定 kubelet 网络插件，则使用 noop 插件， 该插件设置 net/bridge/bridge-nf-call-iptables=1，以确保简单的配置 （如带网桥的 Docker）与 iptables 代理正常工作。

本地回路 CNI

除了安装到节点上用于实现 Kubernetes 网络模型的 CNI 插件外，Kubernetes 还需要容器运行时提供一个本地回路接口 lo，用于各个沙箱（Pod 沙箱、虚机沙箱……）。 实现本地回路接口的工作可以通过复用 CNI 本地回路插件来实现， 也可以通过开发自己的代码来实现 （参阅 CRI-O 中的示例）。

支持 hostPort

CNI 网络插件支持 hostPort。你可以使用官方 portmap 插件，它由 CNI 插件团队提供，或者使用你自己的带有 portMapping 功能的插件。

如果你想要启动 hostPort 支持，则必须在 cni-conf-dir 指定 portMappings capability。 例如：

{
  "name": "k8s-pod-network",
  "cniVersion": "0.4.0",
  "plugins": [
    {
      "type": "calico",
      "log_level": "info",
      "datastore_type": "kubernetes",
      "nodename": "127.0.0.1",
      "ipam": {
        "type": "host-local",
        "subnet": "usePodCidr"
      },
      "policy": {
        "type": "k8s"
      },
      "kubernetes": {
        "kubeconfig": "/etc/cni/net.d/calico-kubeconfig"
      }
    },
    {
      "type": "portmap",
      "capabilities": {"portMappings": true},
      "externalSetMarkChain": "KUBE-MARK-MASQ"
    }
  ]
}

支持流量整形

实验功能

CNI 网络插件还支持 Pod 入站和出站流量整形。 你可以使用 CNI 插件团队提供的 bandwidth 插件，也可以使用你自己的具有带宽控制功能的插件。

如果你想要启用流量整形支持，你必须将 bandwidth 插件添加到 CNI 配置文件 （默认是 /etc/cni/net.d）并保证该可执行文件包含在你的 CNI 的 bin 文件夹内 (默认为 /opt/cni/bin)。

{
  "name": "k8s-pod-network",
  "cniVersion": "0.4.0",
  "plugins": [
    {
      "type": "calico",
      "log_level": "info",
      "datastore_type": "kubernetes",
      "nodename": "127.0.0.1",
      "ipam": {
        "type": "host-local",
        "subnet": "usePodCidr"
      },
      "policy": {
        "type": "k8s"
      },
      "kubernetes": {
        "kubeconfig": "/etc/cni/net.d/calico-kubeconfig"
      }
    },
    {
      "type": "bandwidth",
      "capabilities": {"bandwidth": true}
    }
  ]
}

现在，你可以将 kubernetes.io/ingress-bandwidth 和 kubernetes.io/egress-bandwidth 注解添加到 Pod 中。例如：

apiVersion: v1
kind: Pod
metadata:
  annotations:
    kubernetes.io/ingress-bandwidth: 1M
    kubernetes.io/egress-bandwidth: 1M
...

接下来

• 进一步了解关于集群网络的信息
• 进一步了解关于网络策略的信息
• 进一步了解关于排查 CNI 插件相关错误的信息

2.2 - 设备插件

Kubernetes 提供了一个设备插件框架，你可以用它来将系统硬件资源发布到 Kubelet。

供应商可以实现设备插件，由你手动部署或作为 DaemonSet 来部署，而不必定制 Kubernetes 本身的代码。目标设备包括 GPU、高性能 NIC、FPGA、 InfiniBand 适配器以及其他类似的、可能需要特定于供应商的初始化和设置的计算资源。

注册设备插件

kubelet 提供了一个 Registration 的 gRPC 服务：

service Registration {
	rpc Register(RegisterRequest) returns (Empty) {}
}

设备插件可以通过此 gRPC 服务在 kubelet 进行注册。在注册期间，设备插件需要发送下面几样内容：

• 设备插件的 Unix 套接字。
• 设备插件的 API 版本。
• ResourceName 是需要公布的。这里 ResourceName 需要遵循扩展资源命名方案， 类似于 vendor-domain/resourcetype。（比如 NVIDIA GPU 就被公布为 nvidia.com/gpu。）

成功注册后，设备插件就向 kubelet 发送它所管理的设备列表，然后 kubelet 负责将这些资源发布到 API 服务器，作为 kubelet 节点状态更新的一部分。

比如，设备插件在 kubelet 中注册了 hardware-vendor.example/foo 并报告了节点上的两个运行状况良好的设备后，节点状态将更新以通告该节点已安装 2 个 "Foo" 设备并且是可用的。

然后，用户可以请求设备作为 Pod 规范的一部分， 参见 Container。 请求扩展资源类似于管理请求和限制的方式， 其他资源，有以下区别：

• 扩展资源仅可作为整数资源使用，并且不能被过量使用
• 设备不能在容器之间共享

示例

假设 Kubernetes 集群正在运行一个设备插件，该插件在一些节点上公布的资源为 hardware-vendor.example/foo。 下面就是一个 Pod 示例，请求此资源以运行一个工作负载的示例：

---
apiVersion: v1
kind: Pod
metadata:
  name: demo-pod
spec:
  containers:
    - name: demo-container-1
      image: registry.k8s.io/pause:2.0
      resources:
        limits:
          hardware-vendor.example/foo: 2
#
# 这个 pod 需要两个 hardware-vendor.example/foo 设备
# 而且只能够调度到满足需求的节点上
#
# 如果该节点中有 2 个以上的设备可用，其余的可供其他 Pod 使用

设备插件的实现

设备插件的常规工作流程包括以下几个步骤：

1. 初始化。在这个阶段，设备插件将执行特定于供应商的初始化和设置，以确保设备处于就绪状态。

2. 插件使用主机路径 /var/lib/kubelet/device-plugins/ 下的 UNIX 套接字启动一个 gRPC 服务，该服务实现以下接口：

   service DevicePlugin {
      // GetDevicePluginOptions 返回与设备管理器沟通的选项。
      rpc GetDevicePluginOptions(Empty) returns (DevicePluginOptions) {}
   
      // ListAndWatch 返回 Device 列表构成的数据流。
      // 当 Device 状态发生变化或者 Device 消失时，ListAndWatch
      // 会返回新的列表。
      rpc ListAndWatch(Empty) returns (stream ListAndWatchResponse) {}
   
      // Allocate 在容器创建期间调用，这样设备插件可以运行一些特定于设备的操作，
      // 并告诉 kubelet 如何令 Device 可在容器中访问的所需执行的具体步骤
      rpc Allocate(AllocateRequest) returns (AllocateResponse) {}
   
      // GetPreferredAllocation 从一组可用的设备中返回一些优选的设备用来分配，
      // 所返回的优选分配结果不一定会是设备管理器的最终分配方案。
      // 此接口的设计仅是为了让设备管理器能够在可能的情况下做出更有意义的决定。
      rpc GetPreferredAllocation(PreferredAllocationRequest) returns (PreferredAllocationResponse) {}
   
      // PreStartContainer 在设备插件注册阶段根据需要被调用，调用发生在容器启动之前。
      // 在将设备提供给容器使用之前，设备插件可以运行一些诸如重置设备之类的特定于
      // 具体设备的操作，
      rpc PreStartContainer(PreStartContainerRequest) returns (PreStartContainerResponse) {}
   }
   

   说明：

   插件并非必须为 GetPreferredAllocation() 或 PreStartContainer() 提供有用的实现逻辑， 调用 GetDevicePluginOptions() 时所返回的 DevicePluginOptions 消息中应该设置一些标志，表明这些调用（如果有）是否可用。kubelet 在直接调用这些函数之前，总会调用 GetDevicePluginOptions() 来查看哪些可选的函数可用。

3. 插件通过位于主机路径 /var/lib/kubelet/device-plugins/kubelet.sock 下的 UNIX 套接字向 kubelet 注册自身。

   说明：

   工作流程的顺序很重要。插件必须在向 kubelet 注册自己之前开始提供 gRPC 服务，才能保证注册成功。

4. 成功注册自身后，设备插件将以提供服务的模式运行，在此期间，它将持续监控设备运行状况， 并在设备状态发生任何变化时向 kubelet 报告。它还负责响应 Allocate gRPC 请求。 在 Allocate 期间，设备插件可能还会做一些特定于设备的准备；例如 GPU 清理或 QRNG 初始化。 如果操作成功，则设备插件将返回 AllocateResponse，其中包含用于访问被分配的设备容器运行时的配置。 kubelet 将此信息传递到容器运行时。

   AllocateResponse 包含零个或多个 ContainerAllocateResponse 对象。 设备插件在这些对象中给出为了访问设备而必须对容器定义所进行的修改。 这些修改包括：

   • 注解
   • 设备节点
   • 环境变量
   • 挂载点
   • 完全限定的 CDI 设备名称
   说明：

   设备管理器处理完全限定的 CDI 设备名称时， 需要为 kubelet 和 kube-apiserver 启用 DevicePluginCDIDevices 特性门控。 这在 Kubernetes v1.28 版本中作为 Alpha 特性被加入。

处理 kubelet 重启

设备插件应能监测到 kubelet 重启，并且向新的 kubelet 实例来重新注册自己。 新的 kubelet 实例启动时会删除 /var/lib/kubelet/device-plugins 下所有已经存在的 Unix 套接字。 设备插件需要能够监控到它的 Unix 套接字被删除，并且当发生此类事件时重新注册自己。

设备插件部署

你可以将你的设备插件作为节点操作系统的软件包来部署、作为 DaemonSet 来部署或者手动部署。

规范目录 /var/lib/kubelet/device-plugins 是需要特权访问的， 所以设备插件必须要在被授权的安全的上下文中运行。 如果你将设备插件部署为 DaemonSet，/var/lib/kubelet/device-plugins 目录必须要在插件的 PodSpec 中声明作为 卷（Volume） 被挂载到插件中。

如果你选择 DaemonSet 方法，你可以通过 Kubernetes 进行以下操作： 将设备插件的 Pod 放置在节点上，在出现故障后重新启动守护进程 Pod，来进行自动升级。

API 兼容性

之前版本控制方案要求设备插件的 API 版本与 Kubelet 的版本完全匹配。 自从此特性在 v1.12 中进阶为 Beta 后，这不再是硬性要求。 API 是版本化的，并且自此特性进阶 Beta 后一直表现稳定。 因此，kubelet 升级应该是无缝的，但在稳定之前 API 仍然可能会有变更，还不能保证升级不会中断。

作为一个项目，Kubernetes 建议设备插件开发者：

• 注意未来版本中设备插件 API 的变更。
• 支持多个版本的设备插件 API，以实现向后/向前兼容性。

若在需要升级到具有较新设备插件 API 版本的某个 Kubernetes 版本的节点上运行这些设备插件， 请在升级这些节点之前先升级设备插件以支持这两个版本。 采用该方法将确保升级期间设备分配的连续运行。

监控设备插件资源

为了监控设备插件提供的资源，监控代理程序需要能够发现节点上正在使用的设备， 并获取元数据来描述哪个指标与容器相关联。 设备监控代理暴露给 Prometheus 的指标应该遵循 Kubernetes Instrumentation Guidelines， 使用 pod、namespace 和 container 标签来标识容器。

kubelet 提供了 gRPC 服务来使得正在使用中的设备被发现，并且还为这些设备提供了元数据：

// PodResourcesLister 是一个由 kubelet 提供的服务，用来提供供节点上
// Pod 和容器使用的节点资源的信息
service PodResourcesLister {
    rpc List(ListPodResourcesRequest) returns (ListPodResourcesResponse) {}
    rpc GetAllocatableResources(AllocatableResourcesRequest) returns (AllocatableResourcesResponse) {}
    rpc Get(GetPodResourcesRequest) returns (GetPodResourcesResponse) {}
}

List gRPC 端点

这一 List 端点提供运行中 Pod 的资源信息，包括类似独占式分配的 CPU ID、设备插件所报告的设备 ID 以及这些设备分配所处的 NUMA 节点 ID。 此外，对于基于 NUMA 的机器，它还会包含为容器保留的内存和大页的信息。

从 Kubernetes v1.27 开始，List 端点可以通过 DynamicResourceAllocation API 提供在 ResourceClaims 中分配的当前运行 Pod 的资源信息。 要启用此特性，必须使用以下标志启动 kubelet：

--feature-gates=DynamicResourceAllocation=true,KubeletPodResourcesDynamicResources=true

// ListPodResourcesResponse 是 List 函数的响应
message ListPodResourcesResponse {
    repeated PodResources pod_resources = 1;
}

// PodResources 包含关于分配给 Pod 的节点资源的信息
message PodResources {
    string name = 1;
    string namespace = 2;
    repeated ContainerResources containers = 3;
}

// ContainerResources 包含分配给容器的资源的信息
message ContainerResources {
    string name = 1;
    repeated ContainerDevices devices = 2;
    repeated int64 cpu_ids = 3;
    repeated ContainerMemory memory = 4;
    repeated DynamicResource dynamic_resources = 5;
}

// ContainerMemory 包含分配给容器的内存和大页信息
message ContainerMemory {
    string memory_type = 1;
    uint64 size = 2;
    TopologyInfo topology = 3;
}

// Topology 描述资源的硬件拓扑结构
message TopologyInfo {
        repeated NUMANode nodes = 1;
}

// NUMA 代表的是 NUMA 节点
message NUMANode {
        int64 ID = 1;
}

// ContainerDevices 包含分配给容器的设备信息
message ContainerDevices {
    string resource_name = 1;
    repeated string device_ids = 2;
    TopologyInfo topology = 3;
}

// DynamicResource 包含通过 Dynamic Resource Allocation 分配到容器的设备信息
message DynamicResource {
    string class_name = 1;
    string claim_name = 2;
    string claim_namespace = 3;
    repeated ClaimResource claim_resources = 4;
}

// ClaimResource 包含每个插件的资源信息
message ClaimResource {
    repeated CDIDevice cdi_devices = 1 [(gogoproto.customname) = "CDIDevices"];
}

// CDIDevice 指定 CDI 设备信息
message CDIDevice {
    // 完全合格的 CDI 设备名称
    // 例如：vendor.com/gpu=gpudevice1
    // 参阅 CDI 规范中的更多细节：
    // https://github.com/container-orchestrated-devices/container-device-interface/blob/main/SPEC.md
    string name = 1;
}

GetAllocatableResources gRPC 端点

端点 GetAllocatableResources 提供工作节点上原始可用的资源信息。 此端点所提供的信息比导出给 API 服务器的信息更丰富。

// AllocatableResourcesResponses 包含 kubelet 所了解到的所有设备的信息
message AllocatableResourcesResponse {
    repeated ContainerDevices devices = 1;
    repeated int64 cpu_ids = 2;
    repeated ContainerMemory memory = 3;
}

ContainerDevices 会向外提供各个设备所隶属的 NUMA 单元这类拓扑信息。 NUMA 单元通过一个整数 ID 来标识，其取值与设备插件所报告的一致。 设备插件注册到 kubelet 时 会报告这类信息。

gRPC 服务通过 /var/lib/kubelet/pod-resources/kubelet.sock 的 UNIX 套接字来提供服务。 设备插件资源的监控代理程序可以部署为守护进程或者 DaemonSet。 规范的路径 /var/lib/kubelet/pod-resources 需要特权来进入， 所以监控代理程序必须要在获得授权的安全的上下文中运行。 如果设备监控代理以 DaemonSet 形式运行，必须要在插件的 PodSpec 中声明将 /var/lib/kubelet/pod-resources 目录以卷的形式被挂载到设备监控代理中。

Get gRPC 端点

Get 端点提供了当前运行 Pod 的资源信息。它会暴露与 List 端点中所述类似的信息。 Get 端点需要当前运行 Pod 的 PodName 和 PodNamespace。

// GetPodResourcesRequest 包含 Pod 相关信息
message GetPodResourcesRequest {
    string pod_name = 1;
    string pod_namespace = 2;
}

要启用此特性，你必须使用以下标志启动 kubelet 服务：

--feature-gates=KubeletPodResourcesGet=true

Get 端点可以提供与动态资源分配 API 所分配的动态资源相关的 Pod 信息。 要启用此特性，你必须确保使用以下标志启动 kubelet 服务：

--feature-gates=KubeletPodResourcesGet=true,DynamicResourceAllocation=true,KubeletPodResourcesDynamicResources=true

设备插件与拓扑管理器的集成

拓扑管理器是 Kubelet 的一个组件，它允许以拓扑对齐方式来调度资源。 为了做到这一点，设备插件 API 进行了扩展来包括一个 TopologyInfo 结构体。

message TopologyInfo {
    repeated NUMANode nodes = 1;
}

message NUMANode {
    int64 ID = 1;
}

设备插件希望拓扑管理器可以将填充的 TopologyInfo 结构体作为设备注册的一部分以及设备 ID 和设备的运行状况发送回去。然后设备管理器将使用此信息来咨询拓扑管理器并做出资源分配决策。

TopologyInfo 支持将 nodes 字段设置为 nil 或一个 NUMA 节点的列表。 这样就可以使设备插件通告跨越多个 NUMA 节点的设备。

将 TopologyInfo 设置为 nil 或为给定设备提供一个空的 NUMA 节点列表表示设备插件没有该设备的 NUMA 亲和偏好。

下面是一个由设备插件为设备填充 TopologyInfo 结构体的示例：

pluginapi.Device{ID: "25102017", Health: pluginapi.Healthy, Topology:&pluginapi.TopologyInfo{Nodes: []*pluginapi.NUMANode{&pluginapi.NUMANode{ID: 0,},}}}

设备插件示例

下面是一些设备插件实现的示例：

• AMD GPU 设备插件
• 适用于通用 Linux 设备和 USB 设备的通用设备插件
• Intel 设备插件支持 Intel GPU、FPGA、QAT、VPU、SGX、DSA、DLB 和 IAA 设备
• KubeVirt 设备插件 用于硬件辅助的虚拟化
• 为 Container-Optimized OS 所提供的 NVIDIA GPU 设备插件
• RDMA 设备插件
• SocketCAN 设备插件
• Solarflare 设备插件
• SR-IOV 网络设备插件
• Xilinx FPGA 设备插件

接下来

• 查看调度 GPU 资源来学习使用设备插件
• 查看在节点上如何公布扩展资源
• 学习拓扑管理器
• 阅读如何在 Kubernetes 中使用 TLS Ingress 的硬件加速

3 - 扩展 Kubernetes API

3.1 - 定制资源

定制资源（Custom Resource） 是对 Kubernetes API 的扩展。 本页讨论何时向 Kubernetes 集群添加定制资源，何时使用独立的服务。 本页描述添加定制资源的两种方法以及怎样在二者之间做出抉择。

定制资源

资源（Resource） 是 Kubernetes API 中的一个端点， 其中存储的是某个类别的 API 对象的一个集合。 例如内置的 Pod 资源包含一组 Pod 对象。

定制资源（Custom Resource） 是对 Kubernetes API 的扩展，不一定在默认的 Kubernetes 安装中就可用。定制资源所代表的是对特定 Kubernetes 安装的一种定制。 不过，很多 Kubernetes 核心功能现在都用定制资源来实现，这使得 Kubernetes 更加模块化。

定制资源可以通过动态注册的方式在运行中的集群内或出现或消失，集群管理员可以独立于集群更新定制资源。 一旦某定制资源被安装，用户可以使用 kubectl 来创建和访问其中的对象，就像他们为 Pod 这种内置资源所做的一样。

定制控制器

就定制资源本身而言，它只能用来存取结构化的数据。 当你将定制资源与定制控制器（Custom Controller） 结合时， 定制资源就能够提供真正的声明式 API（Declarative API）。

Kubernetes 声明式 API 强制对职权做了一次分离操作。 你声明所用资源的期望状态，而 Kubernetes 控制器使 Kubernetes 对象的当前状态与你所声明的期望状态保持同步。 声明式 API 的这种机制与命令式 API（你指示服务器要做什么，服务器就去做什么）形成鲜明对比。

你可以在一个运行中的集群上部署和更新定制控制器，这类操作与集群的生命周期无关。 定制控制器可以用于任何类别的资源，不过它们与定制资源结合起来时最为有效。 Operator 模式就是将定制资源与定制控制器相结合的。 你可以使用定制控制器来将特定于某应用的领域知识组织起来，以编码的形式构造对 Kubernetes API 的扩展。

我是否应该向我的 Kubernetes 集群添加定制资源？

在创建新的 API 时， 请考虑是将你的 API 与 Kubernetes 集群 API 聚合起来， 还是让你的 API 独立运行。

声明式 API

典型地，在声明式 API 中：

• 你的 API 包含相对而言为数不多的、尺寸较小的对象（资源）。
• 对象定义了应用或者基础设施的配置信息。
• 对象更新操作频率较低。
• 通常需要人来读取或写入对象。
• 对象的主要操作是 CRUD 风格的（创建、读取、更新和删除）。
• 不需要跨对象的事务支持：API 对象代表的是期望状态而非确切实际状态。

命令式 API（Imperative API）与声明式有所不同。 以下迹象表明你的 API 可能不是声明式的：

• 客户端发出“做这个操作”的指令，之后在该操作结束时获得同步响应。
• 客户端发出“做这个操作”的指令，并获得一个操作 ID，之后需要检查一个 Operation（操作） 对象来判断请求是否成功完成。
• 你会将你的 API 类比为远程过程调用（Remote Procedure Call，RPC）。
• 直接存储大量数据；例如每个对象几 kB，或者存储上千个对象。
• 需要较高的访问带宽（长期保持每秒数十个请求）。
• 存储有应用来处理的最终用户数据（如图片、个人标识信息（PII）等）或者其他大规模数据。
• 在对象上执行的常规操作并非 CRUD 风格。
• API 不太容易用对象来建模。
• 你决定使用操作 ID 或者操作对象来表现悬决的操作。

我应该使用一个 ConfigMap 还是一个定制资源？

如果满足以下条件之一，应该使用 ConfigMap：

• 存在一个已有的、文档完备的配置文件格式约定，例如 mysql.cnf 或 pom.xml。
• 你希望将整个配置文件放到某 configMap 中的一个主键下面。
• 配置文件的主要用途是针对运行在集群中 Pod 内的程序，供后者依据文件数据配置自身行为。
• 文件的使用者期望以 Pod 内文件或者 Pod 内环境变量的形式来使用文件数据， 而不是通过 Kubernetes API。
• 你希望当文件被更新时通过类似 Deployment 之类的资源完成滚动更新操作。

如果以下条件中大多数都被满足，你应该使用定制资源（CRD 或者 聚合 API）：

• 你希望使用 Kubernetes 客户端库和 CLI 来创建和更改新的资源。
• 你希望 kubectl 能够直接支持你的资源；例如，kubectl get my-object object-name。
• 你希望构造新的自动化机制，监测新对象上的更新事件，并对其他对象执行 CRUD 操作，或者监测后者更新前者。
• 你希望编写自动化组件来处理对对象的更新。
• 你希望使用 Kubernetes API 对诸如 .spec、.status 和 .metadata 等字段的约定。
• 你希望对象是对一组受控资源的抽象，或者对其他资源的归纳提炼。

添加定制资源

Kubernetes 提供了两种方式供你向集群中添加定制资源：

• CRD 相对简单，创建 CRD 可以不必编程。
• API 聚合需要编程， 但支持对 API 行为进行更多的控制，例如数据如何存储以及在不同 API 版本间如何转换等。

Kubernetes 提供这两种选项以满足不同用户的需求，这样就既不会牺牲易用性也不会牺牲灵活性。

聚合 API 指的是一些下位的 API 服务器，运行在主 API 服务器后面；主 API 服务器以代理的方式工作。这种组织形式称作 API 聚合（API Aggregation，AA） 。 对用户而言，看起来仅仅是 Kubernetes API 被扩展了。

CRD 允许用户创建新的资源类别同时又不必添加新的 API 服务器。 使用 CRD 时，你并不需要理解 API 聚合。

无论以哪种方式安装定制资源，新的资源都会被当做定制资源，以便与内置的 Kubernetes 资源（如 Pods）相区分。

CustomResourceDefinitions

CustomResourceDefinition API 资源允许你定义定制资源。 定义 CRD 对象的操作会使用你所设定的名字和模式定义（Schema）创建一个新的定制资源， Kubernetes API 负责为你的定制资源提供存储和访问服务。 CRD 对象的名称必须是合法的 DNS 子域名。

CRD 使得你不必编写自己的 API 服务器来处理定制资源，不过其背后实现的通用性也意味着你所获得的灵活性要比 API 服务器聚合少很多。

关于如何注册新的定制资源、使用新资源类别的实例以及如何使用控制器来处理事件， 相关的例子可参见定制控制器示例。

API 服务器聚合

通常，Kubernetes API 中的每个资源都需要处理 REST 请求和管理对象持久性存储的代码。 Kubernetes API 主服务器能够处理诸如 Pod 和 Service 这些内置资源， 也可以按通用的方式通过 CRD 来处理定制资源。

聚合层（Aggregation Layer） 使得你可以通过编写和部署你自己的 API 服务器来为定制资源提供特殊的实现。 主 API 服务器将针对你要处理的定制资源的请求全部委托给你自己的 API 服务器来处理， 同时将这些资源提供给其所有客户端。

选择添加定制资源的方法

CRD 更为易用；聚合 API 则更为灵活。请选择最符合你的需要的方法。

通常，如何存在以下情况，CRD 可能更合适：

• 定制资源的字段不多；
• 你在组织内部使用该资源或者在一个小规模的开源项目中使用该资源，而不是在商业产品中使用。

比较易用性

CRD 比聚合 API 更容易创建。

高级特性与灵活性

聚合 API 可提供更多的高级 API 特性，也可对其他特性实行定制；例如，对存储层进行定制。

公共特性

与在 Kubernetes 平台之外实现定制资源相比， 无论是通过 CRD 还是通过聚合 API 来创建定制资源，你都会获得很多 API 特性：

准备安装定制资源

在向你的集群添加定制资源之前，有些事情需要搞清楚。

第三方代码和新的失效点的问题

尽管添加新的 CRD 不会自动带来新的失效点（Point of Failure），例如导致第三方代码被在 API 服务器上运行， 类似 Helm Charts 这种软件包或者其他安装包通常在提供 CRD 的同时还包含带有第三方代码的 Deployment，负责实现新的定制资源的业务逻辑。

安装聚合 API 服务器时，也总会牵涉到运行一个新的 Deployment。

存储

定制资源和 ConfigMap 一样也会消耗存储空间。创建过多的定制资源可能会导致 API 服务器上的存储空间超载。

聚合 API 服务器可以使用主 API 服务器相同的存储。如果是这样，你也要注意此警告。

身份认证、鉴权授权以及审计

CRD 通常与 API 服务器上的内置资源一样使用相同的身份认证、鉴权授权和审计日志机制。

如果你使用 RBAC 来执行鉴权授权，大多数 RBAC 角色都不会授权对新资源的访问 （除了 cluster-admin 角色以及使用通配符规则创建的其他角色）。 你要显式地为新资源的访问授权。CRD 和聚合 API 通常在交付时会包含针对所添加的类别的新的角色定义。

聚合 API 服务器可能会使用主 API 服务器相同的身份认证、鉴权授权和审计机制，也可能不会。

访问定制资源

Kubernetes 客户端库可用来访问定制资源。 并非所有客户端库都支持定制资源。Go 和 Python 客户端库是支持的。

当你添加了新的定制资源后，可以用如下方式之一访问它们：

• kubectl
• Kubernetes 动态客户端
• 你所编写的 REST 客户端
• 使用 Kubernetes 客户端生成工具所生成的客户端。 生成客户端的工作有些难度，不过某些项目可能会随着 CRD 或聚合 API 一起提供一个客户端。

接下来

• 了解如何使用聚合层扩展 Kubernetes API
• 了解如何使用 CustomResourceDefinition 来扩展 Kubernetes API

3.2 - Kubernetes API 聚合层

使用聚合层（Aggregation Layer），用户可以通过附加的 API 扩展 Kubernetes， 而不局限于 Kubernetes 核心 API 提供的功能。 这里的附加 API 可以是现成的解决方案，比如 metrics server， 或者你自己开发的 API。

聚合层不同于 定制资源（Custom Resources）。 后者的目的是让 kube-apiserver 能够识别新的对象类别（Kind）。

聚合层

聚合层在 kube-apiserver 进程内运行。在扩展资源注册之前，聚合层不做任何事情。 要注册 API，你可以添加一个 APIService 对象，用它来 “申领” Kubernetes API 中的 URL 路径。 自此以后，聚合层将把发给该 API 路径的所有内容（例如 /apis/myextension.mycompany.io/v1/…） 转发到已注册的 APIService。

APIService 的最常见实现方式是在集群中某 Pod 内运行扩展 API 服务器（Extension API Server）。 如果你在使用扩展 API 服务器来管理集群中的资源，该扩展 API 服务器（也被写成 "extension-apiserver"） 一般需要和一个或多个控制器一起使用。 apiserver-builder 库同时提供构造扩展 API 服务器和控制器框架代码。

响应延迟

扩展 API 服务器（Extension API Server）与 kube-apiserver 之间需要存在低延迟的网络连接。 发现请求需要在五秒钟或更短的时间内完成到 kube-apiserver 的往返。

如果你的扩展 API 服务器无法满足这一延迟要求，应考虑如何更改配置以满足需要。

接下来

• 阅读配置聚合层文档， 了解如何在自己的环境中启用聚合器。
• 接下来，了解安装扩展 API 服务器， 开始使用聚合层。
• 从 API 参考资料中研究关于 APIService 的内容。

或者，学习如何使用 CustomResourceDefinition 扩展 Kubernetes API。