Merge branch 'tmp/split' into tmp/merge

Signed-off-by: Luke Shumaker <lukeshu@datawire.io>

concepts/context-prop.md

@@ -18,8 +18,19 @@ An application like Datadog or New Relic will use agents running on services thr
 
 ## What are intercepts and preview URLs?
 
-[Intercepts](../../reference/intercepts) and [preview URLs](../../howtos/preview-urls/) are functions of Telepresence that enable easy local development from a remote Kubernetes cluster and offer a preview environment for sharing and real-time collaboration.
-
-Telepresence also uses custom headers and header propagation for controllable intercepts and preview URLs instead of for tracing. The headers facilitate the smart routing of requests either to live services in the cluster or services running locally on a developer’s machine.
+[Intercepts](../../reference/intercepts) and [preview
+URLs](../../howtos/preview-urls/) are functions of Telepresence that
+enable easy local development from a remote Kubernetes cluster and
+offer a preview environment for sharing and real-time collaboration.
+
+Telepresence uses custom HTTP headers and header propagation to
+identify which traffic to intercept both for plain personal intercepts
+and for personal intercepts with preview URLs; these techniques are
+more commonly used for distributed tracing, so what they are being
+used for is a little unorthodox, but the mechanisms for their use are
+already widely deployed because of the prevalence of tracing.  The
+headers facilitate the smart routing of requests either to live
+services in the cluster or services running locally on a developer’s
+machine.
 
 Preview URLs, when created, generate an ingress request containing a custom header with a token (the context). Telepresence sends this token to [Ambassador Cloud](https://app.getambassador.io) with other information about the preview. Visiting the preview URL directs the user to Ambassador Cloud, which proxies the user to the cluster ingress with the token header injected into the request. The request carrying the header is routed in the cluster to the appropriate pod (the propagation). The Traffic Agent on the service pod sees the header and intercepts the request, redirecting it to the local developer machine that ran the intercept.

install/migrate-from-legacy.md

@@ -6,7 +6,18 @@ In legacy Telepresence, a pod running a service was swapped with a pod running t
 
 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 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.
+Telepresence 2 introduces a [new
+architecture](../../reference/architecture/) built around "intercepts"
+that addresses these problems.  With the new Telepresence, a sidecar
+proxy ("traffic agent") 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 personal intercepts, where rather
+than re-routing all traffic to the laptop/workstation, it only
+re-routes the traffic designated as belonging to that user, so that
+multiple developers can intercept the same service at the same time
+without disrupting normal operation or disrupting eacho.
 
 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.
 

quick-start/demo-node.md

@@ -215,7 +215,10 @@ We’ve now set up a local development environment for the DataProcessingService
 </Alert>
 
 ## 7. Create a Preview URL
-Create preview URLs to do selective intercepts, meaning only traffic coming from the preview URL will be intercepted, so you can easily share the services you’re working on with your teammates.
+
+Create a personal intercept with a preview URL; meaning that only
+traffic coming from the preview URL will be intercepted, so you can
+easily share the services you’re working on with your teammates.
 
 1. Clean up your previous intercept by removing it:
 `telepresence leave dataprocessingservice`

quick-start/qs-go.md

@@ -249,7 +249,10 @@ We’ve now set up a local development environment for the DataProcessingService
 </Alert>
 
 ## 7. Create a Preview URL
-Create preview URLs to do selective intercepts, meaning only traffic coming from the preview URL will be intercepted, so you can easily share the services you’re working on with your teammates.
+
+Create a personal intercept with a preview URL; meaning that only
+traffic coming from the preview URL will be intercepted, so you can
+easily share the services you’re working on with your teammates.
 
 1. Clean up your previous intercept by removing it:
 `telepresence leave dataprocessingservice`

quick-start/qs-java.md

@@ -243,7 +243,10 @@ We’ve now set up a local development environment for the DataProcessingService
 </Alert>
 
 ## 7. Create a Preview URL
-Create preview URLs to do selective intercepts, meaning only traffic coming from the preview URL will be intercepted, so you can easily share the services you’re working on with your teammates.
+
+Create a personal intercept with a preview URL; meaning that only
+traffic coming from the preview URL will be intercepted, so you can
+easily share the services you’re working on with your teammates.
 
 1. Clean up your previous intercept by removing it:
 `telepresence leave dataprocessingservice`

quick-start/qs-node.md

@@ -237,7 +237,10 @@ We’ve now set up a local development environment for the DataProcessingService
 </Alert>
 
 ## 7. Create a Preview URL
-Create preview URLs to do selective intercepts, meaning only traffic coming from the preview URL will be intercepted, so you can easily share the services you’re working on with your teammates.
+
+Create a personal intercept with a preview URL; meaning that only
+traffic coming from the preview URL will be intercepted, so you can
+easily share the services you’re working on with your teammates.
 
 1. Clean up your previous intercept by removing it:
 `telepresence leave dataprocessingservice`

quick-start/qs-python-fastapi.md

@@ -234,7 +234,10 @@ We’ve now set up a local development environment for the DataProcessingService
 </Alert>
 
 ## 7. Create a Preview URL
-Create preview URLs to do selective intercepts, meaning only traffic coming from the preview URL will be intercepted, so you can easily share the services you’re working on with your teammates.
+
+Create a personal intercept with a preview URL; meaning that only
+traffic coming from the preview URL will be intercepted, so you can
+easily share the services you’re working on with your teammates.
 
 1. Clean up your previous intercept by removing it:
 `telepresence leave dataprocessingservice`

quick-start/qs-python.md

@@ -245,7 +245,10 @@ We’ve now set up a local development environment for the DataProcessingService
 </Alert>
 
 ## 7. Create a Preview URL
-Create preview URLs to do selective intercepts, meaning only traffic coming from the preview URL will be intercepted, so you can easily share the services you’re working on with your teammates.
+
+Create a personal intercept with a preview URL; meaning that only
+traffic coming from the preview URL will be intercepted, so you can
+easily share the services you’re working on with your teammates.
 
 1. Clean up your previous intercept by removing it:
 `telepresence leave dataprocessingservice`

reference/cluster-config.md

@@ -74,9 +74,10 @@ Secrets that it detects to be formatted as one of those types.
 
 ## Air gapped cluster
 
-If your cluster is air gapped (it does not have access to the
-internet and therefore cannot connect to Ambassador Cloud), some additional
-configuration is required to acquire a license use selective intercepts.
+If your cluster is on an isolated network such that it cannot
+communicate with Ambassador Cloud, then some additional configuration
+is required to acquire a license key in order to use personal
+intercepts.
 
 ### Create a license
 
@@ -125,8 +126,10 @@ pulled and in a registry your cluster can pull from.
 
 5. Have users use the `images` [config key](../config/#images) keys so telepresence uses the aforementioned image for their agent.
 
-Users will now be able to use selective intercepts with the
-`--preview-url=false` flag (since use of preview URLs requires a connection to Ambassador Cloud).
+Users will now be able to use preview intercepts with the
+`--preview-url=false` flag.  Even with the license key, preview URLs
+cannot be used without enabling direct communication with Ambassador
+Cloud, as Ambassador Cloud is essential to their operation.
 
 If using Helm to install the server-side components, see the chart's [README](https://github.com/telepresenceio/telepresence/tree/release/v2/charts/telepresence) to learn how to configure the image registry and license secret.