译者：安雪艳 校对：无

Kubernetes API

用户指南记录了主系统和API概念。

API规范文档描述了API整体规范。

Kubernetes通过Swagger记录API所有细节。Kubernetes apiserver (aka "master")提供了一个API接口用于获取Kubernetes API的Swagger spec，默认在路径/swaggerapi下，/swagger-ui是可以使用浏览器查看API文档的UI 。我们会定期更新静态生成UI。

远程访问API在访问文档有讨论。

Kubernetes API是系统描述性配置的基础。 Kubectl命令行工具被用于创建，更新，删除，获取API对象。

Kubernete通过API资源存储自己序列化状态(现在存储在etcd)。

Kubernetes被分成多个组件，各部分通过API相互交互。

API更改

根据经验，任何成功的系统都需要成长和改变，可能是一个新的示例出现，也可能是对已有系统进行更改。因此，我们希望Kubernetes API也可以持续的改变和成长。在较长一段时间内，我们不打算中断已有客户端。一般情况，经常会有新的API资源和新的资源字段增加。删除资源或者字段会有一个跟踪废弃流程。删除功能有一个小的废弃策略叫做TBD，但是Kubernetes到达1.0版本时，将会有一个详细的策略代替。

如何构成一个兼容性的改变以及如何更改API的详细信息都在API变化文档

API版本

为了使删除字段或者重构资源表示更加容易，Kubernetes支持多个API版本。每一个版本都在不同API路径下，例如 /api/v1 或者/apis/extensions/v1beta1.

我们选择版本时时根据API而不是根据资源或者字段来确认的，API为系统资源和行为提供了一个清晰的，一致性的视图，并且可以控制访问生命周期结束和／或测试的APIs。

注意API版本控制和软件版本控制只能间接的相关联。文档API and release versioning proposal 描述了API版本控制和软件版本控制两者之间的关系。

