Add docs for headless services.

Signed-off-by: Jose Cortes <[email protected]>

reference/cluster-config.md

@@ -246,6 +246,12 @@ Note that this <code>initContainer</code> requires `NET_ADMIN` capabilities.
 If your cluster administrator has disabled them, you will be unable to use numeric ports with the agent injector.
 </Alert>
 
+<Alert severity="info">
+This requires the Traffic Agent to run as GID <code>7777</code>. By default, this is disabled on openshift clusters.
+To enable running as GID <code>7777</code> on a specific openshift namespace, run:
+<code>oc adm policy add-scc-to-group anyuid system:serviceaccounts:$NAMESPACE</code>
+</Alert>
+
 For example, the following service is using a numeric port, so Telepresence would inject an initContainer into it:
 ```yaml
 apiVersion: v1
@@ -284,9 +290,3 @@ spec:
           ports:
             - containerPort: 8080
 ```
-
-### Note on Intercepting Headless Services
-<Alert severity="info">
-Note that this utilizes the <code>initContainer</code> that requires `NET_ADMIN` capabilities.
-If your cluster administrator has disabled them, you will be unable to use numeric ports with the agent injector.
-</Alert>

reference/intercepts.md

@@ -265,3 +265,79 @@ intercepted
 
 If there are multiple ports that you need forwarded, simply repeat the
 flag (`--to-pod=<sidecarPort0> --to-pod=<sidecarPort1>`).
+
+## Intercepting headless services
+
+Kubernetes supports creating [services without a ClusterIP](https://kubernetes.io/docs/concepts/services-networking/service/#headless-services),
+which, when they have a pod selector, serve to provide a DNS record that will directly point to the service's backing pods.
+Telepresence supports intercepting these `headless` services as it would a regular service with a ClusterIP.
+So, for example, if you have the following service:
+
+```yaml
+---
+apiVersion: v1
+kind: Service
+metadata:
+  name: my-headless
+spec:
+  type: ClusterIP
+  clusterIP: None
+  selector:
+    service: my-headless
+  ports:
+  - port: 8080
+    targetPort: 8080
+---
+apiVersion: apps/v1
+kind: StatefulSet
+metadata:
+  name: my-headless
+  labels:
+    service: my-headless
+spec:
+  replicas: 1
+  serviceName: my-headless
+  selector:
+    matchLabels:
+      service: my-headless
+  template:
+    metadata:
+      labels:
+        service: my-headless
+    spec:
+      containers:
+        - name: my-headless
+          image: jmalloc/echo-server
+          ports:
+            - containerPort: 8080
+          resources: {}
+```
+
+You can intercept it like any other:
+
+```console
+$ telepresence intercept my-headless --port 8080
+Using StatefulSet my-headless
+intercepted
+    Intercept name    : my-headless
+    State             : ACTIVE
+    Workload kind     : StatefulSet
+    Destination       : 127.0.0.1:8080
+    Volume Mount Point: /var/folders/j8/kzkn41mx2wsd_ny9hrgd66fc0000gp/T/telfs-524189712
+    Intercepting      : all TCP connections
+```
+
+<Alert severity="info">
+This utilizes an <code>initContainer</code> that requires `NET_ADMIN` capabilities.
+If your cluster administrator has disabled them, you will be unable to use numeric ports with the agent injector.
+</Alert>
+
+<Alert severity="info">
+This requires the Traffic Agent to run as GID <code>7777</code>. By default, this is disabled on openshift clusters.
+To enable running as GID <code>7777</code> on a specific openshift namespace, run:
+<code>oc adm policy add-scc-to-group anyuid system:serviceaccounts:$NAMESPACE</code>
+</Alert>
+
+<Alert severity="info">
+Intercepting headless services without a selector is not supported.
+</Alert>

releaseNotes.yml

@@ -67,7 +67,7 @@ items:
           intercept. This leverages the same approach as intercepting numeric ports when
           using the mutating webhook injector, mainly requires the <code>initContainer</code>
           to have <code>NET_ADMIN</code> capabilities.
-        docs: reference/cluster-config/#note-on-intercepting-headless-services
+        docs: reference/intercepts/#intercepting-headless-services
 
       - type: change
         title: Use one tunnel per connection instead of multiplexing into one tunnel