From 4e1375ccde9bb96f11afbdb2fcdd69eabf369b1c Mon Sep 17 00:00:00 2001 From: Donny Yung Date: Tue, 11 May 2021 13:02:09 -0400 Subject: [PATCH] (from getambassador.io) Addressing PR feedback Handled things such as, standardizing capitaliation of Telepresence (unless showing commands), using legacy Telepresence to refer to the old python version, and changing Telepresence 2 to just Telepresence. Additionally, used past tense when describing what legacy Telepresence did to further emphasize it is old and Telepresence is what they should use now. --- install/index.md | 2 +- install/migrate-tp2.md | 54 +++++++++++++++++++++--------------------- 2 files changed, 28 insertions(+), 28 deletions(-) diff --git a/install/index.md b/install/index.md index 94793b922b..435a8bbdf9 100644 --- a/install/index.md +++ b/install/index.md @@ -14,6 +14,6 @@ Follow one of our [quick start guides](../quick-start/) to start using Teleprese ## Installing older version of Telepresence -Use these URLs to download an older version for your OS, replacing `x.x.x` with the versions you want. +Use these URLs to download an older version for your OS, replacing `x.y.z` with the versions you want. diff --git a/install/migrate-tp2.md b/install/migrate-tp2.md index bff4ffd7fa..017e602482 100644 --- a/install/migrate-tp2.md +++ b/install/migrate-tp2.md @@ -1,32 +1,32 @@ -# Migrate to Telepresence 2 from Legacy Telepresence +# Migrate from Legacy Telepresence -Telepresence 2 (the current major version) has different mechanics and requires a different mental model from [Telepresence 1](https://www.telepresence.io/) when working with local instances of your services. +Telepresence (formerly referenced as Telepresence 2, which is the current major version) has different mechanics and requires a different mental model from [legacy Telepresence](https://www.telepresence.io/) when working with local instances of your services. -In Telepresence 1, a pod running a service is swapped with a pod running the Telepresence proxy. This proxy receives traffic intended for the service, and sends the traffic onward to the target workstation or laptop. We called this mechanism "swap-deployment". +In legacy Telepresence, a pod running a service was swapped with a pod running the Telepresence proxy. This proxy received traffic intended for the service, and sent the traffic onward to the target workstation or laptop. We called this mechanism "swap-deployment". In practice, this mechanism, while simple in concept, had some challenges. Losing the connection to the cluster would leave the deployment in an inconsistent state. Swapping the pods would take time. -Telepresence 2 introduces a [new architecture](../../reference/architecture/) built around "intercepts" that addresses this problem. With Telepresence 2, a sidecar proxy is injected onto the pod. The proxy then intercepts traffic intended for the pod and routes it to the workstation/laptop. The advantage of this approach is that the service is running at all times, and no swapping is used. By using the proxy approach, we can also do selective intercepts, where certain types of traffic get routed to the service while other traffic gets routed to your laptop/workstation. +Telepresence introduces a [new architecture](../../reference/architecture/) built around "intercepts" that addresses these problems. With Telepresence, a sidecar proxy is injected onto the pod. The proxy then intercepts traffic intended for the pod and routes it to the workstation/laptop. The advantage of this approach is that the service is running at all times, and no swapping is used. By using the proxy approach, we can also do selective intercepts, where certain types of traffic get routed to the service while other traffic gets routed to your laptop/workstation. Please see [the Telepresence quick start](../../quick-start/) for an introduction to running intercepts and [the intercept reference doc](../../reference/intercepts/) for a deep dive into intercepts -## Using Telepresence 1 Commands +## Using legacy Telepresence Commands -First please ensure you've [installed Telepresence 2](../). +First please ensure you've [installed Telepresence](../). -Telepresence 2 is able to translate common Telepresence 1 commands into native Telepresence 2 commands. -So if you want to get started quickly, you can just use the same old telepresence commands you are used -to with the telepresence 2 binary. +Telepresence is able to translate common legacy Telepresence commands into native Telepresence commands. +So if you want to get started quickly, you can just use the same legacy Telepresence commands you are used +to with the Telepresence binary. -For example, say you have a deployment (myserver) that you want to swap deployment (equivalent to intercept in -telepresence 2) with a python server, you could run the following command: +For example, say you have a deployment (`myserver`) that you want to swap deployment (equivalent to intercept in +Telepresence) with a python server, you could run the following command: ``` $ telepresence --swap-deployment myserver --expose 9090 --run python3 -m http.server 9090 < help text > Legacy telepresence command used -Command roughly translates to the following in Telepresence 2: +Command roughly translates to the following in Telepresence: telepresence intercept echo-easy --port 9090 -- python3 -m http.server 9090 running... Connecting to traffic manager... @@ -40,27 +40,24 @@ intercepted Intercepting : all TCP connections Serving HTTP on :: port 9090 (http://[::]:9090/) ... ``` -Telepresence will let you know what the telepresence 1 command has mapped to and automatically -runs it. So you can get started with Telepresence 2 today, using the commands you are used to -and it will help you learn the Telepresence 2 syntax. +Telepresence will let you know what the legacy Telepresence command has mapped to and automatically +runs it. So you can get started with Telepresence today, using the commands you are used to +and it will help you learn the Telepresence syntax. -### Telepresence 1 Commands Limitations -Some of the commands and flags from Telepresence 1 either didn't apply to telepresence 2 or -aren't yet supported in telepresence 2. For some known popular commands, such as --method, -telepresence will include output letting you know that the flag has went away. For flags that -Telepresence 2 can't translate yet, it will let you know that that flag is "unknown". +### Legacy Telepresence Command Limitations +Some of the commands and flags from legacy Telepresence either didn't apply to Telepresence or +aren't yet supported in Telepresence. For some known popular commands, such as --method, +Telepresence will include output letting you know that the flag has went away. For flags that +Telepresence can't translate yet, it will let you know that that flag is "unsupported". -If we are missing any flags or functionality that is integral to your usage, please let us know +If Telepresence is missing any flags or functionality that is integral to your usage, please let us know by [creating an issue](https://github.com/telepresenceio/telepresence/issues) and/or talking to us on our [Slack channel](https://a8r.io/Slack)! ## Telepresence Changes -Since the new architecture deploys a traffic-manager into the Ambassador namespace, please take a look at -our [rbac guide](../../reference/rbac) if you run into any issues with permissions while updating to telepresence 2. - -Telepresence 2 installs the traffic-manager in the cluster and traffic-agents when performing intercepts (including -with --swap-deployment) and leaves them. If you use --swap-deployment, the intercept will be left once the process +Telepresence installs a Traffic Manager in the cluster and Traffic Agents alongside workloads when performing intercepts (including +with `--swap-deployment`) and leaves them. If you use `--swap-deployment`, the intercept will be left once the process dies, but the agent will remain. There's no harm in leaving the agent running alongside your service, but when you -want to remove them from the cluster, the telepresence uninstall command will help: +want to remove them from the cluster, the following Telepresence command will help: ``` $ telepresence uninstall --help Uninstall telepresence agents and manager @@ -75,3 +72,6 @@ Flags: -h, --help help for uninstall -n, --namespace string If present, the namespace scope for this CLI request ``` + +Since the new architecture deploys a Traffic Manager into the Ambassador namespace, please take a look at +our [rbac guide](../../reference/rbac) if you run into any issues with permissions while upgrading to Telepresence.