客户端

• 1: client-go
• 1.1: client-go介绍
• 1.1.1: client-go介绍
• 2: controller-runtime
• 2.1: controller-runtime介绍
• 2.2: controller-runtime package概况
• 2.3: 使用builder的基础controller
• 2.4: controller-runtime设计
• 2.4.1: 缓存选项
• 3: operator
• 4: kubebuilder
• 5: Kubernetes Programming with go学习笔记
• 5.1: [第一章]Kubernetes API介绍
• 5.1.1: Kubernetes 平台一览
• 5.1.2: openapi规范
• 5.1.3: Group-Version-Resource
• 5.1.4: Verbs 和 Kinds
• 5.1.5: 子资源
• 5.1.6: 官方API参考文档
• 5.2: [第二章]Kubernetes API操作
• 5.3: [第三章]在Go中使用API资源
• 5.4: [第4章]使用通用类型
• 5.5: [第5章]API Machinery
• 5.6: [第6章]client-go类库
• 5.7: [第7章]测试使用Client-go的应用程序
• 5.8: [第8章]用自定义资源定义扩展Kubernetes API
• 5.9: [第9章]使用自定义资源
• 5.10: [第10章]用Controller-Runtime库编写Operator
• 5.10.1: controller-runtime简介
• 5.10.2: Manager
• 5.10.3: Controller
• 5.10.4: 将管理器资源注入 Reconciler 中
• 5.10.5: 使用客户端
• 5.10.6: 日志
• 5.10.7: 事件
• 5.11: [第11章]编写 Reconcile 循环
• 5.12: [第12章]测试 Reconcile 循环
• 5.13: [第13章]使用 kubebuilder 创建 Operator
• 6: Programming Kubernetes with go

1 - client-go

1.1 - client-go介绍

1.1.1 - client-go介绍

client-go是一个调用kubernetes集群资源对象API的客户端，即通过client-go实现对kubernetes集群中资源对象（包括deployment、service、ingress、replicaSet、pod、namespace、node等）的增删改查等操作。大部分对kubernetes进行前置API封装的二次开发都通过client-go这个第三方包来实现。

2 - controller-runtime

kubernetes-sigs/controller-runtime: Repo for the controller-runtime subproject of kubebuilder (sig-apimachinery) (github.com)

2.1 - controller-runtime介绍

Kubernetes controller-runtime 项目是一套用于构建 controller 控制器的 Go 库。它被 Kubebuilder 和 operator SDK 所使用。对于新项目来说，这两个项目都是一个很好的起点。

2.2 - controller-runtime package概况

https://pkg.go.dev/sigs.k8s.io/controller-runtime/pkg

pkg 包提供了用于构建 controller 控制器的库。控制器实现了 Kubernetes API，是构建 operator、workload API、配置API、自动缩放器等的基础。

client

客户端为读写Kubernetes对象提供了一个 读+写 的客户端。

cache

缓存提供了一个读客户端，用于从本地缓存中读取对象。缓存可以注册 handler 来响应更新缓存的事件。

manager

Manager是创建 controller 控制器的必要条件，并提供 controller 的共享依赖关系，如客户端、缓存、scheme 等。 controller 应该通过 manager 调用 Manager.Start 来启动。

Controller

Controller 通过响应事件（对象创建、更新、删除）来实现 Kubernetes API，并确保对象的 Spec 中指定的状态与系统的状态相匹配。这被称为 reconcile（调和）。如果它们不匹配，Controller 将根据需要创建/更新/删除对象，使它们匹配。

Controller 被实现为处理 reconcile.Requests（为特定对象 reconcile 状态的请求）的工作队列。

与 http handler 不同的是，Controller 不直接处理事件，而是将 Requests 入列来最终 reconcile 对象。这意味着多个事件的处理可能会被批量进行，而且每次 reconcile 都必须读取系统的全部状态。

• Controller 需要提供一个 Reconciler 来执行从工作队列中拉出的工作。

• Controller 需要配置 Watches，以便将 reconcile.Requests 入列并对事件进行响应。

Webhook

Admission Webhooks 是一种扩展 kubernetes APIs 的机制。Webhooks 可以配置目标事件类型（对象创建、更新、删除），API 服务器将在某些事件发生时向它们发送 AdmissionRequests。Webhooks 可以修改和（或）验证嵌入在 AdmissionReview 请求中的对象，并将响应发回给 API 服务器。

有2种类型的 Admission Webhooks ：修改（mutating）和验证（validating）的 Admission Webhooks 。修改的 webhook 是用来在 API 服务器接纳之前修改 core API 对象或 CRD 实例。验证 webhook 用于验证对象是否符合某些要求。

• Admission Webhooks 需要提供 Handler（s）来处理收到的 AdmissionReview 请求。

Reconciler

Reconciler 是提供给 Controller 的一个函数，可以在任何时候用对象的名称和命名空间来调用。当被调用时，Reconciler 将确保系统的状态与 Reconciler 被调用时在对象中指定的内容相匹配。

例子： 为一个 ReplicaSet 对象调用 Reconciler。ReplicaSet 指定了5个副本，但系统中只存在 3 个 Pod。Reconciler 又创建了2个Pod，并将其 OwnerReference 设置为指向 ReplicaSet，并设置 controller=true。

• Reconciler 包含 Controller 的所有业务逻辑。

• Reconciler 通常只对单一对象类型工作。- 例如，它将只对 ReplicaSets 进行调节。对于单独的类型，使用单独的 Controller。如果你想从其他对象触发 reconcile，你可以提供一个映射（例如所有者引用/owner references），将触发 reconcile 的对象映射到被 reconcile 的对象。

• Reconciler 被提供给要 reconcile 的对象的名称/命名空间。

• Reconciler 不关心负责触发 Reconcile 的事件内容或事件类型。例如，ReplicaSet 是否被创建或更新并不重要，Reconciler 总是将系统中的 Pod 数量与它被调用时在对象中指定的数量进行比较。

Source

resource.Source 是 Controller.Watch 的参数，提供了事件流。事件通常来自于 watch Kubernetes APIs（例如：Pod Create, Update, Delete）。

例如：source.Kind 使用 Kubernetes API Watch 端点，为 GroupVersionKind 提供创建、更新、删除事件。

• Source 通常通过 Watch API 为 Kubernetes 对象提供事件流（如对象创建、更新、删除）。

• 在几乎所有情况下，用户都应该只使用所提供的 Source 实现，而不是实现自己的。

EventHandler

handler.EventHandler 是 Controller.Watch 的参数，它在响应事件时入队 reconcile.Requests。

例如：一个来自 Source 的 Pod 创建事件被提供给 eventhandler.EnqueueHandler，它入队包含 Pod 的名称/命名空间的reconcile.Request。

• EventHandlers 通过入队 reconcile.Requests 来为一个或多个对象处理事件。

• EventHandlers 可以将一个对象的事件映射到同一类型的另一个对象的 reconcile.Request 上。

• EventHandlers 可以将一个对象的事件映射到不同类型的另一个对象的 reconcile.Request 。例如，将 Pod 事件映射到拥有它的 ReplicaSet 的 reconcile.Request 上。

• EventHandlers 可以将一个对象的事件映射到相同或不同类型的对象的多个 reconcile.Request 。例如，将一个 Node 事件映射到响应集群大小事件的对象上。

• 在几乎所有情况下，用户都应该只使用所提供的 EventHandler 实现，而不是实现自己的。

Predicate

predicate.Predicate 是 Controller.Watch 的一个可选的参数，用于过滤事件。这使得常见的过滤器可以被重复使用和组合。

• Predicate 接收一个事件，并返回bool（ true为enqueue ）。

• Predicate 是可选的参数

• 用户应该使用所提供的 Predicate 实现，但可以实现额外的 Predicate，例如：generation 改变，标签选择器改变等。

PodController 图例

Source 提供事件：

• &source.KindSource{&v1.Pod{}} -> (Pod foo/bar Create Event)

EventHandlers 入队请求：

• &handler.EnqueueRequestForObject{} -> (reconcile.Request{types.NamespaceName{Name: "foo", Namespace: "bar"}})

Reconciler 被调用，携带参数Request：

• Reconciler(reconcile.Request{types.NamespaceName{Name: "foo", Namespace: "bar"}})

用法

下面的例子显示了创建一个新的 Controller 程序，该程序响应 Pod 或 ReplicaSet 事件，对 ReplicaSet 对象进行 Reconcile。Reconciler 函数只是给 ReplicaSet 添加一个标签。

参见 examples/builtins/main.go 中的使用实例。

Controller 实例：

• 1. Watch ReplicaSet 和 Pods Source

  • 1.1 ReplicaSet -> handler.EnqueueRequestForObject – 用 ReplicaSet 的命名空间和名称来入队请求。

  • 1.2 Pod (由 ReplicaSet 创建) -> handler.EnqueueRequestForOwnerHandler –以拥有的 ReplicaSet 命名空间和名称来入队Request。

• 2. 响应事件，对 ReplicaSet 进行 Reconcile

  • 2.1 创建 ReplicaSet 对象 -> 读取 ReplicaSet，尝试读取 Pods -> 如果空缺就创建 Pods。

  • 2.2 创建 Pods 锁触发的 Reconciler -> 读取 ReplicaSet 和 Pods，什么都不做。

  • 2.3 从其他角色中刪除Pods而触发Reconciler -> 读取 ReplicaSet 和 Pods，创建替代Pods。

监视和事件处理

Controller 可以观察多种类型的对象（如Pods、ReplicaSets和 deployment），但他们只 reconcile 一个类型。当一种类型的对象必须更新以响应另一种类型的对象的变化时，EnqueueRequestsFromMapFunc 可用于将事件从一种类型映射到另一种类型。例如，通过重新 reconcile 某些API的所有实例来响应集群大小调整事件（添加/删除节点）。

Deployment Controller 可能使用 EnqueueRequestForObject 和 EnqueueRequestForOwner 来：

• 观察 Deployment 事件–入队 Deployment 的命名空间和名称。

• 观察 ReplicaSet 事件– 入队创建 ReplicaSet 的 Deployment 的命名空间和名称（例如，所有者/Owner）。

注意：reconcile.Requests 在入队的时候会被去重。同一个 ReplicaSet 的许多 Pod 事件可能只触发1个 reconcile 调用，因为每个事件都会导致 handler 试图为 ReplicaSet 入队相同的 reconcile.Request。

Controller的编写技巧

Reconciler 运行时的复杂性：

• 最好是编写 Controllers 来执行N次O(1) reconcile（例如对N个不同的对象），而不是执行1次O(N) reconcile（例如对一个管理着N个其他对象的单一对象）。

• 例子： 如果你需要更新所有服务以响应一个节点的添加– reconcile 服务但观察节点（转变为服务对象的名称/命名空间），而不是 reconcile 节点并更新服务。

事件复用：

• 对同一名称/命名空间的 reconcile 请求在入队时被批量和去重处理。这使 Controller 能够优雅地处理单个对象的大量事件。将多个事件源复用到一个对象类型上，将对不同对象类型的事件进行批量请求。

• 例如： ReplicaSet 的 Pod 事件被转换为 ReplicaSet 名称/命名空间，因此 ReplicaSet 将只对来自多个 Pod 的多个事件进行1次Reconciled。

目录

2.3 - 使用builder的基础controller

https://pkg.go.dev/sigs.k8s.io/controller-runtime/pkg/builder#example-Builder

概述

Package builder包装了其他的控制器运行时库，并展示了构建普通控制器的简单模式。

如果项目在未来需要更多的自定义行为，使用builder包构建的项目可以在底层包的基础上进行简单的重构。

例子

这个例子创建了一个简单的应用程序 ControllerManagedBy，为ReplicaSets 和 Pod 进行了配置。

• 为ReplicaSets创建一个新的应用程序，管理 ReplicaSet 所拥有的 Pod，并调用到 ReplicaSetReconciler。

• 启动应用程序。

package main

import (
	"context"
	"fmt"
	"os"

	appsv1 "k8s.io/api/apps/v1"
	corev1 "k8s.io/api/core/v1"

	"sigs.k8s.io/controller-runtime/pkg/builder"
	"sigs.k8s.io/controller-runtime/pkg/client"
	"sigs.k8s.io/controller-runtime/pkg/client/config"

	logf "sigs.k8s.io/controller-runtime/pkg/log"
	"sigs.k8s.io/controller-runtime/pkg/log/zap"
	"sigs.k8s.io/controller-runtime/pkg/manager"
	"sigs.k8s.io/controller-runtime/pkg/manager/signals"
	"sigs.k8s.io/controller-runtime/pkg/reconcile"
)

func main() {
	logf.SetLogger(zap.New())

	var log = logf.Log.WithName("builder-examples")

	mgr, err := manager.New(config.GetConfigOrDie(), manager.Options{})
	if err != nil {
		log.Error(err, "could not create manager")
		os.Exit(1)
	}

	err = builder.
		ControllerManagedBy(mgr).  // Create the ControllerManagedBy
		For(&appsv1.ReplicaSet{}). // ReplicaSet is the Application API
		Owns(&corev1.Pod{}).       // ReplicaSet owns Pods created by it
		Complete(&ReplicaSetReconciler{
			Client: mgr.GetClient(),
		})
	if err != nil {
		log.Error(err, "could not create controller")
		os.Exit(1)
	}

	if err := mgr.Start(signals.SetupSignalHandler()); err != nil {
		log.Error(err, "could not start manager")
		os.Exit(1)
	}
}

// ReplicaSetReconciler is a simple ControllerManagedBy example implementation.
type ReplicaSetReconciler struct {
	client.Client
}

// Implement the business logic:
// This function will be called when there is a change to a ReplicaSet or a Pod with an OwnerReference
// to a ReplicaSet.
//
// * Read the ReplicaSet
// * Read the Pods
// * Set a Label on the ReplicaSet with the Pod count.
func (a *ReplicaSetReconciler) Reconcile(ctx context.Context, req reconcile.Request) (reconcile.Result, error) {

	rs := &appsv1.ReplicaSet{}
	err := a.Get(ctx, req.NamespacedName, rs)
	if err != nil {
		return reconcile.Result{}, err
	}

	pods := &corev1.PodList{}
	err = a.List(ctx, pods, client.InNamespace(req.Namespace), client.MatchingLabels(rs.Spec.Template.Labels))
	if err != nil {
		return reconcile.Result{}, err
	}

	rs.Labels["pod-count"] = fmt.Sprintf("%v", len(pods.Items))
	err = a.Update(ctx, rs)
	if err != nil {
		return reconcile.Result{}, err
	}

	return reconcile.Result{}, nil
}

仅有

package main

import (
	"context"
	"fmt"
	"os"

	appsv1 "k8s.io/api/apps/v1"
	corev1 "k8s.io/api/core/v1"

	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"

	"sigs.k8s.io/controller-runtime/pkg/builder"
	"sigs.k8s.io/controller-runtime/pkg/client"
	"sigs.k8s.io/controller-runtime/pkg/client/config"

	logf "sigs.k8s.io/controller-runtime/pkg/log"
	"sigs.k8s.io/controller-runtime/pkg/log/zap"
	"sigs.k8s.io/controller-runtime/pkg/manager"
	"sigs.k8s.io/controller-runtime/pkg/manager/signals"
	"sigs.k8s.io/controller-runtime/pkg/reconcile"
)

