Skip to content

Commit 2bf05f9

Browse files
mvazquezcmvazquezc
committed
Added scoregenerator API proposal
Signed-off-by: Mario Vazquez <[email protected]>
1 parent 48e5ad2 commit 2bf05f9

File tree

2 files changed

+214
-0
lines changed

2 files changed

+214
-0
lines changed

‎enhancements/sig-architecture/32-extensiblescheduling/score-generator/README.md‎

Lines changed: 196 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,196 @@
1+
# New API: AddOnPlacementScoreGenerator
2+
3+
## Release Signoff Checklist
4+
5+
- [ ] Enhancement is `implemented`
6+
- [ ] Design details are appropriately documented from clear requirements
7+
- [ ] Test plan is defined
8+
- [ ] Graduation criteria for dev preview, tech preview, GA
9+
- [ ] User-facing documentation is created in [website](https://github.com/open-cluster-management-io/open-cluster-management-io.github.io/)
10+
11+
## Summary
12+
13+
This proposal will be adding a new OCM API named `AddOnPlacementScoreGenerator`
14+
which helps the administrators to provide custom values to Addon controllers
15+
that generate `AddOnPlacementScores`.
16+
17+
A valid `AddOnPlacementScoreGenerator` resource should be in a "cluster namespace" and
18+
the associated config resources will be delivered to the associated managed cluster
19+
with that "cluster namespace".
20+
21+
## Motivation
22+
23+
### Influence Addon controllers behavior
24+
25+
Currently, when writing an Addon in order to extend the scheduling capabilities of OCM
26+
there is no way to influence behavior of that addon via an API. The controller will run
27+
and update the status for the `AddOnPlacementScores` object.
28+
29+
One of the use-cases we want to cover is testing latency from managed clusters to a set
30+
of user-define locations. With the current `AddOnPlacementScores` implementation we would
31+
need to hard code these locations or maybe use something like a `ConfigMap` that gets consumed
32+
by the controller. We don't find these solutions flexible enough, so our proposal would be having
33+
a new API to influence the behavior of such controllers.
34+
35+
Let's say I want to test latencies to redhat.com and google.com and place my application based on
36+
the managed cluster with the lowest latency to redhat.com.
37+
38+
Providing I created the required controller with the hardcoded locations (redhat.com and google.com)
39+
an `AddOnPlacementScores` similar to this one would be created on each managed cluster running this addon:
40+
41+
~~~yaml
42+
apiVersion: cluster.open-cluster-management.io/v1alpha1
43+
kind: AddOnPlacementScore
44+
metadata:
45+
name: cluster1-generator
46+
namespace: cluster1
47+
status:
48+
conditions:
49+
- lastTransitionTime: "2021-10-28T08:31:39Z"
50+
message: AddOnPlacementScore updated successfully
51+
reason: AddOnPlacementScoreUpdated
52+
status: "True"
53+
type: AddOnPlacementScoreUpdated
54+
validUntil: "2021-10-29T18:31:39Z"
55+
scores:
56+
- name: "redhat-com-avgLatency"
57+
value: 30
58+
- name: "google-com-avgLatency"
59+
value: 50
60+
~~~
61+
62+
Now, a `Placement` like this could be used:
63+
64+
~~~yaml
65+
apiVersion: cluster.open-cluster-management.io/v1beta1
66+
kind: Placement
67+
metadata:
68+
name: latency-placement
69+
namespace: ns1
70+
spec:
71+
numberOfClusters: 3
72+
prioritizerPolicy:
73+
mode: Exact
74+
configurations:
75+
- scoreCoordinate:
76+
type: AddOn
77+
addOn:
78+
resourceName: cluster1-generator
79+
scoreName: redhat-com-avgLatency
80+
weight: -1
81+
~~~
82+
83+
Other applications may use latency to google.com.
84+
85+
Now, we want to add linux.com to the list of locations to test. With the current implementation we
86+
will need to edit the code of the addon controller and include the test to linux.com + the result to be added
87+
to the `AddOnPlacementScore`.
88+
89+
To fix above issue, the proposal is to create a new API `AddOnPlacementScoreGenerator`, which could
90+
look like this for the example above:
91+
92+
~~~yaml
93+
apiVersion: cluster.open-cluster-management.io/v1alpha1
94+
kind: AddOnPlacementScoreGenerator
95+
metadata:
96+
name: cluster1-generator
97+
namespace: cluster1
98+
spec:
99+
addOnPlacementSelector:
100+
name: latency
101+
namespace: cluster1
102+
latencies:
103+
- name: redhat-com-avgLatency
104+
url: https://redhat.com
105+
runs: 2
106+
waitBetweenRuns: 10s
107+
- name: google-com-avgLatency
108+
url: https://google.com
109+
- name: linux-com-avgLatency
110+
url: https://linux.com
111+
~~~
112+
113+
Our controller can now read the `AddOnPlacementScoreGenerator` and our specific controller will be interested on
114+
everything below `.spec.latencies`. For example, the redhat-com-avgLatency will have the result of running two latency
115+
tests to https://redhat.com and waiting 10s between runs, then the mean value will be posted to the `AddOnPlacementScore`
116+
status.
117+
118+
## Goals & Non-Goals
119+
120+
### Goals
121+
122+
- Help the administrators to provide custom values to addon controllers that generate `AddOnPlacementScores`
123+
124+
### Non-Goals
125+
126+
- Addond developers need to develop their own controller to consume this new API.
127+
128+
### Future goals
129+
130+
- It is currently assumed that the user of `AddOnPlacementScoreGenerator` is either a
131+
cluster admin or a user who can create `AddOnPlacementScoreGenerator` in the hub cluster's
132+
managed "cluster namespace".
133+
134+
## Design
135+
136+
### Component & API
137+
138+
We purpose to adding a new custom resource named
139+
`AddOnPlacementScoreGenerator` introduced into OCM by this proposal:
140+
141+
A sample of the `AddOnPlacementScoreGenerator` will be:
142+
143+
~~~yaml
144+
apiVersion: cluster.open-cluster-management.io/v1alpha1
145+
kind: AddOnPlacementScoreGenerator
146+
metadata:
147+
name: cluster1-generator
148+
namespace: cluster1
149+
spec:
150+
addOnPlacementSelector:
151+
name: latency
152+
namespace: cluster1
153+
latencies:
154+
- name: redhat-com-avgLatency
155+
url: https://redhat.com
156+
runs: 2
157+
waitBetweenRuns: 10s
158+
otherPlugin:
159+
- name: score-name
160+
optionConsumedByPlugin: optionValue
161+
162+
~~~
163+
164+
The `AddOnPlacementScoreGenerator` resource is expected to be
165+
created under the "cluster namespace" which is a namespace with
166+
the same name as the managed cluster, the `AddOnPlacementScoreGenerator`
167+
delivered to the managed cluster will have the same name as the
168+
`AddOnPlacementScoreGenerator` resource.
169+
170+
The addon controller must setup a watcher and reconcile `AddOnPlacementScoreGenerator`.
171+
172+
### Test Plan
173+
174+
- Unit tests
175+
- Integration tests
176+
177+
### Graduation Criteria
178+
179+
#### Alpha
180+
181+
At first, This proposal will be in the alpha stage and needs to meet
182+
183+
1. The new APIs are reviewed and accepted;
184+
2. Implementation is completed to support the functionalities;
185+
3. Develop test cases to demonstrate this proposal works correctly;
186+
187+
#### Beta
188+
1. Need to revisit the API shape before upgrading to beta based on user feedback.
189+
190+
### Upgrade / Downgrade Strategy
191+
TBD
192+
193+
### Version Skew Strategy
194+
N/A
195+
196+
## Alternatives

‎enhancements/sig-architecture/32-extensiblescheduling/score-generator/metadata.yaml‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
title: score-generator
2+
authors:
3+
- "@mvazquezc"
4+
reviewers:
5+
- "@deads2k"
6+
- "@qiujian16"
7+
- "@elgnay"
8+
- "@haoqing0110"
9+
approvers:
10+
- "@deads2k"
11+
- "@qiujian16"
12+
- "@elgnay"
13+
- "@haoqing0110"
14+
creation-date: 2023-04-13
15+
last-updated: 2023-04-13
16+
status: provisional
17+
see-also:
18+
- "/enhancements/sig-architecture/32-extensiblescheduling"

0 commit comments

Comments
 (0)