Documentation for 2.22

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

@@ -2,17 +2,11 @@
 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/
+authors: 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 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 -->

blog/2025-03-14-telepresence-2.22.md

@@ -0,0 +1,109 @@
+---
+title: Telepresence 2.22
+description: What's new in Telepresence 2.22.
+slug: telepresence-2.22
+authors: thallgren
+---
+
+Telepresence 2.22 introduces several compelling features, notably the telepresence replace command, a JSON schema for Helm chart values, greater control over Traffic Manager's namespace scope, and improved customization of remote mount behavior.
+
+<!-- truncate -->
+
+## Telepresence Replace: Container-Level Substitution
+
+Telepresence introduces `telepresence replace`, a new command that offers a distinct method for interacting with containers, complementing `telepresence intercept` and `telepresence ingest`.
+
+### Distinguishing Features of `replace`
+
+While superficially similar to `intercept`, `replace` operates with fundamental differences:
+
+1.  **Container-Wide Scope:** `replace` substitutes an entire container, redirecting all its traffic, whereas `intercept` focuses on specific services or service/container ports.
+2.  **Direct Container Port Mapping:** The `--port` flag in `replace` directly maps to container ports.
+3.  **Optional Port Interception:** Unlike `intercept`, `replace` can function without intercepting any specific ports.
+4.  **Complete Container Replacement:** During a `replace`, the original container within the cluster is deactivated and fully substituted.
+
+### Rationale: Addressing Container-Level Substitution Needs
+
+The existing `telepresence intercept --replace` flag, which targets specific ports, prompted the development of the dedicated `replace` command.
+
+`intercept` inherently focuses on port-level traffic redirection. However, scenarios arise where container-level substitution is required without specific port interception. For instance, a message-queue consumer container might not expose any ports. Introducing a `--no-ports` flag to `intercept --replace` would create a logical contradiction, as "intercept" implies port-based traffic redirection.
+
+Therefore, `replace` was introduced to provide a clear and consistent mechanism for container-level substitution.
+
+### Deprecation of the `--replace` flag
+The `telepresence intercept --replace` flag is now deprecated. While it remains functional, a warning will be issued, recommending the use of `telepresence replace` instead.
+
+### Generic term for Ingest, Intercept, and Replace
+
+Client engagement of a container is defined as the act of ingesting, intercepting, or replacing that container. Consequently, the term 'engage' will appear frequently throughout the documentation.
+
+## Traffic Manager Namespaces
+
+The namespaces that the Telepresence Traffic Manager cares about can be declared in the Helm chart, and multiple  Traffic Managers can be installed that deal with their own set of namespaces as long as there's no overlap. This has been the case before this release. Two things are new though:
+
+1. **Namespaces are consistently declared:** Prior to this release, the namespace declaration was scattered into several Helm chart values, such as `manager.Rbac.namespaces`, `client.Rbac.namespaces`, and `agentInjector.webhook.namespaceSelector`. The definition is now unified to the mutual exclusive top-level Helm chart values `namespaces` and `namespaceSelector`.
+2. **The conflict detection is all-encompassing**: The old way of declaring namespaces implied that the Traffic Manager was either "cluster wide" (no declaration existed) or "namespaced". A conflict would be detected between two "namespaced" installation, but not between a "namespaced" and a "cluster wide" installation. This is no longer the case. All conflicting namespace selectors will yield errors and Helm will refuse to install them.
+
+### Dynamic or Static Selector
+
+A namespace selector can be dynamic or static. Telepresence will consider a selector that just targets the namespace name as a _static_ selector. Selectors using other labels, or negation of labels (using operator `NotIn`) are considered _dynamic_. The Difference is that the former isn't sensitive to changes (except, of course, the removal of a namespace) whereas the latter will take effect immediately if the set of matching namespaces changes.
+
+Sample _static_ selector, selecting the namespaces "alpha" and "beta":
+```yaml
+namespaceSelector:
+  matchExpressions:
+  - key: kubernetes.io/metadata.name
+    operator: In
+    values:
+    - alpha
+    - beta
+```
+
+This type of selector can also be declared using the short form `namespaces`:
+```yaml
+namespaces:
+- alpha
+- beta
+```
+
+Sample _dynamic_ selector, selecting namespaces where the label "example.com/managed" is "true" and "example.com/environment" is "dev" or "qa":
+
+```yaml
+namespaceSelector:
+  matchLabels:
+    example.com/managed: "true"
+  matchExpressions:
+  - key: example.com/environment
+    operator: In
+    values:
+    - dev
+    - qa
+```
+
+## Volume Mount Policies
+
+This feature gives the user control over what volumes that the traffic-agent will share with the client, how those volumes are shared (read-write or read-only), and also give the client a hint about volumes that are not shared but will be expected by the locally running container.
+
+Mount policies can be configured globally for a Traffic Manager using Helm chart values, or individually for a workload using template annotations.
+
+A volume policy can be `Ignore`, `Local`, `Remote`, or `RemoteReadOnly`. See the [Control Volume Sharing](/docs/reference/cluster-config#control-volume-sharing) section in the reference documentation for detailed information on the Helm chart value and annotation.
+
+## JSON-Schema for the Helm Chart Values
+
+It is no longer possible to enter invalid, misspelled, or otherwise non-existent configuration parameters when doing
+a `helm install|upgrade` or `telepresence helm install|upgrade`, because all values are now guarded using a JSON-schema.
+
+A new `telepresence helm lint` command was also added, which corresponds to [helm lint](https://helm.sh/docs/helm/helm_lint/), but uses the Helm chart embedded in the `telepresence` binary.
+
+## Other Notable Changes
+
+### Annotation Prefix Change
+All annotations now use the prefix `telepresence.io/`. This prefix was already used by labels added by Telepresence. The former annotation prefix `telepresence.getambassador.io/` will continue to work, but a warning will be printed in the logs.
+
+### Configmap `telepresence-agents` is no longer used
+The Traffic Agent configurations stored in the `telepresence-agents` configmap are now instead added as pod-annotations. The configmap is no longer used, and can be safely removed.
+
+### Rollbacks Triggered Using Pod Eviction
+When the configuration for a pod changes as the result of a client engaging with the pod, the pod will now be evicted in order to trigger the mutating webhook. This vouches for simpler logic and faster response times when engaging and ending an engagement. In earlier releases, Telepresence would instead patch the workload. The workload might still be triggered if the eviction fails due to the pod's disruption policy.
+
+Please check out the [Release Notes](/docs/release-notes) for a full list of all new features, changes, and bug-fixes.

blog/authors.yml

@@ -0,0 +1,7 @@
+thallgren:
+  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/

docusaurus.config.ts

@@ -78,6 +78,13 @@ const config: Config = {
 						const linkToItem = ((linkItem: LinkItem) => {
 							if (linkItem.link) {
 								idSet.delete(linkItem.link);
+								if(linkItem.link.startsWith("https://")) {
+									return {
+										type: 'link',
+										label: linkItem.title,
+										href: linkItem.link
+									}
+								}
 								return {
 									type: 'doc',
 									label: linkItem.title,

versioned_docs/version-2.21/reference/rbac.md

@@ -266,4 +266,4 @@ roleRef:
   apiGroup: rbac.authorization.k8s.io
 ```
 
-The user will also need the [Traffic Manager connect permission](#traffic-manager-connect-permission) described above.
+The user will also need the [Traffic Manager connect permission](#cluster-wide-installation) described above.

versioned_docs/version-2.22/CONTRIBUTING.md

@@ -0,0 +1,23 @@
+# Telepresence Documentation
+
+This folder contains the Telepresence documentation in a format suitable for a versioned folder in the
+telepresenceio/telepresence.io repository. The folder will show up in that repository when a new minor revision
+tag is created here.
+
+Assuming that a 2.20.0 release is pending, and that a release/v2.20.0 branch has been created, then:
+```console
+$ export TELEPRESENCE_VERSION=v2.20.0
+$ make prepare-release
+$ git push origin {,rpc/}v2.20.0 release/v2.20.0
+```
+
+will result in a `docs/v2.20` folder with this folder's contents in the telepresenceio/telepresence.io repository.
+
+Subsequent bugfix tags for the same minor tag, i.e.:
+```console
+$ export TELEPRESENCE_VERSION=v2.20.1
+$ make prepare-release
+$ git push origin {,rpc/}v2.20.1 release/v2.20.1
+```
+will not result in a new folder when it is pushed, but it will update the content of the `docs/v2.20` folder to
+reflect this folder's content for that tag.

versioned_docs/version-2.22/README.md

@@ -0,0 +1,48 @@
+---
+description: Main menu when using plain markdown. Excluded when generating the website
+---
+# <img src="images/logo.png" height="64px"/> Telepresence Documentation
+raw markdown version, more bells and whistles at [telepresence.io](https://telepresence.io)
+
+- [Quick start](quick-start.md)
+- Install Telepresence
+  - [Install Client](install/client.md)
+  - [Upgrade Client](install/upgrade.md)
+  - [Install Traffic Manager](install/manager.md)
+  - [Cloud Provider Prerequisites](install/cloud.md)
+- Core concepts
+  - [The developer experience and the inner dev loop](concepts/devloop.md)
+  - [Making the remote local: Faster feedback, collaboration and debugging](concepts/faster.md)
+  - [Intercepts](concepts/intercepts.md)
+- How do I...
+  - [Code and debug an application locally](howtos/engage.md)
+  - [Use Telepresence with Docker](howtos/docker.md)
+  - [Work with large clusters](howtos/large-clusters.md)
+  - [Host a cluster in Docker or a VM](howtos/cluster-in-vm.md)
+  - [Use Telepresence with Azure (Microsoft Learn)](https://learn.microsoft.com/en-us/azure/aks/use-telepresence-aks.md)
+- Technical reference
+  - [Architecture](reference/architecture.md)
+  - [Client reference](reference/client.md)
+  - [Laptop-side configuration](reference/config.md)
+  - [Cluster-side configuration](reference/cluster-config.md)
+  - [Using Docker for engagements](reference/docker-run.md)
+  - [Running Telepresence in a Docker container](reference/inside-container.md)
+  - [Environment variables](reference/environment.md)
+  - Engagements
+    - [Configure intercept using CLI](reference/engagements/cli.md)
+    - [Traffic Agent Sidecar](reference/engagements/sidecar.md)
+    - [Target a specific container](reference/engagements/container.md)
+  - [Volume mounts](reference/volume.md)
+  - [DNS resolution](reference/dns.md)
+  - [RBAC](reference/rbac.md)
+  - [Telepresence and VPNs](reference/vpn.md)
+  - [Networking through Virtual Network Interface](reference/tun-device.md)
+  - [Connection Routing](reference/routing.md)
+  - [Monitoring](reference/monitoring.md)
+- Comparisons
+  - [Telepresence vs mirrord](compare/mirrord.md)
+- [FAQs](faqs.md)
+- [Troubleshooting](troubleshooting.md)
+- [Community](community.md)
+- [Release Notes](release-notes.md)
+- [Licenses](licenses.md)

versioned_docs/version-2.22/community.md

@@ -0,0 +1,13 @@
+---
+title: Community
+hide_table_of_contents: true
+---
+
+# Community
+
+## Contributor's guide
+Please review our [contributor's guide](https://github.com/telepresenceio/telepresence/blob/release/v2/CONTRIBUTING.md)
+on GitHub to learn how you can help make Telepresence better.
+
+## Meetings
+Check out our community [meeting schedule](https://github.com/telepresenceio/telepresence/blob/release/v2/MEETING_SCHEDULE.md) for opportunities to interact with Telepresence developers.

versioned_docs/version-2.22/compare/mirrord.md

@@ -0,0 +1,76 @@
+---
+title: "Telepresence vs mirrord"
+hide_table_of_contents: true
+---
+
+## Telepresence
+
+Telepresence is a very feature rich tool, designed to handle a large majority of use-cases. You can use it as a cluster VPN only, or use one of its three different ways (replace, intercept, or ingest) to engage with the cluster's resources.
+
+Telepresence is intended to be installed in the cluster by an administrator and then let clients connect with a very limited set of permissions. This model is generally required by larger companies.
+
+The client can be either completely contained in Docker or run directly on the workstation. The latter will require the creation of a virtual network device, and hence admin access.
+
+## mirrord
+
+Mirrord was designed with simplicity in mind. You install the CLI tool, and that's it. It will do the rest automatically under the hood.
+
+Mirrord solves the same problem as Telepresence, but in a different way. Instead of providing a proper network
+device and remotely mounted filesystems, mirrord will link the client application with a `mirrord-layer` shared library. This library will intercept accesses to the network, file system, and environment variables, and reroute them to a corresponding process in the cluster (the `mirrord-agent`) which then interacts with the targeted pod.
+
+### Limitations
+
+While mirrotd is simple to set up, the chosen approach has several limitations, both on the client and the cluster side.
+
+### Limitations when using dynamic loading:
+
+1. It will only work on Linux and macOS platforms. There's no native support on Windows.
+2. It will only work with dynamically linked executables.
+3. It cannot be used with docker unless you rebuild the container and inject the `mirrord-layer` into it.
+4. `DYLD_INSERT_LIBRARIES` causes various problems on macOS (SIP prevents it from being used), especially on silicon-based machines where mirrord will require Rosetta.
+5. Should Apple decide to protect their intel-based platform the same way as the silicon-based one in a future release, then mirrord will likely be problematic to use on that platform.
+
+### Cluster Permissions
+
+Mirrord does not require a sidecar. Instead they install a the `mirror-agent` into the namespace of the pod that it impersonates. That agent requires several permissions that a cluster admin might consider a security risk:
+
+* `CAP_NET_ADMIN` and `CAP_NET_RAW` - required for modifying routing tables
+* `CAP_SYS_PTRACE` - required for reading target pod environment
+* `CAP_SYS_ADMIN` - required for joining target pod network namespace
+
+Unless using "mirrord for Teams" (proprietary), all users must have permissions to create the job running the `mirror-agent` in the cluster.
+
+## Comparison Telepresence vs mirrord
+
+This comparison chart applies to the Open Source editions of both products.
+
+| Feature                                                                    | Telepresence | mirrord |
+|----------------------------------------------------------------------------|--------------|---------|
+| Run or Debug your cluster containers locally                               | ✅            | ✅       |
+| Does not need administrative permission on workstation                     | ✅ [^1]       | ✅       |
+| Can be used with very large clusters                                       | ✅            | ✅       |
+| Works without interrupting the remote service                              | ✅ [^2]       | ✅       |
+| Doesn't require injection of a sidecar                                     | ✅ [^3]       | ✅       |
+| Supports connecting to clusters over a corporate VPN                       | ✅            | ✅       |
+| Can intercept traffic                                                      | ✅            | ✅       |
+| Can ingest a container                                                     | ✅            | ❌       |
+| Can replace a container                                                    | ✅            | ❌       |
+| Can mirror traffic                                                         | ❌            | ✅       |
+| Can act as a cluster VPN only                                              | ✅            | ❌       |
+| Will work with statically linked binaries                                  | ✅            | ❌       |
+| Runs natively on windows                                                   | ✅            | ❌       |
+| Can intercept traffic to and from pod's localhost                          | ✅            | ❌       |
+| Remotely mounted file system available from all applications               | ✅            | ❌       |
+| Cluster network available to all applications (including browser)          | ✅            | ❌       |
+| Can run the same docker container locally without rebuilding it            | ✅            | ❌       |
+| Provides remote mounts as volumes in docker                                | ✅            | ❌       |
+| Does not require special capabilities such as CAP_SYS_ADMIN in the cluster | ✅            | ❌       |
+| Centralized client configuration using Helm chart                          | ✅            | ❌       |
+| Installed using a JSON-schema validated Helm chart                         | ✅            | ❌       |
+| Client need no special RBAC permissions                                    | ✅            | ❌       |
+
+[^1]: Telepresence will not require root access on the workstation when running in docker mode.
+
+[^2]: The remote service will only restart when a traffic-agent sidecar is installed. Pod disruption budgets or pre-installed agents can be used to avoid interruptions.
+
+[^3]: A traffic-agent is necessary when engaging with a pod. It is unnecessary when using Telepresence as a VPN.