Shulou(Shulou.com)05/31 Report--

This article mainly introduces the Kubernetes API design in the use of Conditions related knowledge, detailed and easy to understand, simple and fast operation, has a certain reference value, I believe that everyone will read this Kubernetes API design in the use of Conditions article will have some gains, let's take a look at it.

introduction

Most Kubernetes resource objects contain a status.conditions field, which is used to indicate the status of the resource. For example, status.conditions in the deployment resource is as follows:

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

The above conditions information is easy to read (will be explained in detail later), but there is a problem that has puzzled the author, that is:

What is the difference between conditions and status?

What are the design principles of conditions? When designing API extensions, how should conditions be defined?

This section starts with the design principles of conditions and then introduces some lessons learned in designing conditions.

conditions Design principles

Conditions is hosted in the status field of the resource object and is used to indicate the status of the resource like other field values of status. However, conditions is designed to provide a common data structure to represent the status of resources, which usually provides more detailed information than other fields of status (such as status switch time, update time). Conditions is actually an extension mechanism, and external monitoring programs can monitor the status of various resources indiscriminately according to conditions without paying too much attention to other information in the resource object status.

The status.conditions field is typically a slice, where each element represents a state of the resource that is updated by a particular controller, such as the Deployment controller, which updates the status.conditions information of the deployment object. Conditions acts as an extension mechanism, and it also enables third-party controllers to add new states. Usually the information in status.conditions is calculated by the controller based on the resource's status and other fields.

condition field content

Usually a condition must contain two pieces of information: type and status. Before Kubernetes v1.19, there was no uniform standard for condition, resulting in many APIs defining their own conditions. For example:

The Condition used by Deployment is type DeploymentCondition struct;

The Pod uses a Condition of type PodCondition structure;

Fortunately, Kubernetes v1.19 community provides a standard condition type definition, due to compatibility considerations, Kubernetes existing API may not be able to use this standard type, but for future new APIs will use this standard type, and I suggest that users design CRD extensions should also use this standard type.

The standard condition type is defined as follows:

type ConditionStatus stringconst ( ConditionTrue ConditionStatus = "True" ConditionFalse ConditionStatus = "False" ConditionUnknown ConditionStatus = "Unknown")type Condition struct { //Type (using hump style), such as "Available." Type string //Status (enumerated values: True, False, Unknown). Status ConditionStatus The observed generation. //If ObservedGeneration is smaller than metada.generation, it is not the latest state. // +optional ObservedGeneration int64 //Last change time LastTransitionTime Time //Status change reason (using hump style), e.g."New ReplicaSetAvailable" Reason string //Description information, such as "Deployment has minimum availability" Message string `json:"message" protobuf:"bytes,6,opt,name=message"`}

The standard condition type definition further specifies the individual fields of condition. All fields are required except ObservedGeneration, which is optional.

condition design convention

In order for conditions to work best, certain design conventions need to be observed:

Convention 1: The condition definition must have clear information

Each condition needs to convey a clear information that the user cares about, and the user does not need to speculate and calculate according to other states of the resource when reading this information.

Rule 2: Condition must be compatible

Once a condition is defined, it becomes part of the API and needs to provide the same stability guarantees as the API. If a new condition is needed, it can still be added (without breaking compatibility), but whether the existing condition can be changed needs to be determined according to the API maturity. For example, the API of stable cannot be changed, and the API of alpha can be changed.

Convention 3: condition needs to be updated the first time the controller processes a resource

The controller needs to update condition.status as soon as possible, even if the status is Unknown. The advantage of doing so is that other components know that the controller is tuning the resource.

However, not all controllers follow this convention, i.e., the controller does not report a particular condition (in which case the condition state value may be Unknown), and the condition may not be determined yet and needs to be determined at the next tuning. In this case, the external component cannot read the specific condition, and it can be assumed that the condition is Unknown.

Convention 4: Condition type names need to be readable

Use human-readable names for condition type names, and avoid double negative contexts as much as possible. For example, the type name Ready is better than Failed because Failed = False is a double negative when the condition state is False and is less understandable than Ready = False.

Rule 5: Do not define condition as a state machine.

Condition needs to describe the deterministic state of the current resource, not the state in the current resource state machine. In layman's terms, condition types require the use of adjectives (e.g. Ready) or past verbs (Succeeded) rather than the current runtime (e.g. Deploying).

About "How to use Conditions in Kubernetes API design" The content of this article is introduced here, thank you for reading! I believe everyone has a certain understanding of the knowledge of "How to use Conditions in Kubernetes API design." If you still want to learn more knowledge, please pay attention to the industry information channel.

Welcome to subscribe "Shulou Technology Information " to get latest news, interesting things and hot topics in the IT industry, and controls the hottest and latest Internet news, technology news and IT industry trends.