Skip to content

Commit 1e409a5

Browse files
robscottrobscott
committed
Adding KEP 2365: IngressClass Namespaced Params
1 parent 0f59248 commit 1e409a5

File tree

3 files changed

+310
-0
lines changed

3 files changed

+310
-0
lines changed

‎keps/prod-readiness/sig-network/2365.yaml

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
kep-number: 2365
2+
alpha:
3+
approver: "@johnbelamaric"

‎keps/sig-network/2365-ingressclass-namespaced-params/README.md

Lines changed: 267 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,267 @@
1+
# KEP-2365: IngressClass Namespaced Params
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+
- [Risks and Mitigations](#risks-and-mitigations)
11+
- [Design Details](#design-details)
12+
- [Test Plan](#test-plan)
13+
- [Unit Tests](#unit-tests)
14+
- [Graduation Criteria](#graduation-criteria)
15+
- [Alpha release](#alpha-release)
16+
- [Alpha -&gt; Beta Graduation](#alpha---beta-graduation)
17+
- [Beta -&gt; GA Graduation](#beta---ga-graduation)
18+
- [Upgrade / Downgrade Strategy](#upgrade--downgrade-strategy)
19+
- [Version Skew Strategy](#version-skew-strategy)
20+
- [Production Readiness Review Questionnaire](#production-readiness-review-questionnaire)
21+
- [Feature Enablement and Rollback](#feature-enablement-and-rollback)
22+
- [Rollout, Upgrade and Rollback Planning](#rollout-upgrade-and-rollback-planning)
23+
- [Monitoring Requirements](#monitoring-requirements)
24+
- [Dependencies](#dependencies)
25+
- [Scalability](#scalability)
26+
- [Troubleshooting](#troubleshooting)
27+
- [Implementation History](#implementation-history)
28+
- [Drawbacks](#drawbacks)
29+
- [Alternatives](#alternatives)
30+
<!-- /toc -->
31+
32+
## Release Signoff Checklist
33+
34+
Items marked with (R) are required *prior to targeting to a milestone / release*.
35+
36+
- [ ] (R) Enhancement issue in release milestone, which links to KEP dir in [kubernetes/enhancements] (not the initial KEP PR)
37+
- [x] (R) KEP approvers have approved the KEP status as `implementable`
38+
- [x] (R) Design details are appropriately documented
39+
- [x] (R) Test plan is in place, giving consideration to SIG Architecture and SIG Testing input
40+
- [x] (R) Graduation criteria is in place
41+
- [x] (R) Production readiness review completed
42+
- [x] (R) Production readiness review approved
43+
- [ ] "Implementation History" section is up-to-date for milestone
44+
- [ ] User-facing documentation has been created in [kubernetes/website], for publication to [kubernetes.io]
45+
- [ ] Supporting documentation—e.g., additional design documents, links to mailing list discussions/SIG meetings, relevant PRs/issues, release notes
46+
47+
## Summary
48+
49+
This KEP proposes adding new Scope and Namespace fields to the IngressClass
50+
ParametersRef field.
51+
52+
## Motivation
53+
54+
After the initial release of IngressClass, a number of use cases called for the
55+
ability to reference namespace-scoped Parameters. For example, one could use a
56+
GatewayClass parameters CR to describe how and where a controller should be
57+
provisioned. This same thought process was also happening in the Service APIs
58+
subproject. It was ultimately deemed worthwhile for GatewayClass if we could
59+
also gain approval for a parallel API change to IngressClass.
60+
61+
### Goals
62+
63+
- Allow referencing namespace-scoped Parameters resources.
64+
65+
### Non-Goals
66+
67+
- Requiring all Parameters resources to be namespace-scoped.
68+
69+
## Proposal
70+
71+
Add new Scope and Namespace fields to the IngressClass ParametersRef field.
72+
73+
### Risks and Mitigations
74+
75+
The option to reference namespace-scoped Parameters resources could lead to
76+
confusion. It is relatively rare for resource references to be able to target
77+
both cluster-scoped and namespace-scoped resources. We believe that the
78+
advantages of this KEP outweigh this potential confusion.
79+
80+
## Design Details
81+
82+
This will result in adding a new `IngressClassParametersReference` type that
83+
closely mirrors the existing `TypedLocalObjectReference` type that is currently
84+
in use.
85+
86+
```golang
87+
// IngressClassParametersReference identifies an API object. This can be used
88+
// to specify a cluster-scoped or namespace-scoped resource.
89+
type IngressClassParametersReference struct {
90+
// APIGroup is the group for the resource being referenced. If APIGroup is not
91+
// specified, the specified Kind must be in the core API group. For any other
92+
// third-party types, APIGroup is required.
93+
// +optional
94+
APIGroup *string
95+
// Kind is the type of resource being referenced.
96+
Kind string
97+
// Name is the name of resource being referenced.
98+
Name string
99+
// Scope represents if this refers to a cluster or namespace scoped resource.
100+
// This may be set to "cluster" or "namespace".
101+
// Default: "cluster"
102+
Scope string
103+
// Namespace is the namespace of the resource being referenced. This field is
104+
// required when scope is set to "namespace".
105+
// +optional
106+
Namespace *string
107+
}
108+
```
109+
110+
Use of these new `Scope` and `Namespace` fields will be guarded by a new
111+
`IngressClassNamespacedParams` feature gate.
112+
113+
### Test Plan
114+
115+
#### Unit Tests
116+
- When feature gate is disabled:
117+
- Ensure that namespace and scope fields can not be set on a newly created
118+
IngressClass resource.
119+
- Ensure that namespace and scope field can not be changed if it is not
120+
already set on an IngressClass resource.
121+
- Ensure that namespace and scope field can be changed if it is already set on
122+
an IngressClass resource.
123+
- When feature gate is enabled:
124+
- Ensure that namespace and scope field can be set on a newly created
125+
IngressClass resource.
126+
- Ensure that namespace and scope field can be changed if it is not already
127+
set on an IngressClass resource.
128+
- Ensure that namespace and scope field can be changed if it is already set on
129+
an IngressClass resource.
130+
131+
### Graduation Criteria
132+
133+
#### Alpha release
134+
135+
- Implementation complete
136+
- Test plan complete
137+
- Documentation added covering how params resources should and should not be
138+
used
139+
140+
#### Alpha -> Beta Graduation
141+
142+
- Existed in alpha for at least 1 minor release
143+
144+
#### Beta -> GA Graduation
145+
146+
- Existed in beta for at least 1 minor release
147+
148+
### Upgrade / Downgrade Strategy
149+
150+
N/A
151+
152+
### Version Skew Strategy
153+
154+
See unit tests above.
155+
156+
## Production Readiness Review Questionnaire
157+
158+
### Feature Enablement and Rollback
159+
160+
* **How can this feature be enabled / disabled in a live cluster?**
161+
- [x] Feature gate (also fill in values in `kep.yaml`)
162+
- Feature gate name: IngressClassNamespacedParams
163+
- Components depending on the feature gate: API Server
164+
165+
* **Does enabling the feature change any default behavior?**
166+
A new API field can be set. This may enable new behavior for Ingress
167+
controllers that support the field.
168+
169+
* **Can the feature be disabled once it has been enabled (i.e. can we roll back
170+
the enablement)?**
171+
Yes.
172+
173+
* **What happens if we reenable the feature if it was previously rolled back?**
174+
The fields becomes accessible again.
175+
176+
* **Are there any tests for feature enablement/disablement?**
177+
Yes.
178+
179+
### Rollout, Upgrade and Rollback Planning
180+
181+
* **How can a rollout fail? Can it impact already running workloads?**
182+
N/A
183+
184+
* **What specific metrics should inform a rollback?**
185+
N/A
186+
187+
* **Were upgrade and rollback tested? Was the upgrade->downgrade->upgrade path tested?**
188+
N/A
189+
190+
* **Is the rollout accompanied by any deprecations and/or removals of features,
191+
APIs, fields of API types, flags, etc.?**
192+
No.
193+
194+
### Monitoring Requirements
195+
196+
* **How can an operator determine if the feature is in use by workloads?**
197+
N/A
198+
199+
* **What are the SLIs (Service Level Indicators) an operator can use to
200+
determine the health of the service?**
201+
N/A
202+
203+
* **What are the reasonable SLOs (Service Level Objectives) for the above SLIs?**
204+
N/A
205+
206+
* **Are there any missing metrics that would be useful to have to improve
207+
observability of this feature?**
208+
No.
209+
210+
### Dependencies
211+
212+
* **Does this feature depend on any specific services running in the cluster?**
213+
No
214+
215+
### Scalability
216+
217+
* **Will enabling / using this feature result in any new API calls?**
218+
No
219+
220+
* **Will enabling / using this feature result in introducing new API types?**
221+
Yes, IngressClassParametersReference.
222+
223+
* **Will enabling / using this feature result in any new calls to the cloud
224+
provider?**
225+
No
226+
227+
* **Will enabling / using this feature result in increasing size or count of the
228+
existing API objects?**
229+
Will very slightly increase the size of the IngressClass resource. Generally
230+
less than 10 of these resources should exist in a cluster.
231+
232+
* **Will enabling / using this feature result in increasing time taken by any
233+
operations covered by [existing SLIs/SLOs]?**
234+
No
235+
236+
* **Will enabling / using this feature result in non-negligible increase of
237+
resource usage (CPU, RAM, disk, IO, ...) in any components?**
238+
No
239+
240+
### Troubleshooting
241+
242+
* **How does this feature react if the API server and/or etcd is unavailable?**
243+
N/A
244+
245+
* **What are other known failure modes?**
246+
N/A
247+
248+
* **What steps should be taken if SLOs are not being met to determine the problem?**
249+
N/A
250+
251+
## Implementation History
252+
253+
- January 28, 2021: KEP written
254+
255+
## Drawbacks
256+
257+
Potential for confusion with a params reference that can point to both namespace
258+
scoped and cluster scoped resources.
259+
260+
## Alternatives
261+
262+
- Each controller could assume all parameters were in a predefined namespace.
263+
This would likely lead to more confusion since it would be different for each
264+
implementation.
265+
266+
- We could not support namespace-scoped parameters references. This would be
267+
simplest but would rule out some compelling use cases.

‎keps/sig-network/2365-ingressclass-namespaced-params/kep.yaml

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
title: IngressClass Namespaced Params
2+
kep-number: 2365
3+
authors:
4+
- "@robscott"
5+
owning-sig: sig-network
6+
status: implementable
7+
creation-date: "2021-01-28"
8+
reviewers:
9+
- "@danehans"
10+
- "@cmluciano"
11+
- "@hbagdi"
12+
- "@bowei"
13+
approvers:
14+
- "@thockin"
15+
prr-approvers:
16+
- "@johnbelamaric"
17+
see-also:
18+
- "/keps/sig-network/1453-ingress-api"
19+
20+
# The target maturity stage in the current dev cycle for this KEP.
21+
stage: alpha
22+
23+
# The most recent milestone for which work toward delivery of this KEP has been
24+
# done. This can be the current (upcoming) milestone, if it is being actively
25+
# worked on.
26+
latest-milestone: "v1.21"
27+
28+
# The milestone at which this feature was, or is targeted to be, at each stage.
29+
milestone:
30+
alpha: "v1.21"
31+
beta: "v1.22"
32+
stable: "v1.23"
33+
34+
# The following PRR answers are required at alpha release
35+
# List the feature gate name and the components for which it must be enabled
36+
feature-gates:
37+
- name: IngressClassNamespacedParams
38+
components:
39+
- kube-apiserver
40+
disable-supported: true

0 commit comments

Comments
 (0)