Skip to content

Commit 567b090

Browse files
deads2kdeads2k
committed
provide recommended .status.conditions schema
1 parent 5e330ad commit 567b090

File tree

2 files changed

+163
-0
lines changed

2 files changed

+163
-0
lines changed

‎keps/sig-api-machinery/1623-standardize-conditions/README.md

Lines changed: 144 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,144 @@
1+
# KEP-1623: Standardize Conditions.
2+
3+
<!-- toc -->
4+
- [Release Signoff Checklist](#release-signoff-checklist)
5+
- [Summary](#summary)
6+
- [Motivation](#motivation)
7+
- [Goals](#goals)
8+
- [Non-Goals](#non-goals)
9+
- [Proposal](#proposal)
10+
- [Noteworthy choices](#noteworthy-choices)
11+
- [Graduation Criteria](#graduation-criteria)
12+
- [Upgrade / Downgrade Strategy](#upgrade--downgrade-strategy)
13+
- [Version Skew Strategy](#version-skew-strategy)
14+
- [Implementation History](#implementation-history)
15+
- [Drawbacks](#drawbacks)
16+
- [Alternatives](#alternatives)
17+
<!-- /toc -->
18+
19+
## Release Signoff Checklist
20+
21+
<!--
22+
**ACTION REQUIRED:** In order to merge code into a release, there must be an
23+
issue in [kubernetes/enhancements] referencing this KEP and targeting a release
24+
milestone **before the [Enhancement Freeze](https://git.k8s.io/sig-release/releases)
25+
of the targeted release**.
26+
27+
For enhancements that make changes to code or processes/procedures in core
28+
Kubernetes i.e., [kubernetes/kubernetes], we require the following Release
29+
Signoff checklist to be completed.
30+
31+
Check these off as they are completed for the Release Team to track. These
32+
checklist items _must_ be updated for the enhancement to be released.
33+
-->
34+
35+
- [ ] Enhancement issue in release milestone, which links to KEP dir in [kubernetes/enhancements] (not the initial KEP PR)
36+
- [ ] KEP approvers have approved the KEP status as `implementable`
37+
- [ ] Design details are appropriately documented
38+
- [ ] Test plan is in place, giving consideration to SIG Architecture and SIG Testing input
39+
- [ ] Graduation criteria is in place
40+
- [ ] "Implementation History" section is up-to-date for milestone
41+
- [ ] User-facing documentation has been created in [kubernetes/website], for publication to [kubernetes.io]
42+
- [ ] Supporting documentation e.g., additional design documents, links to mailing list discussions/SIG meetings, relevant PRs/issues, release notes
43+
44+
<!--
45+
**Note:** This checklist is iterative and should be reviewed and updated every time this enhancement is being considered for a milestone.
46+
-->
47+
48+
[kubernetes.io]: https://kubernetes.io/
49+
[kubernetes/enhancements]: https://git.k8s.io/enhancements
50+
[kubernetes/kubernetes]: https://git.k8s.io/kubernetes
51+
[kubernetes/website]: https://git.k8s.io/website
52+
53+
## Summary
54+
55+
While many Kuberentes APIs have `.status.conditions`, the schema of `condition` varies a lot between them.
56+
There is very little commonality at the level of serialization, proto-encoding, and required vs optional.
57+
Conditions are central enough to the API to make a common golang type with a fixed schema.
58+
The schema can be a strong recommendation to all API authors.
59+
60+
## Motivation
61+
62+
Allow general consumers to expect a common schema for `.status.conditions` and share golang logic for common Get, Set, Is for `.status.conditions`.
63+
The pattern is well-established and we have a good sense of the schema we now want.
64+
65+
### Goals
66+
67+
1. For all new APIs, have a common type for `.status.conditions`.
68+
2. Provide common utility methods for `HasCondition`, `IsConditionTrue`, `SetCondition`, etc.
69+
3. Provide recommended defaulting functions that set required fields and can be embedded into conversion/default functions.
70+
71+
### Non-Goals
72+
73+
1. Update all existing APIs to make use of the new condition type.
74+
75+
## Proposal
76+
77+
Introduce a type into k8s.io/apimachinery/pkg/apis/meta/v1 for `Condition` that looks like
78+
```go
79+
type Condition struct {
80+
// Type of condition in CamelCase.
81+
// +required
82+
Type string `json:"type" protobuf:"bytes,1,opt,name=type"`
83+
// Status of the condition, one of True, False, Unknown.
84+
// +required
85+
Status ConditionStatus `json:"status" protobuf:"bytes,2,opt,name=status"`
86+
// Last time the condition transitioned from one status to another.
87+
// This should be when the underlying condition changed. If that is not known, then using the time when the API field changed is acceptable.
88+
// +required
89+
LastTransitionTime metav1.Time `json:"lastTransitionTime" protobuf:"bytes,3,opt,name=lastTransitionTime"`
90+
// The reason for the condition's last transition in CamelCase.
91+
// The specific API may choose whether or not this field is considered a guaranteed API.
92+
// +required
93+
Reason string `json:"reason" protobuf:"bytes,4,opt,name=reason"`
94+
// A human readable message indicating details about the transition.
95+
// This field is never considered a guaranteed API and may be empty/missing.
96+
// +optional
97+
Message string `json:"message,omitempty" protobuf:"bytes,5,opt,name=message"`
98+
}
99+
```
100+
101+
This is not strictly compatible with any of our existing conditions because of either proto ordinals,
102+
required vs optional, or omitEmpty or not.
103+
However, it encapsulates the best of what we've learned and will allow new APIs to have a unified type.
104+
105+
### Noteworthy choices
106+
1. `lastTransitionTime` is required.
107+
Some current implementations allow this to be missing, but this makes it difficult for consumers.
108+
By requiring it, the actor setting the field can set it to the best possible value instead of having clients try to guess.
109+
2. `reason` is required.
110+
The actor setting the value should always describe why the condition is the way it is, even if that value is, unknown unknowns.
111+
No other actor has the information to make a better choice.
112+
3. `lastHeartbeatTime` is removed.
113+
This field caused excessive write loads as we scaled.
114+
If an API needs this concept, it should codify it separately and possibly using a different resource.
115+
116+
### Graduation Criteria
117+
118+
Because meta/v1 APIs are necessarily v1, this would go direct to GA.
119+
Using a meta/v1beta1 isn't a meaningful distinction since this type is embedded into other types which own their own versions.
120+
121+
### Upgrade / Downgrade Strategy
122+
123+
This KEP isn't proposing that existing types be changed.
124+
This means that individual upgrade/downgrade situations will be handled discretely.
125+
By providing recommended defaulting functions, individual APIs will be able to more easily transition to the new condition type.
126+
127+
### Version Skew Strategy
128+
129+
Standard defaulting and conversion will apply.
130+
APIs which have extra values for this type may have to go through an intermediate version that drops them or accept
131+
that certain optional fields of their conditions will be dropped.
132+
Depending on the individual APIs and when their extra fields are deprecated, this could be acceptable choice.
133+
134+
## Implementation History
135+
136+
## Drawbacks
137+
138+
1. There may be some one-time pain when new versions are created for APIs that wish to consume this common schema.
139+
Switching is not strictly required, but it is encouraged.
140+
141+
## Alternatives
142+
143+
1. We could recommend a schema and not provide one. This doesn't seem very nice to consumers.
144+

‎keps/sig-api-machinery/1623-standardize-conditions/kep.yaml

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
title: KEP Template
2+
kep-number: 1623
3+
authors:
4+
- "@deads2k"
5+
owning-sig: sig-apimachinery
6+
participating-sigs:
7+
- sig-apimachinery
8+
- sig-apps
9+
- sig-architecture
10+
status: implementable
11+
creation-date: 2020-03-23
12+
reviewers:
13+
- "@lavalamp"
14+
- "@smarterclayton"
15+
approvers:
16+
- "@derekwaynecarr"
17+
- "@liggitt"
18+
see-also:
19+
replaces:

0 commit comments

Comments
 (0)