Skip to content

Commit da768b5

Browse files
alpebmateiidavid
alpeb
and
mateiidavid
authored
Refactored README.md (#97)
* Refactored README.md Supersedes #85 Cleared it up a little bit and fixed some bugs. Co-authored-by: Matei David <[email protected]>
1 parent bcc14fe commit da768b5

File tree

3 files changed

+167
-51
lines changed

3 files changed

+167
-51
lines changed

‎README.md‎

Lines changed: 51 additions & 45 deletions
Original file line numberDiff line numberDiff line change
@@ -8,45 +8,15 @@ The mechanism relies on Linkerd’s traffic-splitting functionality by providing
88
an operator to alter the backend services' weights in real time depending on
99
their readiness.
1010

11-
## Failover criteria
11+
## Table of contents
1212

13-
The failover criteria is readiness failures on the targeted Pods. This is
14-
directly reflected on the Endpoints pointing to those Pods: only when Pods are
15-
ready, does the `addresses` field of the relevant Endpoints get populated.
16-
17-
## Services declaration
18-
19-
The primitive used to declare the services to fail over is Linkerd's
20-
`TrafficSplit` CRD. The `spec.service` field contains the service name addressed
21-
by clients, and the `spec.backends` fields contain all the possible services
22-
that apex service might be served by. The service to be considered as primary is
23-
declared in the `failover.linkerd.io/primary-service` annotation. Those backend
24-
services can be located in the current cluster or they can point to mirror
25-
services backed by services in other clusters (through Linkerd's multicluster
26-
functionality).
27-
28-
## Operator
29-
30-
Linkerd-failover is an operator to be installed in the local cluster (there
31-
where the clients consuming the service live), whose responsibility is to watch
32-
over the state of the Endpoints that are associated to the backends of the
33-
`TrafficSplit`, reacting to the failover criteria explained above.
34-
35-
## Failover logic
36-
37-
The following describes the logic used to change the `TrafficSplit` weights:
38-
39-
- Whenever the primary backend is ready, all the weight is set to it, setting
40-
the weights for all the secondary backends to zero.
41-
- Whenever the primary backend is not ready, the following rules apply only if
42-
there is at least one secondary backend that is ready:
43-
- The primary backend’s weight is set to zero
44-
- The weight is distributed equally among all the secondary backends that
45-
are ready
46-
- Whenever a secondary backend changes its readiness, the weight is
47-
redistributed among all the secondary backends that are ready
48-
- Whenever both the primary and secondaries are all unavailable, the connection
49-
will fail at the client-side, as expected.
13+
- [Requirements](#requirements)
14+
- [Configuration](#configuration)
15+
- [Installation](#installation)
16+
- [Example](#example)
17+
- [Implementation details](#implementation-details)
18+
- [Failover criteria](#failover-criteria)
19+
- [Failover logic](#failover-criteria)
5020

5121
## Requirements
5222

@@ -60,9 +30,13 @@ The following Helm values are available:
6030
- `selector`: determines which `TrafficSplit` instances to consider for
6131
failover. It defaults to `failover.linkerd.io/controlled-by={{.Release.Name}}`
6232
(the value refers to the release name used in `helm install`).
33+
- `logLevel`, `logFormat`: for configuring the operator's logging.
6334

6435
## Installation
6536

37+
The SMI extension and the operator are to be installed in the local cluster
38+
(where the clients consuming the service are located).
39+
6640
Linkerd-smi installation:
6741

6842
```console
@@ -74,21 +48,28 @@ helm install linkerd-smi -n linkerd-smi --create-namespace linkerd-smi/linkerd-s
7448
Linkerd-failover installation:
7549

7650
```console
77-
helm install linkerd-failover -n linkerd-failover --create-namespace --devel linkerd/linkerd-failover
78-
```
79-
80-
### Running locally for testing
51+
# In case you haven't added the linkerd-edge repo already
52+
helm repo add linkerd-edge https://helm.linkerd.io/edge
53+
helm repo up
8154

82-
```console
83-
cargo run
55+
helm install linkerd-failover -n linkerd-failover --create-namespace --devel linkerd-edge/linkerd-failover
8456
```
8557

8658
## Example
8759

8860
The following `TrafficSplit` serves as the initial state for a failover setup.
61+
62+
Clients should send requests to the apex service `sample-svc`. The primary
63+
service that will serve these requests is declared through the
64+
`failover.linkerd.io/primary-service` annotation, `sample-svc` in this case.
65+
8966
When `sample-svc` starts failing, the weights will be switched over the other
9067
backends.
9168

69+
Note that the failover services can be located in the local cluster, or they can
70+
point to mirror services backed by services in other clusters (through Linkerd's
71+
multicluster functionality).
72+
9273
```yaml
9374
apiVersion: split.smi-spec.io/v1alpha2
9475
kind: TrafficSplit
@@ -97,7 +78,7 @@ metadata:
9778
annotations:
9879
failover.linkerd.io/primary-service: sample-svc
9980
labels:
100-
app.kubernetes.io/managed-by: linkerd-failover
81+
failover.linkerd.io/controlled-by: linkerd-failover
10182
spec:
10283
service: sample-svc
10384
backends:
@@ -112,3 +93,28 @@ spec:
11293
- service: sample-svc-asia1
11394
weight: 0
11495
```
96+
97+
## Implementation details
98+
99+
### Failover criteria
100+
101+
The failover criteria is readiness failures on the targeted Pods. This is
102+
directly reflected on the Endpoints object associated with those Pods: only when
103+
Pods are ready, does the `addresses` field of the relevant Endpoints get
104+
populated.
105+
106+
### Failover logic
107+
108+
The following describes the logic used to change the `TrafficSplit` weights:
109+
110+
- Whenever the primary backend is ready, all the weight is set to it, setting
111+
the weights for all the secondary backends to zero.
112+
- Whenever the primary backend is not ready, the following rules apply only if
113+
there is at least one secondary backend that is ready:
114+
- The primary backend’s weight is set to zero.
115+
- The weight is distributed equally among all the secondary backends that
116+
are ready.
117+
- Whenever a secondary backend changes its readiness, the weight is
118+
redistributed among all the secondary backends that are ready
119+
- Whenever both the primary and secondaries are unavailable, the connection will
120+
fail at the client-side, as expected.

‎charts/linkerd-failover/README.md‎

Lines changed: 58 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -7,24 +7,79 @@
77

88
**Homepage:** <https://linkerd.io>
99

10-
## Linkerd-smi Required
10+
## Requirements
1111

1212
Besides Linkerd and the operator itself, since we make use of the `TrafficSplit`
1313
CRD, it is required to install the `linkerd-smi` extension.
1414

15+
## Configuration
16+
17+
The following Helm values are available:
18+
19+
- `selector`: determines which `TrafficSplit` instances to consider for
20+
failover.
21+
- `logLevel`, `logFormat`: for configuring the operators logging.
22+
1523
## Installation
1624

25+
The SMI extension and the operator are to be installed in the local cluster
26+
(there where the clients consuming the service are located).
27+
1728
Linkerd-smi installation:
1829

1930
```console
20-
helm repo add linderd-smi https://linkerd.github.io/linkerd-smi
31+
helm repo add linkerd-smi https://linkerd.github.io/linkerd-smi
32+
helm repo up
2133
helm install linkerd-smi -n linkerd-smi --create-namespace linkerd-smi/linkerd-smi
2234
```
2335

2436
Linkerd-failover installation:
2537

2638
```console
27-
helm install linkerd-failover -n linkerd-failover --create-namespace --devel linkerd/linkerd-failover
39+
# In case you haven't added the linkerd-edge repo already
40+
helm repo add linkerd-edge https://helm.linkerd.io/edge
41+
helm repo up
42+
43+
helm install linkerd-failover -n linkerd-failover --create-namespace --devel linkerd-edge/linkerd-failover
44+
```
45+
46+
## Example
47+
48+
The following `TrafficSplit` serves as the initial state for a failover setup.
49+
50+
Clients should send requests to the apex service `sample-svc`. The primary
51+
service that will serve these requests is declared through the
52+
`failover.linkerd.io/primary-service` annotation, `sample-svc` in this case.
53+
54+
When `sample-svc` starts failing, the weights will be switched over the other
55+
backends.
56+
57+
Note that the failover services can be located in the local cluster, or they can
58+
point to mirror services backed by services in other clusters (through Linkerd's
59+
multicluster functionality).
60+
61+
```yaml
62+
apiVersion: split.smi-spec.io/v1alpha2
63+
kind: TrafficSplit
64+
metadata:
65+
name: sample-svc
66+
annotations:
67+
failover.linkerd.io/primary-service: sample-svc
68+
labels:
69+
failover.linkerd.io/controlled-by: linkerd-failover
70+
spec:
71+
service: sample-svc
72+
backends:
73+
- service: sample-svc
74+
weight: 1
75+
- service: sample-svc-central1
76+
weight: 0
77+
- service: sample-svc-east1
78+
weight: 0
79+
- service: sample-svc-east2
80+
weight: 0
81+
- service: sample-svc-asia1
82+
weight: 0
2883
```
2984
3085
## Get involved

‎charts/linkerd-failover/README.md.gotmpl‎

Lines changed: 58 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -8,24 +8,79 @@
88

99
{{ template "chart.homepageLine" . }}
1010

11-
## Linkerd-smi Required
11+
## Requirements
1212

1313
Besides Linkerd and the operator itself, since we make use of the `TrafficSplit`
1414
CRD, it is required to install the `linkerd-smi` extension.
1515

16+
## Configuration
17+
18+
The following Helm values are available:
19+
20+
- `selector`: determines which `TrafficSplit` instances to consider for
21+
failover.
22+
- `logLevel`, `logFormat`: for configuring the operators logging.
23+
1624
## Installation
1725

26+
The SMI extension and the operator are to be installed in the local cluster
27+
(there where the clients consuming the service are located).
28+
1829
Linkerd-smi installation:
1930

2031
```console
21-
helm repo add linderd-smi https://linkerd.github.io/linkerd-smi
32+
helm repo add linkerd-smi https://linkerd.github.io/linkerd-smi
33+
helm repo up
2234
helm install linkerd-smi -n linkerd-smi --create-namespace linkerd-smi/linkerd-smi
2335
```
2436

2537
Linkerd-failover installation:
2638

2739
```console
28-
helm install linkerd-failover -n linkerd-failover --create-namespace --devel linkerd/linkerd-failover
40+
# In case you haven't added the linkerd-edge repo already
41+
helm repo add linkerd-edge https://helm.linkerd.io/edge
42+
helm repo up
43+
44+
helm install linkerd-failover -n linkerd-failover --create-namespace --devel linkerd-edge/linkerd-failover
45+
```
46+
47+
## Example
48+
49+
The following `TrafficSplit` serves as the initial state for a failover setup.
50+
51+
Clients should send requests to the apex service `sample-svc`. The primary
52+
service that will serve these requests is declared through the
53+
`failover.linkerd.io/primary-service` annotation, `sample-svc` in this case.
54+
55+
When `sample-svc` starts failing, the weights will be switched over the other
56+
backends.
57+
58+
Note that the failover services can be located in the local cluster, or they can
59+
point to mirror services backed by services in other clusters (through Linkerd's
60+
multicluster functionality).
61+
62+
```yaml
63+
apiVersion: split.smi-spec.io/v1alpha2
64+
kind: TrafficSplit
65+
metadata:
66+
name: sample-svc
67+
annotations:
68+
failover.linkerd.io/primary-service: sample-svc
69+
labels:
70+
failover.linkerd.io/controlled-by: linkerd-failover
71+
spec:
72+
service: sample-svc
73+
backends:
74+
- service: sample-svc
75+
weight: 1
76+
- service: sample-svc-central1
77+
weight: 0
78+
- service: sample-svc-east1
79+
weight: 0
80+
- service: sample-svc-east2
81+
weight: 0
82+
- service: sample-svc-asia1
83+
weight: 0
2984
```
3085

3186
## Get involved

0 commit comments

Comments
 (0)