You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
add missing docs (external scheduler and plugin extender) (#287)
* add missing docs (external scheduler and plugin extender)
* fix minor point
* fix based on the suggestion
* fix broken import
* add the important note on the top
Copy file name to clipboardExpand all lines: README.md
+65-28Lines changed: 65 additions & 28 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -9,32 +9,81 @@ Nowadays, the scheduler is configurable/extendable in the multiple ways:
9
9
- etc...
10
10
11
11
But, unfortunately, not all configurations/expansions yield good results.
12
-
Those who customize the scheduler need to make sure their scheduler is working as expected, and doesn't have an unacceptably negative impact on the scheduling.
12
+
Those who customize the scheduler need to make sure their scheduler is working as expected,
13
+
and doesn't have an unacceptably negative impact on the scheduling.
13
14
14
-
In real Kubernetes, we cannot know the results of scheduling in detail without reading the logs, which usually requires privileged access to the control plane.
15
-
That's why we are developing a simulator for kube-scheduler -- you can try out the behavior of the scheduler with web UI while checking which plugin made what decision for which Node.
15
+
In real Kubernetes, we cannot know the results of scheduling in detail without reading the logs,
16
+
which usually requires privileged access to the control plane.
17
+
18
+
That's why we are developing a simulator for kube-scheduler
19
+
-- you can try out the behavior of the scheduler while checking which plugin made what decision for which Node.
16
20
17
21
## Simulator's architecture
18
22
19
23
We have several components:
20
-
- Simulator (in `/simulator`)
21
-
- Web UI (in `/web`)
24
+
- Simulator (in `/simulator`): the core implementation of the simulator
25
+
- Web UI (in `/web`): the Web client of the simulator
22
26
- Coming soon... :) (see [./keps](./keps) to see some nice ideas we're working on)
23
27
24
28
### Simulator
25
29
26
-
Simulator internally has kube-apiserver, scheduler, and HTTP server.
30
+
Simulator is kube-apiserver + scheduler + the HTTP server which mainly for the web UI.
31
+
32
+
There are several ways to integrate your scheduler into the simulator.
33
+
See [integrate-your-scheduler.md](simulator/docs/integrate-your-scheduler.md).
34
+
35
+
You can create any resources by communicating with kube-apiserver in any ways (kubectl, k8s client library, or web UI described next)
36
+
and see how scheduling is done.
37
+
38
+
When you create Pods, Pods will get annotations from the simulator which contains the scheduling results per plugins or extenders.
You can utilize these results to understand your scheduler, check/test your configurations or customized scheduler's behavior.
27
69
28
-
You can create any resources by communicating with kube-apiserver via kubectl, k8s client library, or web UI.
70
+
Further expansion, you can export internal state more, change specific behaviours on plugins etc by implementing [PluginExtender](./simulator/docs/plugin-extender.md).
71
+
72
+
The simulator has its own configuration,
73
+
you can refer to the [documentation](./simulator/docs/simulator-server-config.md).
29
74
30
75
See the following docs to know more about simulator:
31
76
- [how-it-works.md](simulator/docs/how-it-works.md): describes about how the simulator works.
32
77
- [kube-apiserver.md](simulator/docs/kube-apiserver.md): describe about kube-apiserver in simulator. (how you can configure and access)
33
-
-[api.md](simulator/docs/api.md): describes about HTTP server the simulator has.
78
+
- [api.md](simulator/docs/api.md): describes about HTTP server the simulator has. (mainly for the webUI)
34
79
35
80
### Web UI
36
81
37
-
Web UI is one of the clients of simulator, but it's optimized for simulator.
82
+
It's well-optimized Web UI for the simulator.
83
+
84
+
Web UI is the best way to check the scheduler's behavior very easily.
85
+
Nice table view for the scheduling result, the scheduler configuration reload feature, etc...
86
+
every core features of the simulator can be access with human-friendly ways!
38
87
39
88
From the web, you can create/edit/delete these resources to simulate a cluster.
40
89
@@ -48,7 +97,7 @@ From the web, you can create/edit/delete these resources to simulate a cluster.
Also, You can change the configuration of the scheduler through [KubeSchedulerConfiguration](https://kubernetes.io/docs/reference/scheduling/config/).
66
113
67
-
You can pass a path to KubeSchedulerConfiguration via the environment variable `KUBE_SCHEDULER_CONFIG_PATH` and the simulator will start kube-scheduler with that configuration.
68
-
69
-
Note: changes to any fields other than `.profiles` are disabled on simulator, since they do not affect the results of the scheduling.
114
+
(Note: changes to any fields other than `.profiles` are disabled on simulator, since they do not affect the results of the scheduling.)
If you want to use your custom plugins as out-of-tree plugins in the simulator, please follow [this doc](simulator/docs/how-to-use-custom-plugins/README.md).
74
-
75
118
## Getting started
76
119
77
-
You can find more information about environment variables available in the simulator server
The simulator server configuration can also be set through the configuration file,
82
-
you can refer to the [documentation](./simulator/docs/simulator-server-config.md).
83
-
84
120
### Run simulator with Docker
85
121
86
122
We have [docker-compose.yml](docker-compose.yml) to run the simulator easily. You should install [docker](https://docs.docker.com/engine/install/) and [docker-compose](https://docs.docker.com/compose/install/) firstly.
@@ -101,7 +137,7 @@ Please allocate enough memory in that case.
101
137
102
138
You have to run frontend, server and etcd.
103
139
104
-
#### Run simulator server and etcd
140
+
#### 1. Run simulator server and etcd
105
141
106
142
To run this simulator's server, you have to install Go and etcd.
107
143
@@ -114,12 +150,13 @@ make start
114
150
115
151
It starts etcd and simulator-server locally.
116
152
117
-
#### Run simulator frontend
153
+
#### 2. Run simulator frontend
118
154
119
155
To run the frontend, please see [README.md](web/README.md) on ./web dir.
120
156
121
-
## [Beta] Existing cluster importing
157
+
## Beta features
122
158
159
+
### [Beta] Existing cluster importing
123
160
124
161
The simulator can import resources from your cluster.
125
162
You can use it by setting an `EXTERNAL_IMPORT_ENABLED` environment variable to `1`.
You can change the scheduler configuration in Web UI or
18
+
by passing a default KubeSchedulerConfiguration file via the environment variable `KUBE_SCHEDULER_CONFIG_PATH`.
19
+
20
+
### Example
21
+
22
+
We will explain the case where you want to add [nodenumber](../sample/nodenumber/plugin.go) plugin as example.
23
+
24
+
The nodenumber plugin is an example plugin that favors nodes that have the number suffix which is the same as the number suffix of the pod name.
25
+
And we can configure it via `NodeNumberArgs`.
26
+
27
+
First, you need to add registry for the nodenumber plugin to `outOfTreeRegistries`.
28
+
29
+
```go
30
+
outOfTreeRegistries = runtime.Registry{
31
+
// TODO(user): add your plugins registries here.
32
+
nodenumber.Name: nodenumber.New,
33
+
}
34
+
```
35
+
36
+
Now you can use the nodenumber plugin in the simulator.
37
+
38
+
If you apply this configuration to the scheduler, you can see the nodenumber plugin is working (and NodeNumberArgs is applied to the nodenumber plugin) in the simulator,
39
+
and see the nodenumber plugin's result like other in-tree plugins.
0 commit comments