func main() {
	logf.SetLogger(zap.New())

	var log = logf.Log.WithName("builder-examples")

	mgr, err := manager.New(config.GetConfigOrDie(), manager.Options{})
	if err != nil {
		log.Error(err, "could not create manager")
		os.Exit(1)
	}

	cl := mgr.GetClient()
	err = builder.
		ControllerManagedBy(mgr).                  // Create the ControllerManagedBy
		For(&appsv1.ReplicaSet{}).                 // ReplicaSet is the Application API
		Owns(&corev1.Pod{}, builder.OnlyMetadata). // ReplicaSet owns Pods created by it, and caches them as metadata only
		Complete(reconcile.Func(func(ctx context.Context, req reconcile.Request) (reconcile.Result, error) {
			// Read the ReplicaSet
			rs := &appsv1.ReplicaSet{}
			err := cl.Get(ctx, req.NamespacedName, rs)
			if err != nil {
				return reconcile.Result{}, client.IgnoreNotFound(err)
			}

			// List the Pods matching the PodTemplate Labels, but only their metadata
			var podsMeta metav1.PartialObjectMetadataList
			err = cl.List(ctx, &podsMeta, client.InNamespace(req.Namespace), client.MatchingLabels(rs.Spec.Template.Labels))
			if err != nil {
				return reconcile.Result{}, client.IgnoreNotFound(err)
			}

			// Update the ReplicaSet
			rs.Labels["pod-count"] = fmt.Sprintf("%v", len(podsMeta.Items))
			err = cl.Update(ctx, rs)
			if err != nil {
				return reconcile.Result{}, err
			}

			return reconcile.Result{}, nil
		}))
	if err != nil {
		log.Error(err, "could not create controller")
		os.Exit(1)
	}

	if err := mgr.Start(signals.SetupSignalHandler()); err != nil {
		log.Error(err, "could not start manager")
		os.Exit(1)
	}
}

2.4 - controller-runtime设计

https://github.com/kubernetes-sigs/controller-runtime/tree/main/designs

这些是对 Controller Runtime 进行修改的设计文件。它们的存在是为了帮助记录编写 Controller Runtime 的设计过程，但可能不是最新的（更多内容见下文）。

并非所有对 Controller Runtime 的修改都需要设计文档–只有重大的修改才需要。使用你的最佳判断。

当提交设计文件时，我们鼓励你写概念验证，而且完全可以在提交设计文件的同时提交概念验证PR，因为概念验证过程可以帮助消除困惑，并且可以帮助模板中的示例部分。

过时的设计

Controller Runtime 文档 GoDoc 应该被认为是 Controller Runtime 的经典的、最新的参考和架构文档。

然而，如果你看到一个过时的设计文档，请随时提交一个PR，将其标记为这样，并添加一个链接到问题的附录，记录事情的变化原因。比如说：

2.4.1 - 缓存选项

https://github.com/kubernetes-sigs/controller-runtime/blob/main/designs/cache_options.md

这份文件描述了我们对未来缓存选项的设想。

目标

• 使每个人对我们想要支持的缓存的设置及其配置保持一致
• 确保我们既支持复杂的缓存设置，又提供一个直观的配置用户体验。

非目标

• 描述缓存本身的设计和实现。我们的假设是，最细的级别是 “每个对象的多命名空间和不同的选择器”/“per-object multiple namespaces with distinct selectors”，这可以通过一个 “元缓存”/“meta cache” 来实现，这个 “元缓存” 委托给每个对象，并通过扩展当前的多命名空间缓存。
• 概述这些设置何时实施的时间表。只要有人站出来做实际的工作，实施就会逐渐发生。

提案

const (
   AllNamespaces = corev1.NamespaceAll
)

type Config struct {
  // LabelSelector 指定标签选择器。nil值允许默认。
  LabelSelector labels.Selector

  // FieldSelector 指定字段选择器。nil值允许默认。
  FieldSelector fields.Selector

  // Transform 指定转换函数。nil值允许默认。
  Transform     toolscache.TransformFunc

  // UnsafeDisableDeepCopy 指定针对缓存的List和Get请求是否不需要DeepCopy。nil值允许默认。
  UnsafeDisableDeepCopy *bool
}


type ByObject struct {
  // Namespaces 将命名空间名称映射到缓存设置。如果设置，只有该映射中的命名空间将被缓存。
  // 
  // 映射值中的设置如果因为整体值为零或具体设置为零而未设置，将被默认。为防止这种情况，请为特定的设置使用一个空值。
  // 
  // 可以通过使用 AllNamespaces 常量作为映射键，为某些命名空间设置特定的Config，但缓存所有命名空间。这将包括所有没有特定设置的名字空间。
  // 
  // nil的映射允许将其默认为缓存的DefaultNamespaces设置。
  //
  // 空的映射可以防止这种情况。
  //
  // 对于集群范围内的对象必须取消设置。
  Namespaces map[string]*Config

  // Config will be used for cluster-scoped objects and to default
  // Config in the Namespaces field.
  //
  // It gets defaulted from the cache'sDefaultLabelSelector, DefaultFieldSelector,
  // DefaultUnsafeDisableDeepCopy and DefaultTransform.
  Config *Config
}

type Options struct {
  // ByObject specifies per-object cache settings. If unset for a given
  // object, this will fall through to Default* settings.
  ByObject map[client.Object]*ByObject

  // DefaultNamespaces maps namespace names to cache settings. If set, it
  // will be used for all objects that have a nil Namespaces setting.
  //
  // It is possible to have a specific Config for just some namespaces
  // but cache all namespaces by using the `AllNamespaces` const as the map
  // key. This wil then include all namespaces that do not have a more
  // specific setting.
  //
  // The options in the Config that are nil will be defaulted from
  // the respective Default* settings.
  DefaultNamespaces map[string]*Config

  // DefaultLabelSelector is the label selector that will be used as
  // the default field label selector for everything that doesn't
  // have one configured.
  DefaultLabelSelector labels.Selector

  // DefaultFieldSelector is the field selector that will be used as
  // the default field selector for everything that doesn't have
  // one configured.
  DefaultFieldSelector fields.Selector

  // DefaultUnsafeDisableDeepCopy is the default for UnsafeDisableDeepCopy
  // for everything that doesn't specify this.
  DefaultUnsafeDisableDeepCopy *bool

  // DefaultTransform will be used as transform for all object types
  // unless they have a more specific transform set in ByObject.
  DefaultTransform toolscache.TransformFunc

  // HTTPClient is the http client to use for the REST client
  HTTPClient *http.Client

  // Scheme is the scheme to use for mapping objects to GroupVersionKinds
  Scheme *runtime.Scheme

  // Mapper is the RESTMapper to use for mapping GroupVersionKinds to Resources
  Mapper meta.RESTMapper

  // SyncPeriod determines the minimum frequency at which watched resources are
  // reconciled. A lower period will correct entropy more quickly, but reduce
  // responsiveness to change if there are many watched resources. Change this
  // value only if you know what you are doing. Defaults to 10 hours if unset.
  // there will a 10 percent jitter between the SyncPeriod of all controllers
  // so that all controllers will not send list requests simultaneously.
  //
  // This applies to all controllers.
  //
  // A period sync happens for two reasons:
  // 1. To insure against a bug in the controller that causes an object to not
  // be requeued, when it otherwise should be requeued.
  // 2. To insure against an unknown bug in controller-runtime, or its dependencies,
  // that causes an object to not be requeued, when it otherwise should be
  // requeued, or to be removed from the queue, when it otherwise should not
  // be removed.
  //
  // If you want
  // 1. to insure against missed watch events, or
  // 2. to poll services that cannot be watched,
  // then we recommend that, instead of changing the default period, the
  // controller requeue, with a constant duration `t`, whenever the controller
  // is "done" with an object, and would otherwise not requeue it, i.e., we
  // recommend the `Reconcile` function return `reconcile.Result{RequeueAfter: t}`,
  // instead of `reconcile.Result{}`.
  SyncPeriod *time.Duration

}

3 - operator

https://github.com/operator-framework/operator-sdk

4 - kubebuilder

Introduction - The Kubebuilder Book

5 - Kubernetes Programming with go学习笔记

https://learning.oreilly.com/library/view/kubernetes-programming-with/9781484290262/

本书首先介绍了Kubernetes API的结构以及它为哪些运维服务。接下来的章节展示了如何使用API和API库中定义的Go结构编写本地Kubernetes资源定义。还介绍了各种实用工具，以帮助您处理不同的资源字段，并将您的资源定义转换为YAML或JSON。接下来，你将学习如何与Kubernetes API服务器互动，使用client-go库创建、删除、更新和监控集群中的资源。有一整章专门介绍了为使用 client-go库 测试你的程序而提供的工具。接下来有一个例子来总结本书的第一部分，描述了如何编写一个kubectl插件。接下来，你将学习如何使用自定义资源定义扩展Kubernetes API，以及如何以通用方式编写Kubernetes资源，以及如何使用非结构化概念创建自己的资源。接下来的章节将深入研究 controller-runtime 库，它对通过编写 operator 来扩展Kubernetes非常有用，以及利用该库的 kubebuilder 框架，帮助你在几分钟内开始编写 operator。

读完本书后，你将深入了解Kubernetes API的结构以及Kubernetes资源在其中的组织方式，并拥有一个完整的工具箱来帮助你编写Kubernetes客户端和 operator 程序。

你将学到什么

• 了解Kubernetes API及其资源是如何组织的
• 用Go编写Kubernetes资源
• 在集群中创建资源
• 利用你新获得的知识来编写Kubernetes客户端和 operator 程序

5.1 - [第一章]Kubernetes API介绍

Kubernetes平台的入口是API。本章通过强调Kubernetes API的核心作用来探索Kubernetes的架构。然后，它侧重于Kubernetes API的HTTP REST性质，以及为组织它所管理的许多资源而添加的扩展。

5.1.1 - Kubernetes 平台一览

在链条的一侧，用户声明高级资源来构建要部署的应用程序： Deployments，Ingresses，等等。

在中间，controller 被激活，将这些资源转化为低级别的资源（Pod），调度器将这些资源分配到节点。在链条的另一端，节点代理将低级别的资源部署到节点上。

Kubernetes 平台的主要元素（通常称为控制平面）在图1-1中突出显示，并在下文中描述：

1. API server: 这是控制平面上的中心点；用户和控制平面的各个部分联系这个API来创建、获取、删除、更新和观察资源。

2. etcd数据库: 只能由API服务器访问，用于保存与资源有关的数据。

3. Controller manager: 运行 Controller，将用户声明的高级资源转化为部署在节点上的低级别资源。控制器连接到API服务器，观察高层资源，创建、删除和更新低层资源，以满足高层资源中声明的规格。

4. Scheduler: 将低级资源分配到各个节点上。调度器连接到API服务器，观察未受影响的资源并将其连接到节点上。

5. Kubelet: 这是一个运行在集群所有节点上的代理，每个代理都管理着影响到其节点的工作负载。kubelet 连接到 API 服务器，观察影响到其节点的Pods资源，并使用本地容器运行时部署相关容器。

6. Kube proxy: 这是一个在集群的所有节点上运行的代理，每个代理都管理着影响其节点的网络配置。Kube proxy 连接到API服务器，观察服务资源并在其节点上配置相关的网络规则。

5.1.2 - openapi规范

Kubernetes 的API 是HTTP REST API。Kubernetes 团队提供了 OpenAPI 格式的API规范，V2格式的规范在 https://github.com/kubernetes/kubernetes/tree/master/api/openapi-spec，Kubernetes v1.24 v3 格式的规范在 https://github.com/kubernetes/kubernetes/tree/master/api/openapi-spec/v3。

这些规范也可以从 API 服务器的这些路径访问： /openapi/v2 和 /openapi/v3 。

OpenAPI规范是由不同部分组成的，其中有路径列表和定义列表。路径是你用来请求这个API的URL，对于每个路径，规范给出了不同的操作，如 get、delte 或 post 。然后，对于每个操作，规范指出了什么是请求的参数和主体格式，以及什么是可能的响应代码和相关的响应主体格式。

请求和响应的参数和主体可以是简单的类型，也可以是更普遍的包含数据的结构。定义列表包括帮助建立操作的请求和响应的参数和主体的数据结构。

图1-2是一个 User API 规范的简化视图。这个API可以接受两个不同的路径： /user/{userId} 和 /user。第一个路径，/user/{userId}，可以接受两个操作，分别是 get 和 delete，用来接收特定用户的信息，给出其用户ID；以及删除特定用户的信息，给出其用户ID。第二个路径，/user，可以接受一个单一的操作，post，以添加一个新的用户，给定其信息。

在这个API中，给出了一个 User 结构体的定义，描述了一个用户的信息：其ID、first name 和 last name。这个数据结构被用于第一条路径上的 get 操作的响应体中，以及第二条路径上的 post 操作的请求体中。

5.1.3 - Group-Version-Resource

Kubernetes API 是 REST API，因此它管理资源和资源的路径，这些资源遵循REST的命名惯例–即使用复数名称来识别资源，并将这些资源分组。

因为 Kubernetes API 管理着数以百计的资源，所以它们被分组，而且因为 API 的发展，这些资源是有版本的。由于这些原因，每个资源都属于一个给定的 group和 version，每个资源都由 Group-Version-Resource 唯一标识，通常称为 GVR。

要找到 Kubernetes API 中的各种资源，你可以浏览 OpenAPI 规范，提取不同的路径。传统的资源（如pod或节点）将在 Kubernetes API 的早期引入，都属于组 core 和版本v1。

管理整个集群的遗留资源的路径遵循 /api/v1/<plural_resource_name> 的格式–例如，/api/v1/nodes 来管理节点。请注意，core group 在路径中不被代表。要管理特定命名空间中的资源，路径格式是 /api/v1/namespaces/<namespace_name>/<plural_resource_name> –例如，/api/v1/namespaces/default/pods 用于管理默认命名空间中的pod。

较新的资源可以通过格式为 /apis/<group>/<version>/<plural_resource_name>或 /apis/<group>/<version>/namespaces/<namespace_name>/<plural_resource_name> 的路径访问。

概括地说，获取资源的各种路径的格式是：

• /api/v1/<plural_name> - 访问传统的非命名空间的资源。例如：/api/v1/nodes，访问无命名空间的节点资源。或

• 访问整个集群的传统命名方式的资源，例如：/api/v1/pods，访问所有命名空间的pod。

• /api/v1/namespaces/<ns>/<plural_name> - 访问特定命名空间中的遗留带命名空间的资源。例如：/api/v1/namespaces/default/pods，访问默认命名空间中的pod。

• /apis/<group>/<version>/<plural_name> - 访问特定组和版本中的非命名空间资源。例如：/apis/storage.k8s.io/v1/storageclasses来访问非命名空间的storageclasses（组storage.k8s.io，版本v1）。或

• 访问整个集群的命名空间资源。例如：/apis/apps/v1/deployments，访问所有命名空间的 deployment。

• /apis/<group>/<version>/namespaces/<ns>/<plural_name> - 访问特定命名空间的命名资源。例如：/apis/apps/v1/namespaces/default/deployments访问默认命名空间中的deployment（分组为 apps，版本为 v1）。

5.1.4 - Verbs 和 Kinds

Kubernetes API为该规范添加了两个概念：Kubernetes API Verbs （动词）和Kubernetes Kinds。

Kubernetes API Verbs 被直接映射到 OpenAPI 规范中的操作。定义的 Verbs 动词是 get、create、update、patch、delete、list、watch 和d eletecollection。与HTTP动词的对应关系可以在表1-1中找到。

表1-1 Kubernetes API动词和HTTP动词的对应关系

