《Kubernetes设计与实现》
  • Introduction
  • 内容简介
  • 前言
  • [第二章:Kubernetes基础]
    • 2.3 Kubernetes API
  • [第三章:工作负载管理]
    • [3.1 Pod]
      • 3.1.1 Pod概述
      • 3.1.1 Pod初体验
    • [3.2 ReplicationController]
      • 3.2.1 ReplicationController概述
      • 3.2.2 ReplicationController初体验
    • [3.3 ReplicaSet]
      • 3.3.1 ReplicaSet概述
      • 3.3.2 ReplicaSet初体验
    • [3.4 Deployment]
      • 3.4.1 Deployment概述
      • 3.4.2 Deployment初体验
    • [3.5 DaemonSet]
      • 3.5.1 DaemonSet概述
      • 3.5.2 DaemonSet初体验
  • [第四章:服务]
    • [4.1 Service]
      • 4.1.1 Service概述
      • 4.1.1 Service上手体验
  • [第六章:配置管理]
    • [6.1 Secret--机密信息管理]
      • 6.1.1 Secret概述
  • [第七章:集群认证]
    • [7.1 证书]
      • 7.1.1 证书基础
      • 7.1.2 证书签发流程
  • [第九章:准入控制器]
    • [9.1 准入控制器概述]
      • 9.1.1 概述
      • [9.1.2 内置默认启动的插件]
        • 9.1.2.1 NamespaceLifecycle
        • 9.1.2.15 MutatingAdmissionWebhook
  • [第十章:ResourceQuota]
    • 10.1 ResourceQuota概述
  • [第十六章:API设计约定]
    • 16.1 字段可选性设计约定
    • 16.2 condition设计约定
    • 16.3 event设计约定
  • [第十九章:Kubernetes生态]
    • [19.1 Kind]
      • [19.1.1 Kind概述]
      • 19.1.2 映射端口到主机
      • 19.1.3 配置端口转发
由 GitBook 提供支持
在本页
  • 导读
  • conditions设计原则
  • condition字段内容
  • condition设计约定
  • 约定一:condition定义要有明确的信息
  • 约定二:condition需要保持兼容
  • 约定三:condition需要控制器第一次处理资源时更新
  • 约定四:condition类型名需要确保可读性
  • 约定五:condition不要定义成状态机

这有帮助吗?

  1. [第十六章:API设计约定]

16.2 condition设计约定

导读

绝大部分Kubernetes资源对象都包含status.conditions字段,用来表示资源状态,比如deployment资源中的status.conditions如下所示:

  conditions:
  - lastTransitionTime: "2020-12-15T01:52:53Z"
    lastUpdateTime: "2020-12-15T01:52:53Z"
    message: Deployment has minimum availability.
    reason: MinimumReplicasAvailable
    status: "True"
    type: Available
  - lastTransitionTime: "2020-12-15T01:52:39Z"
    lastUpdateTime: "2020-12-15T01:52:53Z"
    message: ReplicaSet "nginx-deployment-85b45874d9" has successfully progressed.
    reason: NewReplicaSetAvailable
    status: "True"
    type: Progressing

以上conditions的信息是很容易读懂的(后面还会详细解释),然而有个问题曾经令笔者非常困惑,那就是:

  • conditions和status到底有什么区别?

  • conditions的设计原则是什么?在设计API扩展时,该如何定义conditions?

本节会先从conditions的设计原则讲起,再介绍一些设计conditions时的一些经验总结。

conditions设计原则

conditions寄居于资源对象的status字段中,与status其他字段值一样都用来表示资源的状态。不过conditions的设计初衷是提供一种通用的数据结构表示资源的状态,它通常能够提供比status其他字段更详细的信息(比如状态切换时间、更新时间),conditions实际上是一种扩展机制,外部监控程序可以根据conditions无差别地监控各种资源的状态,而不必过分关注资源对象status中的其他信息。

通常status.conditions字段类型为切片,切片中的每个元素表示资源的某个状态,该状态由特定的控制器更新,比如Deployment控制器会更新deployment对象的status.conditions信息。conditions作为扩展机制,它还支持第三方控制器增加新的状态。通常status.conditions中的信息由控制器根据资源的status其他字段计算出来。

condition字段内容

通常一个condition必须包含type(状态类型)和status(状态值)两个信息。在Kubernetes v1.19版之前,关于condition并没有统一的标准,导致众多API都自行定义了condition。比如:

  • Deployment使用的Condition为type DeploymentCondition struct;

  • Pod使用的Condition为type PodCondition struct;

庆幸的是,在Kubernetesv1.19版本社区提供了一个标准的condition类型定义,由于兼容性考虑,Kubernetes既有的API不一定能采用这一标准类型,但对于后续新增的API将会使用这一标准类型,并且笔者建议用户设计的CRD扩展也应使用这一标准类型。

标准的condition类型定义如下所示:

type ConditionStatus string

const (
    ConditionTrue    ConditionStatus = "True"
    ConditionFalse   ConditionStatus = "False"
    ConditionUnknown ConditionStatus = "Unknown"
)

type Condition struct {
    // 类型(使用驼峰风格),如”Available“。
    Type string
    // 状态(枚举值:”True“、”False“和”Unknown“)。
    Status ConditionStatus
    // 观察到的generation。
    // 如果ObservedGeneration 比metada.generation小,说明不是最新状态。
    // +optional
    ObservedGeneration int64
    // 上次变化时间
    LastTransitionTime Time
    // 状态变化原因(使用驼峰风格),如”NewReplicaSetAvailable“
    Reason string
    // 描述信息,如”Deployment has minimum availability“
    Message string `json:"message" protobuf:"bytes,6,opt,name=message"`
}

标准的condition类型定义对condition的各个字段做了进一步约定。除了ObservedGeneration是可选的以外,其他字段都是必填的。

condition设计约定

为了让condition起到最大的作用,需要遵守一定的设计约定:

约定一:condition定义要有明确的信息

每个condition需要传递一个用户关心的明确信息,用户读取到该信息不需要再根据资源的其他状态来揣测和计算。

约定二:condition需要保持兼容

condition一旦被定义,它就成了API中的一部分,需要跟API一样提供稳定性保证。如果需要新的condition仍然可以增加(没有破坏兼容性),但既有的condition是否能够改变就需要根据API成熟度来决定,比如stable的API不可以改变,alpha的API可以改变。

约定三:condition需要控制器第一次处理资源时更新

控制器需要尽快地更新condition状态值(condition.status),即便该状态值为Unknown,这么做的好处是可以让其他组件了解到控制器正在调谐这个资源。

然而,并不是所有的控制器都能遵守这个约定,即控制器并不会报告特定的condition(此时该condition状态值可能为Unknown),可能该condition还无法确定,需要在下一次调谐时决定。此种情况下,外部组件无法读取到特定的condition,可以假设该condition为Unknown。

约定四:condition类型名需要确保可读性

condition类型名要使用人类可读的名称,而且尽量避免出现双重否定的语境。例如,类型名Ready比使用Failed要好,因为condition状态为False时,Failed = False将出现双重否定,不如Ready = False容易理解。

约定五:condition不要定义成状态机

condition需要描述当前资源的确定状态,而不是当前资源状态机中的状态。通俗地讲,condition类型需要使用形容词(如Ready)或过去动词(Succeeded),而不是使用当前运行时(如Deploying)。

上一页16.1 字段可选性设计约定下一页16.3 event设计约定

最后更新于4年前

这有帮助吗?