Kubernetes API

• 1: 公共定义
• 1.1: 删除选项
• 1.2: 标签选择器
• 1.3: ListMeta
• 1.4: LocalObjectReference
• 1.5: NodeSelectorRequirement
• 1.6: ObjectFieldSelector
• 1.7: ObjectReference
• 1.8: Patch
• 1.9: Quantity
• 1.10: ResourceFieldSelector
• 1.11: TypedLocalObjectReference

1 - 公共定义

1.1 - 删除选项

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

删除 API 对象时可能会提供 DeleteOptions。

• apiVersion (string)

  APIVersion 定义对象表示的版本化模式。 服务器应将已识别的模式转换为最新的内部值，并可能拒绝无法识别的值。 更多信息：https ://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources

• dryRun ([]string)

  该值如果存在，则表示不应保留修改。 无效或无法识别的 dryRun 指令将导致错误响应并且不会进一步处理请求。有效值为：

  • All：处理所有试运行阶段（Dry Run Stages）

• gracePeriodSeconds (int64)

  表示对象被删除之前的持续时间（以秒为单位）。 值必须是非负整数。零值表示立即删除。如果此值为 nil，则将使用指定类型的默认宽限期。如果未指定，则为每个对象的默认值。

• kind (string)

  kind 是一个字符串值，表示此对象代表的 REST 资源。 服务器可以从客户端提交请求的端点推断出此值。此值无法更新，是驼峰的格式。 更多信息：https ://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds 。

• orphanDependents (boolean)

  已弃用：该字段将在 1.7 中弃用，请使用 propagationPolicy 字段。 该字段表示依赖对象是否应该是孤儿。如果为 true/false，对象的 finalizers 列表中会被添加上或者移除掉 “orphan” 终结器（Finalizer）。 可以设置此字段或者设置 propagationPolicy 字段，但不能同时设置以上两个字段。

• preconditions (Preconditions)

  先决条件必须在执行删除之前完成。如果无法满足这些条件，将返回 409（冲突）状态。

  执行操作（更新、删除等）之前必须满足先决条件。

  • preconditions.resourceVersion (string)

    指定目标资源版本（resourceVersion）。

  • preconditions.uid (string)

    指定目标 UID.

• propagationPolicy (string)

  表示是否以及如何执行垃圾收集。可以设置此字段或 orphanDependents 字段，但不能同时设置二者。 默认策略由 metadata.finalizers 中现有终结器（Finalizer）集合和特定资源的默认策略决定。 可接受的值为： Orphan - 令依赖对象成为孤儿对象；Background - 允许垃圾收集器在后台删除依赖项；Foreground - 一个级联策略，前台删除所有依赖项。

1.2 - 标签选择器

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

标签选择器是对一组资源的标签查询。

matchLabels 和 matchExpressions 的结果按逻辑与的关系组合。一个 empty 标签选择器匹配所有对象。一个 null 标签选择器不匹配任何对象。

• matchExpressions ([]LabelSelectorRequirement)

  matchExpressions 是 LabelSelectorRequirement 的列表，这些需求结果按逻辑与的关系来计算。

  标签选择器要求是包含值、键和关联键和值的运算符的选择器。

  • matchExpressions.key (string)， 必填

    补丁策略: 按照键 key 合并

    key 是选择器应用的标签键.

  • matchExpressions.operator (string)，必填

    operator 表示键与一组值的关系。有效的运算符包括 In、NotIn、Exists 和 DoesNotExist。

  • matchExpressions.values ([]string)

    values 是一个字符串值数组。如果运算符为 In 或 NotIn，则 values 数组必须为非空。

    如果运算符是 Exists 或 DoesNotExist，则 values 数组必须为空。

    该数组在战略性补丁（Strategic Merge Patch）期间被替换。