Kubernetes Kinds 是 OpenAPI 规范中定义的一个子集。当向 Kubernetes API 发出请求时，数据结构会通过请求和响应的主体进行交换。这些结构共享共同的字段，apiVersion 和 kind，以帮助请求的参与者识别这些结构。

如果你想让你的 User API 管理这个 Kind 概念，User 结构体将包含两个额外的字段，apiVersion 和 kind –例如，其值为 v1 和 User。要确定 Kubernetes OpenAPI 规范中的定义是否是 Kubernetes Kind，你可以查看定义的 x-kubernetes-group-version-kind 字段。如果这个字段被定义了，那么该定义就是一个 kind，它给你提供了apiVersion 和 kind 字段的值。

5.1.5 - 子资源

按照REST API的惯例，资源可以有子资源。子资源是属于另一个资源的，可以通过在资源名称后面指定其名称来访问，如下所示：

• /api/v1/<plural>/<res-name>/<sub-resource>

  例如: /api/v1/nodes/node1/status

• /api/v1/namespaces/<ns>/<plural>/<res-name>/<sub-resource>

  例如: /api/v1/namespaces/ns1/pods/pod1/status

• /apis/<group>/<version>/<plural>/<res-name>/<sub-resource>

  例如: /apis/storage.k8s.io/v1/volumeattachments/volatt1/status

• /apis/<grp>/<v>/namespaces/<ns>/<plural>/<name>/<sub-res>

  例如: /apis/apps/v1/namespaces/ns1/deployments/dep1/status

大多数 Kubernetes 资源都有一个 status 子资源。你可以看到，在编写 operator 时，operator 需要更新 status 子资源，以便能够表明 operator 观察到的这个资源的状态。在status 子资源中可以执行的操作有：get、patch 和 update。Pod有更多的子资源，包括 attach, binding, eviction, exec, log, portforward, 和 proxy。这些子资源对于获取特定的正在运行的 pod 的信息，或者在正在运行的 pod 上执行一些特定的操作，等等都很有用。

可以缩放的资源（即 deployment 、replicaset 等）有一个 scale 子资源。可以在 scale 子资源中执行的操作是 get、patch和update。

5.1.6 - 官方API参考文档

该API的官方参考文档在 https://kubernetes.io/docs/reference/kubernetes-api/。API管理的资源首先按类别（即工作负载、存储等）分组，对于每个类别，你可以获得一个带有简短描述的资源名称列表（图1-3）。

注意，这些类别并不是 Kubernetes API 定义的一部分，而是在本网站中用来帮助没有经验的用户在众多的可用资源中找到自己的方向。

准确地说，显示的名称不是REST意义上的资源名称，而是相关的主体种类，如图1-4所示。例如，在管理Pod时，REST路径中使用的资源名称是pods（即小写和复数），而在HTTP请求中用于交换Pod信息的定义被命名为Pod（即大写和单数）。请注意，其他种类可以与同一资源相关联。在本章的例子中，PodList种类（用于交换关于Pod列表的信息）也存在。

Deployment 文档

让我们来探讨一下这个地址提供的 Deployment 的参考文档：https://kubernetes.io/docs/reference/kubernetes-api/workload-resources/deployment-v1/。该页的标题 “Deployment” 是与图1-5所示的 Deployment 资源有关的主要种类。

头中指出的 apiVersion 可以帮助您为部署资源编写 YAML 清单，因为您需要为 Kubernetes 清单中的每个资源指定 apiVersion 和 kind。

在这种情况下，您知道部署的清单将以下列内容开始：

apiVersion: apps/v1
kind: Deployment

下一个 header 指出了编写Go代码时要使用的 import 。在第三章中，你将看到在Go中描述资源时如何使用这个导入。

在 header 之后，描述了一个结构体定义的列表，也可以从图1-6中的 Deployment 文档页的目录中获取。第一个是资源的主要种类（kind），后面可以选择用于第一种领域的结构体定义。

例如，Deployment kind 包含一个 spec 字段，类型为 DeploymentSpec，这将在后面描述。请注意，DeploymentSpec 不是在HTTP请求期间直接交换的结构体，因此，它不是一个 kind ，也不包含 kind 或 apiVersion 字段。

在主要 kind 及其相关定义之后，将显示与该资源相关的其他 kind。在本例中，是 DeploymentList kind。

操作文档

资源的API文档的下一个主题是对该资源或其子资源可能进行的操作列表，也可以从目录页中访问（见图1-6）。如图1-7所示，通过检查创建部署的操作细节，你可以看到要使用的HTTP请求动词和路径、请求过程中要传递的参数，以及可能的响应。请求使用的HTTP动词是POST，路径是 /apis/apps/v1/namespaces/{namespace}/deployments。

路径的 {namespace} 部分表示一个路径参数，它将被你想在其上创建部署的命名空间的名称所取代。你可以指定查询参数：dryRun、fieldManager、fieldValidation 和 pretty。这些参数将遵循格式为 path?dryRun=All 的路径。

请求的主体必须是一个Deployment 的种类。当使用 kubectl 时，你正在编写包含这个主体的 Kubernetes Manifest。在第三章中，你将看到如何在Go中构建主体。响应的HTTP代码可能是： 200、201、202和401；对于2xx代码，响应体将包含一个 Deployment 类型。

pod文档

有些结构体包含许多字段。对于它们，Kubernetes API 文档对字段进行了分类。一个例子是Pod资源的文档。

Pod 资源的文档页面首先包含主要种类 Pod 的描述，然后是 PodSpec 结构体的描述。PodSpec 结构体包含约40个字段。为了帮助你理解这些字段之间的关系，并简化它们的探索，它们被安排成不同的分类（categories）。PodSpec 字段的分类如下： Containers, Volumes, Scheduling, Lifecycle，等等。

此外，对于包含嵌套字段的字段，它们的描述一般是 inline 显示，以避免在结构体描述之间来回穿梭。然而，对于复杂的结构体，描述会随后在页面上报告，并且在字段名旁边有一个链接，以便能够方便地访问它。

对于 Spec 和 Status 结构来说，这种情况一直存在，因为它们在几乎所有的资源中都非常常见。此外，Pod中使用的一些结构体也是如此–例如，Container、EphemeralContainer、LifecycleHandler、NodeAffinity等等。

一些在多个资源中使用的结构被放置在通用定义部分，在字段名旁边有一个链接，可以很容易地访问它。在图1-8中，你可以看到 PodSpec 结构描述里面的容器类别。

你还可以看到，containers 和 initContainers 这些字段的类型与Container相同，Container在本页后面有描述，可以通过链接访问。imagePullSecrets字段的类型是 LocalObjectReference，这在通用定义部分有描述，也可以通过链接访问。

单页版的文档

另一个版本的API参考文档存在，并在一个页面上呈现。这个版本涵盖了一个Kubernretes版本所服务的所有资源版本（不仅仅是最新的版本）。这个版本（如果你想，改变路径的最后部分，以导航到另一个Kubernetes版本）可以在以下网址找到：

https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.24/

总结

在本章中，你已经能够发现Kubernetes平台的架构，以及API server 发挥的核心作用。Kubernetes API 是一个HTTP REST API，资源被分类为各种有版本的分组。

类型 kind 是用于在API服务器和客户端之间交换数据的特定结构。你可以使用 Kubernetes 官方网站，以人类可读的形式浏览API规范，发现各种资源和种类的结构，每个资源和子资源的不同操作，以及它们相关的动词。

5.2 - [第二章]Kubernetes API操作

上一章介绍了 Kubernetes API 遵循 REST 原则，使用户能够操作资源。

在本章中，你将学习如何通过直接发出 HTTP 请求来执行各种操作。在你的日常工作中，你可能不需要直接与HTTP层进行交互，但了解API在这个层面上的工作原理是很重要的，这样你就能理解如何用更高层次的库更容易地使用它。

检查请求

在开始编写你自己的HTTP请求之前，你可以用 kubectl 检查哪些请求是在执行kubectl命令时使用的。这可以通过使用大于或等于6的 verbose 标志-v来实现。表2-1显示了在每个级别上显示的信息。

例如，如果你想知道在获取所有命名空间的pod时被调用的URL，你可以使用以下命令：

$ kubectl get pods --all-namespaces -v6

loader.go:372] Config loaded from file:  /home/user/.kube/config
round_trippers.go:553] GET https://192.168.1.194:6443/api/v1/pods?limit=500 200 OK in 745 milliseconds

在该命令的输出中，你可以看到使用的路径是 /api/v1/pods。或者，在获取特定命名空间的pod时，你可以看到使用的路径是 /api/v1/namespaces/default/pods

$ kubectl get pods --namespace default -v6

loader.go:372] Config loaded from file:  /home/user/.kube/config
round_trippers.go:553] GET https://192.168.1.194:6443/api/v1/namespaces/default/pods?limit=500 200 OK in 138 milliseconds

• 动词级别

提出请求

本节研究了你可以对Kubernetes资源进行的所有操作。

使用 kubectl 作为代理

你必须经过认证才能向集群的 Kubernetes API 发出请求，除非你的集群接受未经认证的请求，但这是不可能的。

运行认证的HTTP请求的方法是使用kubectl作为代理，使其处理认证。为此，可以使用 kubectl proxy命令：

kubectl proxy

开始在 127.0.0.1:8001 上提供服务

在一个新的终端上，你现在可以运行你的 HTTP 请求，不需要任何认证。接下来，定义一个HOST变量来访问代理：

HOST=http://127.0.0.1:8001

创建资源

你可以通过首先创建描述该资源的Kubernetes清单来创建一个新的资源–例如，要创建一个Pod，你可以写：

cat > pod.yaml <<EOF
apiVersion: v1
kind: Pod
metadata:
  name: nginx
spec:
  containers:
  - image: nginx
    name: nginx
EOF

然后，你需要将资源描述传递到POST请求的正文中（注意，-X POST标志可以省略，因为使用的是 -data-binary 标志）。例如，要创建一个pod资源，请使用：

curl $HOST/api/v1/namespaces/project1/pods -H "Content-Type: application/yaml" --data-binary @pod.yaml

这等同于运行kubectl命令：

kubectl create --namespace project1 -f pod.yaml -o json

请注意，命名空间在 pod.yaml 文件中没有被指出。如果你添加它，你必须在 YAML 文件和路径中指定相同的命名空间，否则你会得到一个错误–即提供的对象的命名空间与请求中发送的命名空间不匹配。

获取资源的信息

你可以使用GET请求来获取特定资源的信息，并在路径中传递其名称作为参数（如果是命名空间的资源，还要传递其命名空间）。在这个例子中，你将请求project1命名空间中的nginx的信息：

curl -X GET $HOST/api/v1/namespaces/project1/pods/nginx

这将返回JSON格式的资源信息，使用与该资源相关的种类作为结构；在这个例子中，它是一个Pod种类。这等同于运行kubectl命令：

kubectl get pods --namespace project1 nginx -o json

获取资源列表

对于命名空间的资源，你可以获得整个集群或特定命名空间的资源列表。对于非命名空间的资源，你可以获得资源的列表。在任何情况下，你将使用GET请求。

集群范围

要获得集群范围内的资源列表，对于带命名空间的或不带命名空间的资源；例如，对于pod资源，使用以下方法：

curl $HOST/api/v1/pods

这将返回所有命名空间的pod列表的信息，使用PodList种类。这等同于运行kubectl命令：

kubectl get pods --all-namespaces -o json

在特定的命名空间中

要获得特定命名空间中的资源列表，你需要在路径中指明命名空间；例如，对于pod资源，可以这样使用：

curl $HOST/api/v1/namespaces/project1/pods

这将返回project1命名空间中的pod列表信息，使用PodList种类。这等同于运行kubectl命令：

kubectl get pods --namespace project1 -o json

筛选列表的结果

当运行一个 list 请求时，你会得到这类资源的完整列表，在指定的命名空间或集群范围内，取决于你的请求。

你可能想过滤这个结果。在Kubernetes中过滤资源最常见的方法是使用标签 label。为此，资源需要有定义的标签；然后，在列表请求中，你可以定义一些标签选择器。也可以通过使用字段选择器，根据一组有限的字段来过滤资源。

使用标签选择器

所有 Kubernetes 资源都可以定义标签。例如，在创建pod时，你可以用kubectl定义一些标签：

kubectl run nginx1 --image nginx --labels mylabel=foo
kubectl run nginx2 --image nginx --labels mylabel=bar

这导致了带有在资源的元数据部分定义的标签的 pod：

$ kubectl get pods nginx1 -o yaml
apiVersion: v1
kind: Pod
metadata:
  labels:
    mylabel: foo
  name: nginx1
[...]
$ kubectl get pods nginx2 -o yaml
apiVersion: v1
kind: Pod
metadata:
  labels:
    mylabel: bar
  name: nginx2
[...]

现在，当运行 list 请求时，你可以通过使用 labelSelector 查询参数定义一些标签选择器来过滤这些资源，这个参数可以包含一个逗号分隔的选择器列表。

• 选择所有定义特定标签的资源，无论其值如何；例如，mylabel标签：

  curl "$HOST/api/v1/namespaces/default/pods?labelSelector=mylabel"
  

• 选择所有没有定义特定标签的资源；例如，mylabel标签：

  curl "$HOST/api/v1/namespaces/default/pods?labelSelector=\!mylabel"
  

  注意：

  标签名称前的感叹号（！）–使用反斜线字符（\）是因为感叹号是shell的一个特殊字符。

• 选择所有定义有特定值的标签的资源；例如，mylabel的值是foo：

  curl "$HOST/api/v1/namespaces/default/pods?labelSelector=mylabel==foo"
  

  或者

  curl "$HOST/api/v1/namespaces/default/pods?labelSelector=mylabel=foo"
  

• 选择所有定义标签的资源，其值与特定的标签不同；例如，标签mylabel的值与foo不同：

  curl "$HOST/api/v1/namespaces/default/pods?labelSelector=mylabel\!=foo"
  

  注意：

  等号（=）前的感叹号（！）–使用反斜杠字符（\）是因为感叹号是shell的一个特殊字符。

• 选择所有定义有一组值的标签的资源；例如，具有foo或baz其中一个值的标签mylabel：

  curl "$HOST/api/v1/namespaces/default/pods?labelSelector=mylabel+in+(foo,baz)"
  

  注意:

  加号字符（+），它对URL中的空格进行编码。原来的选择器是：mylabel in (foo,baz)。

• 选择所有定义标签的资源，其值不在一组值中；例如，标签mylabel的值与foo或baz不同：

  curl "$HOST/api/v1/namespaces/default/pods?labelSelector=mylabel+notin+(foo,baz)"
  

  注意:

  加号字符（+），它对URL中的空格进行编码。原来的选择器是：mylabel notin (foo,baz)。

你可以用逗号把几个选择器分开来组合。这将充当一个 AND 操作符。例如，要选择所有定义了标签 mylabel 并且标签otherlabel等于bar的资源，你可以使用以下标签选择器：

curl "$HOST/api/v1/namespaces/default/pods?labelSelector=mylabel,otherlabel==bar"

使用字段选择器

你可以使用一组有限的字段来过滤资源。对于所有资源，你可以在 metadata.name 字段上进行过滤；对于所有 namespaced 资源，你可以在metadata.namespace 字段上过滤。

下面是 Kubernetes 1.23的其他可用于过滤的字段列表，具体取决于资源：

core.event:

• involvedObject.apiVersion
• involvedObject.fieldPath
• involvedObject.kind
• involvedObject.name
• involvedObject.namespace
• involvedObject.resourceVersion
• involvedObject.uid
• reason
• reportingComponent
• source
• type

