add inject reference and SCSS styling (kubernetes#3)

* add inject reference and SCSS styling Signed-off-by: Zach Arnold <[email protected]> * remove static folder Signed-off-by: Zach Arnold <[email protected]>
mikutas · Aug 28, 2018 · 04dc2a1 · 04dc2a1
1 parent 0038bca
commit 04dc2a1
Show file tree

Hide file tree

Showing 10 changed files with 208 additions and 6 deletions.
diff --git a/.gitignore b/.gitignore
@@ -1,3 +1,4 @@
 .*.swp
 .DS_Store
 tmp
+.idea
diff --git 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)
diff --git 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
@@ -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
@@ -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.
+<br /><br />
+
+If you run the command `linkerd inject -h` it will provide you with the same information as the table below:
+<br /><br />
+
+
+{.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` |
+
+<br />
+
+## 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.
diff --git 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
@@ -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
@@ -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
@@ -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;
diff --git 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;
+  }
+}