Docs and release notes for 2.24.0

Signed-off-by: Thomas Hallgren <thomas@tada.se>

Author: thallgren

versioned_docs/version-2.24/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.24/README.md

@@ -0,0 +1,119 @@
+---
+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)
+  - [Extend Docker Compose with Telepresence](howtos/docker-compose.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)
+  - [Telepresence CLI](reference/cli/telepresence.md)
+    - [telepresence completion](reference/cli/telepresence_completion.md)
+    - [telepresence compose](reference/cli/telepresence_compose.md)
+      - [attach](reference/cli/telepresence_compose_attach.md)
+      - [build](reference/cli/telepresence_compose_build.md)
+      - [commit](reference/cli/telepresence_compose_commit.md)
+      - [config](reference/cli/telepresence_compose_config.md)
+      - [cp](reference/cli/telepresence_compose_cp.md)
+      - [create](reference/cli/telepresence_compose_create.md)
+      - [down](reference/cli/telepresence_compose_down.md)
+      - [events](reference/cli/telepresence_compose_events.md)
+      - [exec](reference/cli/telepresence_compose_exec.md)
+      - [export](reference/cli/telepresence_compose_export.md)
+      - [images](reference/cli/telepresence_compose_images.md)
+      - [kill](reference/cli/telepresence_compose_kill.md)
+      - [logs](reference/cli/telepresence_compose_logs.md)
+      - [ls](reference/cli/telepresence_compose_ls.md)
+      - [pause](reference/cli/telepresence_compose_pause.md)
+      - [port](reference/cli/telepresence_compose_port.md)
+      - [ps](reference/cli/telepresence_compose_ps.md)
+      - [publish](reference/cli/telepresence_compose_publish.md)
+      - [pull](reference/cli/telepresence_compose_pull.md)
+      - [push](reference/cli/telepresence_compose_push.md)
+      - [restart](reference/cli/telepresence_compose_restart.md)
+      - [rm](reference/cli/telepresence_compose_rm.md)
+      - [run](reference/cli/telepresence_compose_run.md)
+      - [scale](reference/cli/telepresence_compose_scale.md)
+      - [start](reference/cli/telepresence_compose_start.md)
+      - [stats](reference/cli/telepresence_compose_stats.md)
+      - [stop](reference/cli/telepresence_compose_stop.md)
+      - [top](reference/cli/telepresence_compose_top.md)
+      - [unpause](reference/cli/telepresence_compose_unpause.md)
+      - [up](reference/cli/telepresence_compose_up.md)
+      - [version](reference/cli/telepresence_compose_version.md)
+      - [wait](reference/cli/telepresence_compose_wait.md)
+      - [watch](reference/cli/telepresence_compose_watch.md)
+    - [telepresence config](reference/cli/telepresence_config.md)
+      - [view](reference/cli/telepresence_config_view.md)
+    - [telepresence connect](reference/cli/telepresence_connect.md)
+    - [telepresence curl](reference/cli/telepresence_curl.md)
+    - [telepresence docker-run](reference/cli/telepresence_docker-run.md)
+    - [telepresence gather-logs](reference/cli/telepresence_gather-logs.md)
+    - [telepresence genyaml](reference/cli/telepresence_genyaml.md)
+      - [annotations](reference/cli/telepresence_genyaml_annotations.md)
+      - [annotations](reference/cli/telepresence_genyaml_annotations.md)
+      - [config](reference/cli/telepresence_genyaml_config.md)
+      - [container](reference/cli/telepresence_genyaml_container.md)
+      - [initcontainer](reference/cli/telepresence_genyaml_initcontainer.md)
+      - [volume](reference/cli/telepresence_genyaml_volume.md)
+    - [telepresence helm](reference/cli/telepresence_helm.md)
+      - [helm install](reference/cli/telepresence_helm_install.md)
+      - [helm lint](reference/cli/telepresence_helm_lint.md)
+      - [helm uninstall](reference/cli/telepresence_helm_uninstall.md)
+      - [helm upgrade](reference/cli/telepresence_helm_upgrade.md)
+      - [helm version](reference/cli/telepresence_helm_version.md)
+    - [telepresence ingest](reference/cli/telepresence_ingest.md)
+    - [telepresence intercept](reference/cli/telepresence_intercept.md)
+    - [telepresence leave](reference/cli/telepresence_leave.md)
+    - [telepresence list](reference/cli/telepresence_list.md)
+    - [telepresence list-contexts](reference/cli/telepresence_list-contexts.md)
+    - [telepresence list-namespaces](reference/cli/telepresence_list-namespaces.md)
+    - [telepresence loglevel](reference/cli/telepresence_loglevel.md)
+    - [telepresence quit](reference/cli/telepresence_quit.md)
+    - [telepresence replace](reference/cli/telepresence_replace.md)
+    - [telepresence serve](reference/cli/telepresence_serve.md)
+    - [telepresence status](reference/cli/telepresence_status.md)
+    - [telepresence uninstall](reference/cli/telepresence_uninstall.md)
+    - [telepresence version](reference/cli/telepresence_version.md)
+    - [telepresence wiretap](reference/cli/telepresence_wiretap.md)
+  - [Laptop-side configuration](reference/config.md)
+  - [Cluster-side configuration](reference/cluster-config.md)
+  - [Using Docker for engagements](reference/docker-run.md)
+  - [Telepresence Compose Extensions](reference/compose.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)
+  - [Telepresence Docker Plugins](reference/plugins.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.24/common/quantity.md

@@ -0,0 +1,7 @@
+---
+title: Quantity
+---
+Quantity is measured in bytes. You can express it as a plain integer or as a fixed-point number using E, G, M, or K. You can also use the power-of-two equivalents: Gi, Mi, Ki. For example, the following represent roughly the same value:
+```
+128974848, 129e6, 129M, 123Mi
+```

versioned_docs/version-2.24/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.24/compare/mirrord.md

@@ -0,0 +1,74 @@
+---
+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 inject code that intercepts 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 with Code Injection
+
+Telepresence 1.x used the [code injection approach](https://www.getambassador.io/blog/code-injection-on-linux-and-macos), but desided to abandon it due to several limitations:
+
+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 mirror traffic                                                         | ✅            | ✅       |
+| Can ingest a container                                                     | ✅            | ❌       |
+| Can replace a container                                                    | ✅            | ❌       |
+| 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.

versioned_docs/version-2.24/concepts/devloop.md

@@ -0,0 +1,55 @@
+---
+title: The developer experience and the inner dev loop
+hide_table_of_contents: true
+---
+
+# The developer experience and the inner dev loop
+
+## How is the developer experience changing?
+
+The developer experience is the workflow a developer uses to develop, test, deploy, and release software.
+
+Typically this experience has consisted of both an inner dev loop and an outer dev loop. The inner dev loop is where the individual developer codes and tests, and once the developer pushes their code to version control, the outer dev loop is triggered.
+
+The outer dev loop is _everything else_ that happens leading up to release. This includes code merge, automated code review, test execution, deployment, controlled (canary) release, and observation of results. The modern outer dev loop might include, for example, an automated CI/CD pipeline as part of a GitOps workflow and a progressive delivery strategy relying on automated canaries, i.e. to make the outer loop as fast, efficient and automated as possible.
+
+Cloud-native technologies have fundamentally altered the developer experience in two ways: one, developers now have to take extra steps in the inner dev loop; two, developers need to be concerned with the outer dev loop as part of their workflow, even if most of their time is spent in the inner dev loop.
+
+Engineers now must design and build distributed service-based applications _and_ also assume responsibility for the full development life cycle. The new developer experience means that developers can no longer rely on monolithic application developer best practices, such as checking out the entire codebase and coding locally with a rapid “live-reload” inner development loop. Now developers have to manage external dependencies, build containers, and implement orchestration configuration (e.g. Kubernetes YAML). This may appear trivial at first glance, but this adds development time to the equation.
+
+## What is the inner dev loop?
+
+The inner dev loop is the single developer workflow. A single developer should be able to set up and use an inner dev loop to code and test changes quickly.
+
+Even within the Kubernetes space, developers will find much of the inner dev loop familiar. That is, code can still be written locally at a level that a developer controls and committed to version control.
+
+In a traditional inner dev loop, if a typical developer codes for 360 minutes (6 hours) a day, with a traditional local iterative development loop of 5 minutes — 3 coding, 1 building, i.e. compiling/deploying/reloading, 1 testing inspecting, and 10-20 seconds for committing code — they can expect to make ~70 iterations of their code per day. Any one of these iterations could be a release candidate. The only “developer tax” being paid here is for the commit process, which is negligible.
+
+![traditional inner dev loop](../images/trad-inner-dev-loop.png#devloop)
+
+## In search of lost time: How does containerization change the inner dev loop?
+
+The inner dev loop is where writing and testing code happens, and time is critical for maximum developer productivity and getting features in front of end users. The faster the feedback loop, the faster developers can refactor and test again.
+
+Changes to the inner dev loop process, i.e., containerization, threaten to slow this development workflow down. Coding stays the same in the new inner dev loop, but code has to be containerized. The _containerized_ inner dev loop requires a number of new steps:
+
+* packaging code in containers
+* writing a manifest to specify how Kubernetes should run the application (e.g., YAML-based configuration information, such as how much memory should be given to a container)
+* pushing the container to the registry
+* deploying containers in Kubernetes
+
+Each new step within the container inner dev loop adds to overall development time, and developers are repeating this process frequently. If the build time is incremented to 5 minutes — not atypical with a standard container build, registry upload, and deploy — then the number of possible development iterations per day drops to ~40. At the extreme that’s a 40% decrease in potential new features being released. This new container build step is a hidden tax, which is quite expensive.
+
+
+![container inner dev loop](../images/container-inner-dev-loop.png#devloop)
+
+## Tackling the slow inner dev loop
+
+A slow inner dev loop can negatively impact frontend and backend teams, delaying work on individual and team levels and slowing releases into production overall.
+
+For example:
+
+* Frontend developers have to wait for previews of backend changes on a shared dev/staging environment (for example, until CI/CD deploys a new version) and/or rely on mocks/stubs/virtual services when coding their application locally. These changes are only verifiable by going through the CI/CD process to build and deploy within a target environment.
+* Backend developers have to wait for CI/CD to build and deploy their app to a target environment to verify that their code works correctly with cluster or cloud-based dependencies as well as to share their work to get feedback.
+
+New technologies and tools can facilitate cloud-native, containerized development. And in the case of a sluggish inner dev loop, developers can accelerate productivity with tools that help speed the loop up again.