• matchLabels (map[string]string)

  matchLabels 是 {key,value} 键值对的映射。

  matchLabels 映射中的单个 {key,value} 键值对相当于 matchExpressions 的一个元素，其键字段为 key，运算符为 In，values 数组仅包含 value。

  所表达的需求最终要按逻辑与的关系组合。

1.3 - ListMeta

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

ListMeta 描述了合成资源必须具有的元数据，包括列表和各种状态对象。 一个资源仅能有 {ObjectMeta, ListMeta} 中的一个。

• continue (string)

  如果用户对返回的条目数量设置了限制，则 continue 可能被设置，表示服务器有更多可用的数据。 该值是不透明的，可用于向提供此列表服务的端点发出另一个请求，以检索下一组可用的对象。 如果服务器配置已更改或时间已过去几分钟，则可能无法继续提供一致的列表。 除非你在错误消息中收到此令牌（token），否则使用此 continue 值时返回的 resourceVersion 字段应该和第一个响应中的值是相同的。

• remainingItemCount (int64)

  remainingItemCount 是列表中未包含在此列表响应中的后续项目的数量。 如果列表请求包含标签或字段选择器，则剩余项目的数量是未知的，并且在序列化期间该字段将保持未设置和省略。 如果列表是完整的（因为它没有分块或者这是最后一个块），那么就没有剩余的项目，并且在序列化过程中该字段将保持未设置和省略。 早于 v1.15 的服务器不设置此字段。remainingItemCount 的预期用途是估计集合的大小。 客户端不应依赖于设置准确的 remainingItemCount。

• resourceVersion (string)

  标识该对象的服务器内部版本的字符串，客户端可以用该字段来确定对象何时被更改。 该值对客户端是不透明的，并且应该原样传回给服务器。该值由系统填充，只读。 更多信息：https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#concurrency-control-and-consistency。

• selfLink (string)

  selfLink 表示此对象的 URL，由系统填充，只读。

  已弃用。 Kubernetes 将在 1.20 版本中停止传播该字段，并计划在 1.21 版本中删除该字段。

1.4 - LocalObjectReference

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

LocalObjectReference 包含足够的信息，可以让你在同一命名空间（namespace）内找到引用的对象。

• name (string)

  被引用者的名称。 更多信息: https://kubernetes.io/zh/docs/concepts/overview/working-with-objects/names/#names。

1.5 - NodeSelectorRequirement

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

节点选择器是要求包含键、值和关联键和值的运算符的选择器。

• key (string), 必选

  选择器适用的标签键。

• operator (string), 必选

  表示键与一组值的关系的运算符。有效的运算符包括：In、NotIn、Exists、DoesNotExist、Gt 和 Lt。

  可选值:

  • "DoesNotExist"
  • "Exists"
  • "Gt"
  • "In"
  • "Lt"
  • "NotIn"

• values ([]string)

  字符串数组。如果运算符为 In 或 NotIn，则数组必须为非空。 如果运算符为 Exists 或 DoesNotExist，则数组必须为空。 如果运算符为 Gt 或 Lt，则数组必须有一个元素，该元素将被译为整数。 该数组在合并计划补丁时将被替换。

1.6 - ObjectFieldSelector

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

ObjectFieldSelector 选择对象的 APIVersioned 字段。

• fieldPath (string), 必需的

  在指定 API 版本中要选择的字段的路径。

• apiVersion (string)

  fieldPath 写入时所使用的模式版本，默认为 "v1"。

1.7 - ObjectReference

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

ObjectReference包含足够的信息，允许你检查或修改引用的对象。

• apiVersion (string)

  被引用者的 API 版本。

• fieldPath (string)

  如果引用的是对象的某个对象是整个对象，则该字符串而不是应包含的 JSON/Go 字段有效访问语句， 例如desiredState.manifest.containers[ 2 ]。例如，如果对象引用针对的是 Pod 中的一个容器， 此字段取值类似于：spec.containers{name}（name指触发的容器的名称）， 或者如果没有指定容器名称，spec.containers[ 2 ]（此Pod中索引为2的容器）。 选择这种只是为了有一些定义好的语法来引用对象的部分。

