W.I.P. Blog entry for version 2.21.0

Signed-off-by: Thomas Hallgren <[email protected]>

Author: thallgren

blog/2024-12-10-telepresence-2.21.md

@@ -0,0 +1,93 @@
+---
+title: Telepresence 2.21
+description: What's new in Telepresence 2.21.
+slug: telepresence-2.21
+authors:
+  - name: Thomas Hallgren
+    title: Maintainer of Telepresence OSS
+    url: https://github.com/thallgren
+    image_url: https://github.com/thallgren.png
+    socials:
+      linkedin: https://www.linkedin.com/in/thallgren/
+---
+
+Telepresence 2.21.0 has been released, and here is a walkthrough of its many new features, such as  automatic VPN
+conflict avoidance, the new `telepresence ingest` command, and the improved docker  support provided by commands like
+`telepresence curl` and `telepresence docker-run`.
+
+<!-- truncate -->
+
+## No More VPN Conflicts
+
+One of the most common problems for Telepresence users has been that the IP ranges used by the Kubernetes cluster that
+they connect to collide with IP ranges provided by other already existing networks on the workstation. Telepresence
+would refuse to connect when such a conflict was detected, and require that the user somehow specified how to resolve
+it. This is no longer the case. Starting with version 2.21.0, Telepresence will proactively resolve the conflict by
+moving the cluster subnets out of the way!
+
+### Virtual Network Address Translation (VNAT)
+The process of moving a subnet is fairly simple. The Telepresence DNS resolver will translate IPs returned by the
+cluster DNS resolver into an IP range that is guaranteed not to conflict, and the Telepresence Virtual Network
+Interface will then translate them back to their original on access.
+
+Telepresence will also ensure that any references to those IPs in the environment that is propagated when using
+`telepresence ingest` or `telepresence intercept` are translated as well. A local process using the environment will
+hence be able to use those IPs to connect to resources in the cluster.
+
+### VNAT Caveats
+
+Telepresence may not accurately detect cluster-side IP addresses being used by services running locally on a workstation
+in certain scenarios. This limitation arises when local services obtain IP addresses from remote sources such as
+databases or configmaps, or when IP addresses are sent to it in API calls.
+
+Using commands like `nslookup <svc name>` may show different IP addresses than the ones shown when using commands like
+`kubernetes get svc <svc name>` if the service subnet is subjected to VNAT translation. The same is true for if using
+`nslookup <pod name>` and `kubernetes get pod -o wide`.
+
+In situations where VNAT causes problems, it can be disabled. Consult the Technical Reference documentation for more
+details on how to do that.
+
+## New Ingest Command
+
+Sometimes, intercepting network traffic to a container isn't the most efficient solution. For example, if you're working
+with a Kafka service that only interacts with a message broker, or if you're planning to send data to your local
+application through other means, just accessing the container's environment and volume mounts might be more practical.
+The new `telepresence ingest <workload> [--container <container name>]` command was designed for exactly this purpose.
+
+The ingest and intercept commands are very similar, but while the intercept will target a port to intercept (and
+implicitly a container), the ingest command will target a container directly.
+
+An ingest is also less intrusive. Since volumes are always mounted read-only, and everything happens on the client side,
+there's no conflict when several ingests of the same container, possibly on different workstations, happen
+simultaneously.
+
+## Improved Docker Support
+
+The cluster network that Telepresence makes available when connecting using `telepresence connect --docker`, will be
+confined to the daemon container, so commands like `curl` or `nslookup` would not find the cluster resources when
+executed on the host. To run a curl command, you'd have to do something like:
+
+### telepresence curl
+
+```bash
+docker run --network container:<daemon container name> curlimages/curl <name of service>
+```
+
+The command `telepresence curl` will run a standard `curl` from a docker image that shares the daemon container's
+network, and the above can be replaced with:
+
+```bash
+telepresence curl <name of service>
+```
+
+### telepresence docker-run
+
+The telepresence docker-run will do a `docker run` and attach the daemon network. It will also ensure that port
+flags like `--publish`, `--expose` works by circumventing the Docker network limitation using ephemeral socat
+containers. It will even enable adding additional `--network` flags by temporarily adding them to the daemon container.
+
+The `telpresence intercept/ingest --docker-run` now also leverages this technique.
+
+
+
+

docusaurus.config.ts

@@ -124,6 +124,11 @@ const config: Config = {
 					docId: 'quick-start',
 					label: 'Docs',
 				},
