Documentation update for GitHub Codespaces support.

Signed-off-by: Thomas Hallgren <thomas@tada.se>
telepresenceio · Nov 14, 2024 · c05db5f · c05db5f
1 parent 10e7dd9
commit c05db5f
Show file tree

Hide file tree

Showing 4 changed files with 44 additions and 0 deletions.
diff --git a/CHANGELOG.yml b/CHANGELOG.yml
@@ -33,6 +33,15 @@ docDescription: >-
   environments, access to instantaneous feedback loops, and highly
   customizable development environments.
 items:
+  - version: 2.20.3
+    date: TBD
+    notes:
+      - type: bugfix
+        title: Ensure that Telepresence works with GitHub Codespaces
+        body: >-
+          GitHub Codespaces runs in a container, but not as root. Telepresence didn't handle this situation
+          correctly and only started the user daemon. The root daemon was never started.
+        docs: https://github.com/telepresenceio/telepresence/issues/3722
   - version: 2.20.2
     date: 2024-10-21
     notes:

diff --git a/docs/reference/inside-container.md b/docs/reference/inside-container.md
@@ -4,6 +4,8 @@ hide_table_of_contents: true
 ---
 # Running Telepresence inside a container
 
+## Run with the daemon and intercept handler in containers
+
 The `telepresence connect` command now has the option `--docker`. This option tells telepresence to start the Telepresence daemon in a
 docker container.
 
@@ -13,3 +15,24 @@ like macFUSE or WinFSP to mount the remote file systems.
 
 The intercept handler (the process that will receive the intercepted traffic) must also be a docker container, because that is the only
 way to access the cluster network that the daemon makes available, and to mount the docker volumes needed.
+
+## Run everything in a container
+
+Environments like [GitHub Codespaces](https://docs.github.com/en/codespaces/overview) runs everything in a container. Your shell, the
+telepresence CLI, and both its daemons. This means that the container must be configured so that it allows Telepresence to set up its
+Virtual Network Interface before you issue a `telepresence connect`.
+
+There are several conditions that must be met.
+
+- Access to the `/dev/net/tun` device
+- The `NET_ADMIN` capability
+- If you're using IPv6, then you also need sysctl `net.ipv6.conf.all.disable_ipv6=0`
+
+The Codespaces `devcontainer.json` will typically need to include:
+
+```json
+    "runArgs": [
+        "--privileged",
+        "--cap-add=NET_ADMIN",
+    ],
+```
diff --git a/docs/release-notes.md b/docs/release-notes.md
@@ -1,6 +1,13 @@
 
 [comment]: # (Code generated by relnotesgen. DO NOT EDIT.)
 # <img src="images/logo.png" height="64px"/> Telepresence Release Notes
+## Version 2.20.3
+## <div style="display:flex;"><img src="images/bugfix.png" alt="bugfix" style="width:30px;height:fit-content;"/><div style="display:flex;margin-left:7px;">[Ensure that Telepresence works with GitHub Codespaces](https://github.com/telepresenceio/telepresence/issues/3722)</div></div>
+<div style="margin-left: 15px">
+
+GitHub Codespaces runs in a container, but not as root. Telepresence didn't handle this situation correctly and only started the user daemon. The root daemon was never started.
+</div>
+
 ## Version 2.20.2 <span style="font-size: 16px;">(October 21)</span>
 ## <div style="display:flex;"><img src="images/bugfix.png" alt="bugfix" style="width:30px;height:fit-content;"/><div style="display:flex;margin-left:7px;">Crash in traffic-manager configured with agentInjector.enabled=false</div></div>
 <div style="margin-left: 15px">

diff --git a/docs/release-notes.mdx b/docs/release-notes.mdx
@@ -7,6 +7,11 @@ import { Note, Title, Body } from '@site/src/components/ReleaseNotes'
 [comment]: # (Code generated by relnotesgen. DO NOT EDIT.)
 
 # Telepresence Release Notes
+## Version 2.20.3
+<Note>
+	<Title type="bugfix" docs="https://github.com/telepresenceio/telepresence/issues/3722">Ensure that Telepresence works with GitHub Codespaces</Title>
+	<Body>GitHub Codespaces runs in a container, but not as root. Telepresence didn't handle this situation correctly and only started the user daemon. The root daemon was never started.</Body>
+</Note>
 ## Version 2.20.2 <span style={{fontSize:'16px'}}>(October 21)</span>
 <Note>
 	<Title type="bugfix">Crash in traffic-manager configured with agentInjector.enabled=false</Title>