Prepare v2.22.0-rc.0

build-aux/main.mk

@@ -31,7 +31,7 @@ bindir ?= $(or $(shell go env GOBIN),$(shell go env GOPATH|cut -d: -f1)/bin)
 # https://github.com/moby/buildkit/blob/master/frontend/dockerfile/docs/syntax.md.
 export DOCKER_BUILDKIT := 1
 
-GOLANGCI_VERSION:=v1.64.5
+GOLANGCI_VERSION:=v1.64.7
 
 .PHONY: FORCE
 FORCE:

build-aux/unparsable-packages.yaml

@@ -1,15 +1,3 @@
-sigs.k8s.io/yaml:
-  - Apache-2.0
-sigs.k8s.io/yaml/goyaml.v2:
-  - Apache-2.0
-  - MIT
-sigs.k8s.io/yaml/goyaml.v3:
-  - Apache-2.0
-  - MIT
-sigs.k8s.io/json:
-  - Apache-2.0
-sigs.k8s.io/json/internal/golang/encoding/json:
-  - BSD-3-Clause
 github.com/fclairamb/go-log:
   - MIT
 github.com/fclairamb/go-log/noop:

docs/README.md

@@ -19,6 +19,7 @@ raw markdown version, more bells and whistles at [telepresence.io](https://telep
   - [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)
@@ -38,6 +39,8 @@ raw markdown version, more bells and whistles at [telepresence.io](https://telep
   - [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)

docs/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.

docs/doc-links.yml

@@ -28,6 +28,8 @@
       link: howtos/large-clusters
     - title: Host a cluster in Docker or a VM
       link: howtos/cluster-in-vm
+    - title: Use Telepresence with Azure (Microsoft Learn)
+      link: https://learn.microsoft.com/en-us/azure/aks/use-telepresence-aks
 - title: Technical reference
   items:
     - title: Architecture
@@ -66,6 +68,10 @@
       link: reference/routing
     - title: Monitoring
       link: reference/monitoring
+- title: Comparisons
+  items:
+    - title: Telepresence vs mirrord
+      link: compare/mirrord
 - title: FAQs
   link: faqs
 - title: Troubleshooting

docs/faqs.md

@@ -6,11 +6,11 @@ hide_table_of_contents: true
 
 # FAQs
 
-** Why Telepresence?**
+### Why Telepresence
 
 Modern microservices-based applications that are deployed into Kubernetes often consist of tens or hundreds of services. The resource constraints and number of these services means that it is often difficult to impossible to run all of this on a local development machine, which makes fast development and debugging very challenging. The fast [inner development loop](concepts/devloop.md) from previous software projects is often a distant memory for cloud developers.
 
-Telepresence enables you to connect your local development machine seamlessly to the cluster via a two way proxying mechanism. This enables you to code locally and run the majority of your services within a remote Kubernetes cluster -- which in the cloud means you have access to effectively unlimited resources.
+Telepresence enables you to connect your local development machine seamlessly to the cluster via a two-way proxying mechanism. This enables you to code locally and run the majority of your services within a remote Kubernetes cluster — which in the cloud means you have access to effectively unlimited resources.
 
 Ultimately, this empowers you to develop services locally and still test integrations with dependent services or data stores running in the remote cluster.
 
@@ -22,79 +22,80 @@ You can also "intercept" any requests made to a service. This is similar to repl
 
 Finally, you can "ingest" a service. Again, similar to a "replace", but nothing changes in the cluster during an "ingest", and no traffic is routed to the workstation.
 
-** What operating systems does Telepresence work on?**
+#### What operating systems does Telepresence work on?
 
-Telepresence currently works natively on macOS (Intel and Apple Silicon), Linux, and Windows.
+Telepresence currently works natively on macOS, Linux, and Windows.
 
-** What protocols can be intercepted by Telepresence?**
+#### What architecture does Telepresence work on?
+
+All Telepresence binaries are released for both AMD (Intel) and ARM (Apple Silicon) chips. 
+
+#### What protocols can be intercepted by Telepresence?
 
 Both TCP and UDP are supported.
 
-** When using Telepresence run a cluster service locally, are the Kubernetes cluster environment variables proxied on my local machine?**
+#### When using Telepresence to run a cluster service locally, are the Kubernetes cluster environment variables proxied on my local machine?
 
 Yes, you can either set the container's environment variables on your machine or write the variables to a file to use with Docker or another build process. You can also directly pass the environments to a handler that runs locally. Please see [the environment variable reference doc](reference/environment.md) for more information.
 
-** When using Telepresence to run a cluster service locally, can the associated container volume mounts also be mounted by my local machine?**
+#### When using Telepresence to run a cluster service locally, can the associated container volume mounts also be mounted by my local machine?
 
-Yes, please see [the volume mounts reference doc](reference/volume.md) for more information.
+Yes, and when running Docker, they can be used as docker volumes. Please see [the volume mounts reference doc](reference/volume.md) for more information.
 
-** When connected to a Kubernetes cluster via Telepresence, can I access cluster-based services via their DNS name?**
+#### When connected to a Kubernetes cluster via Telepresence, can I access cluster-based services via their DNS name?
 
 Yes. After you have successfully connected to your cluster via `telepresence connect -n <my_service_namespace>` you will be able to access any service in the connected namespace in your cluster via their DNS name.
 
 This means you can curl endpoints directly e.g. `curl <my_service_name>:8080/mypath`.
 
 You can also access services in other namespaces using their namespaced qualified name, e.g.`curl <my_service_name>.<my_other_namespace>:8080/mypath`.
 
-You can connect to databases or middleware running in the cluster, such as MySQL, PostgreSQL and RabbitMQ, via their service name.
+In essence, Telepresence makes the DNS of the connected namespace available locally. This means that you can connect to all databases or middleware running in the cluster, such as MySQL, PostgreSQL and RabbitMQ, via their service name.
 
-** When connected to a Kubernetes cluster via Telepresence, can I access cloud-based services and data stores via their DNS name?**
+#### When connected to a Kubernetes cluster via Telepresence, can I access cloud-based services and data stores via their DNS name?
 
 You can connect to cloud-based data stores and services that are directly addressable within the cluster (e.g. when using an [ExternalName](https://kubernetes.io/docs/concepts/services-networking/service/#externalname) Service type), such as AWS RDS, Google pub-sub, or Azure SQL Database.
 
-
-
-
-** Will Telepresence be able to engage with workloads running on a private cluster or cluster running within a virtual private cloud (VPC)?**
+#### Will Telepresence be able to engage with workloads running on a private cluster or cluster running within a virtual private cloud (VPC)?
 
 Yes, but it doesn't need to have a publicly accessible IP address.
 
 The cluster must also have access to an external registry to be able to download the traffic-manager and traffic-agent images that are deployed when connecting with Telepresence.
 
-** Why does running Telepresence require sudo access for the local daemon unless it runs in a Docker container?**
+#### Why does running Telepresence require sudo access for the local daemon unless it runs in a Docker container?
 
 The local daemon needs sudo to create a VIF (Virtual Network Interface) for outbound routing and DNS. Root access is needed to do that unless the daemon runs in a Docker container.
 
-** What components get installed in the cluster when running Telepresence?**
+#### What components get installed in the cluster when running Telepresence?
 
-A single `traffic-manager` service is deployed in the `ambassador` namespace within your cluster, and this manages resilient intercepts and connections between your local machine and the cluster.
+A `traffic-manager` service is deployed in a namespace of your choice (default 'ambassador') within your cluster, and this manages resilient intercepts and connections between your local machine and the cluster.
 
-A Traffic Agent container is injected per pod that is being engaged. The first time a `replace`, an `ingest`, or an `intercept` is made on a workload, all pods associated with this workload will be restarted with the Traffic Agent automatically injected.
+A Traffic Agent container is injected per pod that is being engaged. The injection happens the first time a `replace`, an `ingest`, or an `intercept` is made on a workload, unless you choose to control the injection using an annotation, in which case the injection happens when the `traffic-manager` is installed.
 
-** How can I remove all the Telepresence components installed within my cluster?**
+#### How can I remove all the Telepresence components installed within my cluster?
 
 You can run the command `telepresence helm uninstall` to remove everything from the cluster, including the `traffic-manager`, and all the `traffic-agent` containers injected into each pod being engaged.
 
+You also can run the command `telepresence uninstall <workload>` to remove the injected `traffic-agent` containers injected into each pod for that workload.
+
 Also run `telepresence quit -s` to stop all local daemons running.
 
-** What language is Telepresence written in?**
+#### What language is Telepresence written in?
 
 All components of the Telepresence application and cluster components are written using Go. 
 
-** How does Telepresence connect and tunnel into the Kubernetes cluster?**
+#### How does Telepresence connect and tunnel into the Kubernetes cluster?
 
 The connection between your laptop and cluster is established by using
 the `kubectl port-forward` machinery (though without actually spawning
 a separate program) to establish a TLS encrypted connection to Telepresence
 Traffic Manager and Traffic Agents in the cluster, and running Telepresence's custom VPN
 protocol over that connection.
 
-<a name="idps"></a>
-
-** Is Telepresence OSS open source?**
+#### Is Telepresence OSS open source?
 
-Yes it is! You'll find both source code and documentation in the [Telepresence GitHub repository](https://github.com/telepresenceio/telepresence), licensed using the [apache License Version 2.0](https://github.com/telepresenceio/telepresence?tab=License-1-ov-file#readme).
+Yes, it is! You'll find both source code and documentation in the [Telepresence GitHub repository](https://github.com/telepresenceio/telepresence), licensed using the [apache License Version 2.0](https://github.com/telepresenceio/telepresence?tab=License-1-ov-file#readme).
 
-** How do I share my feedback on Telepresence?**
+#### How do I share my feedback on Telepresence?
 
 Your feedback is always appreciated and helps us build a product that provides as much value as possible for our community. You can chat with us directly on our #telepresence-oss channel at the [CNCF Slack](https://slack.cncf.io), and also report issues or create pull-requests on the GitHub repository.

docs/howtos/large-clusters.md

@@ -47,4 +47,4 @@ Managers, as long as each one manages its own unique set of namespaces.
 
 A client that connects to a Traffic Manager will automatically be limited to its managed namespaces.
 
-See [Installing a namespaced-scoped traffic-manager](../install/manager.md#installing-a-namespace-scoped-traffic-manager) for details.
+See [Installing a namespaced-scoped traffic-manager](../install/manager.md#limiting-the-namespace-scope) for details.

docs/reference/architecture.md

@@ -43,4 +43,4 @@ running `telepresence list` or `kubectl describe pod <pod-name>`.
 Depending on if an `replace` or `intercept` is active or not, the Traffic Agent will either route the incoming request 
 to your workstation, or it will pass it along to the container in the pod usually handling requests.
 
-Please see [Traffic Agent Sidecar](intercepts/sidecar.md) for details.
+Please see [Traffic Agent Sidecar](engagements/sidecar.md) for details.

docs/reference/rbac.md

@@ -27,7 +27,7 @@ kind: Config
 clusters:
 - name: my-cluster # Must match the cluster value in the contexts config
   cluster:
-    ## The cluster field is highly cloud dependent.
+    ## The cluster field is highly cloud-dependent.
 contexts:
 - name: my-context
   context:
@@ -56,6 +56,8 @@ set up differently depending on if the manager is installed using a dynamic or a
 The Traffic Manager will require cluster wide access to several resources when it lacks a namespace selector, or when it
 is configured with a dynamic namespace selector.
 
+### Traffic Manager Permissions
+
 These are the permissions required by the `traffic-manager` account in such a configuration:
 
 ```yaml
@@ -262,4 +264,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](#traffic-manager-permissions) described above.