作者：Jordan Liggitt（谷歌）

作为Kubernetes的维护者，咱们始终在寻找在放弃兼容性的同时进步可用性的办法。在开发个性、分类bug和答复反对问题的过程中，咱们积攒了有助于Kubernetes用户理解的信息。在过来，信息的共享仅限于公布阐明、布告电子邮件、文档和博客文章等内部办法。除非有人晓得该信息并设法找到它，否则他们不会从中受害。

在Kubernetes v1.19中，咱们增加了一个个性，容许Kubernetes API服务器向API客户机发送正告。正告是应用规范的Warning响应头发送的，因而它不会以任何形式更改状态代码或响应体。这容许服务器发送正告，任何API客户端都能够轻松读取，同时放弃与以前的客户端版本兼容。

正告在kubectl v1.19+的stderr输入和k8s.io/client-go客户端库v0.19.0+的日志输入。k8s.io/client-go的设定能够按过程或按客户端笼罩。

弃用的正告

咱们应用这个新性能的第一种形式是，对应用已弃用的API（deprecated API）发送正告。

Kubernetes是一个疾速倒退的大型项目。即便对于全职从事我的项目的人来说，跟上每个版本中的变动也是一件令人生畏的事件。一种重要的扭转是API的弃用。随着Kubernetes中的API降级到GA版本，预公布的API版本将被弃用并最终被删除。

即便有一个缩短的弃用期，并且在公布阐明中蕴含了弃用，它们依然很难跟踪。在弃用期间，预公布API依然无效，容许多个版本转换为稳固的API版本。然而，咱们发现，用户通常甚至没有意识到他们所依赖的API版本曾经弃用，直到他们降级到不再提供它的版本。

从v1.19开始，每当向弃用的REST API发出请求时，都会在API响应的同时返回一个正告。此正告包含无关API将不再可用的版本的详细信息，以及替换的API版本。

因为正告来自服务器，在客户端被拦挡，所以它实用于所有的kubectl命令，包含像kubectl apply这样的高级命令，和像kubectl get --raw这样的低级命令：

这有助于受弃用影响的人晓得他们收回的申请已被弃用，他们须要多长时间来解决这个问题，以及他们应该应用什么API来代替。当用户利用本人没有创立的清单时，这尤其有用，这样他们就有工夫分割作者，要求更新版本。

咱们还意识到，应用已弃用API的人通常不是负责降级集群的同一个人，因而咱们增加了两个面向管理员的工具，以帮忙跟踪已弃用API的应用状况，并确定何时降级是平安的。

指标

从Kubernetes v1.19开始，当向已弃用的REST API端点发出请求时，在kube-apiserver过程中将apiserver_requested_deprecated_apis度量指标设置为1。此指标具备API group、version、resource、subresource的标签，以及一个removed_version标签，该标签批示不再提供API的Kubernetes版本。

这是一个应用kubectl、prom2json和jq的示例查问，用于确定API服务器的以后实例申请了哪些弃用的API：

kubectl get --raw /metrics | prom2json | jq '  .[] | select(.name=="apiserver_requested_deprecated_apis").metrics[].labels'

输入：

{  "group": "extensions",  "removed_release": "1.22",  "resource": "ingresses",  "subresource": "",  "version": "v1beta1"}{  "group": "rbac.authorization.k8s.io",  "removed_release": "1.22",  "resource": "clusterroles",  "subresource": "",  "version": "v1beta1"}

这显示了弃用的extensions/v1beta1 Ingress和rbac.authorization.k8s.io/v1beta1 ClusterRole API在此服务器上被申请，将在v1.22中被删除。

咱们能够将这些信息与apiserver_request_total指标连接起来，以取得对于向这些API收回的申请的更多细节：

kubectl get --raw /metrics | prom2json | jq '  # set $deprecated to a list of deprecated APIs  [    .[] |     select(.name=="apiserver_requested_deprecated_apis").metrics[].labels |    {group,version,resource}  ] as $deprecated     |    # select apiserver_request_total metrics which are deprecated  .[] | select(.name=="apiserver_request_total").metrics[] |  select(.labels | {group,version,resource} as $key | $deprecated | index($key))'

输入：

{  "labels": {    "code": "0",    "component": "apiserver",    "contentType": "application/vnd.kubernetes.protobuf;stream=watch",    "dry_run": "",    "group": "extensions",    "resource": "ingresses",    "scope": "cluster",    "subresource": "",    "verb": "WATCH",    "version": "v1beta1"  },  "value": "21"}{  "labels": {    "code": "200",    "component": "apiserver",    "contentType": "application/vnd.kubernetes.protobuf",    "dry_run": "",    "group": "extensions",    "resource": "ingresses",    "scope": "cluster",    "subresource": "",    "verb": "LIST",    "version": "v1beta1"  },  "value": "1"}{  "labels": {    "code": "200",    "component": "apiserver",    "contentType": "application/json",    "dry_run": "",    "group": "rbac.authorization.k8s.io",    "resource": "clusterroles",    "scope": "cluster",    "subresource": "",    "verb": "LIST",    "version": "v1beta1"  },  "value": "1"}

