From 04dc2a15a3447402ccde7327f1a2f83eddcbf6dd Mon Sep 17 00:00:00 2001 From: Zach Arnold Date: Tue, 28 Aug 2018 14:43:56 -0700 Subject: [PATCH] add inject reference and SCSS styling (#3) * add inject reference and SCSS styling Signed-off-by: Zach Arnold * remove static folder Signed-off-by: Zach Arnold --- .gitignore | 1 + linkerd.io/content/2/adding-your-service.md | 5 + linkerd.io/content/2/automatic-tls.md | 2 +- linkerd.io/content/2/debugging-an-app.md | 2 +- linkerd.io/content/2/inject-reference.mmark | 182 ++++++++++++++++++++ linkerd.io/content/2/overview.md | 4 +- linkerd.io/content/2/prometheus.md | 2 +- linkerd.io/content/2/proxy-metrics.md | 2 +- linkerd.io/static/scss/custom.scss | 5 + linkerd.io/static/scss/index.scss | 9 + 10 files changed, 208 insertions(+), 6 deletions(-) create mode 100644 linkerd.io/content/2/inject-reference.mmark diff --git a/.gitignore b/.gitignore index 69d3e1a9ffbc8..3a9f2138a8cb9 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,4 @@ .*.swp .DS_Store tmp +.idea \ No newline at end of file diff --git a/linkerd.io/content/2/adding-your-service.md b/linkerd.io/content/2/adding-your-service.md index bcaa5bf2560fd..63ab931e2c8b3 100644 --- a/linkerd.io/content/2/adding-your-service.md +++ b/linkerd.io/content/2/adding-your-service.md @@ -79,3 +79,8 @@ on port 35, use the command: linkerd inject deployment.yml --skip-inbound-ports=35 \ | kubectl apply -f - ``` + +## Inject Command Reference + +For more information on how the inject command works and all of the parameters +that can be set, look at the [Inject Command Reference](../inject-reference) \ No newline at end of file diff --git a/linkerd.io/content/2/automatic-tls.md b/linkerd.io/content/2/automatic-tls.md index 840fdfa42a852..d4fb7d89f05eb 100644 --- a/linkerd.io/content/2/automatic-tls.md +++ b/linkerd.io/content/2/automatic-tls.md @@ -3,7 +3,7 @@ date = "2018-07-31T12:00:00-07:00" title = "Experimental: automatic TLS" [menu.l5d2docs] name = "Experimental: Automatic TLS" - weight = 7 + weight = 8 +++ Linkerd can be configured to automatically negotiate Transport Layer Security diff --git a/linkerd.io/content/2/debugging-an-app.md b/linkerd.io/content/2/debugging-an-app.md index 9d6afec95b54d..5ef25ac4a84fd 100644 --- a/linkerd.io/content/2/debugging-an-app.md +++ b/linkerd.io/content/2/debugging-an-app.md @@ -3,7 +3,7 @@ date = "2018-07-31T12:00:00-07:00" title = "Example: debugging an app" [menu.l5d2docs] name = "Example: Debugging" - weight = 4 + weight = 5 +++ This section assumes you've followed the steps in the [Getting diff --git a/linkerd.io/content/2/inject-reference.mmark b/linkerd.io/content/2/inject-reference.mmark new file mode 100644 index 0000000000000..58d8ac9b62910 --- /dev/null +++ b/linkerd.io/content/2/inject-reference.mmark @@ -0,0 +1,182 @@ ++++ +date = "2018-08-28T08:00:00-07:00" +title = "Linkerd Inject Reference" +[menu.l5d2docs] + name = "Inject Command Reference" + weight = 4 ++++ + +The `linkerd inject` command allows for a quick and reliable setup of the Linkerd Proxy in a Kubernetes Deployment. +This page is useful as a reference to help you understand what `linkerd inject` is doing under the hood, +as well as provide a reference for the flags that can be passed at the command line. +

+ +If you run the command `linkerd inject -h` it will provide you with the same information as the table below: +

+ + +{.table .pure-table .table-striped .table-responsive .table-hover} +| Flag | Explanation | Example | +| -----| --- | --- | +| `--api-port` | The ort where the Linkerd controller is running (default 8086). If you changed any of the port settings on `linkerd install` this flag will be necessary. | `--api-port=9045` | +| `--control-port` | The proxy port to use for control (default 4190). This is the port the Linkerd Proxy Pod uses communicates with the control plane. If 4190 is a reserved port for your application, it can be changed with this flag. | `--control-port=5431`| +| `-h, --help` | The command that prints this table out, but on the command line. | `-h` | +| `--image-pull-policy` | The Docker image pull policy (default "IfNotPresent"). For the injected Linkerd Proxy images (or your own modified variant) choose whether or not you want to have the Kubelet pull the image from the registry Always or Ony If Not Present. | `--image-pull-policy="Always"` | +| `--inbound-port` | The proxy port to use for inbound traffic (default 4143). This port number is arbitrary, but can be changed if your Pod has that port reserved inbound or outbound already. | `--inbound-port=1234`| +| `--init-image` | The Linkerd init container image name (default "gcr.io/linkerd-io/proxy-init"). If you have modified (or made private) the Linkerd Proxy Init Container, you will adjust that here. | `--init-image="quay.io/org/imagename"`| +| `-v, --linkerd-version` | Tag to be used for Linkerd images (default "v18.8.2"). IMPORTANT this version should be the same as your Linkerd control plane version. | `-v="1.0.0"`| +| `--metrics-port` | The proxy port to serve metrics on (default 4191). This port number is arbitrary, but you will want to update your Prometheus installation to match this port number if you change it. | `--metrics-port=10234` | +| `--outbound-port` | The proxy port to use for outbound traffic (default 4140). This port number is arbitrary, but can be changed if your Pod has that port reserved inbound or outbound already. | `--outbound-port=1234` | +| `--proxy-bind-timeout` | The timeout the proxy will use (default "10s"). The amount of time to allow the proxy to bind to the Pod's network interface and begin receiving traffic on behalf of your deployment. If you have especially long start time for a container, you may consider adjusting this. This string will eventually be converted to a [Rust Duration](https://doc.rust-lang.org/beta/std/time/struct.Duration.html), so you'll want to keep this this of the form "[0-9]*s" | `--proxy-bind-timeout="30s"` | +| `--proxy-image` | The linkerd proxy container image name (default "gcr.io/linkerd-io/proxy"). If you have modified (or made private) the Linkerd Proxy Init Container, you will adjust that here. | `--proxy-image="quay.io/org/imagename"` | +| `--proxy-log-level` | The log level for the proxy (default "warn,linkerd2_proxy=info"). The first value is the log level for the Init Container, and the second is the level for the Proxy Container. | `--proxy-log-level="info,linkerd2_proxy=debug"` | +| `--proxy-uid` | Run the proxy under this user ID (default 2102) | `--proxy-uid=123` | +| `--registry` | Docker registry to pull images from (default "gcr.io/linkerd-io") | `--registry="quay.io/ygrene` | +| `--skip-inbound-ports` | Ports that should skip the proxy and send directly to the application (default []). IMPORTANT! If there is a port you do not want Linkerd proxying (for example SMTP port 25) you will _need_ to put it in this list. | `--skip-inbound-ports=25,26,27` | +| `--skip-outbound-ports` | Outbound ports that should skip the proxy (default []). Similarly to the above, if there are outbound ports you don't want leaving the pod from the `--outbound-port` (such as MySQL,) they need to be listed here. | `--skip-outbound-ports=25,3306,5432` | +| `--tls` | Enable TLS; valid settings: "optional". Whether or not you want Linkerd Proxy to attempt an mTLS session between two Pods in the mesh. The only option that is valid is "optional". | `--tls="optional"`| +| `--api-addr` | Override the `kubeconfig` and communicate directly with the control plane at host:port (mostly for testing). | `--api-addr="127.0.0.1:80"` | +| `--kubeconfig` | Path to the kubeconfig file to use for CLI requests. The local path for your Kubernetes config manifest. | `--kubeconfig="~/.kube/config"` | +| `-l, --linkerd-namespace` | Namespace in which Linkerd is installed (default "linkerd"). If you modified the `linkerd install` command and adjusted the Kubernetes Namespace it was deployed into, you'll want to adjust it here. | `-l="default"` | +| `--verbose` | Turn on debug logging. Log all the things. (Especially those things that `linkerd inject` does.) | `--verbose` | + +
+ +## What `linkerd inject` Is Doing +`linkerd inject` is modifying the Kubernetes Deployment manifest that is being passed to it +either as a file or as a stream to its standard in. It is adding two things: + +1. An Init Container (supported as of Kubernetes version 1.6 or greater) +1. A Linkerd Proxy sidecar container into each Pod belonging to your Deployment + +The Init Container is responsible for pulling configuration (such as certificates) from the Kubernetes API/Linkerd Controller, +as well as provide configuration to the Linkerd Proxy container for its runtime. + +## Example Deployment + +Let's say for example you have the following deployment saved as `deployment.yaml`: + +```yaml +apiVersion: apps/v1 +kind: Deployment +metadata: + name: example-deployment + namespace: default +spec: + replicas: 3 + selector: + matchLabels: + app: example-deployment + env: default + template: + metadata: + labels: + app: example-deployment + env: default + spec: + containers: + - name: app + image: quay.io/ygrene/hello-docker + ports: + - containerPort: 3000 +``` + +Now, we can run the `linkerd inject` command as follows: + +```bash +$ linkerd inject --proxy-log-level="debug" --skip-outbound-ports=3306 deployment.yaml > deployment_with_linkerd.yaml +``` + +The output of that file should look like the following: + +```yaml +apiVersion: apps/v1 +kind: Deployment +metadata: + creationTimestamp: null + name: example-deployment + namespace: default +spec: + replicas: 3 + selector: + matchLabels: + app: example-deployment + env: default + strategy: {} + template: + metadata: + annotations: + linkerd.io/created-by: linkerd/cli v18.8.2 + linkerd.io/proxy-version: v18.8.2 + creationTimestamp: null + labels: + app: example-deployment + env: default + linkerd.io/control-plane-ns: linkerd + linkerd.io/proxy-deployment: example-deployment + spec: + containers: + - image: quay.io/ygrene/hello-docker + name: app + ports: + - containerPort: 3000 + resources: {} + - env: + - name: LINKERD2_PROXY_LOG + value: debug + - name: LINKERD2_PROXY_BIND_TIMEOUT + value: 10s + - name: LINKERD2_PROXY_CONTROL_URL + value: tcp://proxy-api.linkerd.svc.cluster.local:8086 + - name: LINKERD2_PROXY_CONTROL_LISTENER + value: tcp://0.0.0.0:4190 + - name: LINKERD2_PROXY_METRICS_LISTENER + value: tcp://0.0.0.0:4191 + - name: LINKERD2_PROXY_PRIVATE_LISTENER + value: tcp://127.0.0.1:4140 + - name: LINKERD2_PROXY_PUBLIC_LISTENER + value: tcp://0.0.0.0:4143 + - name: LINKERD2_PROXY_POD_NAMESPACE + valueFrom: + fieldRef: + fieldPath: metadata.namespace + image: gcr.io/linkerd-io/proxy:v18.8.2 + imagePullPolicy: IfNotPresent + name: linkerd-proxy + ports: + - containerPort: 4143 + name: linkerd-proxy + - containerPort: 4191 + name: linkerd-metrics + resources: {} + securityContext: + runAsUser: 2102 + terminationMessagePolicy: FallbackToLogsOnError + initContainers: + - args: + - --incoming-proxy-port + - "4143" + - --outgoing-proxy-port + - "4140" + - --proxy-uid + - "2102" + - --inbound-ports-to-ignore + - 4190,4191 + - --outbound-ports-to-ignore + - "3306" + image: gcr.io/linkerd-io/proxy-init:v18.8.2 + imagePullPolicy: IfNotPresent + name: linkerd-init + resources: {} + securityContext: + capabilities: + add: + - NET_ADMIN + privileged: false + terminationMessagePolicy: FallbackToLogsOnError +status: {} +--- + +``` + +Note here how the Init Container and Proxy Sidecar Container are added to the manifest with configuration we passed as command line flags. \ No newline at end of file diff --git a/linkerd.io/content/2/overview.md b/linkerd.io/content/2/overview.md index e5536111fa8c8..83f43971891d0 100644 --- a/linkerd.io/content/2/overview.md +++ b/linkerd.io/content/2/overview.md @@ -66,7 +66,7 @@ The complete config for this test may be found in the [perf-baseline environment](https://github.com/linkerd/linkerd-examples/tree/master/perf-baseline). | Metric | Value | -| ----------- | ---------: | +| ----------- | --------- | | Memory | 20.5MB | | CPU | 0.107 cores | | p50 latency | <1ms | @@ -82,7 +82,7 @@ The complete config for this test may be found in the [lifecycle test environment](https://github.com/linkerd/linkerd-examples/tree/master/lifecycle). | Process | Memory (MB) | CPU (cores) | -| ------------- | ----------: | ----------: | +| ------------- | ---------- | ---------- | | *Total* | *363* | *0.051* | | Prometheus | 232 | 0.036 | | Grafana | 26 | 0.007 | diff --git a/linkerd.io/content/2/prometheus.md b/linkerd.io/content/2/prometheus.md index 049e1526360d6..ec4c11eb8baa7 100644 --- a/linkerd.io/content/2/prometheus.md +++ b/linkerd.io/content/2/prometheus.md @@ -3,7 +3,7 @@ date = "2018-07-31T12:00:00-07:00" title = "Exporting metrics to Prometheus" [menu.l5d2docs] name = "Exporting to Prometheus" - weight = 5 + weight = 6 +++ If you have an existing Prometheus cluster, it is very easy to export Linkerd's diff --git a/linkerd.io/content/2/proxy-metrics.md b/linkerd.io/content/2/proxy-metrics.md index 1e19542483501..78a394ecad337 100644 --- a/linkerd.io/content/2/proxy-metrics.md +++ b/linkerd.io/content/2/proxy-metrics.md @@ -3,7 +3,7 @@ date = "2018-07-31T12:00:00-07:00" title = "Metrics exported by the proxy" [menu.l5d2docs] name = "Proxy Metrics" - weight = 6 + weight = 7 +++ The Linkerd proxy exposes metrics that describe the traffic flowing through the diff --git a/linkerd.io/static/scss/custom.scss b/linkerd.io/static/scss/custom.scss index bd4711ce1daa9..0496f7b75b78a 100644 --- a/linkerd.io/static/scss/custom.scss +++ b/linkerd.io/static/scss/custom.scss @@ -4,3 +4,8 @@ $primary: #236Ad9; $font-family-sans-serif: lato,helvetica neue,sans-serif; $headings-font-weight: 300; + +$table-cell-min-width: 10em; + +$code-color: #343a40; +$code-background: #e9ecef; \ No newline at end of file diff --git a/linkerd.io/static/scss/index.scss b/linkerd.io/static/scss/index.scss index ffcd5ab91cc66..24a5b0f668fb4 100644 --- a/linkerd.io/static/scss/index.scss +++ b/linkerd.io/static/scss/index.scss @@ -62,3 +62,12 @@ footer li { border-top: 0px !important; } } + +code { + $code-background: $code-background; +} +.table { + td { + min-width: $table-cell-min-width; + } +} \ No newline at end of file