Skip to content

Commit 7b39417

Browse files
timebertttimebertt
committed
Update docs
1 parent dea3ce5 commit 7b39417

File tree

4 files changed

+29
-29
lines changed

4 files changed

+29
-29
lines changed

‎docs/development.md‎

Lines changed: 3 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -120,13 +120,12 @@ The `Secrets` created by the example shard controller should be assigned to the
120120
$ kubectl create cm foo
121121
configmap/foo created
122122

123-
$ kubectl get cm,secret -L shard.alpha.sharding.timebertt.dev/50d858e0-example
124-
NAME DATA AGE 50D858E0-EXAMPLE
123+
$ kubectl get cm,secret -L shard.alpha.sharding.timebertt.dev/example
124+
NAME DATA AGE EXAMPLE
125125
configmap/foo 0 1s shard-656d588475-5746d
126126

127-
NAME TYPE DATA AGE 50D858E0-EXAMPLE
127+
NAME TYPE DATA AGE EXAMPLE
128128
secret/dummy-foo Opaque 0 1s shard-656d588475-5746d
129-
secret/dummy-kube-root-ca.crt Opaque 0 2m14s
130129
```
131130

132131
## Monitoring

‎docs/evaluation.md‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -25,20 +25,20 @@ To perform a quick test of the webhosting-operator, create some example `Website
2525
$ kubectl apply -k webhosting-operator/config/samples
2626
...
2727

28-
$ kubectl -n project-foo get website,deploy,svc,ing -L shard.alpha.sharding.timebertt.dev/ef3d63cd-webhosting-operator
29-
NAME THEME PHASE SINCE AGE EF3D63CD-WEBHOSTING-OPERATOR
28+
$ kubectl -n project-foo get website,deploy,svc,ing -L shard.alpha.sharding.timebertt.dev/webhosting-operator
29+
NAME THEME PHASE SINCE AGE WEBHOSTING-OPERATOR
3030
website.webhosting.timebertt.dev/homepage exciting Ready 6s 16s webhosting-operator-98ff76b66-tdrtc
3131
website.webhosting.timebertt.dev/official lame Ready 5s 16s webhosting-operator-98ff76b66-tdrtc
3232

33-
NAME READY UP-TO-DATE AVAILABLE AGE EF3D63CD-WEBHOSTING-OPERATOR
33+
NAME READY UP-TO-DATE AVAILABLE AGE WEBHOSTING-OPERATOR
3434
deployment.apps/homepage-98bad4 1/1 1 1 15s webhosting-operator-98ff76b66-tdrtc
3535
deployment.apps/official-10ff22 1/1 1 1 15s webhosting-operator-98ff76b66-tdrtc
3636

37-
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE EF3D63CD-WEBHOSTING-OPERATOR
37+
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE WEBHOSTING-OPERATOR
3838
service/homepage-98bad4 ClusterIP 100.82.128.107 <none> 8080/TCP 16s webhosting-operator-98ff76b66-tdrtc
3939
service/official-10ff22 ClusterIP 100.82.194.21 <none> 8080/TCP 16s webhosting-operator-98ff76b66-tdrtc
4040

