From 2ead3f22471a8c3124a3c01c43f0a4af1d2fa3a6 Mon Sep 17 00:00:00 2001
From: Jose Cortes <josecortes@datawire.io>
Date: Fri, 15 Oct 2021 10:01:33 -0400
Subject: [PATCH] Add docs for headless services.

Signed-off-by: Jose Cortes <josecortes@datawire.io>
---
 reference/cluster-config.md | 12 +++---
 reference/intercepts.md     | 76 +++++++++++++++++++++++++++++++++++++
 releaseNotes.yml            |  2 +-
 3 files changed, 83 insertions(+), 7 deletions(-)

diff --git a/reference/cluster-config.md b/reference/cluster-config.md
index b5873ae2da..6def6a934a 100644
--- a/reference/cluster-config.md
+++ b/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>
diff --git a/reference/intercepts.md b/reference/intercepts.md
index 608d9fca34..007cdb7203 100644
--- a/reference/intercepts.md
+++ b/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>
diff --git a/releaseNotes.yml b/releaseNotes.yml
index 565d53252b..d5e53d9903 100644
--- a/releaseNotes.yml
+++ b/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