不同的API版本会有不同级别的稳定性和支持。每个级别的详细描述包含在文档API Changes documentation中。 内容主要概括如下：

  • Alpha 级别:
    • 版本名称包含了 alpha (e.g. `v1alpha1).
    • 可能是有问题的。实现的功能可能隐含问题，功能默认是不可用的。
    • 支持的功能可能在没有通知的情况下随时删除。
    • API的更改可能存在冲突，但是在后续的软件发布中不会有任何通知。
    • 由于bugs风险的增加和缺乏长期的支持，推荐在短暂的集群测试中使用。
  • Beta 级别:
    • 版本名称包含了 beta (e.g. v2beta3).
    • 代码已经测试过。实现的功能认为是安全的，功能默认是可用的。
    • 所有已支持的功能不会被删除，细节可能会发生变化。
    • 对象的模式和／或定义在随后的beta版本或者稳定版本可能以不兼容的方式改变。在这种情况下，Kubernetes会提供合并到下一个版本的指南。这一过程中可能会要求删除，编译和重新创建API对象。编译过程中可能会要求一些选择。根据不同的功能可能会需要一些应用的下载时间。
    • 在随后的发布中存在一些非兼容性的更改，所已推荐在不重要的非商业化的情况下使用。如果你已经有多个集群，并且可以单独更新，你可以放宽这个限制。
    • 请尝试我们的bete版本功能并且给出反馈！因为已经是beta版本，对于我们来说太多的更改可能不太实用
  • Stable 级别:
    • 版本名称中包含 vX 这里的X是一个整数.
    • 稳定版本的功能在后续的版本发布中会一直存在。

API群组

为了使扩展Kubernetes API更加简单，我们正在实现API groups. API群组是一些可以读和／或更改相同基础资源的简单的不同的接口。API群组被定义在一个REST路径下，在apiVersion的一个序列化对象的字段。

当前有两个API群组在使用：

  1. "core"群组，在REST路径/api/v1下，但不是apiVersion字段的一部分。e.g. apiVersion: v1。
  2. "extensions"群组, 在REST路径/apis/extensions/$VERSION下, 并且使用apiVersion: extensions/$VERSION(e.g. 当前是apiVersion: extensions/v1beta1).

未来我们希望有更多的API群组，并且所有的群组都在REST路径 /apis/$API_GROUP下，并且使用apiVersion: $API_GROUP/$VERSION。我们希望将来有一种方式支持三方可以创建自己的API groups，并且可以避免命名冲突。

扩展资源

默认情况下Jobs, Ingress和HorizontalPodAutoscalers都是可用的。其他的扩展资源通过设置apiserver的runtime-config使其可用。runtime-config多个值可通过都逗号分开。例如：设置部署可用，jobs不可用命令，--runtime-config=extensions/v1beta1/deployments=true,extensions/v1beta1/jobs=false

v1beta1, v1beta2, and v1beta3已经废弃；请转到v1 ASAP

2015年6月4日，Kubernetes v1 API已经默认可以使用。v1beta1和v1beta2 APIs在2015年6月1日删除。v1beta3计划会在2015年6月6日删除。

v1转换技巧(从v1beta3)

我们已经将所有文档和例子转换成v1版本。并且写了一个简单的 API转换工具来进行简单的转换。使用kubectl create --validate命令可以使你的json或者yaml按照Swagger spec规范有效。

v1beta3和v1版本之间最重要的不同是服务的改变。

  • service.spec.portalIP属性重命名为service.spec.clusterIP。
  • service.spec.createExternalLoadBalancer已经被删除。 定义了service.spec.type: "LoadBalancer"来代替，用于创建外部负载均衡。
  • service.spec.publicIPs属性已经被废弃，现在叫做service.spec.deprecatedPublicIPs。当v1beta3删除时，这个属性也会被完全删除。这个字段的多数用户使用这个字段来公开nodes上的services端口。现在这些用户应该使用service.spec.type: "NodePort"来代替。 获取更多信息可阅读External Services。如果这些还是不能满足你的需求，请提交issue或者联系@thockin。

v1beta3和v1版本之间其他的不同：

  • pod.spec.containers[*].privileged和pod.spec.containers[*].capabilities属性已经合并到pod.spec.containers[*].securityContext属性。可以查看文档Security Contexts。
  • pod.spec.host属性被重命名为pod.spec.nodeName。
  • endpoints.subsets[*].addresses.IP被重命名为endpoints.subsets[*].addresses.ip。
  • pod.status.containerStatuses[*].state.termination和pod.status.containerStatuses[*].lastState.termination属性被分别重命名为pod.status.containerStatuses[*].state.terminated和pod.status.containerStatuses[*].lastState.terminated。
  • pod.status.Condition属性被重命名为pod.status.conditions。
  • status.details.id属性被重命名为status.details.name。

v1beta3转换技巧(从v1beta1/2)

v1beta1/2和v1beta3重要不同点:

  • 资源id现在称作``name```.
  • name，labels，annotations，和其他元数据现在内嵌在一个称作metadata的map中
  • desiredState 现在称作spec，currentState 现在称作`status
  • /minions 已经被移到/nodes, 且资源包括各种 Node
  • namesapce是必要条件(对于所有资源namesapce)且已经从一个URL参数改为路径：/api/v1beta3/namespaces/{namespace}/{resource_collection}/{resource_name}. 如果之前你没有使用过namespace，在这可以使用default.
  • 所有资源收集器的名字已经小写 - 已经废弃 replicationControllers，使用 `replicationcontrollers来代替。
  • 查看某个资源的改变，可打开一个HTTP或者Websocket连接查询，并且提供?watch=true请求参数和resourceVersion参数进行查询。
  • labels查询参数已经被重命名为labelSelector。
  • fields查询参数已经被重命名为fieldSelector。
  • Container中的entrypoint已经被重命名为command，而command被重命名为args.
  • Container, volume, and node资源的定义已经被内嵌到一个maps (e.g., resources{cpu:1})并没有作为独立的字段，并且资源数值支持后缀而不是固定的(e.g., milli-cores)。
  • 重新启动策略简单的表示为字串(e.g., "Always")而不是作为一个内嵌的map(always{}).
  • Pull策略从PullAlways, PullNever，和PullIfNotPresent变成了Always，Never，和IfNotPresent。
  • volume source被内联到volume而非嵌套。
  • 宿主机volumes已经从hostDir变成了hostPath，这样做的好处是，挂载的可以是一个文件也可以是一个路径。