Kubernetes API 使用指南

Kubernetes API 使用文档
https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.10/

API 概述

※ 资源分类

这是对 Kubernetes API 及其主要功能提供的基本资源类型的高级概述。

• Workloads： 用于在集群中管理和运行容器；
• Discovery & LB：用于将 Workloads “缝合”到一个可从外部访问的负载均衡的服务中；
• Config & Storage：用于将初始化数据注入到应用程序中，并保留容器外部的数据；
• Cluster：用于定义如何配置集群，这些通常仅由集群运营商使用；
• Metadata：用于配置群集内其他资源的行为，例如用于扩展 Workloads 的 Horizo​​ntalPodAutoscaler

※ 资源对象

资源对象通常包含3个组件：

• ResourceSpec：这由用户定义并描述系统所期望的状态，在创建或更新对象时填写；
• ResourceStatus：这由服务器填写并报告系统的当前状态，只有 Kubernetes 组件才能填写此内容；
• Resource ObjectMeta：这是关于资源的元数据，例如 name / type / api version / annotations / labels，包含可能由后端用户和系统更新的字段（如 annotations）

※ 资源操作

大部分资源提供如下操作：

▶ Create

Create 操作会在存储后端创建资源。资源创建后，系统将应用所期望的状态。

▶ Update

更新有 2 种形式：Replace 和 Patch

Replace：替换资源对象将通过提供的 spec 替换现有的 spec 来更新资源。对于读写操作，这是安全的，因为如果资源在读和写之间被修改，则会发生乐观锁定失败。注意：ResourceStatus 将被系统忽略，并且不会被更新，要更新状态，必须调用特定的状态更新操作。

注意：替换资源对象可能不会立即传播到下游对象。例如，替换 ConfigMap 或 Secret 资源不会导致所有 Pod 看到更改，除非 Pod 在带外重新启动。

Patch：Patch 会更改特定字段，如何合并更改是每个字段定义的。列表可以被替换或合并，合并列表不会保留排序。

Patch 操作永远不会导致乐观锁定失败，并且最后一次写入会获胜。如果在更新之前未读取完整状态，或者乐观锁定失败不可取，则建议使用 patch 操作。修补复杂 types、arrays 和 maps 时，如何应用修补程序是以每个字段为基础定义的，并可以替换字段的当前值，也可以将内容合并到当前值中。

▶ Read

读取有 3 种方式：Get 、 List 和 Watch

Get： 按名称检索特定的资源对象；

List：检索命名空间内特定类型的所有资源对象，并且结果可以限制为与选择器查询结果匹配的资源；

List All Namespaces：像 List 一样，但是跨所有命名空间检索资源；

Watch：Watch 将在对象更新时汇出结果，类似于回调，watch 用于响应资源的更改。

▶ Delete

Delete 将删除资源。根据特定的资源，子对象可能会或可能不会被服务器当做垃圾收集，详情请参阅特定资源对象的注释。

▶ 额外操作

资源可以定义特定于该资源类型的附加操作。

Rollback：将 PodTemplate 回滚到以前的版本，仅适用于某些资源类型；

Read / Write Scale：读取或更新给定资源的副本数量，仅适用于某些资源类型；

Read / Write Status：读取或更新资源对象的状态，状态只能通过这些更新操作进行更改。

WORKLOADS

Workloads 资源负责管理和运行集群上的容器。容器（Containers）由控制器（Controllers）通过 Pod 创建，Pods 运行容器并提供环境依赖，如注入到容器中的共享或永久存储卷、配置或加密数据。

最常见的控制器是：

• Deployments 无状态持久应用（如 http servers）
• StatefulSets 有状态持久应用（如 database）
• Jobs 运行至完成的应用 （如 batch jobs）

DISCOVERY & LOAD BALANCING

Discovery and Load Balancing 负责将 Workloads “缝合” 到一个可从外部访问的负载均衡的服务中。默认情况下，Workloads 只能在群集内访问，它们必须通过 LoadBalancer 或 NodePort Service 暴露到外部。对于开发，可以使用 kubectl proxy 命令通过代理 api 主机访问内部可访问的 Workloads 。

常用的资源类型：

• Services 提供跨多个 Workload 副本的负载均衡的单个 IP 端点。
• Ingress 提供路由到一个或多个服务的https(s) 端点

CONFIG & STORAGE

Config and Storage 资源负责将数据注入到应用程序中，并保留容器外部的数据。

常用的资源类型：

• ConfigMaps 通过环境变量、命令行参数或文件提供注入应用的 K-V 键值对
• Secrets 通过文件提供注入应用的二进制数据
• Volumes 提供容器外部的文件系统。 可能在同一个 Pod 中跨 Container 容器共享，并且其寿命持续超出 Container 或 Pod。

METADATA

Metadata resources 负责集群内其他资源的行为。

常用的资源类型：

• HorizontalPodAutoscaler 自动缩放 workloads 的副本数量以响应加载
• PodDisruptionBudget 在执行维护时，可以配置给定 workloads 中的多少副本可能同时不可用
• ThirdPartyResource 使用自己的类型扩展Kubernetes API
• Event 群集中资源生命周期事件的通知

API 调用方式

▶ kubectl

示例：创建 Deployment

$ echo 'apiVersion: apps/v1
kind: Deployment
metadata:
  name: deployment-example
spec:
  replicas: 3
  revisionHistoryLimit: 10
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx:1.10
        ports:
        - containerPort: 80
' | kubectl create -f -

yaml 文件编写的规则拆解如下图：

其他资源的创建或其他操作，都可以按照这种方式来操作。

▶ curl

需要使用 kubectl proxy

$ kubectl proxy
$ curl -X POST -H 'Content-Type: application/yaml' --data '
apiVersion: apps/v1beta1
kind: Deployment
metadata:
  name: deployment-example
spec:
  replicas: 3
  revisionHistoryLimit: 10
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx:1.10
        ports:
        - containerPort: 80
' http://127.0.0.1:8001/apis/apps/v1/namespaces/default/deployments