core.namespace:

• status.phase

core.node:

• spec.unschedulable

core.pod:

• spec.nodeName
• spec.restartPolicy
• spec.schedulerName
• spec.serviceAccountName
• status.nominatedNodeName
• status.phase
• status.podIP

core.replicationcontroller:

• status.replicas

core.secret:

• type

apps.replicaset:

• status.replicas

batch.job:

• status.successful

certificates.certificatesigningrequest:

• spec.signerName

现在，当运行 list 请求时，你可以通过使用 fieldSelector 参数来指示一些字段选择器来过滤这些资源，该参数可以包含一个逗号分隔的选择器列表。

• 选择某个字段有特定值的所有资源；例如，字段 status.phase 的值为Running：

  curl "$HOST/api/v1/namespaces/default/pods?fieldSelector=status.phase==Running"
  

  或者

  curl "$HOST/api/v1/namespaces/default/pods?fieldSelector=status.phase=Running"
  

• 选择某个字段的值与特定字段不同的所有资源；例如，字段 status.phase 的值与 Running 不同：

  curl "$HOST/api/v1/namespaces/default/pods?fieldSelector=status.phase\!=Running"
  

你可以用逗号把几个选择器分开来组合。这将充当一个AND运算符。例如，要选择所有 phase 等于 “运行 “且重启策略不是 “总是 “的 pod，你可以使用这个字段选择器：

curl "$HOST/api/v1/namespaces/default/pods?fieldSelector=status.phase==Running,spec.restartPolicy\!=Always"

删除资源

要删除资源，你需要在路径中指定它的名字（和带有命名空间的资源的命名空间）并使用DELETE请求。例如，要删除pod，使用下面的方法：

curl -X DELETE "$HOST/api/v1/namespaces/project1/pods/nginx"

这将以 JSON 格式返回被删除资源的信息，使用与该资源相关的种类–本例是Pod kind。

这相当于运行kubectl命令（除了你不能得到关于被删除资源的信息，只能通过-o name标志得到它的名字）：

kubectl delete pods --namespace project1 nginx

删除资源的集合

也可以使用DELETE请求删除特定命名空间中的特定资源集合；对于命名空间的资源，在路径中指明命名空间：

curl -X DELETE "$HOST/api/v1/namespaces/project1/pods"

这将以JSON格式返回被删除资源的信息，使用与资源相关的List种类；在这个例子中，PodList种类。

这相当于运行kubectl命令（除了不能获得被删除资源的信息，只能通过-o name标志获得其名称）：

kubectl delete pods --namespace project1 --all

注意

不可能像使用kubectl命令那样，在一次请求中从所有命名空间中删除所有特定种类的资源：kubectl delete pods –all-namespaces –all。

更新资源

通过使用PUT请求并在路径中指定名称（和带有命名空间的资源的命名空间）以及在请求正文中指定新的资源信息，可以替换关于特定资源的完整信息。

为了说明这一点，你可以首先定义一个新的 deployment，使用以下命令：

cat > deploy.yaml <<EOF
apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx
spec:
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - image: nginx
        name: nginx
EOF

然后，你可以用以下方法在集群中创建这个部署：

curl "$HOST/apis/apps/v1/namespaces/project1/deployments" -H "Content-Type: application/yaml" --data-binary @deploy.yaml

接下来，你可以为部署创建一个更新的清单；例如，通过以下命令更新容器的镜像（这将把镜像名称nginx替换为nginx:latest）：

cat deploy.yaml | sed 's/image: nginx/image: nginx:latest/' > deploy2.yaml

最后，你可以使用以下请求来更新部署到集群中：

curl -X PUT "$HOST/apis/apps/v1/namespaces/project1/deployments/nginx" -H "Content-Type: application/yaml" --data-binary @deploy2.yaml

这等同于运行kubectl命令：

kubectl replace --namespace project1  -f deploy2.yaml -o json

更新资源时的冲突管理

当用以前的技术更新一个资源时，如果另一个参与者在你创建它和你更新它之间对资源进行了修改，那么在你更新资源时，其他参与者所做的修改将会丢失。

为了避免这种冲突的风险，你可以先读取资源信息（使用GET请求），在资源的元数据中找到 resourceVersion 字段的值，然后在你要更新的资源的规格中指出这个resourceVersion。

通过发送带有该 resourceVersion 的PUT请求，API 服务器将比较所收到的资源和当前资源的 resourceVersion 值。如果数值不同（因为另一个参与者在此期间修改了该资源），API服务器将回复错误： 操作无法在[…]上完成：该对象已被修改；请将您的修改应用到最新的版本上并重试。

为了说明问题，让我们来创建部署（如果你已经从上一节创建了它，请确保在这样做之前删除它）：

curl "$HOST/apis/apps/v1/namespaces/project1/deployments" -H "Content-Type: application/yaml" --data-binary @deploy.yaml

你将收到一个响应，表明你所创建的资源的 resourceVersion；在这个例子中，它是668867：

