API 参考

概述

参考：

在本部分笔记后面的章节，各资源 Manifest 详解，其实已经描述了 API 中各个字段的含义。所以本篇文章不会详解每个 API，而是记录一下如何通过 Kubernetes 官网来查找 API 详解，以及如何使用官方文档查看 API 详解。

如果笔记中记录得不够详细，kubectl explain 命令也看着不方便，那么通过这篇文章中介绍的官方文档中的 API 详解来查看，将会更加直观。

Kubernetes API 参考中将会描述每种资源的 Manifests 中每个字段(即.YAML 中的节点)的含义。

这是单一页面的样子。左侧是根据对资源的分类而形成的目录，右侧是完整的页面

这是多级页面的样子，该 API 详解是内含在官方文档中的，并且对 API 进行了细致的分类

字段的类型占位符

官方文档中，将每个字段的类型，放在字段名称后面的 () 中，效果如图：

image.png

详见：YAML 中关于对各种文档的使用说明示例。

下面是几种基本的类型介绍：

[]TYPE # 基本数组组成，数组元素类型为 TYPE，比如 []STRING 格式应该就是下面这样

args:
  - deletecr
  - --ns
  - --name

OBJECT # 基本对象类型，也称为 Mapping 类型。

resources:
  limits:
    cpu: "2"
    memory: 2Gi
  requests:
    cpu: 500m
    memory: 400Mi

[]OBJECT # 数组中的元素是对象的特殊类型

containers:
  - args:
      - AAA
      - BBB
    name: XXX
    image: XXX
  - name: YYY
    image: YYY

map[STRING]STRING # 特殊的对象类型。键 和 值 的数据类型都是 STRING

labels:
  key1: value1
  key2: value2

API 分类

在每种资源的 Manifests 中，会有一些共用的部分称为 Common Definitions(通用定义)（也可以说是功能定义），比如常见的 LabelSelector，这属于资源的 Manifests 的一部分。很多组件在解析 Manifests 中的通用定义时，都会遵循相同的规则。除了通用定义以外的，都属于 K8S 的资源定义，比如定义 Pod 的 API 参考、定义 Service 的 API 参考等等。

Config and Storage Resources

ConfigMap

ConfigMap holds configuration data for pods to consume.

Secret

Secret holds secret data of a certain type.

Volume

Volume represents a named volume in a pod that may be accessed by any container in the pod.

PersistentVolumeClaim

PersistentVolumeClaim is a user’s request for and claim to a persistent volume.

PersistentVolume

PersistentVolume (PV) is a storage resource provisioned by an administrator.

StorageClass

StorageClass describes the parameters for a class of storage for which PersistentVolumes can be dynamically provisioned.

VolumeAttachment

VolumeAttachment captures the intent to attach or detach the specified volume to/from the specified node.

CSIDriver

CSIDriver captures information about a Container Storage Interface (CSI) volume driver deployed on the cluster.

CSINode

CSINode holds information about all CSI drivers installed on a node.

CSIStorageCapacity v1beta1

CSIStorageCapacity stores the result of one CSI GetCapacity call.

Authentication Resources

ServiceAccount

ServiceAccount binds together: a name, understood by users, and perhaps by peripheral systems, for an identity a principal that can be authenticated and authorized * a set of secrets.

TokenRequest

TokenRequest requests a token for a given service account.

TokenReview

TokenReview attempts to authenticate a token to a known user.

CertificateSigningRequest

CertificateSigningRequest objects provide a mechanism to obtain x509 certificates by submitting a certificate signing request, and having it asynchronously approved and issued.

Authorization Resources

LocalSubjectAccessReview

LocalSubjectAccessReview checks whether or not a user or group can perform an action in a given namespace.

SelfSubjectAccessReview

SelfSubjectAccessReview checks whether or the current user can perform an action.

SelfSubjectRulesReview

SelfSubjectRulesReview enumerates the set of actions the current user can perform within a namespace.

SubjectAccessReview

SubjectAccessReview checks whether or not a user or group can perform an action.

ClusterRole

ClusterRole is a cluster level, logical grouping of PolicyRules that can be referenced as a unit by a RoleBinding or ClusterRoleBinding.

ClusterRoleBinding

ClusterRoleBinding references a ClusterRole, but not contain it.

Role

Role is a namespaced, logical grouping of PolicyRules that can be referenced as a unit by a RoleBinding.

RoleBinding

RoleBinding references a role, but does not contain it.

Policies Resources

LimitRange

LimitRange sets resource usage limits for each kind of resource in a Namespace.

ResourceQuota

ResourceQuota sets aggregate quota restrictions enforced per namespace.

NetworkPolicy

NetworkPolicy describes what network traffic is allowed for a set of Pods.

PodDisruptionBudget

PodDisruptionBudget is an object to define the max disruption that can be caused to a collection of pods.

PodSecurityPolicy v1beta1

PodSecurityPolicy governs the ability to make requests that affect the Security Context that will be applied to a pod and container.

Extend Resources

CustomResourceDefinition

CustomResourceDefinition represents a resource that should be exposed on the API server.

MutatingWebhookConfiguration

MutatingWebhookConfiguration describes the configuration of and admission webhook that accept or reject and may change the object.

ValidatingWebhookConfiguration

ValidatingWebhookConfiguration describes the configuration of and admission webhook that accept or reject and object without changing it.

Cluster Resources

Node

Node is a worker node in Kubernetes.

Namespace

Namespace provides a scope for Names.

Event

Event is a report of an event somewhere in the cluster.

APIService

APIService represents a server for a particular GroupVersion.

Lease

Lease defines a lease concept.

RuntimeClass

RuntimeClass defines a class of container runtime supported in the cluster.

FlowSchema v1beta1

FlowSchema defines the schema of a group of flows.

PriorityLevelConfiguration v1beta1

PriorityLevelConfiguration represents the configuration of a priority level.

Binding

Binding ties one object to another; for example, a pod is bound to a node by a scheduler.

ComponentStatus

ComponentStatus (and ComponentStatusList) holds the cluster validation info.

Kubernetes API 删除和弃用流程

参考：

Kubernetes 项目有一个记录良好的特性弃用策略[1]。该策略规定，只有当同一 API 的更新的、稳定的版本可用时，才可以弃用稳定的 API，并且 API 对于每个稳定性级别都有一个最短的生存期。给弃用的 API，是在未来的 Kubernetes 版本中被标记为删除的 API；它将继续运行，直到给删除（从弃用至少一年），但使用将导致显示警告。删除的 API 在当前版本中不再可用，此时你必须迁移到使用替换的 API。

  • GA（Generally available，普遍可用）或稳定的 API 版本可能会被标记为弃用，但不得在 Kubernetes 的主要版本中删除。
  • 测试版或预发布 API 版本弃用后，必须支持 3 个版本。
  • Alpha 或实验 API 版本可能会在任何版本中被删除，恕不另行通知。

无论某个 API 是因为某个功能从测试版升级到稳定版而被删除，还是因为该 API 没有成功，所有的删除都遵循这个弃用策略。每当删除一个 API 时，迁移选项都会在文档中提供说明。


最后修改 August 22, 2024: kubernetes (84b81f69)