diff --git a/concepts/context-prop.md b/concepts/context-prop.md index dc9ee18f..b3eb41e3 100644 --- a/concepts/context-prop.md +++ b/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. diff --git a/concepts/intercepts.md b/concepts/intercepts.md index c39a80eb..4b1e770f 100644 --- a/concepts/intercepts.md +++ b/concepts/intercepts.md @@ -70,7 +70,7 @@ export function TabsContainer({ children, ...props }) { -## No intercept +# No intercept @@ -81,7 +81,7 @@ This is the normal operation of your cluster without Telepresence. -## Global intercept +# Global intercept @@ -117,7 +117,7 @@ with all your dev tools. -## 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 ` | Only intercept the endpoint for this exact path | +| `--http-path-prefix ` | Only intercept endpoints with a matching path prefix | +| `--http-path-regex ` | Only intercept endpoints that match the given regular expression | + diff --git a/howtos/intercepts.md b/howtos/intercepts.md index ea088950..6adebd6c 100644 --- a/howtos/intercepts.md +++ b/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 --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 --port [:] --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 diff --git a/howtos/preview-urls.md b/howtos/preview-urls.md index cad231fc..670f72dd 100644 --- a/howtos/preview-urls.md +++ b/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(":example-service") Preview URL : https://.preview.edgestack.me Layer 5 Hostname : dev-environment.edgestack.me - - ``` + ``` 5. Start your local environment using the environment variables retrieved in the previous step. diff --git a/install/telepresence-pro.md b/install/telepresence-pro.md new file mode 100644 index 00000000..f7a86bb1 --- /dev/null +++ b/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. + + + + +```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 +``` + + + + +```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 +``` + + + + +```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 +``` + + + + +# 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`. diff --git a/quick-start/demo-node.md b/quick-start/demo-node.md index 3d7a687b..5dcbd654 100644 --- a/quick-start/demo-node.md +++ b/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/) diff --git a/quick-start/demo-react.md b/quick-start/demo-react.md index 91e06e8b..7c7c00cc 100644 --- a/quick-start/demo-react.md +++ b/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/) diff --git a/quick-start/go.md b/quick-start/go.md index 65b88f6f..bd3e1e55 100644 --- a/quick-start/go.md +++ b/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/) diff --git a/quick-start/index.md b/quick-start/index.md index efcb65b5..f2305d72 100644 --- a/quick-start/index.md +++ b/quick-start/index.md @@ -2,6 +2,6 @@ description: Telepresence Quick Start. --- -import TelepresenceQuickStartLanding from './TelepresenceQuickStartLanding' +import TelepresenceQuickStartLanding from './TelepresenceQuickStartLanding'; diff --git a/quick-start/qs-cards.js b/quick-start/qs-cards.js index 31582355..0d8c7226 100644 --- a/quick-start/qs-cards.js +++ b/quick-start/qs-cards.js @@ -28,39 +28,38 @@ export default function CenteredGrid() { - - Collaborating + + Create a Local K8s Dev Environment - 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. - - Outbound Sessions + + Collaborating - 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. - - FAQs + + Outbound Sessions - 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. diff --git a/quick-start/qs-go.md b/quick-start/qs-go.md index 37291657..c2514635 100644 --- a/quick-start/qs-go.md +++ b/quick-start/qs-go.md @@ -390,6 +390,10 @@ Normal traffic coming to your app gets the greenPreview URL now shows exactly what is running on your local laptop -- in a way that can be securely shared with anyone you work with. +## 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. + ## What's Next? diff --git a/quick-start/telepresence-quickstart-landing.less b/quick-start/telepresence-quickstart-landing.less index 1a8c3ddc..37304255 100644 --- a/quick-start/telepresence-quickstart-landing.less +++ b/quick-start/telepresence-quickstart-landing.less @@ -1,184 +1,160 @@ @import '~@src/components/Layout/vars.less'; -.doc-body .telepresence-quickstart-landing { +.telepresence-quickstart-landing { font-family: @InterFont; color: @black; margin: 0 auto 140px; max-width: @docs-max-width; min-width: @docs-min-width; - h1, - h2 { + h1 { color: @blue-dark; - font-style: normal; font-weight: normal; letter-spacing: 0.25px; - } - - h1 { font-size: 33px; - line-height: 40px; + } + p { + font-size: 0.875rem; + line-height: 24px; + margin: 0; + padding: 0; + } - svg { - vertical-align: text-bottom; + .demo-cluster-container { + display: grid; + margin: 40px 0; + grid-template-columns: repeat(2, 1fr); + column-gap: 40px; + @media screen and (max-width: 720px) { + grid-template-columns: repeat(1, 1fr); + row-gap: 50px; } } - - h2 { - font-size: 23px; - line-height: 33px; - margin: 0 0 1rem; - - .highlight-mark { - background: transparent; + .main-title-container { + display: flex; + flex-direction: column; + align-items: center; + p { + text-align: center; + font-size: 0.875rem; + } + } + h2.title { + font-size: 1.5rem; + color: @black; + font-weight: normal; + margin: 0 0 10px 0; + padding: 0; + &.underlined { + padding-bottom: 2px; + border-bottom: 3px solid @grey-separator; + text-align: center; + } + strong { + font-weight: 600; + } + } + .reading-time { + color: #7c7c87; + margin: 0; + } + .get-started { + font-size: 0.875rem; + font-weight: 600; + letter-spacing: 1.25px; + display: flex; + align-items: center; + margin: 20px 20px 10px; + text-decoration: none; + &.green { + color: @green; + } + &.green:hover { + color: @green-dark; + } + &.blue { + color: @blue; + } + &.blue:hover { color: @blue-dark; - background: -moz-linear-gradient( - top, - transparent 0%, - transparent 60%, - fade(@blue-electric, 15%) 60%, - fade(@blue-electric, 15%) 100% - ); - background: -webkit-gradient( - linear, - left top, - left bottom, - color-stop(0%, transparent), - color-stop(60%, transparent), - color-stop(60%, fade(@blue-electric, 15%)), - color-stop(100%, fade(@blue-electric, 15%)) - ); - background: -webkit-linear-gradient( - top, - transparent 0%, - transparent 60%, - fade(@blue-electric, 15%) 60%, - fade(@blue-electric, 15%) 100% - ); - background: -o-linear-gradient( - top, - transparent 0%, - transparent 60%, - fade(@blue-electric, 15%) 60%, - fade(@blue-electric, 15%) 100% - ); - background: -ms-linear-gradient( - top, - transparent 0%, - transparent 60%, - fade(@blue-electric, 15%) 60%, - fade(@blue-electric, 15%) 100% - ); - background: linear-gradient( - to bottom, - transparent 0%, - transparent 60%, - fade(@blue-electric, 15%) 60%, - fade(@blue-electric, 15%) 100% - ); - filter: progid:DXImageTransform.Microsoft.gradient( startColorstr='transparent', endColorstr='fade(@blue-electric, 15%)',GradientType=0 ); - padding: 0 3px; - margin: 0 0.1em 0 0; } } - .telepresence-choice { - background: @white; + .box-container { + border: 1.5px solid @grey-separator; + border-radius: 5px; + padding: 10px; + position: relative; + &::before { + content: ''; + position: absolute; + width: 14px; + height: 14px; + border-radius: 50%; + top: 0; + left: 50%; + transform: translate(-50%, -50%); + } + &.green::before { + background: @green; + box-shadow: 0 0 0 5px #00c05b45; + } + &.blue::before { + background: @blue; + box-shadow: 0 0 0 5px #0066ff45; + } + p { + font-size: 0.875rem; + line-height: 24px; + padding: 0; + } + } + .connector-container { + display: flex; + justify-content: center; + span { + background: @grey-separator; + width: 1.5px; + height: 37px; + } + } + + .telepresence-video { border: 2px solid @grey-separator; box-shadow: -6px 12px 0px fade(@black, 12%); border-radius: 8px; padding: 20px; + h2.telepresence-video-title { + padding: 0; + margin: 0; + } strong { color: @blue; } } - .telepresence-choice-wrapper { - border-bottom: solid 1px @grey-separator; - column-gap: 60px; - display: inline-grid; - grid-template-columns: repeat(2, 1fr); - margin: 20px 0 50px; - padding: 0 0 62px; - width: 100%; - - .telepresence-choice { - ol { - li { - font-size: 14px; - } - } - - .get-started-button { - background-color: @green; - border-radius: 5px; - color: @white; - display: inline-flex; - font-style: normal; - font-weight: 600; - font-size: 14px; - line-height: 24px; - margin: 0 0 15px 5px; - padding: 13px 20px; - align-items: center; - letter-spacing: 1.25px; - text-decoration: none; - text-transform: uppercase; - transition: background-color 200ms linear 0ms; - - svg { - fill: @white; - height: 20px; - width: 20px; - } - - &:hover { - background-color: @green-dark; - text-decoration: none; - } - } - - p { - font-style: normal; - font-weight: normal; - font-size: 16px; - line-height: 26px; - letter-spacing: 0.5px; - } + .video-section { + display: grid; + grid-template-columns: 1fr 2fr; + column-gap: 10px; + @media screen and (max-width: 1400px) { + grid-template-columns: 1fr; } - } - - .video-wrapper { - display: flex; - flex-direction: row; - ul { - li { - font-size: 14px; - margin: 0 10px 10px 0; - } + font-size: 14px; + margin: 0 10px 6px 0; } - - div { - &.video-container { - flex: 1 1 70%; - position: relative; + .video-container { + position: relative; + padding-bottom: 56.25%; // 16:9 aspect ratio + height: 0; + iframe { + position: absolute; + top: 0; + left: 0; width: 100%; - padding-bottom: 39.375%; - - .video { - position: absolute; - top: 0; - left: 0; - width: 100%; - height: 100%; - border: 0; - } - } - - &.description { - flex: 0 1 30%; + height: 100%; } } } diff --git a/reference/architecture.md b/reference/architecture.md index 47facb0b..a7427486 100644 --- a/reference/architecture.md +++ b/reference/architecture.md @@ -21,6 +21,9 @@ another. The Telepresence Daemon runs on a developer's workstation and is its main point of communication with the cluster's network. All requests from and to the cluster go through the Daemon, which communicates with the Traffic Manager. +When you run telepresence login, Telepresence installs an enhanced Telepresence Daemon. This replaces the open source +User Daemon and allows you to create intercepts on your local machine from Ambassador Cloud. + ## Traffic Manager The Traffic Manager is the central point of communication between Traffic Agents in the cluster and Telepresence Daemons diff --git a/reference/client/login.md b/reference/client/login.md index 269a240d..78335197 100644 --- a/reference/client/login.md +++ b/reference/client/login.md @@ -29,6 +29,14 @@ box via SSH, or are using Telepresence in CI), then you may instead have Ambassador Cloud issue an API key that you pass to `telepresence login` with the `--apikey` flag. +## Telepresence + +When you run `telepresence login`, the CLI installs +a Telepresence binary. The Telepresence enhanced free client of the [User +Daemon](../../architecture) communicates with the Ambassador Cloud to +provide fremium features including the ability to create intercepts from +Ambassador Cloud. + ## Acquiring an API key 1. Log in to Ambassador Cloud at https://app.getambassador.io/ . diff --git a/reference/cluster-config.md b/reference/cluster-config.md index 48aaa6f9..1db27ef7 100644 --- a/reference/cluster-config.md +++ b/reference/cluster-config.md @@ -83,7 +83,7 @@ intercepts. ### Create a license -1. +1. 2. Generate a new license (if one doesn't already exist) by clicking *Generate New License*. diff --git a/reference/config.md b/reference/config.md index 3d42b005..6722bc93 100644 --- a/reference/config.md +++ b/reference/config.md @@ -31,9 +31,6 @@ grpc: maxReceiveSize: 10Mi telepresenceAPI: port: 9980 -intercept: - appProtocolStrategy: portName - defaultPort: "8088" ``` #### Timeouts @@ -65,6 +62,8 @@ case insensitive: - `info` - `warning` or `warn` - `error` + - `fatal` + - `panic` For whichever log-level you select, you will get logs labeled with that level and of higher severity. (e.g. if you use `info`, you will also get logs labeled `error`. You will NOT get logs labeled `debug`. @@ -135,28 +134,16 @@ The `telepresenceAPI` controls the behavior of Telepresence's RESTful API server If the `traffic-manager` is auto-installed, its webhook agent injector will be configured to add the `TELEPRESENCE_API_PORT` environment to the app container when the `traffic-agent` is injected. See [RESTful API server](../restapi) for more info. -#### Intercept -The `intercept` controls applies to how telepresence will intercept the communications to the intercepted service. +#### Daemons -The `defaultPort` controls which port is selected when no `--port` flag is given to the `telepresence intercept` command. The default value is "8080". +`daemons` controls which binary to use for the user daemon. By default it will +use the Telepresence binary. For example, this can be used to tell Telepresence to +use the Telepresence Pro binary. -The `appProtocolStrategy` is only relevant when using personal intercepts. This controls how telepresence selects the application protocol to use when intercepting a service that has no `service.ports.appProtocol` defined. Valid values are: +| Field | Description | Type | Default | +|--------------------|-------------------------------------------------------------|--------------------|--------------------------------------| +| `userDaemonBinary` | The path to the binary you want to use for the User Daemon. | [string][yaml-str] | The path to Telepresence executable | -| Value | Resulting action | -|--------------|--------------------------------------------------------------------------------------------------------| -| `http2Probe` | The telepresence traffic-agent will probe the intercepted container to check whether it supports http2 | -| `portName` | Telepresence will make an educated guess about the protocol based on the name of the service port | -| `http` | Telepresence will use http | -| `http2` | Telepresence will use http2 | - -When `portName` is used, Telepresence will determine the protocol by the name of the port: `[-suffix]`. The following protocols are recognized: - -| Protocol | Meaning | -|----------|---------------------------------------| -| `http` | Plaintext HTTP/1.1 traffic | -| `http2` | Plaintext HTTP/2 traffic | -| `https` | TLS Encrypted HTTP (1.1 or 2) traffic | -| `grpc` | Same as http2 | ## Per-Cluster Configuration Some configuration is not global to Telepresence and is actually specific to a cluster. Thus, we store that config information in your kubeconfig file, so that it is easier to maintain per-cluster configuration. diff --git a/reference/intercepts/index.md b/reference/intercepts/index.md index bd9c5bdc..20b0094d 100644 --- a/reference/intercepts/index.md +++ b/reference/intercepts/index.md @@ -43,8 +43,8 @@ login`](../client/login/)) changes the Telepresence defaults in two ways. First, being logged in to Ambassador Cloud causes Telepresence to -default to `--mechanism=http --http-match=auto` (or just -`--http-match=auto`, as `--http-match` implies `--mechanism=http`). +default to `--mechanism=http --http-match=auto --http-path-prefix=/` ( +`--mechanism=http` is redundant. It is implied by other `--http-xxx` flags). If you hadn't been logged in it would have defaulted to `--mechanism=tcp`. This tells Telepresence to use the Ambassador Cloud traffic-agent to do smart "personal" intercepts and only @@ -52,8 +52,8 @@ intercept a subset of HTTP requests, rather than just intercepting the entirety of all TCP connections. This is important for working in a shared cluster with teammates, and is important for the preview URL functionality below. See `telepresence intercept --help` for -information on using `--http-match` to customize which requests it -intercepts. +information on using the `--http-match` and `--http-path-xxx` flags to +customize which requests that are intercepted. Secondly, being logged in causes Telepresence to default to `--preview-url=true`. If you hadn't been logged in it would have @@ -68,26 +68,14 @@ your cluster; if it detects it correctly, may simply press "enter" and accept the default, otherwise you must tell Telepresence the correct value. -When you create an intercept with the `http` mechanism, Telepresence -determines whether the application protocol uses HTTP/1.1 or HTTP/2. If the -service's `ports.appProtocol` field is set, Telepresence uses that. If not, -then Telepresence uses the configured application protocol strategy to determine -the protocol. The default behavior (`http2Probe` strategy) sends a -`GET /telepresence-http2-check` request to your service to determine if it supports -HTTP/2. This is required for the intercepts to behave correctly. - -### TLS - -If the intercepted service has been set up for `--mechanism=http`, Telepresence -needs to terminate the TLS connection for the `http` mechanism to function in your -intercepts. Additionally, you need to ensure the -[TLS annotations](../cluster-config/#tls) are properly entered in your workload’s -Pod template to designate that requests leaving your service still speak TLS -outside of the service as expected. - -Use the `--http-plaintext` flag when doing an intercept when the service in the -cluster is using TLS in case you want to use plaintext for the communication with the -process on your local workstation. +When creating an intercept with the `http` mechanism, the +traffic-agent sends a `GET /telepresence-http2-check` request to your +service and to the process running on your local machine at the port +specified in your intercept, in order to determine if they support +HTTP/2. This is required for the intercepts to behave correctly. If +you do not have a service running locally when the intercept is +created, the traffic-agent will use the result it got from checking +the in-cluster service. ## Supported workloads @@ -192,12 +180,12 @@ Finally, run `telepresence leave ` to stop the intercept. You can skip the ingress dialogue by setting the relevant parameters using flags. If any of the following flags are set, the dialogue will be skipped and the flag values will be used instead. If any of the required flags are missing, an error will be thrown. -| Flag | Description | Required | -| -------------- | ------------------------------ | --- | -| `--ingress-host` | The ip address for the ingress | yes | -| `--ingress-port` | The port for the ingress | yes | -| `--ingress-tls` | Whether tls should be used | no | -| `--ingress-l5` | Whether a different ip address should be used in request headers | no | +| Flag | Description | Required | +|------------------|------------------------------------------------------------------|------------| +| `--ingress-host` | The ip address for the ingress | yes | +| `--ingress-port` | The port for the ingress | yes | +| `--ingress-tls` | Whether tls should be used | no | +| `--ingress-l5` | Whether a different ip address should be used in request headers | no | ## Creating an intercept when a service has multiple ports @@ -236,7 +224,7 @@ Oftentimes, there's a 1-to-1 relationship between a service and a workload, so telepresence is able to auto-detect which service it should intercept based on the workload you are trying to intercept. But if you use something like -[Argo](https://www.getambassador.io/docs/argo/latest/quick-start/), there may be +[Argo](https://www.getambassador.io/docs/argo/latest/), there may be two services (that use the same labels) to manage traffic between a canary and a stable service. diff --git a/reference/rbac.md b/reference/rbac.md index 2c9af7c1..6c39739e 100644 --- a/reference/rbac.md +++ b/reference/rbac.md @@ -149,7 +149,7 @@ rules: - apiGroups: - "" resources: ["services"] - verbs: ["get", "list", "update"] + verbs: ["get", "list", "update", "watch"] - apiGroups: - "" resources: ["pods/portforward"] @@ -157,7 +157,7 @@ rules: - apiGroups: - "apps" resources: ["deployments", "replicasets", "statefulsets"] - verbs: ["get", "list", "update", "patch"] + verbs: ["get", "list", "update", "patch", "watch"] - apiGroups: - "getambassador.io" resources: ["hosts", "mappings"] @@ -223,7 +223,7 @@ rules: - apiGroups: - "apps" resources: ["deployments", "replicasets", "statefulsets"] - verbs: ["get", "list", "update"] + verbs: ["get", "list", "update", "watch"] - apiGroups: - "getambassador.io" resources: ["hosts", "mappings"] diff --git a/reference/restapi.md b/reference/restapi.md index e3934abd..462abd19 100644 --- a/reference/restapi.md +++ b/reference/restapi.md @@ -10,6 +10,13 @@ On the cluster's side, it's the `traffic-agent` of potentially intercepted pods ## Endpoints +The `consume-here` and `intercept-info` endpoints are both intended to be queried with an optional path query and a set of headers, typically obtained from a Kafka message or similar. Telepresence provides the ID of the intercept in the environment variable [TELEPRESENCE_INTERCEPT_ID](../environment/#telepresence_intercept_id) during an intercept. This ID must be provided in a `x-telepresence-caller-intercept-id: = ` header. Telepresence needs this to identify the caller correctly. The `` will be empty when running in the cluster, but it's harmless to provide it there too, so there's no need for conditional code. + +There are three prerequisites to fulfill before testing The `consume-here` and `intercept-info` endpoints using `curl -v` on the workstation: +1. An intercept must be active +2. The "/healthz" endpoint must respond with OK +3. The ID of the intercept must be known. It will be visible as `ID` in the output of `telepresence list --debug`. + ### healthz The `http://localhost:/healthz` endpoint should respond with status code 200 OK. If it doesn't then something isn't configured correctly. Check that the `traffic-agent` container is present and that the `TELEPRESENCE_API_PORT` has been added to the environment of the application container and/or in the environment that is propagated to the interceptor that runs on the local workstation. @@ -33,85 +40,54 @@ $ curl -v localhost:9980/healthz ``` ### consume-here -`http://localhost:/consume-here` is intended to be queried with a set of headers, typically obtained from a Kafka message or similar, and will respond with "true" (consume the message) or "false" (leave the message on the queue). When running in the cluster, this endpoint will respond with `false` if the headers match an ongoing intercept for the same workload because it's assumed that it's up to the intercept to consume the message. When running locally, the response is inverted. Matching headers means that the message should be consumed. - -Telepresence provides the ID of the intercept in the environment variable [TELEPRESENCE_INTERCEPT_ID](../environment/#telepresence_intercept_id) during an intercept. This ID must be provided in a `x-caller-intercept-id: = ` header. Telepresence needs this to identify the caller correctly. The `` will be empty when running in the cluster, but it's harmless to provide it there too, so there's no need for conditional code. +`http://localhost:/consume-here` will respond with "true" (consume the message) or "false" (leave the message on the queue). When running in the cluster, this endpoint will respond with `false` if the headers match an ongoing intercept for the same workload because it's assumed that it's up to the intercept to consume the message. When running locally, the response is inverted. Matching headers means that the message should be consumed. #### test endpoint using curl -There are three prerequisites to fulfill before testing this endpoint using `curl -v` on the workstation. -1. An intercept must be active -2. The "/healtz" endpoint must respond with OK -3. The ID of the intercept must be known. It will be visible as `x-telepresence-intercept-id` in the output of the `telepresence intercept` and `telepresence list` commands unless the intercept was started with `--http-match` flags. If it was, the `--env-file ` or `--env-json ` flag must be also be used so that the environment can be examined. The variable to look for in the file is `TELEPRESENCE_INTERCEPT_ID`. - -Assuming that the API-server runs on port 9980, that the intercept was started with `-H 'foo: bar`, we can now check that the "/consume-here" returns "true" for the given headers. +Assuming that the API-server runs on port 9980, that the intercept was started with `--http-match x=y --http-path-prefix=/api`, we can now check that the "/consume-here" returns "true" for the path "/api" and given headers. ```console -$ curl -v localhost:9980/consume-here -H 'x-telepresence-caller-intercept-id: 4392d394-100e-4f15-a89b-426012f10e05:apitest' -H 'foo: bar' +$ curl -v localhost:9980/consume-here?path=/api -H 'x-telepresence-caller-intercept-id: 4392d394-100e-4f15-a89b-426012f10e05:apitest' -H 'x: y' * Trying ::1:9980... * Connected to localhost (::1) port 9980 (#0) -> GET /consume-here HTTP/1.1 +> GET /consume-here?path=/api HTTP/1.1 > Host: localhost:9980 > User-Agent: curl/7.76.1 > Accept: */* +> x: y > x-telepresence-caller-intercept-id: 4392d394-100e-4f15-a89b-426012f10e05:apitest -> foo: bar > * Mark bundle as not supporting multiuse < HTTP/1.1 200 OK -< Content-Type: text/plain +< Content-Type: application/json < Date: Fri, 26 Nov 2021 06:43:28 GMT < Content-Length: 4 < * Connection #0 to host localhost left intact -true% +true ``` If you can run curl from the pod, you can try the exact same URL. The result should be "false" when there's an ongoing intercept. The `x-telepresence-caller-intercept-id` is not needed when the call is made from the pod. -#### Example code: - -Here's an example filter written in Go. It divides the actual URL creation (only needs to run once) from the filter function to make the filter more performant: -```go -const portEnv = "TELEPRESENCE_API_PORT" -const interceptIdEnv = "TELEPRESENCE_INTERCEPT_ID" -// apiURL creates the generic URL needed to access the service -func apiURL() (string, error) { - pe := os.Getenv(portEnv) - if _, err := strconv.ParseUint(pe, 10, 16); err != nil { - return "", fmt.Errorf("value %q of env %s does not represent a valid port number", pe, portEnv) - } - return "http://localhost:" + pe, nil -} +### intercept-info +`http://localhost:/intercept-info` is intended to be queried with an optional path query and a set of headers, typically obtained from a Kafka message or similar, and will respond with a JSON structure containing the two booleans `clientSide` and `intercepted`, and a `metadata` map which corresponds to the `--http-meta` key pairs used when the intercept was created. This field is always omitted in case `intercepted` is `false`. -// consumeHereURL creates the URL for the "consume-here" endpoint -func consumeHereURL() (string, error) { - apiURL, err := apiURL() - if err != nil { - return "", err - } - return apiURL + "/consume-here", nil -} - -// consumeHere expects an url created using consumeHereURL() and calls the endpoint with the given -// headers and returns the result -func consumeHere(url string, hm map[string]string) (bool, error) { - rq, err := http.NewRequest("GET", url, nil) - if err != nil { - return false, err - } - rq.Header = make(http.Header, len(hm)+1) - rq.Header.Set("X-Telepresence-Caller-Intercept-Id", os.Getenv(interceptIdEnv)) - for k, v := range hm { - rq.Header.Set(k, v) - } - rs, err := http.DefaultClient.Do(rq) - if err != nil { - return false, err - } - defer rs.Body.Close() - b, err := io.ReadAll(rs.Body) - if err != nil { - return false, err - } - return strconv.ParseBool(string(b)) -} -``` \ No newline at end of file +#### test endpoint using curl +Assuming that the API-server runs on port 9980, that the intercept was started with `--http-match x=y --http-path-prefix=/api --http-meta a=b --http-meta b=c`, we can now check that the "/intercept-info" returns information for the given path and headers. +```console +$ curl -v localhost:9980/intercept-info?path=/api -H 'x-telepresence-caller-intercept-id: 4392d394-100e-4f15-a89b-426012f10e05:apitest' -H 'x: y' +* Trying ::1:9980...* Connected to localhost (127.0.0.1) port 9980 (#0) +> GET /intercept-info?path=/api HTTP/1.1 +> Host: localhost:9980 +> User-Agent: curl/7.79.1 +> Accept: */* +> x: y +> x-telepresence-caller-intercept-id: 4392d394-100e-4f15-a89b-426012f10e05:apitest +> +* Mark bundle as not supporting multiuse +< HTTP/1.1 200 OK +< Content-Type: application/json +< Date: Tue, 01 Feb 2022 11:39:55 GMT +< Content-Length: 68 +< +{"intercepted":true,"clientSide":true,"metadata":{"a":"b","b":"c"}} +* Connection #0 to host localhost left intact +``` diff --git a/reference/vpn.md b/reference/vpn.md index 368a9fa1..cb3f8acf 100644 --- a/reference/vpn.md +++ b/reference/vpn.md @@ -146,7 +146,7 @@ be possible. In that case, your best bet is to attempt to shrink the VPN's CIDR One easy way to do this may be by disabling split tunneling (see the [prerequisites](#prerequisites) section for more on split-tunneling). -Note that once you fix this, you may find yourself landing again in [Case 1](#case-1), and may need +Note that once you fix this, you may find yourself landing again in [Case 1](#case-1-vpn-masked-by-cluster), and may need to use never-proxy rules to whitelist hosts in the VPN: ``` diff --git a/release-notes/telepresence-2.4.10-actions.png b/release-notes/telepresence-2.4.10-actions.png deleted file mode 100644 index 6d849ac2..00000000 Binary files a/release-notes/telepresence-2.4.10-actions.png and /dev/null differ diff --git a/release-notes/telepresence-2.4.10-intercept-config.png b/release-notes/telepresence-2.4.10-intercept-config.png deleted file mode 100644 index e3f1136a..00000000 Binary files a/release-notes/telepresence-2.4.10-intercept-config.png and /dev/null differ diff --git a/release-notes/telepresence-2.5.0-pro-daemon.png b/release-notes/telepresence-2.5.0-pro-daemon.png new file mode 100644 index 00000000..5b82fc76 Binary files /dev/null and b/release-notes/telepresence-2.5.0-pro-daemon.png differ diff --git a/releaseNotes.yml b/releaseNotes.yml index b91a78ec..a9f5f24d 100644 --- a/releaseNotes.yml +++ b/releaseNotes.yml @@ -26,6 +26,7 @@ # `FOO/releaseNotes.yml`, then the image paths are # relative to `FOO/release-notes/`. # - docs: The path to the documentation page where additional information can be found. +# - href: A path from the root to a resource on the getambassador website, takes precedence over a docs link. docTitle: Telepresence Release Notes docDescription: >- @@ -38,6 +39,129 @@ docDescription: >- changelog: https://github.com/telepresenceio/telepresence/blob/$branch$/CHANGELOG.md items: + - version: 2.5.4 + date: "2022-03-29" + notes: + - type: bugfix + title: Linux DNS Concurrency + body: >- + The DNS fallback resolver on Linux now correctly handles concurrent requests without timing them out + - type: bugfix + title: Non-Functional Flag + body: >- + The ingress-l5 flag will no longer be forcefully set to equal the --ingress-host flag + - type: bugfix + title: Automatically Remove Failed Intercepts + body: >- + Intercepts that fail to create are now consistently removed to prevent non-working dangling intercepts from sticking around. + - type: bugfix + title: Agent UID + body: >- + Agent container is no longer sensitive to a random UID or an UID imposed by a SecurityContext. + - type: bugfix + title: Gather-Logs Output Filepath + body: >- + Removed a bad concatenation that corrupted the output path of `telepresence gather-logs`. + - type: change + title: Remove Unnecessary Error Advice + body: >- + An advice to "see logs for details" is no longer printed when the argument count is incorrect in a CLI command. + - type: bugfix + title: Garbage Collection + body: >- + Client and agent sessions no longer leaves dangling waiters in the traffic-manager when they depart. + - type: bugfix + title: Limit Gathered Logs + body: >- + The client's gather logs command and agent watcher will now respect the configured grpc.maxReceiveSize + - type: change + title: In-Cluster Checks + body: >- + The TUN device will no longer route pod or service subnets if it is running in a machine that's already connected to the cluster + - type: change + title: Expanded Status Command + body: >- + The status command includes the install id, user id, account id, and user email in its result, and can print output as JSON + - type: change + title: List Command Shows All Intercepts + body: >- + The list command, when used with the `--intercepts` flag, will list the users intercepts from all namespaces + - version: 2.5.3 + date: "2022-02-25" + notes: + - type: bugfix + title: TCP Connectivity + body: >- + Fixed bug in the TCP stack causing timeouts after repeated connects to the same address + - type: feature + title: Linux Binaries + body: >- + Client-side binaries for the arm64 architecture are now available for linux + - version: 2.5.2 + date: "2022-02-23" + notes: + - type: bugfix + title: DNS server bugfix + body: >- + Fixed a bug where Telepresence would use the last server in resolv.conf + - version: 2.5.1 + date: "2022-02-19" + notes: + - type: bugfix + title: Fix GKE auth issue + body: >- + Fixed a bug where using a GKE cluster would error with: No Auth Provider found for name "gcp" + - version: 2.5.0 + date: "2022-02-18" + notes: + - type: feature + title: Intercept specific endpoints + body: >- + The flags --http-path-equal, --http-path-prefix, and --http-path-regex can can be used in + addition to the --http-match flag to filter personal intercepts by the request URL path + docs: concepts/intercepts#intercepting-a-specific-endpoint + - type: feature + title: Intercept metadata + body: >- + The flag --http-meta can be used to declare metadata key value pairs that will be returned by the Telepresence rest + API endpoint /intercept-info + docs: reference/restapi#intercept-info + - type: change + title: Client RBAC watch + body: >- + The verb "watch" was added to the set of required verbs when accessing services and workloads for the client RBAC + ClusterRole + docs: reference/rbac + - type: change + title: Dropped backward compatibility with versions <=2.4.4 + body: >- + Telepresence is no longer backward compatible with versions 2.4.4 or older because the deprecated multiplexing tunnel + functionality was removed. + - type: change + title: No global networking flags + body: >- + The global networking flags are no longer used and using them will render a deprecation warning unless they are supported by the + command. The subcommands that support networking flags are connect, current-cluster-id, + and genyaml. + - type: bugfix + title: Output of status command + body: >- + The also-proxy and never-proxy subnets are now displayed correctly when using the + telepresence status command. + - type: bugfix + title: SETENV sudo privilege no longer needed + body: >- + Telepresence longer requires SETENV privileges when starting the root daemon. + - type: bugfix + title: Network device names containing dash + body: >- + Telepresence will now parse device names containing dashes correctly when determining routes that it should never block. + - type: bugfix + title: Linux uses cluster.local as domain instead of search + body: >- + The cluster domain (typically "cluster.local") is no longer added to the DNS search on Linux using + systemd-resolved. Instead, it is added as a domain so that names ending with it are routed + to the DNS server. - version: 2.4.11 date: "2022-02-10" notes: @@ -85,7 +209,7 @@ items: - type: bugfix title: Check conditions before asking questions body: >- - User will not be asked to log in or add ingress information when creating an intercept until a check has been + User will not be asked to log in or add ingress information when creating an intercept until a check has been made that the intercept is possible. docs: reference/intercepts/ - type: bugfix @@ -189,7 +313,7 @@ items: - type: bugfix title: Prevent network recursion body: >- - The TUN-device will trap failed connection attempts that results in recursive calls back into the TUN-device (may happen when the + The TUN-device will trap failed connection attempts that results in recursive calls back into the TUN-device (may happen when the cluster runs in a docker-container on the client). docs: reference/routing#connect-recursion - type: bugfix diff --git a/versions.yml b/versions.yml index ef6d2867..199baa0e 100644 --- a/versions.yml +++ b/versions.yml @@ -1,5 +1,5 @@ -version: "2.4.10" +version: "2.5.4" dlVersion: "latest" -docsVersion: "pre-release" +docsVersion: "2.5" branch: release/v2 productName: "Telepresence"