41-
NAME CLASS HOSTS ADDRESS PORTS AGE EF3D63CD-WEBHOSTING-OPERATOR
41+
NAME CLASS HOSTS ADDRESS PORTS AGE WEBHOSTING-OPERATOR
4242
ingress.networking.k8s.io/homepage-98bad4 nginx webhosting.timebertt.dev 80, 443 16s webhosting-operator-98ff76b66-tdrtc
4343
ingress.networking.k8s.io/official-10ff22 nginx webhosting.timebertt.dev 80, 443 15s webhosting-operator-98ff76b66-tdrtc
4444
```

‎docs/getting-started.md‎

Lines changed: 15 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -79,8 +79,8 @@ The sharder created a `MutatingWebhookConfiguration` for the resources listed in
7979

8080
```bash
8181
$ kubectl get mutatingwebhookconfiguration -l alpha.sharding.timebertt.dev/controllerring=example
82-
NAME WEBHOOKS AGE
83-
sharding-50d858e0-example 1 2m50s
82+
NAME WEBHOOKS AGE
83+
controllerring-example 1 2m50s
8484
```
8585

8686
Let's examine the webhook configuration for more details.
@@ -92,7 +92,7 @@ I.e., it gets called for unassigned objects and adds the shard assignment label
9292
apiVersion: admissionregistration.k8s.io/v1
9393
kind: MutatingWebhookConfiguration
9494
metadata:
95-
name: sharding-50d858e0-example
95+
name: controllerring-example
9696
webhooks:
9797
- clientConfig:
9898
service:
@@ -106,7 +106,7 @@ webhooks:
106106
kubernetes.io/metadata.name: default
107107
objectSelector:
108108
matchExpressions:
109-
- key: shard.alpha.sharding.timebertt.dev/50d858e0-example
109+
- key: shard.alpha.sharding.timebertt.dev/example
110110
operator: DoesNotExist
111111
rules:
112112
- apiGroups:
@@ -144,7 +144,7 @@ apiVersion: v1
144144
kind: ConfigMap
145145
metadata:
146146
labels:
147-
shard.alpha.sharding.timebertt.dev/50d858e0-example: shard-9c6678c9f-8jc5b
147+
shard.alpha.sharding.timebertt.dev/example: shard-9c6678c9f-8jc5b
148148
name: foo
149149
namespace: default
150150
```
@@ -162,7 +162,7 @@ apiVersion: v1
162162
kind: Secret
163163
metadata:
164164
labels:
165-
shard.alpha.sharding.timebertt.dev/50d858e0-example: shard-9c6678c9f-8jc5b
165+
shard.alpha.sharding.timebertt.dev/example: shard-9c6678c9f-8jc5b
166166
name: dummy-foo
167167
namespace: default
168168
ownerReferences:
@@ -176,8 +176,8 @@ Let's create a few more `ConfigMaps` and observe the distribution of objects acr
176176

