[v2 (pre-release)] Sync from telepresence.io.git

concepts/context-prop.md

@@ -31,6 +31,7 @@ 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.
+machine. The intercepted traffic can be further limited by using path
+based routing.
 
 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.

concepts/intercepts.md

@@ -70,7 +70,7 @@ export function TabsContainer({ children, ...props }) {
 <TabsContainer>
 <TabPanel class="TabBody" value="regular">
 
-## No intercept
+# No intercept
 
 <Paper style="padding: 1em">
 <Animation class="mode-regular" />
@@ -81,7 +81,7 @@ This is the normal operation of your cluster without Telepresence.
 </TabPanel>
 <TabPanel class="TabBody" value="global">
 
-## Global intercept
+# Global intercept
 
 <Paper style="padding: 1em">
 <Animation class="mode-global" />
@@ -117,7 +117,7 @@ with all your dev tools.
 </TabPanel>
 <TabPanel class="TabBody" value="personal">
 
-## Personal intercept
+# Personal intercept
 
 **Personal intercepts** allow you to be selective and intercept only
 some of the traffic to a service while not interfering with the rest
@@ -183,5 +183,20 @@ while sharing the rest of the development environment.
     service that is running in the cluster.  This enables you to share
     the cluster with a team!
 
+### Intercepting a specific endpoint
+
+It's not uncommon to have one service serving several endpoints. Telepresence is capable of limiting an
+intercept to only affect the endpoints you want to work with by using one of the `--http-path-xxx`
+flags below in addition to using `--http-match` flags. Only one such flag can be used in an intercept
+and, contrary to the `--http-match` flag, it cannot be repeated.
+
+The following flags are available:
+
+| Flag                          | Meaning                                                          |
+|-------------------------------|------------------------------------------------------------------|
+| `--http-path-equal <path>`    | Only intercept the endpoint for this exact path                  |
+| `--http-path-prefix <prefix>` | Only intercept endpoints with a matching path prefix             |
+| `--http-path-regex <regex>`   | Only intercept endpoints that match the given regular expression |
+
 </TabPanel>
 </TabsContainer>

howtos/intercepts.md

@@ -8,21 +8,21 @@ import QSCards from '../quick-start/qs-cards'
 
 # Intercept a service in your own environment
 
-Telepresence enables you to create intercepts to a target Kubernetes workload. Once you have created and intercept, you can code and debug your associated service locally. 
+Telepresence enables you to create intercepts to a target Kubernetes workload. Once you have created and intercept, you can code and debug your associated service locally.
 
 For a detailed walk-though on creating intercepts using our sample app, follow the [quick start guide](../../quick-start/demo-node/).
 
 
 ## Prerequisites
 
-Before you begin, you need to have [Telepresence installed](<../../install/), and either the Kubernetes command-line tool, [`kubectl`](https://kubernetes.io/docs/tasks/tools/install-kubectl/), or the OpenShift Container Platform command-line interface, [`oc`](https://docs.openshift.com/container-platform/4.2/cli_reference/openshift_cli/getting-started-cli.html#cli-installing-cli_cli-developer-commands). This document uses kubectl in all example commands. OpenShift users can substitute oc [commands instead](https://docs.openshift.com/container-platform/4.1/cli_reference/developer-cli-commands.html).
+Before you begin, you need to have [Telepresence installed](../../install/), and either the Kubernetes command-line tool, [`kubectl`](https://kubernetes.io/docs/tasks/tools/install-kubectl/), or the OpenShift Container Platform command-line interface, [`oc`](https://docs.openshift.com/container-platform/4.2/cli_reference/openshift_cli/getting-started-cli.html#cli-installing-cli_cli-developer-commands). This document uses kubectl in all example commands. OpenShift users can substitute oc [commands instead](https://docs.openshift.com/container-platform/4.1/cli_reference/developer-cli-commands.html).
 
 This guide assumes you have a Kubernetes deployment and service accessible publicly by an ingress controller, and that you can run a copy of that service on your laptop.
 
 
 ## Intercept your service with a global intercept
 
-With Telepresence, you can create [global intercepts](../../concepts/intercepts/?intercept=global) that intercept all traffic going to a service in your cluster and route it to your local environment instead. 
+With Telepresence, you can create [global intercepts](../../concepts/intercepts/?intercept=global) that intercept all traffic going to a service in your cluster and route it to your local environment instead.
 
 1. Connect to your cluster with `telepresence connect` and connect to the Kubernetes API server:
 
@@ -55,7 +55,7 @@ With Telepresence, you can create [global intercepts](../../concepts/intercepts/
 
 3. Get the name of the port you want to intercept on your service:
    `kubectl get service <service name> --output yaml`.
-  
+
    For example:
 
    ```console
@@ -72,7 +72,7 @@ With Telepresence, you can create [global intercepts](../../concepts/intercepts/
 4. Intercept all traffic going to the service in your cluster:
     `telepresence intercept <service-name> --port <local-port>[:<remote-port>] --env-file <path-to-env-file>`.
       * For `--port`: specify the port the local instance of your service is running on. If the intercepted service exposes multiple ports, specify the port you want to intercept after a colon.
-      * For `--env-file`: specify a file path for Telepresence to write the environment variables that are set in the pod. 
+      * For `--env-file`: specify a file path for Telepresence to write the environment variables that are set in the pod.
        The example below shows Telepresence intercepting traffic going to service `example-service`. Requests now reach the service on port `http` in the cluster get routed to `8080` on the workstation and write the environment variables of the service to `~/example-service-intercept.env`.
        ```console
        $ telepresence intercept example-service --port 8080:http --env-file ~/example-service-intercept.env

howtos/preview-urls.md

@@ -42,34 +42,32 @@ $ telepresence intercept example-service --port 8080 --env-file ~/ex-svc.env
           You may use an IP address or a DNS name (this is usually a
           "service.namespace" DNS name).
 
-             [default: example-service.default]: ambassador.ambassador
+            [default: -]: ambassador.ambassador
 
      2/4: What's your ingress' TCP port number?
 
             [default: -]: 80
 
-      3/4: Does that TCP port on your ingress use TLS (as opposed to cleartext)?
+     3/4: Does that TCP port on your ingress use TLS (as opposed to cleartext)?
 
-             [default: n]: y
+            [default: n]: y
 
      4/4: If required by your ingress, specify a different hostname
           (TLS-SNI, HTTP "Host" header) to be used in requests.
 
-             [default: ambassador.ambassador]: dev-environment.edgestack.me
+            [default: ambassador.ambassador]: dev-environment.edgestack.me
 
-      Using Deployment example-service
-      intercepted
+     Using deployment example-service
+     intercepted
          Intercept name         : example-service
          State                  : ACTIVE
-         Workload kind          : Deployment
          Destination            : 127.0.0.1:8080
          Service Port Identifier: http
          Intercepting           : HTTP requests that match all of:
            header("x-telepresence-intercept-id") ~= regexp("<intercept id>:example-service")
          Preview URL            : https://<random domain name>.preview.edgestack.me
          Layer 5 Hostname       : dev-environment.edgestack.me
-
-  ```
+   ```
 
 5. Start your local environment using the environment variables retrieved in the previous step.
 

install/telepresence-pro.md

@@ -0,0 +1,66 @@
+import Platform from '@src/components/Platform';
+
+# Install Telepresence Pro
+
+Telepresence Pro is a replacement to Telepresence's User Daemon
+that gives you premium features including:
+* Creating intercepts on your local machine from Ambassador Cloud.
+
+The `telepresence-pro` binary must be installed in the same directory as
+`telepresence`. When you run `telepresence login` it will automatically be
+installed and placed in the correct location. If you are in an air-gapped
+environment or need to install it manually, ensure it is placed in the
+correct directory.
+
+<Platform.TabGroup>
+<Platform.MacOSTab>
+
+```shell
+# In this example, we install the binary in `/usr/local/bin/` since that's where `telepresence`
+# is installed by default
+# Intel Macs
+# 1. Download the latest binary (~60 MB):
+sudo curl -fL https://app.getambassador.io/download/tel-pro/darwin/amd64/$dlVersion$/latest/telepresence-pro -o /usr/local/bin/telepresence-pro
+# 2. Make the binary executable:
+sudo chmod a+x /usr/local/bin/telepresence-pro
+
+# Apple silicon Macs
+# 1. Download the latest binary (~60 MB):
+sudo curl -fL https://app.getambassador.io/download/tel-pro/darwin/arm64/$dlVersion$/latest/telepresence-pro -o /usr/local/bin/telepresence-pro
+# 2. Make the binary executable:
+sudo chmod a+x /usr/local/bin/telepresence-pro
+```
+
+</Platform.MacOSTab>
+<Platform.GNULinuxTab>
+
+```shell
+# In this example, we install the binary in `/usr/local/bin/` since that's where `telepresence`
+# is installed by default
+# 1. Download the latest binary (~60 MB):
+sudo curl -fL https://app.getambassador.io/download/tel-pro/linux/amd64/$dlVersion$/latest/telepresence-pro -o /usr/local/bin/telepresence-pro
+# 2. Make the binary executable:
+sudo chmod a+x /usr/local/bin/telepresence-pro
+```
+
+</Platform.GNULinuxTab>
+<Platform.WindowsTab>
+
+```powershell
+# In this example, we install the binary in `/usr/local/bin/` since that's where `telepresence`
+# is installed by default
+# Make sure you run the following from Powershell as Administrator
+# 1. Download the latest windows zip containing telepresence-pro.exe and its dependencies (~50 MB):
+curl -fL https://app.getambassador.io/download/tel-pro/windows/amd64/$dlVersion$/latest/telepresence-pro.exe -o telepresence-exe
+
+# 2. Move the exe to your path (We recommend the default directory used by telepresence `C:\telepresence`)
+Copy-Item "telepresence-pro.exe" -Destination "C:\telepresence\telepresence-pro.exe" -Force
+```
+
+</Platform.WindowsTab>
+</Platform.TabGroup>
+
+# Upgrade Telepresence Pro
+There are two options to upgrade Telepresence Pro. You can run `telepresence-pro upgrade` to get the latest
+version that is compatible with the current Telepresence version you are using or you can remove the binary
+and Telepresence will automatically install it next time you `telepresence login`.

quick-start/demo-node.md

@@ -4,4 +4,4 @@ description: "Claim a remote demo cluster and learn to use Telepresence to inter
 
 # Telepresence Quick Start
 
-To use a demo cluster provided by Ambassador Labs to learn how Telepresence can be used to intercept services to speed up local development and debugging, follow [this guide](https://www.getambassador.io/docs/telepresence/pre-release/quick-start/demo-node/)
+To use a demo cluster provided by Ambassador Labs to learn how Telepresence can be used to intercept services to speed up local development and debugging, follow [this guide](https://www.getambassador.io/docs/telepresence/2.5/quick-start/demo-node/)

quick-start/demo-react.md

@@ -4,4 +4,4 @@ description: "Claim a remote demo cluster and learn to use Telepresence to inter
 
 # Telepresence Quick Start
 
-To use a demo cluster provided by Ambassador Labs to learn how Telepresence can be used to intercept services to speed up local development and debugging, follow [this guide](https://www.getambassador.io/docs/telepresence/pre-release/quick-start/demo-react/)
+To use a demo cluster provided by Ambassador Labs to learn how Telepresence can be used to intercept services to speed up local development and debugging, follow [this guide](https://www.getambassador.io/docs/telepresence/2.5/quick-start/demo-react/)

quick-start/go.md

@@ -4,4 +4,4 @@ description: "Install Telepresence and learn to use it to intercept services run
 
 # Telepresence Quick Start
 
-To use a demo cluster provided by Ambassador Labs to learn how Telepresence can be used to intercept services to speed up local development and debugging, follow [this guide](https://www.getambassador.io/docs/telepresence/pre-release/quick-start/go/)
+To use a demo cluster provided by Ambassador Labs to learn how Telepresence can be used to intercept services to speed up local development and debugging, follow [this guide](https://www.getambassador.io/docs/telepresence/2.5/quick-start/go/)

quick-start/index.md

@@ -2,6 +2,6 @@
    description: Telepresence Quick Start.
 ---
 
-import TelepresenceQuickStartLanding from './TelepresenceQuickStartLanding'
+import TelepresenceQuickStartLanding from './TelepresenceQuickStartLanding';
 
 <TelepresenceQuickStartLanding/>

quick-start/qs-cards.js

@@ -28,39 +28,38 @@ export default function CenteredGrid() {
         <Grid item xs={4}>
           <Paper variant="outlined" className={classes.paper}>
             <Typography variant="h6" component="h2">
-              <a href="../../howtos/preview-urls/">
-                <b>Collaborating</b>
+              <a href="../../install/qs-java-advanced/">
+                <b>Create a Local K8s Dev Environment</b>
               </a>
             </Typography>
             <Typography variant="body2" component="p">
-              Use preview URLS to collaborate with your colleagues and others
-              outside of your organization.
+              Read the advanced guide on how to create your own complete Kubernetes development environment.
             </Typography>
           </Paper>
         </Grid>
         <Grid item xs={4}>
           <Paper variant="outlined" className={classes.paper}>
             <Typography variant="h6" component="h2">
-              <a href="../../howtos/outbound/">
-                <b>Outbound Sessions</b>
+              <a href="../../howtos/preview-urls/">
+                <b>Collaborating</b>
               </a>
             </Typography>
             <Typography variant="body2" component="p">
-              While connected to the cluster, your laptop can interact with
-              services as if it was another pod in the cluster.
+              Use preview URLS to collaborate with your colleagues and others
+              outside of your organization.
             </Typography>
           </Paper>
         </Grid>
         <Grid item xs={4}>
           <Paper variant="outlined" className={classes.paper}>
             <Typography variant="h6" component="h2">
-              <a href="../../faqs/">
-                <b>FAQs</b>
+              <a href="../../howtos/outbound/">
+                <b>Outbound Sessions</b>
               </a>
             </Typography>
             <Typography variant="body2" component="p">
-              Learn more about uses cases and the technical implementation of
-              Telepresence.
+              While connected to the cluster, your laptop can interact with
+              services as if it was another pod in the cluster.
             </Typography>
           </Paper>
         </Grid>

quick-start/qs-go.md

@@ -390,6 +390,10 @@ Normal traffic coming to your app gets the <strong style="color:green">green</st
   The <strong>Preview URL</strong> now shows exactly what is running on your local laptop -- in a way that can be securely shared with anyone you work with.
 </Alert>
 
+## Create a complete development environment using this demo application
+
+Apply what you've learned from this guide and employ the Emojivoto application in your own local development environment. See the [Creating a local Kubernetes development environment](../../install/qs-go-advanced/) page to learn more.
+
 ## <img class="os-logo" src="../../images/logo.png"/> What's Next?
 
 <QSCards/>