输入显示，只对这些API收回读申请，大多数申请是为了监督已弃用的Ingress API。

你还能够通过以下Prometheus查问找到该信息，该查问返回对于对将在v1.22中删除的已弃用API的申请的信息:

apiserver_requested_deprecated_apis{removed_version="1.22"} * on(group,version,resource,subresource)

审计正文

指标是查看是否正在应用弃用API，以及应用速度的一种疾速办法，然而它们没有蕴含足够的信息来辨认特定的客户机或API对象。从Kubernetes v1.19开始，对已弃用API的申请的审计事件包含一个审计正文"k8s.io/deprecated":"true"。管理员能够应用这些审计事件来标识须要更新的特定客户端或对象。

Custom Resource Definitions

从v1.19开始，除了API服务器正告已弃用API的性能外，CustomResourceDefinition还能够批示它所定义的资源的特定版本已被弃用。当API申请自定义资源的已弃用版本时，将返回一条正告音讯，与内置API的行为相匹配。

如果须要，CustomResourceDefinition的作者还能够为每个版本定制正告。这容许他们提供一个指向迁徙指南的指针，或者在须要时提供其余信息。

apiVersion: apiextensions.k8s.io/v1kind: CustomResourceDefinition  name: crontabs.example.comspec:  versions:  - name: v1alpha1    # This indicates the v1alpha1 version of the custom resource is deprecated.    # API requests to this version receive a warning in the server response.    deprecated: true    # This overrides the default warning returned to clients making v1alpha1 API requests.    deprecationWarning: "example.com/v1alpha1 CronTab is deprecated; use example.com/v1 CronTab (see http://example.com/v1alpha1-v1)"    ...  - name: v1beta1    # This indicates the v1beta1 version of the custom resource is deprecated.    # API requests to this version receive a warning in the server response.    # A default warning message is returned for this version.    deprecated: true    ...  - name: v1    ...

Admission Webhooks

Admission webhook是与Kubernetes集成自定义策略或验证的次要形式。从v1.19开始，admission webhook能够返回正告音讯，这些音讯被传递到申请API客户端。正告能够与容许或回绝录取答复一起返回。

例如，容许一个申请，但正告一个已知的配置不工作，admission webhook能够发送这样的响应：

{  "apiVersion": "admission.k8s.io/v1",  "kind": "AdmissionReview",  "response": {    "uid": "<value from request.uid>",    "allowed": true,    "warnings": [      ".spec.memory: requests >1GB do not work on Fridays"    ]  }}

如果你正在实现一个webhook返回一个正告音讯，这里有一些提醒：

  • 不要在音讯中蕴含“Warning:”前缀（这是客户端在输入中增加的）
  • 应用正告音讯来形容收回API申请的客户端应该纠正或留神的问题
  • 精简；如果可能，将正告限度在120个字符

admission webhook应用这个新个性的形式有很多，我很期待看到人们会提出什么。这里有一些倡议让你开始：

  • webhook实现减少了一个“complain”模式，在这里他们返回正告而不是回绝，以容许尝试一个策略，以验证它是否失常工作，而后开始施行它
  • “lint”或“vet”格调的webhook，查看对象和没有遵循最佳实际是提供正告

Kubectl严格模式

如果你想确保尽快留神到弃用并立刻着手解决它们，kubectl在v1.19中增加了一个--warnings-as-errors选项。应用此选项调用时，kubectl将从服务器接管到的任何正告视为谬误，并以非零退出代码退出：

这能够在CI作业中用于将清单利用到以后服务器，并且须要应用零退出代码传递，以示意CI作业胜利。

将来的可能性

当初，咱们曾经有了一种办法，能够在上下文中向用户传递有用的信息，咱们在思考应用这种办法来改善用户应用Kubernetes的体验。咱们探讨了的两个方面是对于已知有问题的值的正告，因为兼容性起因，咱们不能齐全回绝这些值，以及对于应用不举荐应用的字段或字段值的正告（比方应用beta os/arch节点标签的selector，在v1.14弃用）。我很快乐看到这一畛域的停顿，Kubernetes的应用越来越容易。

Jordan Liggitt是谷歌的一名软件工程师，帮忙领导Kubernetes的认证、受权和API工作。

点击浏览网站原文。

CNCF (Cloud Native Computing Foundation)成立于2015年12月，隶属于Linux  Foundation，是非营利性组织。
CNCF（云原生计算基金会）致力于培养和保护一个厂商中立的开源生态系统，来推广云原生技术。咱们通过将最前沿的模式民主化，让这些翻新为公众所用。扫描二维码关注CNCF微信公众号。