177177
```bash
178178
$ for i in $(seq 1 9); do k create cm foo$i ; done
179-
$ kubectl get cm,secret -L shard.alpha.sharding.timebertt.dev/50d858e0-example
180-
NAME DATA AGE 50D858E0-EXAMPLE
179+
$ kubectl get cm,secret -L shard.alpha.sharding.timebertt.dev/example
180+
NAME DATA AGE EXAMPLE
181181
configmap/foo 0 52s shard-9c6678c9f-8jc5b
182182
configmap/foo1 0 7s shard-9c6678c9f-v4bw2
183183
configmap/foo2 0 6s shard-9c6678c9f-8jc5b
@@ -189,7 +189,7 @@ configmap/foo7 0 6s shard-9c6678c9f-xntqc
189189
configmap/foo8 0 6s shard-9c6678c9f-xntqc
190190
configmap/foo9 0 6s shard-9c6678c9f-8jc5b
191191
192-
NAME TYPE DATA AGE 50D858E0-EXAMPLE
192+
NAME TYPE DATA AGE EXAMPLE
193193
secret/dummy-foo Opaque 0 52s shard-9c6678c9f-8jc5b
194194
secret/dummy-foo1 Opaque 0 7s shard-9c6678c9f-v4bw2
195195
secret/dummy-foo2 Opaque 0 6s shard-9c6678c9f-8jc5b
@@ -234,8 +234,8 @@ As the original shard is not available anymore, moving the objects doesn't need
234234
```bash
235235
$ kubectl get cm --show-labels -w --output-watch-events --watch-only
236236
EVENT NAME DATA AGE LABELS
237-
MODIFIED foo4 0 7m52s shard.alpha.sharding.timebertt.dev/50d858e0-example=shard-9c6678c9f-ppzf7
238-
MODIFIED foo6 0 7m52s shard.alpha.sharding.timebertt.dev/50d858e0-example=shard-9c6678c9f-ppzf7
237+
MODIFIED foo4 0 7m52s shard.alpha.sharding.timebertt.dev/example=shard-9c6678c9f-ppzf7
238+
MODIFIED foo6 0 7m52s shard.alpha.sharding.timebertt.dev/example=shard-9c6678c9f-ppzf7
239239
```
240240

241241
## Adding Shards to the Ring
@@ -270,10 +270,10 @@ This triggers the sharder webhook which immediately assigns the object to the de
270270
```bash
271271
$ kubectl get cm --show-labels -w --output-watch-events --watch-only
272272
EVENT NAME DATA AGE LABELS
273-
MODIFIED foo4 0 9m2s drain.alpha.sharding.timebertt.dev/50d858e0-example=true,shard.alpha.sharding.timebertt.dev/50d858e0-example=shard-9c6678c9f-ppzf7
274-
MODIFIED foo7 0 9m2s drain.alpha.sharding.timebertt.dev/50d858e0-example=true,shard.alpha.sharding.timebertt.dev/50d858e0-example=shard-9c6678c9f-ppzf7
275-
MODIFIED foo4 0 9m2s shard.alpha.sharding.timebertt.dev/50d858e0-example=shard-9c6678c9f-jkgj6
276-
MODIFIED foo7 0 9m2s shard.alpha.sharding.timebertt.dev/50d858e0-example=shard-9c6678c9f-jkgj6
273+
MODIFIED foo4 0 9m2s drain.alpha.sharding.timebertt.dev/example=true,shard.alpha.sharding.timebertt.dev/example=shard-9c6678c9f-ppzf7
274+
MODIFIED foo7 0 9m2s drain.alpha.sharding.timebertt.dev/example=true,shard.alpha.sharding.timebertt.dev/example=shard-9c6678c9f-ppzf7
275+
MODIFIED foo4 0 9m2s shard.alpha.sharding.timebertt.dev/example=shard-9c6678c9f-jkgj6
276+
MODIFIED foo7 0 9m2s shard.alpha.sharding.timebertt.dev/example=shard-9c6678c9f-jkgj6
277277
```
278278

279279
## Clean Up

‎docs/implement-sharding.md‎

Lines changed: 6 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,8 @@ spec:
2929
resource: replicasets
3030
```
3131
32+
Note that the `ControllerRing` name must not be longer than 63 characters because it is used as part of the shard and drain label key (see below).
33+
3234
To allow the sharder to reassign the sharded objects during rebalancing, we need to grant the corresponding permissions.
3335
We need to grant these permissions explicitly depending on what is configured in the `ControllerRing`.
3436
Otherwise, the sharder would basically require `cluster-admin` access.
@@ -166,13 +168,12 @@ func run() error {
166168
In short: use the following label selector on watches for all sharded resources listed in the `ControllerRing`.
167169

168170
```text
169-
shard.alpha.sharding.timebertt.dev/50d858e0-example: my-operator-565df55f4b-5vwpj
171+
shard.alpha.sharding.timebertt.dev/example: my-operator-565df55f4b-5vwpj
170172
```
171173

172174
The sharder assigns all sharded objects by adding a shard label that is specific to the `ControllerRing` (resources could be part of multiple `ControllerRings`).
173-
The shard label's key consists of the `shard.alpha.sharding.timebertt.dev/` prefix followed by the first 8 hex characters of the SHA256 checksum of the `ControllerRing` name followed by a `-` followed by the `ControllerRing` name itself.
174-
The key part after the `/` is shortened to 63 characters so that it is a valid label key.
175-
The checksum is added to the label key to derive unique label keys even for `ControllerRings` with long names that would cause the pattern to exceed the 63 characters limit after the `/`.
175+
The shard label's key consists of the `shard.alpha.sharding.timebertt.dev/` prefix followed by the `ControllerRing` name.
176+
As the key part after the `/` must not exceed 63 characters, the `ControllerRing` name must not be longer than 63 characters.
176177
The shard label's value is the name of the shard, i.e., the name of the shard lease and the shard lease's `holderIdentity`.
177178

178179
Once you have determined the shard label key for your `ControllerRing`, use it as a selector on all watches that your controller starts for any of the sharded resources.
@@ -221,7 +222,7 @@ In short: ensure your sharded controller acknowledges drain operations.
221222
When the drain label like this is added by the sharder, the controller needs to remove both the shard and the drain label and stop reconciling the object.
222223

223224
```text
224-
drain.alpha.sharding.timebertt.dev/50d858e0-example
225+
drain.alpha.sharding.timebertt.dev/example
225226
```
226227

227228
When the sharder needs to move an object from an available shard to another shard for rebalancing, it first adds the drain label to instruct the currently responsible shard to stop reconciling the object.

0 commit comments

Comments
 (0)