{
  "kind": "Deployment",
  "apiVersion": "apps/v1",
  "metadata": {
    "name": "nginx",
    "namespace": "project1",
    "uid": "99d3a1eb-176c-40de-89ec-74313169fe60",
    "resourceVersion": "668867",
    "generation": 1,
  [...]
}

在等待几秒钟后，你可以执行一个GET请求来查找最新的版本，你会收到以下响应：

curl "$HOST/apis/apps/v1/namespaces/project1/deployments/nginx"

{
  "kind": "Deployment",
  "apiVersion": "apps/v1",
  "metadata": {
    "name": "nginx",
    "namespace": "project1",
    "uid": "99d3a1eb-176c-40de-89ec-74313169fe60",
    "resourceVersion": "668908",
    "generation": 1,
  [...]
}

你可以看到 resourceVersion 已经被递增，现在是668908。发生这种情况是因为部署控制器已经自行更新了资源。

现在，如果你把第一次收到的版本添加到YAML清单中，并试图更新部署，你会得到一个错误，表明已经检测到冲突：

cat > deploy2.yaml <<EOF
apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx
  resourceVersion: "668867"
spec:
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - image: nginx
        name: nginx
EOF

curl -X PUT "$HOST/apis/apps/v1/namespaces/project1/deployments/nginx" -H "Content-Type: application/yaml" --data-binary @deploy2.yaml

{
  "kind": "Status",
  "apiVersion": "v1",
  "metadata": {
  },
  "status": "Failure",
  "message": "Operation cannot be fulfilled on deployments.apps \"nginx\": the object has been modified; please apply your changes to the latest version and try again",
  "reason": "Conflict",
  "details": {
    "name": "nginx",
    "group": "apps",
    "kind": "deployments"
  },
  "code": 409
}

现在，如果你使用以下命令用最新的资源版本更新YAML清单，并再次运行PUT命令，操作将成功：

$ sed -i 's/668867/668908/' deploy2.yaml
$ curl -X PUT
 $HOST/apis/apps/v1/namespaces/project1/deployments/nginx
 -H "Content-Type: application/yaml"
 --data-binary @deploy2.yaml
{
  "kind": "Deployment",
  "apiVersion": "apps/v1",
  "metadata": {
    "name": "nginx",
    "namespace": "project1",
    "uid": "99d3a1eb-176c-40de-89ec-74313169fe60",
    "resourceVersion": "671623",
    "generation": 2,
[...]
}

使用 Strategic Merge Patch 来更新资源

当修改资源时，与其发送完整的描述，不如通过使用补丁只发送你想修改的部分。

这可以通过使用带有 application/strategic-merge-patch+json content-type 的 PATCH 请求来实现，并在路径中指定名称（和带有命名空间的资源的命名空间），在请求的正文中指定补丁信息。

补丁信息是 YAML 清单的提取物，其中只包含你想更新的字段。这样做，你在路径中指定的字段将被更新，而补丁中未指定的字段将保持不动。

为了说明这一点，您可以先用以下方式创建一个包含补丁信息的文件：

$ cat > deploy-patch.json <<EOF
{
  "spec":{
    "template":{
      "spec":{
        "containers":[{
          "name":"nginx",
          "image":"nginx:alpine"
        }]
}}}}
EOF

然后，你可以通过以下请求将这个补丁应用于资源：

请注意具体使用的 Content-Type 头为 pplication/strategic-merge-patch+json 。

$ curl -X PATCH
 $HOST/apis/apps/v1/namespaces/project1/deployments/nginx
 -H
 "Content-Type: application/strategic-merge-patch+json"
 --data-binary @deploy-patch.json

这等同于运行 kubectl 命令：

$ kubectl patch deployment nginx --namespace project1
    --patch-file deploy-patch.json
    --type=strategic
    -o json

当字段是单一的值（要么是像字符串这样的简单值，要么是一个有几个字段的对象），补丁的值会取代现有的值。

注意:

如果字段在补丁中不存在，原始值将不会被删除，而是保持不动。你可以为字段指定 null 值，以便从结果中删除它。

修补数组字段

当字段包含数组的值时，其行为与单个值的行为不同。

默认行为取决于 Kubernetes API 规范中为该字段定义的补丁策略。例如，你可以在图2-1中看到，container 结构体 的 env 字段在键名上的补丁策略是 Merge 。补丁策略的另一个可能值是 Replace。

当字段的补丁策略是 Replace（替换）时，结果数组是包含在补丁中的数组，而原始数组中的值不被考虑。

当字段的补丁策略是在特定的键上合并时，原始数组和补丁数组将被合并。补丁数组中包含的元素，但不存在于原始数组中，将被添加到结果中，原始数组和补丁数组中存在的元素将获得补丁元素的值（如果元素的键值相同，则原始数组和补丁数组中的元素是相同的）。

注意

原数组中存在的元素，但在补丁中不存在，将保持不动。

为了说明问题，考虑现有的部署，其中有一个定义了这些环境变量的容器，以及一个定义了这些值的补丁：

**Original       Patch**

env:         env:

\- name: key1    - name: key1

 value: value1    value: value1bis

\- name: key2    - name: key3

 value: value2    value: value3

通过将该补丁应用于现有的部署，产生的环境变量列表将是以下内容：

Result for Merge strategy
env:
- name: key1
  value: value1bis
- name: key2
  value: value2
- name: key3
  value: value3

替换指令

你可以对对象或数组使用替换指令。当对对象使用时，原始对象将被替换成补丁对象。这意味着不在补丁中的字段这次不会出现在结果中；而且这个对象的数组将与补丁中的数组完全相同，不会发生合并操作。

要为对象声明这个指令，你需要为该对象添加一个字段 $patch，值为 replace。例如，下面的补丁将用一个只包含 runAsNonRoot 字段的 securityContext 来替换 nginx 容器的 securityContext：

{
  "spec":{
    "template":{
      "spec":{
        "containers":[{
          "name":"nginx",
          "securityContext": {
            "$patch": "replace",
            "runAsNonRoot": false
}}]}}}}

当与数组一起使用时，原始数组将被补丁数组所取代。

要为数组声明这个指令，你需要为这个数组添加一个对象，其中有一个值为替换的单字段 $patch。例如，下面的补丁将把容器 nginx 的环境变量设置为单一变量key1，而不考虑之前定义的变量数量。

{
  "spec":{
    "template":{
      "spec":{
        "containers":[{
          "name":"nginx",
          "env": [
            { "$patch": "replace"},
            { "name": "key1", "value": "value1" }
          ]
}]}}}}

删除指令

你可以对对象或数组中的对象元素使用删除指令。对对象使用这个指令，就像把这个对象的值声明为空。例如，这个补丁将从容器 nginx 中删除字段securityContext：

{
  "spec":{
    "template":{
      "spec":{
        "containers":[{
          "name":"nginx",
          "securityContext": {
            "$patch": "delete"
          }
}]}}}}

要从列表中删除一个元素，你需要将指令添加到你要删除的元素中。你需要指出键字段（为 Merge 补丁策略指出的键）。例如，你可以用这个补丁来删除名为key1的环境变量：

{
  "spec":{
    "template":{
      "spec":{
        "containers":[
        {
          "name":"nginx",
          "env": [{
              "name": "key1",
              "$patch": "delete"
          }]
}]}}}}

deleteFromPrimitiveList指令

delete 指令只适用于从数组中删除对象。你可以使用 deleteFromPrimitiveList 指令，通过在包含数组的字段名前加上 $deleteFromPrimitiveList/ 来删除数组中的原始元素。例如，要从 nginx 容器的 args 列表中删除 -debug 参数，可以使用以下补丁：

{
  "spec":{
    "template":{
      "spec":{
        "containers":[
        {
          "name":"nginx",
          "$deleteFromPrimitiveList/args": [
            "--debug"
          ]
}]}}}}

注意

这个指令对于 Kubernetes 1.24 和更早的版本不能正常工作，因为它只保留指定的值，而不是只保留其他值。

setElementOrder指令

setElementOrder 指令可以用来将数组中的元素排序成不同的顺序，方法是在包含要排序的数组的字段名前加上 $setElementOrder/。例如，要重新排序部署的 initContainers，可以使用这个补丁：

{
  "spec":{
    "template":{
      "spec":{
        "$setElementOrder/initContainers":[
          { "name": "init2"},
          { "name": "init1"}
        ]}}}}

应用服务器端的资源

正如你在前面的章节中所看到的，你可以更新资源，但在发生冲突的情况下，你需要编写特定的指令来表明如何解决冲突。Kubernetes API 在 Kubernetes 1.16中引入了服务器端应用的Beta功能，从 Kubernetes 1.22开始，它已经成为一个稳定的功能。

服务器端 Apply 操作和 Update 命令一样，不同的是，即使资源在集群中不存在，也可以使用这个命令，而且执行命令时必须提供一个字段管理器。

服务器端应用操作可以使用 PATCH 请求来执行，其内容类型为 application/apply-patch+yaml，并在路径中指定名称（和命名空间的资源），在请求的正文中指定补丁信息。

Kubernetes API 将在资源的一个专用字段（.metadata.managedFields）中保存该资源中完成的应用操作列表。

对于每个保存的 Apply 操作，它所设置的每个字段都被操作期间提供的字段管理器标记为 “owned”。如果 Apply 操作更新了一个由另一个字段管理器拥有的字段，因为之前的 Apply 操作覆盖了这个字段，就会产生冲突。

可以强制执行 Apply 操作，以便用新值建立冲突的字段，并将所有权转移给新的字段管理器。所有权被设置在对象或原始元素中，以及数组的元素中。

例如，字段管理器可以为容器定义一组环境变量，而另一个字段管理器可以为Pod的同一个容器定义一组不同的环境变量。每个字段管理器拥有它的环境变量。如果第一个字段管理器通过删除它的一些环境变量来运行一个新的Apply操作，这些环境变量将从总列表中删除，但另一个字段管理器的环境变量不会受到影响。

为了说明这个例子，你可以为一个部署创建以下YAML清单，该清单为Pod的容器定义了三个环境变量：

# deploy.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx
spec:
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - image: nginx
        name: nginx
        env:
        - name: key1
          value: value1
        - name: key2
          value: value2
        - name: key3
          value: value3

然后，您可以通过使用服务器端应用操作来应用这个清单（注意内容类型头被设置为 application/apply-patch+yaml，查询参数 fieldManager 被设置为manager1）：

$ curl -X PATCH
$HOST/apis/apps/v1/namespaces/project1/deployments/nginx?fieldManager=manager1
 -H
 "Content-Type: application/apply-patch+yaml"
 --data-binary @deploy.yaml

这条命令将创建部署。你可以检查用这个命令创建的部署资源的 .metadata.managedFields（jq被用来获取缩进的JSON形式）：

$ kubectl get deploy nginx -o jsonpath={.metadata.managedFields} | jq
[{
  "apiVersion": "apps/v1",
  "fieldsType": "FieldsV1",
  "fieldsV1": {
    "f:spec": {
      "f:template": {
        "f:spec": {
          "f:containers": {
            "k:{\"name\":\"nginx\"}": {
              ".": {},       ➊
              "f:image": {}, ➋
              "f:name": {}   ➌
              "f:env": {
                "k:{\"name\":\"key1\"}": {
                  ".": {}, "f:name": {}, "f:value": {} ➍
                },
                "k:{\"name\":\"key2\"}": {
                  ".": {}, "f:name": {}, "f:value": {} ➎
                },
                "k:{\"name\":\"key3\"}": {
                  ".": {}, "f:name": {}, "f:value": {} ➏
  }}}}}}}},
  "manager": "manager1",  ➐
  "operation": "Apply",   ➑
  "time": "2022-07-14T16:46:48Z"
},
{
  "apiVersion": "apps/v1",
  "fieldsType": "FieldsV1",
  "fieldsV1": {
    "f:status": {
      "f:availableReplicas": {},
      "f:observedGeneration": {},
      "f:readyReplicas": {},
      "f:replicas": {},
      "f:updatedReplicas": {}
    }
  },
  "manager": "kube-controller-manager", ➒
  "operation": "Update",                ➓
  "subresource": "status",
  "time": "2022-07-14T16:46:52Z"
}]

你可以在managedFields中看到，你的操作被保存为Apply操作，➑，由经理manager1➐； 这个管理器拥有名称为nginx ➊的容器元素、字段image ➋、name ➌，以及名称为key1 ➍、key2 ➎、key3 ➏的env元素。

管理者是用于编辑资源的任何程序；例如，kubectl在使用编辑或应用命令时，或管理这些资源的控制器或操作员。你还可以看到，第二个更新➓类型的操作已被保存，并由kube-controller-manager ➒拥有，因为在你创建部署资源时，部署控制器在其状态中设置了一些值。

现在，第二个管理器，manager2，想更新环境变量key2。它可以通过创建以下内容并运行该命令（注意强制查询参数被设置为真）来实现：

TBD.。。。。。

观察资源

Kubernetes API允许你观察资源。这意味着你的请求不会立即终止，而是一个长期运行的请求，它将发送一个JSON流作为响应，当被监视的资源发生变化时将JSON对象添加到流中。JSON流是一系列由新行分隔的JSON对象–例如：

{ "type": "ADDED", "object": ... }
{ "type": "DELETED", "object": ... }

观察资源的请求与用于列出资源的请求一样，只是将 watch 参数作为查询参数添加。例如，要观察 project1 命名空间的pod，你可以发送这个请求：

curl "$HOST/api/v1/namespaces/project1/pods?watch=true"

在 Kubernetes 术语中，流的每个JSON对象被称为 Watch Event ，它将包含两个字段： type 和 object。类型的值可以是ADDED、MODIFIED、DELETED、BOOKMARK 或 ERROR。对于每一种类型，其对象如表2-2所描述。

表2-2每种类型的观察事件的对象描述

当这个请求被执行时，你会立即得到一系列的 ADDED JSON 对象，描述在请求时集群中存在的所有资源；最终，当集群中的资源被创建、修改或删除时，会有其他事件发生。这相当于运行 kubectl 命令，不同的是不给类型字段，直接给对象的内容：

kubectl get pods --namespace project1 --watch -o json

在列出资源后进行观察

你可以先运行 list 请求来找到现有资源的列表，然后运行 watch 请求来获得这些资源的修改情况，而不是把请求时存在的资源作为 watch 响应的一部分。这样做有一个风险，即在 list 请求和 watch 请求开始之间可能会发生一些修改，而你并没有得到关于这些修改的通知。

对于这种情况，你可以使用列表请求返回的 resourceVersion 值来指示你想在哪个时间点开始你的观察请求。(注意：你需要将 resourceVersion 获取到 List 结构体中，而不是从一个子项中获取。)

作为例子，你可以首先通过使用命令获得 pod 的列表：

curl "$HOST/api/v1/pods"

{
  "kind": "PodList",
  "apiVersion": "v1",
  "metadata": {
    "resourceVersion": "2433789"
  },
  "items": [ ... ]
}

作为对这第一个请求的响应，你会得到资源版本和在请求时存在于项目领域的资源列表。然后，你可以通过指定这个资源版本来执行 watch 请求：

curl "$HOST/api/v1/namespaces/default/pods?watch=true&resourceVersion=2433789"

因此，你不会立即在响应体中收到描述集群中存在的资源的数据；只有当一些资源被修改、添加或删除时，你才会收到数据。

重启观察请求

观察请求可能会被中断，你可能想在这个过程中从最后收到的修改（或之前的修改）重新启动它。

为此，观察响应中的 DELETE、ADD 或 MODIFIED JSON 对象的每个资源部分都包含 resourceVersion，你可以用它来执行一个新的观察请求，就在指定的修改之后开始。例如，你可以启动一个 watch 请求，在几次修改后就中断了：

$ curl "$HOST/api/v1/namespaces/default/pods?watch=true"
{"type":"ADDED","object":{
  "kind":"Pod","apiVersion":"v1","metadata":{
    "resourceVersion":"2435623", ...}, ...}}
{"type":"ADDED","object":{
  "kind":"Pod","apiVersion":"v1","metadata":{
    "resourceVersion":"2354893", ...}, ...}}
{"type":"MODIFIED","object":{
  "kind":"Pod","apiVersion":"v1","metadata":{
    "resourceVersion":"2436655", ...}, ...}}
{"type":"DELETED","object":{
  "kind":"Pod","apiVersion":"v1","metadata":{
    "resourceVersion":"2436677", ...}, ...}}

然后，你可以从上一次请求的任何时间开始，或从最近一次修改后开始，重新启动 watch 请求：

$ curl "$HOST/api/v1/namespaces/default/pods?watch=true&resourceVersion=2436677"

或者在之前的修改之后开始。这样，你将再次收到最新的修改：

$ curl "$HOST/api/v1/namespaces/default/pods?watch=true&resourceVersion=2436655"
{"type":"DELETED","object":{
  "kind":"Pod","apiVersion":"v1","metadata":{
    "resourceVersion":"2436677", ...}, ...}}

允许书签有效地重新启动 watch 请求

正如前一节所示，通过使用标签或字段选择器，可以在资源的子集上执行 watch 会话。例如，这个请求将观察具有特定标签 mylabel 等于 foo 的 pod：

$ curl "$HOST/api/v1/namespaces/project1/pods?labelSelector=mylabel==foo&watch=true"

通过这个请求，你将只获得与你的选择器相匹配的pod的事件，而不是与你的请求不匹配的同一命名空间的其他pod的事件。

当重新启动观察请求时，你将能够使用与选择器相匹配的pod的资源版本；然而，在这个请求之后，其他pod上的许多事件可能已经发生。API服务器将不得不在你在这个旧的资源版本上重启观察时，执行对在此期间创建的所有pod的事件的过滤。

同样，由于API服务器在有限的时间内缓存这些事件，与最近的资源版本相比，旧的资源版本不再可用的风险更大。

为此，你可以使用 allowWatchBookmarks 参数，要求API服务器定期发送包含最新资源版本的 BOOKMARK 事件；这些可能是与你的选择分开的资源版本。

BOOKMARK 事件可能包含一个你请求的种类的对象（例如，如果你在观察pod，则是Pod种类），但这只包括 resourceVersion 字段。

{"type":"BOOKMARK",
  "object":{
    "kind":"Pod",
    "apiVersion":"v1",
    "metadata":{
      "resourceVersion":"2525115",
      "creationTimestamp":null
    },
    "spec":{
      "containers":null
    },
    "status":{}
  }
}

为了说明问题，这里有一个小实验。首先创建两（2）个pod，用选择器观察pod，只匹配第一个pod。你会得到一个匹配的pod的ADDED事件，而且，过了一段时间，你应该得到一个BOOKMARK事件（但不保证）。如果在此期间，该命名空间的pod上没有任何活动，resourceVersion 应该是相同的。

$ kubectl run nginx1 --image nginx --labels mylabel=foo
$ kubectl run nginx2 --image nginx --labels mylabel=bar
$ curl "$HOST/api/v1/namespaces/default/pods?
  labelSelector=mylabel==foo&
  watch=true&
  allowWatchBookmarks=true"
{"type":"ADDED","object":{
  "kind":"Pod","apiVersion":"v1","metadata":{
    "name":"nginx1","resourceVersion":"2520070", ...}, ...}}
{"type":"BOOKMARK","object":{
  "kind":"Pod","apiVersion":"v1","metadata":{
  "resourceVersion":"2520070", ...}, ...}}

在另一个终端，让我们用命令删除不匹配的pod，nginx2：

$ kubectl delete pods nginx2

你不应该收到这个变化的任何事件，因为 pod 不匹配请求选择器，但过了一会儿，你应该收到一个新的 BOOKMARK事件–这次是一个新的资源版本：

{"type":"BOOKMARK","object":{
  "kind":"Pod","apiVersion":"v1","metadata":{
  "resourceVersion":"2532566", ...}, ...}}

在这一点上，你可以从你的第一个终端停止观察请求。

接下来，你可以对命名空间的pod做一些修改–例如，删除 nginx1 pod，重新创建 nginx2 pod：

$ kubectl delete pods nginx1
$ kubectl run nginx2 --image nginx --labels mylabel=bar

现在，你可以使用资源版本 2532566 来重新启动观察请求，当请求停止时，你可以重新启动它：

curl "$HOST/api/v1/namespaces/default/pods?
  labelSelector=mylabel==foo&
  watch=true&
  allowWatchBookmarks=true&
  resourceVersion=2532566"

结果，你可以看到，当你删除这个pod的时候，你得到了 nginx1 的修改和删除的事件。你没有丢失任何事件，而且你使用了一个最新的资源版本，这对API服务器来说更有效率。

将结果分页

当你执行 list 请求时，结果有可能包含很多元素。在这种情况下，最好是通过发出几个请求来分页处理结果，每个响应将发送有限数量的元素。

对于这种情况，要使用 limit 和 continue 查询参数。第一个列表请求需要指定 limit 参数，以表明要返回的元素的最大数量。响应将在List结构的元数据中包含一个 continue 字段，该字段包含一个不透明的标记，以便在下一次请求中使用，以获得下一整块元素。

$ curl "$HOST/api/v1/pods?limit=1"
{
  "kind": "PodList",
  "apiVersion": "v1",
  "metadata": {
    "resourceVersion": "2931316",
    "continue": <continue_token_1>,
    "remainingItemCount": 10
  },
  "items": [{ ... }]
}
$ curl "$HOST/api/v1/pods?limit=1&continue=<continue_token_1>"
{
  "kind": "PodList",
  "apiVersion": "v1",
  "metadata": {
    "resourceVersion": "2931316",
    "continue": <continue_token_2>,
    "remainingItemCount": 9
  },
  "items": [{ ... }]
}

注意，你不需要对每个块使用相同的限制值。你可以把第一个请求的限制值定为1，第二个请求的限制值定为4，第三个请求的限制值定为6。

完整列表的一致性

请注意，两个响应中的 List 结构中的 resourceVersion 是相同的（即例子中的 “resourceVersion”: “2931316”）。当你运行第一个请求时，完整的响应被缓存在服务器上，你可以保证在接下来的几块中得到一个一致的结果，与你获得以下请求的时间以及在此期间对资源的修改无关。在这段时间内创建、修改或删除的资源不会影响下一个块的结果。

然而，有可能在你运行所有的请求之前，缓存就已经过期了。在这种情况下，你会收到一个代码为 410 的错误响应和一个新的继续值。因此，你有两个选择：

1. 启动新的 List 请求，不使用 continue 参数，从头开始重新启动整个 List 会话。
2. 用返回的 continue 值发起新的请求，但是以不一致的方式–也就是说，自第一个 chunk 被返回后，添加、修改或删除的资源将影响响应。

检测最后一个 chunk

你可以从响应的元数据中看到，remainItemCount 表示完成整个响应所需的剩余元素数量。然而，请注意，这个信息只适用于没有选择器的请求（无论是标签还是字段选择器）。

当运行没有选择器的分页列表请求时，服务器可以知道完整列表中的元素数量，并且能够在每次请求后指出剩余元素的数量。当发送完整列表的最后一个元素时，服务器也能够通过在列表结构的元数据中回复一个空的 continue 字段来表明这是最后一个块。

当使用选择器运行分页的列表请求时，服务器无法预先知道完整列表中的元素数量。由于这个原因，它不会在请求后发送剩余元素的数量，而且即使碰巧下一个块是空的，它也会发送一个continue 非空值。

你需要检查返回的列表是空的还是包含的元素少于 limit 字段中请求的元素，这样你就可以检测到最后一个chunk。

获取各种格式的结果

Kubernetes API可以以各种格式返回数据。你可以通过在HTTP请求中指定 Accept 头来询问你希望收到哪种格式。

以表格形式获取结果

kubectl客户端（和其他客户端）以表格的形式显示资源的列表。当运行 list 请求时，你可以要求API服务器给你必要的信息，通过使用 Accept 头来表示这种特定的格式来建立这种表格：

$ curl $HOST/api/v1/pods
-H 'Accept: application/json;as=Table;g=meta.k8s.io;v=v1'
{
  "kind": "Table",
  "apiVersion": "meta.k8s.io/v1",
  "metadata": {
    "resourceVersion": "2995797"
  },
  "columnDefinitions": [ { ... }, { ... }, { ... } ],
  "rows": [ { ... }, { ... } ]
}

这有助于客户端以表格格式显示任何资源的信息，包括自定义资源，因为自定义资源定义将包含关于在哪一列显示资源的哪个字段的信息。

对于请求的任何资源，响应的 kind 将总是 Table。第一个字段 columnDefinitions 描述了表格的每一列，第二个字段 rows 给出了结果中每个资源的列值。

列的定义

列的定义包括 name, type, format, description 和 priority 字段。name 是指该列的标题。type 是该列的 OpenAPI 类型定义（例如，整数、数字、字符串或布尔值）。

可选的 format 是列的类型的 OpenAPI 修改器，给出更多的格式化信息。整数类型的格式是 int32 和 int64，数字类型的格式是 float 和 double，而字符串类型的格式是 byte、binary、data、date-time、password 和 name。name 格式值不是 OpenAPI 规范的一部分，是 Kubernetes API 特有的。它向客户端指出包含资源名称的主列。

priority 字段是一个整数，表示一个列相对于其他列的重要性。当空间有限时，数值较高的列可能会被省略。

行数据

行包括 cells、conditions 和 object 字段。

cells 字段是一个与 columnDefinitions 数组长度相同的数组，包含当前行中显示的资源值。数组中每个元素的JSON类型和可选格式是由相应的列定义的类型和格式推断出来的。

conditions 字段给出了显示该行的具体属性。从Kubernetes 1.23开始，唯一定义的值是 “已完成”，表示该行显示的资源已经运行完成，可以给予较低的视觉优先级。

默认情况下，object 字段包含该列中显示的资源的元数据。你可以在列表请求中添加一个 includeObject 查询参数，以便不需要关于对象的信息（?includeObject=None），或者需要完整的对象（?includeObject=Object）。这个查询参数的默认值是Metadata，它只需要资源的元数据。例如，使用下面的方法来返回没有对象的信息作为行数据的一部分：

$ curl $HOST/api/v1/pods?includeObject=None
-H 'Accept: application/json;as=Table;g=meta.k8s.io;v=v1'

使用YAML格式

在前面的创建资源部分，你看到可以使用 YAML 格式来描述使用 Content-Type: application/yaml 头创建的资源。如果你没有指定这个头，你将需要用JSON格式来描述资源。

也可以使用 Accept: application/yaml 头来获得YAML格式的请求响应。这对Get和List请求有效，但也可以用于创建或更新资源的请求，返回它们的新值。例如，要获得YAML格式的所有pod的列表，请使用这个：

$ curl $HOST/api/v1/pods -H 'Accept: application/yaml'
kind: PodList
metadata:
  resourceVersion: "3009983"
items:
  [...]

或者，要创建一个新的Pod并获得YAML格式的创建的Pod，请使用以下内容：

$ curl $HOST/api/v1/namespaces/default/pods
    -H "Content-Type: application/yaml"
    -H 'Accept: application/yaml'
    --data-binary @pod.yaml

注意：不可能以 YAML 格式获得 Watch 请求的结果。

使用Protobuf格式

Protobuf 格式也可用于向 API 服务器发送数据或从其接收数据。为此，你需要在 Content-Type 或 Accept 中使用 application/vnd.kubernetes.protobuf 类型。

Kubernetes团队不鼓励在 Kubernetes 控制平面之外使用 Protobuf 格式，因为他们不能保证 Protobuf 消息会像JSON消息一样稳定。

如果你决定使用Protobuf格式，你需要知道API服务器不会交换纯粹的 Protobuf 数据，但它会给它添加一个头来检查 Kubernetes 版本之间的兼容性。

apimachinery 库包含Go代码，帮助开发者将数据序列化为各种格式，包括 Protobuf。第5章描述了如何使用这个库。

总结

本章讨论了如何运行 kubectl 以帮助理解其下执行的HTTP请求。然后，它展示了如何使用各种HTTP操作来创建、更新、应用、删除、获取、列出和观察资源的细节。最后，本章介绍了如何以几种格式获得这些操作的结果： JSON、YAML和Protobuf，或以表格的形式。

5.3 - [第三章]在Go中使用API资源

本书的前两章已经描述了Kubernetes API是如何设计的，以及如何使用HTTP请求访问它。具体来说，你已经看到由API管理的资源被组织成Group-Version-Resources，而客户端和API服务器之间交换的对象被Kubernetes API定义为Kinds。本章还显示，在交换过程中，这些数据可以用JSON、YAML或Protobuf编码，这取决于客户端设置的HTTP头。

在接下来的章节中，你将看到如何使用Go语言访问这个API。与Kubernetes API合作需要的两个重要Go库是apimachinery和api。

apimachinery 是一个通用库，它负责Go结构体和以 JSON（或YAML或Protobuf）格式编写的对象之间的数据序列化。这使得客户和API服务器的开发者有可能使用Go结构体编写数据，并在HTTP交换过程中透明地使用这些资源的JSON（或YAML或Protobuf）。

apimachinery 是通用的，因为它不包括任何Kubernetes API资源定义。它使Kubernetes API可以扩展，并使 apimachinery 可用于任何其他使用相同机制的API，即Kinds 和 Group-Version-Resources。

API 库则是 go 结构体的集合，需要在 go 中与Kubernetes API定义的资源一起工作。

API库的源码和导入

API库的源代码可以从 https://github.com/kubernetes/api 。如果你想为这个库做贡献，请注意，源代码不是从这个库管理的，而是从中心库，https://github.com/kubernetes/kubernetes，在 staging/src/k8s.io/api 目录下，源代码从 kubernetes 库同步到 api 库中。

要把 API 库的包导入Go源代码，你需要使用 k8s.io/api 的前缀–例如：

import "k8s.io/api/core/v1"

进入API库的包遵循API的 Group-Version-Resource 结构。当你想使用某个资源的结构体时，你需要通过这种模式导入与该资源的组和版本相关的包：

import "k8s.io/api/<group>/<version>"

包的内容

让我们来检查包中包含的文件–例如，k8s.io/api/apps/v1 包。

types.go

这个文件可以被认为是包的主文件，因为它定义了所有的 Kind 结构体和其他相关的子结构体。它还定义了这些结构体中的枚举字段的所有类型和常量。举个例子，考虑一下 Deployment Kind；Deployment 结构体首先被定义如下：

type Deployment struct {
    metav1.TypeMeta
    metav1.ObjectMeta
    Spec      DeploymentSpec
    Status    DeploymentStatus
}

然后，相关的子结构体，DeploymentSpec 和 DeploymentStatus，都是用这个定义的：

type DeploymentSpec struct {
     Replicas      *int32
     Selector      *metav1.LabelSelector
     Template      v1.PodTemplateSpec
     Strategy      DeploymentStrategy
     [...]
}

type DeploymentStatus struct {
     ObservedGeneration      int64
     Replicas                int32
     [...]
     Conditions              []DeploymentCondition
}

然后，以同样的方式继续处理在前一个结构体中作为类型使用的每一个结构体。

在 DeploymentCondition 结构体中使用的 DeploymentConditionType 类型（这里没列出），以及这个枚举的可能值都被定义：

type DeploymentConditionType string
const (
     DeploymentAvailable DeploymentConditionType = "Available"
     DeploymentProgressing DeploymentConditionType = "Progressing"
     DeploymentReplicaFailure DeploymentConditionType = "ReplicaFailure"
)

你可以看到，每个 Kind 都嵌入了两个结构体：metav1.TypeMeta 和 metav1.ObjectMeta。它们是强制性的，以便被 API Machinery 识别。TypeMeta 结构体包含关于 Kind 的 GVK 的信息，而 ObjectMeta 包含 Kind 的元数据，比如它的 name 。

register.go

这个文件定义了与这个包相关的分组（group）和版本（version），以及这个分组和版本中的 Kinds 列表。当你需要从这个分组-版本中指定一个资源的分组和版本时，可以使用公共变量 SchemeGroupVersion。

它还声明了一个函数 AddToScheme，它可以用来将分组、版本和 Kinds 添加到 Scheme 中。Scheme 是 API Machinery 中的一个抽象概念，用于在Go结构体和Group-Version-Kinds 之间建立映射。这将在第五章 “API Machinery” 中进一步讨论。

doc.go

这个文件和下面的文件包含高级信息，你不需要理解这些信息就可以开始用 Go 编写你的第一个 Kubernetes 资源，但它们会帮助你理解如何在接下来的章节中用自定义资源定义声明新资源。

doc.go 文件包含以下生成文件的说明：

// +k8s:deepcopy-gen=package
// +k8s:protobuf-gen=package
// +k8s:openapi-gen=true

第一条指令被 deepcopy-gen 生成器用来生成 zz_generated.deepcopy.go 文件。第二条指令被 go-to-protobuf 生成器用来生成这些文件：generated.pb.go 和 generated.proto。第三条指令被 genswaggertypedocs 生成器用来生成 type_swagger_doc_generated.go 文件。

generated.pb.go 和 generated.proto

这些文件是由 go-to-protobuf 生成器生成的。当把数据序列化为 Protobuf 格式时，它们被 API Machinery 使用。

types_swagger_doc_generated.go

这个文件是由 genswaggertypedocs 生成器生成的。它在生成 Kubernetes API 的完整 swagger 定义时使用。

zz_generated.deepcopy.go

这个文件是由 deepcopy-gen 生成器生成的。它包含了为包中定义的每个类型生成的 DeepCopyObject 方法的定义。这个方法对于结构体 实现 runtime.Object 接口是必要的，这个接口是在 API Machinery 中定义的，API Machinery 期望所有的 Kind 结构体将实现这个 runtime.Object 接口。

该文件中的接口定义如下：

type Object interface {
     GetObjectKind() schema.ObjectKind
     DeepCopyObject() Object
}

另一个必要的方法，GetObjectKind，被自动添加到嵌入 TypeMeta 结构体的结构体中 – 所有 Kind 结构体都是如此。TypeMeta 结构体的方法定义如下：

func (obj *TypeMeta) GetObjectKind() schema.ObjectKind {
  return obj
}

core/v1中的特定内容

core/v1包除了定义核心资源的结构体外，还定义了特定类型的实用方法，当你把这些类型纳入你的代码中时，这些方法会很有用。

ObjectReference

ObjectReference 可以用来以一种独特的方式引用任何对象。该结构体定义如下：

type ObjectReference struct {
     APIVersion          string
     Kind                string
     Namespace           string
     Name                string
     UID                 types.UID
     ResourceVersion     string
     FieldPath           string
}

为这种类型定义了三种方法：

• SetGroupVersionKind(gvk schema.GroupVersionKind) - 这个方法将根据作为参数传递的 GroupVersionKind 值来设置字段 APIVersion 和 Kind。

• GroupVersionKind() schema.GroupVersionKind - 该方法将根据 ObjectReference 的字段 APIVersion 和 Kind 返回一个 GroupVersionKind 值。

• GetObjectKind() schema.ObjectKind - 这个方法将把 ObjectReference 对象转换成 ObjectKind。前面的两个方法实现了这个 ObjectKind 接口。因为 ObjectReference 上的 DeepCopyObject 方法也被定义了，所以 ObjectReference 将实现 runtime.Object 接口。

ResourceList

ResourceList 类型被定义为一个map，其键是 ResourceName，值是 Quantity。这被用于各种 Kubernetes 资源，以定义资源的 limits 和 requests。

在YAML中，一个使用的例子是当你为一个 container 定义资源的 requests 和 limits 时，如下所示：

apiVersion: v1
kind: Pod
metadata:
  name: mypod
spec:
  containers:
  - name: runtime
    resources:
      requests:
        memory: "64Mi"
        cpu: "250m"
      limits:
        memory: "128Mi"
        cpu: "500m"

在Go中，你可以把 requests 部分写成：

requests := corev1.ResourceList{
     corev1.ResourceMemory:
        *resource.NewQuantity(64*1024*1024, resource.BinarySI),
     corev1.ResourceCPU:
        *resource.NewMilliQuantity(250, resource.DecimalSI),
}

下一章将更详细地描述如何使用 resource.Quantity 类型来定义数量。ResourceList 类型有以下方法：

• Cpu() *resource.Quantity - 返回 map 中 CPU 键的数量，以十进制格式（1250m等）。

• Memory() *resource.Quantity - 返回 map 中 Memory 键的数量，以二进制格式表示（512 Ki, 64 Mi, etc.）

• storage() *resource.Quantity - 返回 map 中 Storage 键的数量，以二进制格式表示（512 Mi, 1 Gi等）。

• Pods() *resource.Quantity - 返回 map 的 Pods 键的数量，以十进制格式（1，10等）。

• StorageEphemeral() *resource.Quantity - 返回 map 中 StorageEphemeral 键的数量，以二进制格式表示（512 Mi, 1 Gi, etc.)

对于这些方法中的每一个，如果键没有在 map 中定义，将返回一个零值的 Quantity。

另一个方法，在内部被前面的方法使用，可以被用来获得非标准格式的数量：

• Name(name ResourceName, defaultFormat resource.Format) *resource.Quantity - 这返回 Name 键的数量，以 defaultFormat 格式。

ResourceName 类型的定义枚举值是 ResourceCPU、ResourceMemory、ResourceStorage、ResourceEphemeralStorage 和 ResourcePods 。

Taint / 污点

Taint 资源是为了应用于节点，以确保不容忍这些污点的 pod 不会被安排到这些节点。Taint 结构体定义如下：

type Taint struct {
    Key            string
    Value          string
    Effect         TaintEffect
    TimeAdded      *metav1.Time
}

TaintEffect 枚举可以得到以下值：

TaintEffectNoSchedule          = "NoSchedule"
TaintEffectPreferNoSchedule    = "PreferNoSchedule"
TaintEffectNoExecute           = "NoExecute"

众所周知的 Taint 键，在特殊情况下被控制平面使用，在这个包中定义如下：

TaintNodeNotReady
   = "node.kubernetes.io/not-ready"
TaintNodeUnreachable
   = "node.kubernetes.io/unreachable"
TaintNodeUnschedulable
   = "node.kubernetes.io/unschedulable"
TaintNodeMemoryPressure
   = "node.kubernetes.io/memory-pressure"
TaintNodeDiskPressure
   = "node.kubernetes.io/disk-pressure"
TaintNodeNetworkUnavailable
   ="node.kubernetes.io/network-unavailable"
TaintNodePIDPressure
   = "node.kubernetes.io/pid-pressure"
TaintNodeOutOfService
   = "node.kubernetes.io/out-of-service"

以下两个方法是在 Taint 上定义的：

• MatchTaint(taintToMatch *Taint) bool - 如果两个污点的 key 和 Effect 值相同，这个方法将返回 true。

• ToString() string - 这个方法将返回 Taint 的字符串表示，格式是这样的： <key>=<value>:<effect>, <key>=<value>:, <key>:<effect>, 或 <key>.

Toleration / 宽容性

Toleration 资源旨在应用于 Pod，使其能够容忍特定节点的污点。Toleration 结构体定义如下：

type Toleration struct {
     Key                  string
     Operator             TolerationOperator
     Value                string
     Effect               TaintEffect
     TolerationSeconds    *int64
}

TolerationOperator 枚举有以下值：

TolerationOpExists    = "Exists"
TolerationOpEqual     = "Equal"

TaintEffect 枚举可以有这些值：

TaintEffectNoSchedule              = "NoSchedule"
TaintEffectPreferNoSchedule        = "PreferNoSchedule"
TaintEffectNoExecute               = "NoExecute"

以下两种方法是在 Toleration 结构体上定义的：

• MatchToleration(tolerationToMatch *Toleration) bool - 如果两个 Toleration 的 Key、Operator、Value 和 Effect值相同，该方法返回true。

• ToleratesTaint(taint *Taint) bool - 如果容忍度能容忍污点，该方法返回 true。容忍器容忍污点的规则如下：

  • Effect： 对于空的 Toleration Effect，所有的 Taint 效果将匹配；否则，Toleration 和 Taint Effect 必须匹配。
  • Operator： 如果 TolerationOperator 是Exists，所有的 Taint 值将匹配；否则，TolerationOperator 是 Equal，Toleration 和 Taint 值必须匹配。
  • Key： 对于空的 Toleration Key，TolerationOperator 必须是Exists，所有 Taint 键（有任何值）都将匹配；否则，Toleration 和 Taint 键必须匹配。

知名标签

控制平面在节点上添加标签；使用的知名键及其用法可以在 core/v1 包的 well_known_labels.go 文件中找到。以下是最著名的。

节点上运行的 kubelet 会填充这些标签：

LabelOSStable      = "kubernetes.io/os"
LabelArchStable    = "kubernetes.io/arch"
LabelHostname      = "kubernetes.io/hostname"

当节点在云提供商上运行时，可以设置这些标签，代表（虚拟）机器的实例类型、它的区域和它的地区：

LabelInstanceTypeStable
    = "node.kubernetes.io/instance-type"
LabelTopologyZone
    = "topology.kubernetes.io/zone"
LabelTopologyRegion
    = "topology.kubernetes.io/region"

用Go写Kubernetes资源

你需要在 Go 中编写 Kubernetes 资源，以创建或更新集群中的资源，可以使用HTTP请求，也可以更广泛地使用 client-go 库。client-go 库将在以后的章节中讨论；但现在，让我们专注于用 Go 编写资源。

要创建或更新资源，你需要为与该资源相关的 Kind 创建结构。例如，要创建 Deployment ，你需要创建 Deployment kind；为此，要初始化 Deployment 结构体，它定义在 API 库的 apps/v1 包中。

导入包

在使用这个结构体之前，需要导入定义这个结构体的包。正如本章开头所见，包名的模式是 k8s.io/api/<group>/<version>。路径的最后部分是一个版本号，但你不应该把它和 Go 模块的版本号混淆。

区别在于，当你导入一个 Go 模块的特定版本时（例如 k8s.io/klog/v2），你将使用版本前的部分作为前缀来访问包的符号，而不需要定义任何别名。原因是在库中，v2目录并不存在，而是代表一个分支名称，进入包的文件以 package klog一行开始，而不是 package v2。

相反，在使用 Kubernetes API 库时，版本号是其中一个包的真实名称，进入这个包的文件确实以 package v1 开始。

如果你不为导入定义别名，你将不得不使用版本名来使用这个包的符号。但是，在阅读代码时，单单是版本号是没有意义的，如果你从同一个文件中包含了几个包，最后会出现几个 v1 包名，这是不可能的。

惯例是用组名定义一个别名，或者，如果你想和同一个组的几个版本一起工作，或者你想让别名更清楚地指向一个API group/verson，你可以用 group/verson 创建别名：

import (
    corev1 "k8s.io/api/core/v1"
    appsv1 "k8s.io/api/apps/v1"
)

现在你可以实例化一个 Deployment 结构体：

myDep := appsv1.Deployment{}

为了编译程序，将需要获取该库。为此，请使用：

$ go get k8s.io/api@latest

或者，如果你想使用特定版本的 Kubernetes API（例如，Kubernetes 1.23），请使用：

$ go get k8s.io/api@v0.23

所有与 Kinds 相关的结构体首先嵌入两个通用结构体： TypeMeta 和 ObjectMeta。这两个结构体都在 API machinery 的 /pkg/apis/meta/v1 包中声明。

TypeMeta字段

TypeMeta 结构体定义如下：

type TypeMeta struct {
     Kind           string
     APIVersion     string
}

你一般不需要自己为这些字段设置值，因为 API machinery 通过维护 Scheme–即 Group-Version-Kinds 和 Go 结构体之间的映射，从结构体的类型推断出这些值。请注意，APIVersion 值是将 Group-Version 写成一个包含 <group>/<version> 的单一字段的另一种方式（或者对于传统的核心组，只有v1）。

ObjectMeta字段

ObjectMeta 结构体定义如下（已废弃的字段和内部字段已被删除）：

Type ObjectMeta {
    Name                string
    GenerateName        string
    Namespace           string
    UID                 types.UID
    ResourceVersion     string
    Generation          int64
    Labels              map[string]string
    Annotations         map[string]string
    OwnerReferences     []OwnerReference
    [...]
}

API machinery 的 /pkg/apis/meta/v1 包为这个结构体的字段定义了 Getters 和 Setters。由于 ObjectMeta 被嵌入到资源结构体中，你可以在资源对象本身中使用这些方法。

名称

这个结构体中最重要的信息是资源的名称。你可以使用 Name 字段来指定资源的确切名称，或者使用 GenerateName 字段来请求 Kubernetes API 为你选择一个独特的名称；它是通过向 GenerateName 值添加一个后缀来建立的，以使其独一无二。

你可以在资源对象上使用 GetName() string 和 SetName(name string) 方法来访问其嵌入的 ObjectMeta 的 Name 字段，例如：

configmap := corev1.ConfigMap{}
configmap.SetName("config")

命名空间

带命名空间的资源需要被放置到一个特定的命名空间。你可能认为你需要在命名空间字段中指出这个命名空间，但是，当你创建或更新一个资源时，你将定义放置该资源的命名空间，作为请求路径的一部分。第2章已经表明，在 project1 命名空间中创建 pod 的请求是：

$ curl $HOST/api/v1/namespaces/project1/pods

如果你在 Pod 结构中指定了不同于 project1 的命名空间，你会得到错误： “the namespace of the provided object does not match the namespace sent on the request.”。由于这些原因，在创建资源时，没有必要设置 Namespace 字段。

UID、ResourceVersion 和 Generation

UID 是集群中过去、现在和未来资源的唯一标识符。它由控制平面设置，在资源的生命周期内从不更新。必须用它来引用一个资源，而不是它的 kind, name, 和 namespace，后者可以描述不同时期的各种资源。

ResourceVersion 是一个不透明的值，代表资源的版本。每当资源被更新时，ResourceVersion 就会改变。

这个 ResourceVersion 用于优化并发控制：如果从 Kubernetes API 获得资源的特定版本，修改它然后把它送回 API 更新；API会检查你送回的资源的ResourceVersion 是最后一个。如果在此期间，另一个进程修改了该资源，ResourceVersion 将被修改，你的请求将被拒绝；在这种情况下，你有责任读取新的版本并再次更新它。这与悲观主义的并发控制不同，在悲观主义的并发控制中，你需要在读取资源之前获得一个锁，并在更新之后释放它。

Generation 是一个序列号，可以被资源的控制器用来表示所需状态（Spec）的版本。只有当资源的 Spec 部分被更新时，它才会被更新，而不是其他部分（标签、注解、状态）。控制器通常使用 Status 部分的 ObservedGeneration 字段来指示哪一代被最后处理并反映在状态中。

标签和注解

标签（Labels）和注解（Annotations）在Go中被定义为 map，其中的键和值都是字符串。

即使标签和注解有非常不同的用途，它们也可以用同样的方式来填充。我们将在本节讨论如何填充标签字段，但这也适用于注释。

如果你知道你想添加为标签的键和值，写标签字段的最简单方法是直接写 map，例如：

mylabels := map[string]string{
     "app.kubernetes.io/component": "my-component",
     "app.kubernetes.io/name":      "a-name",
}

也可以在现有的 map 上添加标签，比如说：

mylabels["app.kubernetes.io/part-of"] = "my-app"

如果你需要从动态值建立标签字段，API Machinery 中提供的标签包提供了一个 Set 类型，可能会有所帮助。

import "k8s.io/apimachinery/pkg/labels"
mylabels := labels.Set{}

提供函数和方法来操作这种类型：

• 函数 ConvertSelectorToLabelsMap 将选择器字符串转换为Set。

• 函数 Conflicts 检查两个 Set 是否有冲突的标签。冲突的标签是指具有相同键但不同值的标签。

• 函数 Merge 将把两个 Set 合并成一个 Set。如果两个集合之间有冲突的标签，第二个集合中的标签将被用于产生的集合中

• 函数 Equals 检查这两个 Set 是否有相同的键和值。

• 方法 Has 表明 Set 是否包含一个键。

• 方法 Get 返回 Set 中给定键的值，如果 Set 中没有定义该键，则返回空字符串。

你可以用值来实例化 Set，你可以用单个的值来填充它，就像你用 map 做的一样：

mySet := labels.Set{
     "app.kubernetes.io/component": "my-component",
     "app.kubernetes.io/name":      "a-name",
}
mySet["app.kubernetes.io/part-of"] = "my-app"

你可以使用以下方法来访问一个资源的标签和注释：

• GetLabels() map[string]string
• SetLabels(labels map[string]string)
• GetAnnotations() map[string]string
• SetAnnotations(annotations map[string]string)

OwnerReferences

当你想表明这个资源被另一个资源所拥有，并且你希望这个资源在所有者不存在时被垃圾收集器收集时，就会在 Kubernetes 资源上设置 OwnerReference。

这在开发 controller 和 operator 时被广泛使用。controller 或operator 创建一些资源来实现另一个资源所描述的规范，它将一个 OwnerReference 放入所创建的资源中，指向给出规范的资源。

例如，Deployment controller 根据在 Deployment 资源中发现的规格创建 ReplicaSet 资源。当你删除 Deployment 时，相关的 ReplicaSet 资源会被垃圾收集器删除，而无需 controller 的任何干预。

OwnerReference 类型定义如下：

type OwnerReference struct {
     APIVersion          string
     Kind                string
     Name                string
     UID                 types.UID
     Controller          *bool
     BlockOwnerDeletion  *bool
}

要知道要引用的对象的 UID，你需要从 Kubernetes API 中使用 get（或list）请求获得该对象。

设置 APIVersion 和 Kind

使用 Client-go 库（第4章展示了如何使用它），APIVersion 和 Kind 将不会被设置；你需要在复制对象之前在被引用对象上设置它们，或者直接在 ownerReference 中设置：

import (
      corev1 "k8s.io/api/core/v1"
     metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
)
// Get the object to reference
pod, err := clientset.CoreV1().Pods(myns).
    Get(context.TODO(), mypodname, metav1.GetOptions{})
If err != nil {
    return err
}
// Solution 1: set the APIVersion and Kind of the Pod
// then copy all information from the pod
pod.SetGroupVersionKind(
    corev1.SchemeGroupVersion.WithKind("Pod"),
)
ownerRef := metav1.OwnerReference{
     APIVersion: pod.APIVersion,
     Kind:       pod.Kind,
     Name:       pod.GetName(),
     UID:        pod.GetUID(),
}
// Solution 2: Copy name and uid from pod
// then set APIVersion and Kind on the OwnerReference
ownerRef := metav1.OwnerReference{
     Name: pod.GetName(),
     UID:  pod.GetUID(),
}
ownerRef.APIVersion, ownerRef.Kind =
    corev1.SchemeGroupVersion.WithKind("Pod").
        ToAPIVersionAndKind()

APIVersion包含与 Group 和 Version 相同的信息。你可以从 schema.GroupVersion 类型的 SchemeGroupVersion 变量中获取信息，该变量定义在与资源相关的API库包中（这里 k8s.io/api/core/v1 为 Pod 资源）。然后你可以添加 Kind 来创建一个 schema.GroupVersionKind。

对于第一个解决方案，你可以在引用的对象上使用 SetGroupVersionKind 方法，从 GroupVersionKind 中设置 APIVersion 和 Kind。对于第二个解决方案，使用 GroupVersionKind 上的 ToAPIVersionAndKind 方法来获取相应的 APIVersion 和 Kind 值，然后再把它们移到 OwnerReference 中。

第5章描述了 API Machinery 以及与 Group、Version 和 Kinds 相关的所有类型和方法。OwnerReference 结构体还包含两个可选的布尔字段： Controller 和 BlockOwnerDeletion。

设置Controller

Controller 字段表示被引用的对象是否是管理 Controller（或 operator）。Controller 或 operator 必须在拥有的资源上将此值设置为 “true”，以表明它正在管理这个拥有的资源。

Kubernetes API 将拒绝在同一资源上添加两个 Controller 设置为 true 的 OwnerReferences。这样一来，一个资源就不可能由两个不同的 Controller 管理。

请注意，这与被各种资源所拥有是不同的。一个资源可以有不同的所有者；在这种情况下，当所有的所有者都被删除时，该资源将被删除，与哪个所有者是控制器无关，如果有的话。

Controller 的这种唯一性对于那些可以 “采用” 资源的 Controller 来说是很有用的。例如，ReplicaSet 可以采用与 ReplicaSet 的选择器相匹配的现有Pod，但前提是该 Pod 还没有被另一个 ReplicaSet 或另一个 Controller 控制。

这个字段的值是一个指向布尔值的指针。你可以声明一个布尔值，并在设置控制器字段时影响其地址，或者使用 Kubernetes Utils Library 的 BoolPtr 函数：

// Solution 1: declare a value and use its address
controller := true
ownerRef.Controller = &controller

// Solution 2: use the BoolPtr function
import (
     "k8s.io/utils/pointer"
)
ownerRef.Controller = pointer.BoolPtr(true)

设置BlockOwnerDeletion

OwnerReference 对于 Controller 或其他进程来说是非常有用的，因为他们不需要关心自有资源的删除问题：当所有者被删除时，自有资源将被 Kubernetes 垃圾收集器删除。

这种行为是可配置的。在资源上使用删除操作时，你可以使用传播策略（Propagation Policy ）选项：

1. Orphan：向 Kubernetes API 表示将拥有的资源变成孤儿，因此它们不会被垃圾收集器删除。
2. Background： 指示 Kubernetes API 在所有者资源被删除后立即从 DELETE 操作中返回，而不是等待自有资源被垃圾收集器删除。
3. Foreground： 指示 Kubernetes API 在所有者和 BlockOwnerDeletion 设置为 “true “的自有资源被删除后，从 DELETE 操作中返回。Kubernetes API 将不会等待其他拥有的资源被删除。

因此，如果你正在编写一个 Controller 或其他进程，需要等待所有拥有的资源被删除，该进程将需要在所有拥有的资源上将 BlockOwnerDeletion 字段设置为true，并在删除所有者资源时使用 Foreground 传播策略。

规格和状态

在常见的 Type 和 Metadata 之后，资源定义一般由两部分组成：Spec 和 Status。

请注意，并非所有资源都是如此。例如，核心的 ConfigMap 和 Secret 资源，仅举几例，不包含 Spec 和 Status 部分。更普遍的是，包含配置数据的资源，不由任何 Controller 管理，不包含这些字段。

Spec 是用户将定义的部分，它表示用户所期望的状态。管理该资源的 Controller 将读取Spec，它将根据 Spec 在集群上创建、更新或删除资源，并将其操作的状态检索到资源的 Status 部分。Controller 用于读取 Spec、应用于集群并检索状态的这个过程被称为 Reconcile Loop。

与编写 YAML 清单 的比较

当您编写 Kubernetes 清单 以用于kubectl时：

• 清单以 apiVersion 和 kind 开始。

• metadata 字段包含该资源的所有元数据。

• Spec 和 Status 字段（或其他）紧随其后。

当您用 Go 编写 Kubernetes 结构体时，会发生以下情况：

• 结构体的类型决定了apiVersion 和 Kind；不需要指定它们。

• metadata 可以通过嵌入metav1.ObjectMeta 结构体来定义，也可以通过在资源上使用元数据设置器（metadata setters ）。

• Spec 和 Status 字段（或其他）紧随其后，使用它们自己的 Go 结构体或其他类型。

举个例子，下面是用 YAML 清单和 Go 定义 Pod 的方法。在 YAML 中：

apiVersion: v1
kind: Pod
metadata:
  name: nginx
  labels:
  - component: my-component,
spec:
  containers:
  - image: nginx
    name: nginx

在 Go 中，当你为元数据使用设置器时：

pod := corev1.Pod{
   Spec: corev1.PodSpec{
      Containers: []corev1.Container{
        {
            Name:  "runtime",
            Image: "nginx",
         },
      },
   },
}
pod.SetName("my-pod")
pod.SetLabels(map[string]string{
     "component": "my-component",
})

或者，在 Go 中，当你将 metav1.ObjectMeta 结构体嵌入到 Pod 结构体中时：

pod2 := corev1.Pod{
     ObjectMeta: metav1.ObjectMeta{
          Name: "nginx",
          Labels: map[string]string{
               "component": "mycomponent",
          },
     },
     Spec: corev1.PodSpec{
          Containers: []corev1.Container{
               {
                    Name:  "runtime",
                    Image: "nginx",
               },
          },
     },
}

完整的例子

这个完整的例子使用到此为止学到的概念，使用 POST 请求在集群上创建一个 Pod。

• ➊ 使用 Go 结构体建立一个 Pod 对象，如本章前面所示

• ➋ 使用序列化器将 Pod 对象序列化为 JSON 格式（详见第五章）。

• ➌ 建立一个 HTTP POST 请求，其主体包含要创建的 Pod，并以 JSON 形式序列化

• ➍ 用建立的请求调用 Kubernetes API

• ➎ 从响应中获取主体

• ➏ 根据响应的状态代码：

如果请求返回 2xx 状态代码：

• ➐ 将响应主体反序列化为一个Pod Go结构体
• ➑ 将创建的Pod对象显示为JSON格式的信息；

否则：

• ➒ 将响应体反序列化为一个状态Go结构体。

• ➓ 将Status对象显示为JSON格式，以获取信息：

package main
import (
  "bytes"
  "encoding/json"
  "fmt"
  "io"
  "net/http"
  corev1 "k8s.io/api/core/v1"
  metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
  "k8s.io/apimachinery/pkg/runtime"
  "k8s.io/apimachinery/pkg/runtime/schema"
  "k8s.io/apimachinery/pkg/runtime/serializer/json"
)
func createPod() error {
  pod := createPodObject() ➊
  serializer := getJSONSerializer()
  postBody, err := serializePodObject(serializer, pod) ➋
  if err != nil {
    return err
  }
  reqCreate, err := buildPostRequest(postBody) ➌
  if err != nil {
    return err
  }
  client := &http.Client{}
  resp, err := client.Do(reqCreate) ➍
  if err != nil {
    return err
  }
  defer resp.Body.Close()
  body, err := io.ReadAll(resp.Body) ➎
  if err != nil {
    return err
  }
  if resp.StatusCode < 300 { ➏
    createdPod, err := deserializePodBody(serializer, body) ➐
    if err != nil {
      return err
    }
    json, err := json.MarshalIndent(createdPod, "", "  ")
    if err != nil {
      return err
    }
    fmt.Printf("%s\n", json) ➑
  } else {
    status, err := deserializeStatusBody(serializer, body) ➒
    if err != nil {
      return err
    }
    json, err := json.MarshalIndent(status, "", "  ")
    if err != nil {
      return err
    }
    fmt.Printf("%s\n", json) ➓
  }
  return nil
}
func createPodObject() *corev1.Pod { ➊
     pod := corev1.Pod{
          Spec: corev1.PodSpec{
               Containers: []corev1.Container{
                    {
                         Name:  "runtime",
                         Image: "nginx",
                    },
               },
          },
     }
     pod.SetName("my-pod")
     pod.SetLabels(map[string]string{
          "app.kubernetes.io/component": "my-component",
          "app.kubernetes.io/name":      "a-name",
     })
     return &pod
}
func serializePodObject( ➋
     serializer runtime.Serializer,
     pod *corev1.Pod,
) (
     io.Reader,
     error,
) {
     var buf bytes.Buffer
     err := serializer.Encode(pod, &buf)
     if err != nil {
          return nil, err
     }
     return &buf, nil
}
func buildPostRequest( ➌
     body io.Reader,
) (
     *http.Request,
     error,
) {
     reqCreate, err := http.NewRequest(
          "POST",
          "http://127.0.0.1:8001/api/v1/namespaces/default/pods",
          body,
     )
     if err != nil {
          return nil, err
     }
     reqCreate.Header.Add(
"Accept",
"application/json",
)
     reqCreate.Header.Add(
"Content-Type",
"application/json",
)
     return reqCreate, nil
}
func deserializePodBody( ➐
     serializer runtime.Serializer,
     body []byte,
) (
     *corev1.Pod,
     error,
) {
     var result corev1.Pod
     _, _, err := serializer.Decode(body, nil, & result)
     if err != nil {
          return nil, err
     }
     return &result, nil
}
func deserializeStatusBody( ➒
     serializer runtime.Serializer,
     body []byte,
) (
     *metav1.Status,
     error,
) {
     var status metav1.Status
     _, _, err := serializer.Decode(body, nil, & status)
     if err != nil {
          return nil, err
     }
     return & status, nil
}
func getJSONSerializer() runtime.Serializer {
     scheme := runtime.NewScheme()
     scheme.AddKnownTypes(
          schema.GroupVersion{
               Group:   "",
               Version: "v1",
          },
          &corev1.Pod{},
          &metav1.Status{},
     )
     return json.NewSerializerWithOptions(
          json.SimpleMetaFactory{},
          nil,
          scheme,
          json.SerializerOptions{},
     )
}

总结

在本章中，你已经发现了在 Go 中与 Kubernetes 合作的第一个库– API库。它本质上是一个 Go 结构体的集合，用于声明 Kubernetes 资源。本章还探讨了 API Machinery 中定义的所有资源共有的元数据字段的定义。

在本章的最后，有一个使用 API Machinery 构建Pod定义的程序实例，然后通过使用HTTP请求调用API服务器在集群中创建这个Pod。

下一章将探讨其他基本库–API Machinery 和 client-go，你将不再需要建立HTTP请求。

5.4 - [第4章]使用通用类型

上一章介绍了如何使用Go结构来定义Kubernetes资源。特别是，它解释了Kubernetes API 库的包的内容，以及与 Kubernetes Kind 相关的每个资源的常见字段。

本章研究了在定义 Kubernetes 资源时可在不同地方使用的常见类型。

指针

Go 结构体中的可选值通常被声明为指向一个值的指针。因此，如果你不想指定可选值，你只需要把它作为一个 nil 指针，如果你需要指定一个值，你必须创建该值并传递其引用。

Kubernetes Utils 库的 pointer 包定义了声明这种可选值的实用函数。

import (
     "k8s.io/utils/pointer"
)

获取值的引用

Int, Int32, Int64, Bool, String, Float32, Float64, 和 Duration 函数接受一个相同类型的参数，并返回一个指向作为参数的值的指针。例如，Int32 函数的定义如下：

func Int32(i int32) *int32 {
     return &i
}

然后，你可以这样使用它：

spec := appsv1.DeploymentSpec{
     Replicas: pointer.Int32(3),
     [...]
}

对指针的解引用

另一种方法是，你可以得到指针所引用的值，或者在指针为零时得到一个默认值。

IntDeref、Int32Deref、Int64Deref、BoolDeref、StringDeref、Float32Deref、Float64Deref 和 DurationDeref 函数接受一个指针和一个默认值作为同一类型的参数，如果指针不为零，它就返回引用的值，否则就是默认值。例如，Int32Deref 函数定义如下：

func Int32Deref(ptr *int32, def int32) int32 {
     if ptr != nil {
          return *ptr
     }
     return def
}

然后，你可以这样使用它：

replicas := pointer.Int32Deref(spec.Replicas, 1)

比较两个引用的值

比较两个指针值可能很有用，考虑到如果它们都是 nil，或者它们引用了两个相等的值，那么它们就是相等的。

Int32Equal, Int64Equal, BoolEqual, StringEqual, Float32Equal, Float64Equal, 和 DurationEqual 函数接受两个相同类型的指针，如果这两个指针为 nil，或者它们引用的值相同，则返回真。例如，Int32Equal 函数定义如下：

func Int32Equal(a, b *int32) bool {
     if (a == nil) != (b == nil) {
          return false
     }
     if a == nil {
          return true
     }
     return *a == *b
}

然后，你可以这样使用它：

eq := pointer.Int32Equal(
     spec1.Replicas,
     spec2.Replicas,
)

请注意，要测试一个可选值的平等性，同时考虑其默认值，你应该使用以下方法：

isOne := pointer.Int32Deref(spec.Replicas, 1) == 1

Quantities

Quantities 是一个数字的定点（fixed-point）表示，用于定义要分配的资源数量（例如，内存、CPU等）。Quantities 能代表的最小值是一纳米（10-9）。

在内部，Quantities 由一个Integer（64位）和一个 Scale 表示，或者，如果 int64 不够大，则由一个 inf.Dec 值表示（由软件包定义在 https://github.com/go-inf/inf ）

import (
     "k8s.io/apimachinery/pkg/api/resource"
)

将字符串解析为数量

定义 Quantity 的第一种方法是通过使用以下函数之一从字符串中解析其值：

• func MustParse(str string) Quantity - 从字符串中解析出 Quantity，如果字符串不代表一个 Quantity，则会出现 panic。当你应用一个你知道是有效的硬编码值时，就可以使用它。
• func ParseQuantity(str string) (Quantity, error) - 从字符串中解析 Quantity，如果字符串不代表一个 Quantity，则返回错误。当你不确定该值是否有效时，可以使用该方法。

Quantity 可以用一个符号、一个数字和一个后缀来写。符号和后缀是可选的。后缀可以是二进制，十进制，或十进制指数。

定义的二进制后缀是 Ki (210), Mi (220), Gi (230), Ti (240), Pi (250) 和 Ei (260)。定义的十进制后缀是 n（10-9），u（10-6），m（10-3），""（100），k（103），M（106），G（109），T（1012），P（1015），和E（1018）。十进制指数后缀用 e 或 E 符号书写，后面是十进制指数–例如，E2代表102。

后缀格式（二进制、十进制或十进制指数）被保存在 Quantity 中，并在序列化 Quantity 时使用。

使用这些函数，数量的内部表示方式（要么是按比例的整数，要么是inf.Dec）将根据解析的值是否可以表示为按比例的整数来决定。

使用 inf.Dec 作为Quantity

使用下面的方法来使用 inf.Dec 作为一个Quantity：

• func NewDecimalQuantity(b inf.Dec, format Format) *Quantity - 通过给出一个 inf.Dec 值，并指出你希望它被序列化的后缀格式来声明 Quantity。
• func (q *Quantity) ToDec() *Quantity - 通过解析一个字符串或使用一个新的函数来初始化一个 Quantity，强制将它存储为一个 inf.Dec。
• func (q *Quantity) AsDec() *inf.Dec - 获得一个作为 inf.Dec 的 Quantity 表示，而不修改内部表示。

使用带刻度的整数作为Quantity

使用下面的方法来使用一个带尺度的整数作为 Quantity：

• func NewScaledQuantity(value int64, scale Scale) *Quantity - 通过给出一个 int64 值和一个刻度来声明 Quantity。后缀的格式将是十进制格式。

• func (q *Quantity) SetScaled(value int64, scale Scale) - 用一个带刻度的整数覆盖 Quantity 值。后缀的格式将保持不变。

• func (q *Quantity) ScaledValue(scale Scale) int64 - 获得带刻度的整数表示，考虑到给定的刻度，不修改内部表示。

• func NewQuantity(value int64, format Format) *Quantity - 通过给出一个 int64 的值来声明 Quantity，刻度被固定为0，并且在序列化过程中使用一个后缀格式。

• func (q *Quantity) Set(value int64) - 用一个整数和一个固定为0的刻度来重写 Quantity 值，后缀的格式将保持不变。

• func (q *Quantity) Value() int64 - 获得一个数量的整数表示，比例为0，不修改内部表示。

• func NewMilliQuantity(value int64, format Format) *Quantity - 通过给出一个int64的值来声明 Quantity，比例固定为-3，后缀格式在序列化时使用。

• func (q *Quantity) SetMilli(value int64) - 用整数和固定为-3的刻度重写一个 Quantity 值。

• func (q *Quantity) MilliValue() int64 - 得到 Quantity 的整数表示，比例为-3，不需要修改内部表示。

对Quantity的操作

以下是对 “数量 “进行操作的方法：

• func (q *Quantity) Add(y Quantity) - 将 y Quantity加入到 q Quantity 中。

• func (q *Quantity) Sub(y Quantity) - 从q数量中减去y数量。

• func (q *Quantity) Cmp(y Quantity) int - 比较q和y的数量。如果两个数量相等返回0，如果q大于y返回1，如果q小于y返回-1。

• func (q *Quantity) CmpInt64(y int64) int - 比较q数量和y的整数。如果两个数量相等，返回0；如果q大于y，返回1；如果q小于y，返回1。

• func (q *Quantity) Neg() - 使q成为它的负值。

• func (q 数量) Equal(v 数量) bool - 测试q和v数量是否相等。

IntOrString

Kubernetes 资源的一些字段接受整数值或字符串值。例如，端口可以用端口号或 IANA 服务名称来定义（如https://www.iana.org/assignments/service-names-port-numbers/service-names-port-numbers.xhtml）。

另一个例子是可以接受整数或百分比的字段。

import (
     "k8s.io/apimachinery/pkg/util/intstr"
)

IntOrString结构定义如下：

type IntOrString struct {
     Type   Type
     IntVal int32
     StrVal string
}

TBD

Time

TBD

总结

本章介绍了在Go中定义Kubernetes资源时使用的常见类型。指针值用于指定可选的值，数量用于指定内存和CPU数量，IntOrString类型用于可写为整数或字符串的值（例如，可以通过数字或名称定义的端口），以及时间–一种可序列化的类型，包装Go时间类型。

5.5 - [第5章]API Machinery

前面几章探讨了Kubernetes API在HTTP层面的工作方式。还探讨了 Kubernetes API 库，该库在Go中定义了由 Kubenretes API 提供的资源。

本章探讨了 Kubernetes API Machinery，它提供了用于处理遵循 Kubernetes API 对象约定的API对象的实用工具。这些约定包括：

• API对象嵌入了一个共同的元数据结构体，TypeMeta，包含两个字段： APIVersion 和 Kind。

• API 对象是在一个单独的包中提供的。

• API 对象是有版本的。

• 提供了转换函数来转换不同的版本。

API Machinery 将提供以下实用程序：

• Scheme抽象，用于：

  • 将 API 对象注册为 Group-Version-Kinds

  • 不同版本的API对象之间的转换

  • 对API对象进行序列化/反序列化

• RESTMapper，在 API 对象（基于嵌入式 APIVersion 和 Kind）和资源名称（REST意义上的）之间进行映射。

本章详细介绍了 API Machinery 所提供的功能。

Schema 包

API Machinery 的 schema 包定义了有用的结构体和函数来处理分组、版本、种类和资源。

import (
    "k8s.io/apimachinery/pkg/runtime/schema"
)

定义了 GroupVersionResource、GroupVersionKind、GroupVersion、GroupResource 和 GroupKind 结构，以及从一个到另一个的转换方法。

此外，还提供了在 GroupVersionKind 和（apiVersion, kind）之间转换的函数： ToAPIVersionAndKind 和 FromAPIVersionAndKind。

Scheme

Scheme 是一个抽象概念，用于将 API 对象注册为 Group-Version-Kinds，在不同版本的 API 对象之间进行转换，并将 API 对象序列化/反序列化。Scheme 是由运行时包中的 API Machinery 提供的一个结构体。这个结构体的所有字段都是未导出（unexported）的。

初始化

Scheme 结构体可以通过 NewScheme 函数进行初始化：

import (
    "k8s.io/apimachinery/pkg/runtime"
)
Scheme := runtime.NewScheme()

在结构体被初始化后，你可以用 AddKnownTypes 方法注册新的 API 对象，方法如下：

func (s *Scheme) AddKnownTypes(gv schema.GroupVersion, types ...Object)

例如，为了将 Pod 和 ConfigMap 对象注册到 core/v1 分组，你可以使用：

import (
    corev1 "k8s.io/api/core/v1"
    "k8s.io/apimachinery/pkg/runtime"
    "k8s.io/apimachinery/pkg/runtime/schema"
)
Scheme := runtime.NewScheme()
func init() {
     Scheme.AddKnownTypes(
        schema.GroupVersion{
            Group:   "",
            Version: "v1",
        },
        &corev1.Pod{},
        &corev1.ConfigMap{},
     )
}