• kind (string)

  被引用者的类别（kind）。 更多信息：https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md #types-kinds

• name (string)

  被引用对象的名称。更多信息：https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names

• namespace (string)

  被引用对象的名字空间。更多信息：https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/

• resourceVersion (string)

  被引用对象的特定资源版本（如果有）。更多信息：https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#concurrency-control-and-consistency

• uid (string)

  被引用对象的UID。更多信息：https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#uids

1.8 - Patch

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

提供 Patch 是为了给 Kubernetes PATCH 请求正文提供一个具体的名称和类型。

1.9 - Quantity

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

数量（Quantity）是数字的定点表示。 除了 String() 和 AsInt64() 的访问接口之外， 它以 JSON 和 YAML形式提供方便的打包和解包方法。

序列化格式如下：

<quantity>        ::= <signedNumber><suffix>
  (注意 <suffix> 可能为空, 例如 <decimalSI> 的 "" 情形。) </br>
<digit>           ::= 0 | 1 | ... | 9 </br>
<digits>          ::= <digit> | <digit><digits> </br>
<number>          ::= <digits> | <digits>.<digits> | <digits>. | .<digits> </br>
<sign>            ::= "+" | "-" </br>
<signedNumber>    ::= <number> | <sign><number> </br>
<suffix>          ::= <binarySI> | <decimalExponent> | <decimalSI> </br>
<binarySI>        ::= Ki | Mi | Gi | Ti | Pi | Ei 
  (国际单位制度；查阅：http://physics.nist.gov/cuu/Units/binary.html) </br>
<decimalSI>       ::= m | "" | k | M | G | T | P | E 
  (注意，1024 = 1ki 但 1000 = 1k；我没有选择大写。) </br>
<decimalExponent> ::= "e" <signedNumber> | "E" <signedNumber> </br>

无论使用三种指数形式中哪一种，没有数量可以表示大于 2⁶³-1 的数，也不可能超过 3 个小数位。 更大或更精确的数字将被截断或向上取整。（例如：0.1m 将向上取整为 1m。） 如果将来我们需要更大或更小的数量，可能会扩展。

当从字符串解析数量时，它将记住它具有的后缀类型，并且在序列化时将再次使用相同类型。

在序列化之前，数量将以“规范形式”放置。这意味着指数或者后缀将被向上或向下调整（尾数相应增加或减少），并确保：

1. 没有精度丢失
2. 不会输出小数数字
3. 指数（或后缀）尽可能大。 除非数量是负数，否则将省略正负号。

例如：

• 1.5 将会被序列化成 “1500m”
• 1.5Gi 将会被序列化成 “1536Mi”

请注意，数量永远不会在内部以浮点数表示。这是本设计的重中之重。

只要它们格式正确，非规范值仍将解析，但将以其规范形式重新输出。（所以应该总是使用规范形式，否则不要执行 diff 比较。）

这种格式旨在使得很难在不撰写某种特殊处理代码的情况下使用这些数字，进而希望实现者也使用定点实现。

1.10 - ResourceFieldSelector

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

ResourceFieldSelector 表示容器资源（CPU，内存）及其输出格式。

• resource (string), 必选

  必选：选择的资源

• containerName (string)

  容器名称：对卷必选，对环境变量可选

• divisor (Quantity)

  指定所曝光资源的输出格式，默认值为“1”

1.11 - TypedLocalObjectReference

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

TypedLocalObjectReference 包含足够的信息，可以让你在同一个名称空间中定位特定类型的引用对象。

• kind (string), 必需

  Kind 是被引用的资源的类型

• name (string), 必需

  Name 是被引用的资源的名称

• apiGroup (string)

  APIGroup 是被引用资源的组。如果不指定 APIGroup，则指定的 Kind 必须在核心 API 组中。对于任何其它第三方类型，都需要 APIGroup。