1# Linkerd Extensions
2
3Linkerd has an extension model which allows 3rd parties to add functionality.
4Each extension consists of a binary CLI named `linkerd-name` (where `name` is
5the name of the extension) as well as a set of Kubernetes resources. To invoke
6an extension, users can run `linkerd name` which will search the current PATH
7for an executable named `linkerd-name` and execute it.
8
9## Installing Extensions
10
11To install an extension, first download the extension executable and put it
12in your PATH. The extension can then be installed into your Kubernetes cluster
13by running `linkerd <extension name> install | kubectl apply -f -`. Similarly,
14it can be uninstalled by running
15`linkerd <extension name> uninstall | kubectl delete -f -`.
16
17A full list of installed extensions can be printed by running `linkerd check`.
18
19## Developing Extensions
20
21The extension must be an executable file named `linkerd-name` where `name` is
22the name of the extension. The name must not be any of the built-in Linkerd
23commands (e.g. `check`) or extensions (e.g. `viz`).
24
25The extension must accept the following flags and respect them any time that
26it communicates with the Kubernetes API. All of these flags must be accepted
27but may be ignored if they are not applicable.
28
29* `--api-addr`: Override kubeconfig and communicate directly with the control
30 plane at host:port (mostly for testing)
31* `--context`: Name of the kubeconfig context to use
32* `--as`: Username to impersonate for Kubernetes operations
33* `--as-group`: Group to impersonate for Kubernetes operations
34* `--help`/`-h`: Print help message
35* `--kubeconfig`: Path to the kubeconfig file to use for CLI requests
36* `--linkerd-namespace`/`-L`: Namespace in which Linkerd is installed
37 [$LINKERD_NAMESPACE]
38* `--verbose`: Turn on debug logging
39
40The extension must implement these commands:
41
42### `linkerd-name install`
43
44This command must print the Kubernetes manifests for the extension as yaml
45which is suitable to be passed to `kubectl apply -f`. These manifests must
46include a Namespace resource with the label `linkerd.io/extension=name` where
47`name` is the name of the extension. This allows Linkerd to detect installed
48extensions.
49
50### `linkerd-name uninstall`
51
52This command must print manifests for all cluster-scoped Kubernetes resources
53belonging to this extension (including the extension Namespace) as yaml which
54is suitable to be passed to `kubectl delete -f`.
55
56### `linkerd-name check`
57
58This command must perform any appropriate health checks for the extension
59including but not limited to checking that the extension resources exist and
60are in a healthy state. This command must exit with a status code of 0 if the
61checks pass or with a nonzero status code if they do not pass. For consistency,
62it is recommended that this command follows the same output formatting as
63`linkerd check`, e.g.
64
65```console
66linkerd-version
67---------------
68√ can determine the latest version
69√ cli is up-to-date
70
71Status check results are √
72```
73
74The final line of output should be either `Status check results are √` or
75`Status check results are ×`.
76
77In addition to the flags described above, `linkerd-name check` must accept the
78following flags:
79
80* `--namespace`/`-n`: Namespace to use for –proxy checks (default: all
81 namespaces)
82* `--output`/`-o`: Output format. One of: table, json, short
83* `--pre`: Only run pre-installation checks, to determine if the extension can
84 be installed
85* `--proxy`: Only run data-plane checks, to determine if the data plane is
86 healthy
87* `--wait`: Maximum allowed time for all tests to pass
88
89If the output format is set to json then output must be in json format
90instead of the output format described above. E.g.
91
92```json
93{
94 "success": false,
95 "categories": [
96 {
97 "categoryName": "kubernetes-api",
98 "checks": [
99 {
100 "description": "can initialize the client",
101 "result": "success"
102 },
103 {
104 "description": "can query the Kubernetes API",
105 "result": "success"
106 },
107 {
108 "description": "linkerd-viz Namespace exists",
109 "hint": "https://linkerd.io/2/checks/#l5d-viz-ns-exists",
110 "error": "could not find the linkerd-viz extension",
111 "result": "error"
112 }
113 ]
114 }
115 ]
116}
117```
118
119In particular, the `linkerd check` command will invoke the check command for
120each extension installed in the cluster and will request json output.
121`linkerd check` may optinally invoke your extension if not installed in the
122cluster (see `linkerd-name _extension-metadata` below to opt-in). To preserve
123forwards compatibility, it is recommended that the check command should ignore
124any unknown flags.
125
126### `linkerd-name _extension-metadata`
127
128This subcommand is optional, and enables an extension to opt-in to being
129executed as part of `linkerd check`, even when there is no corresponding
130extension on the cluster. To opt-in, the output of
131`linkerd-name _extension-metadata` should be json of the form:
132
133```json
134{
135 "name": "linkerd-name",
136 "checks": "always",
137}
138```
139
140Note that for `linkerd check` to validate which extensions are opting-in, it
141runs `linkerd-* _extension-metadata` against every executable in the PATH.
142
143The extension may also implement further commands in addition to the ones
144defined here.
View as plain text