+				{
+					to: 'blog',
+					position: 'left',
+					label: 'Blog'
+				},
 				{
 					to: 'case-studies',
 					position: 'left',

versioned_docs/version-2.21/howtos/intercepts.md

@@ -48,8 +48,8 @@ network telepresence, and remote mounts must be made relative to a specific moun
    ```
 
 3. Get the name of the port you want to intercept on your service:
-   `kubectl get service <service name> --output yaml`.
-
+    `kubectl get service <service name> --output yaml`.
+  
    If we assume that the service and deployment use the same name:
 
    ```console
@@ -64,8 +64,8 @@ network telepresence, and remote mounts must be made relative to a specific moun
    ```
 
 4. Intercept all traffic going to the application in your cluster:
-    ```
-    telepresence intercept &lt;workload-name&gt; --port [&lt;local-port&gt;][:&lt;remote-port&gt;] --env-file &lt;path-to-env-file&gt;`.
+    ```bash
+    telepresence intercept <workload-name> --port [<local-port>][:<remote-port>] --env-file <path-to-env-file>`.
     ```
 
    * For `--port`: specify the port the local instance of your application is running on. If the intercepted service exposes multiple ports, specify the port you want to intercept after a colon.
@@ -84,7 +84,7 @@ network telepresence, and remote mounts must be made relative to a specific moun
       Intercepting  : all TCP connections
     ```
 
-5. &lt;a name="start-local-instance"&gt;&lt;/a&gt;Start your local application using the environment variables retrieved in the previous step.
+5. Start your local application using the environment variables retrieved in the previous step.
    The following are some examples of how to pass the environment variables to your local process:
    * **Visual Studio Code:** specify the path to the environment variables file in the `envFile` field of your configuration.
    * **JetBrains IDE (IntelliJ, WebStorm, PyCharm, GoLand, etc.):** use the [EnvFile plugin](https://plugins.jetbrains.com/plugin/7861-envfile).
@@ -128,7 +128,7 @@ present challenges in terms of toolchain integration, debugging, and the overall
    ```
 
 3. Get the name of the port you want to intercept on your service:
-   `kubectl get service &lt;service name&gt; --output yaml`.
+   `kubectl get service <service name> --output yaml`.
 
    If we assume that the service and deployment use the same name:
 
@@ -144,8 +144,8 @@ present challenges in terms of toolchain integration, debugging, and the overall
    ```
 
 4. Intercept all traffic going to the application in your cluster, and start a local container to handle that intercept:
-    ```
-    telepresence intercept &lt;workload-name&gt; --port [&lt;local-port&gt;][:&lt;remote-port&gt;] --docker-run -- &lt;your local container&gt;.
+    ```bash
+    telepresence intercept <workload-name> --port [<local-port>][:<remote-port>] --docker-run -- <your local container>.
     ```
 
    * For `--port`: If the intercepted service exposes multiple ports, specify the service port you want to intercept after a colon.
@@ -156,15 +156,15 @@ present challenges in terms of toolchain integration, debugging, and the overall
    cluster get routed to the local container and the environment variables of the service are written to `~/example-app-intercept.env`.
 
     ```console
-    $ telepresence intercept example-app --port :http --docker-run -- &lt;your local container&gt;
+    $ telepresence intercept example-app --port :http --docker-run -- <your local container>
     Using Deployment example-app
     intercepted
       Intercept name: example-app
       State         : ACTIVE
       Workload kind : Deployment
       Destination   : 127.0.0.1:8080
       Intercepting  : all TCP connections
-    &lt;output from your local container&gt;
+    <output from your local container>
     ```
 
 5. Query the cluster in which you intercepted an application and verify your local instance being invoked.
@@ -192,7 +192,7 @@ This example assumes that you have the `example-app`
     $ telepresence connect
     Launching Telepresence User Daemon
     Launching Telepresence Root Daemon
-    Connected to context xxx, namespace default (https://&lt;some url&gt;)
+    Connected to context xxx, namespace default (https://<some url>)
     $ telepresence ingest example-app --env-file ~/example-app-intercept.env
     Using Deployment example-app
        Container         : example-app
@@ -212,14 +212,14 @@ You can now:
     ```console
     $ telepresence connect --docker
     Launching Telepresence User Daemon
-    Connected to context xxx, namespace default (https://&lt;some url&gt;)
-    $ telepresence ingest example-app --expose 8080 --docker-run -- &lt;your local container&gt;
+    Connected to context xxx, namespace default (https://<some url>)
+    $ telepresence ingest example-app --expose 8080 --docker-run -- <your local container>
     Using Deployment example-app, container example-app
-    &lt;output from your local container&gt;
+    <output from your local container>
    ```
 
 You can now:
 - Code and debug your local container while it interacts with other services in your cluster.
-- Send request to your local container using localhost:&lt;local port&gt;
+- Send request to your local container using localhost:&lt;local portt&gt;
 - Query services only exposed in your cluster's network using `telepresence curl`.
 - Set breakpoints in a _Remote Debug_ configuration in your IDE to investigate bugs.