Skip to content

Commit

Permalink
Merge branch 'release/v2.4' into donaldyung/from-telepresence.io-2021…
Browse files Browse the repository at this point in the history 
…-09-27/release/v2.4
  • Loading branch information
Donny Yung committed Sep 27, 2021
2 parents 2127810 + a7a120d commit b970065
Show file tree
Hide file tree
Showing 26 changed files with 683 additions and 562 deletions.
4 changes: 2 additions & 2 deletions concepts/intercepts.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -158,9 +158,9 @@ while sharing the rest of the development environment.
Need a browser extension to modify or remove an HTTP-request-headers?
<a class="btn btn-black" href="https://chrome.google.com/webstore/detail/modheader/idgpnmonknjnojddfkpgkljpfnnfcklj">Chrome</a>
<a class="btn-sm-bluedark" href="https://chrome.google.com/webstore/detail/modheader/idgpnmonknjnojddfkpgkljpfnnfcklj">Chrome</a>
{' '}
<a class="btn btn-black" href="https://addons.mozilla.org/firefox/addon/modheader-firefox/">Firefox</a>
<a class="btn-sm-bluedark" href="https://addons.mozilla.org/firefox/addon/modheader-firefox/">Firefox</a>
</Alert>
Expand Down
24 changes: 12 additions & 12 deletions faqs.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ description: "Learn how Telepresence helps with fast development and debugging i

** Why Telepresence?**

Modern microservices-based applications that are deployed into Kubernetes often consist of tens or hundreds of services. The resource constraints and number of these services means that it is often difficult to impossible to run all of this on a local development machine, which makes fast development and debugging very challenging. The fast [inner development loop](../concepts/devloop/) from previous software projects is often a distant memory for cloud developers.
Modern microservices-based applications that are deployed into Kubernetes often consist of tens or hundreds of services. The resource constraints and number of these services means that it is often difficult to impossible to run all of this on a local development machine, which makes fast development and debugging very challenging. The fast [inner development loop](../concepts/devloop/) from previous software projects is often a distant memory for cloud developers.

Telepresence enables you to connect your local development machine seamlessly to the cluster via a two way proxying mechanism. This enables you to code locally and run the majority of your services within a remote Kubernetes cluster -- which in the cloud means you have access to effectively unlimited resources.

Expand All @@ -22,7 +22,7 @@ Telepresence currently works natively on macOS, Linux, and WSL 2. Starting with

** What protocols can be intercepted by Telepresence?**

All HTTP/1.1 and HTTP/2 protocols can be intercepted. This includes:
All HTTP/1.1 and HTTP/2 protocols can be intercepted. This includes:

- REST
- JSON/XML over HTTP
Expand All @@ -35,7 +35,7 @@ If you need another protocol supported, please [drop us a line](https://www.geta

Yes, you can either set the pod's environment variables on your machine or write the variables to a file to use with Docker or another build process. Please see [the environment variable reference doc](../reference/environment) for more information.

** When using Telepresence to intercept a pod, can the associated pod volume mounts also be mounted my local machine?**
** When using Telepresence to intercept a pod, can the associated pod volume mounts also be mounted by my local machine?**

Yes, please see [the volume mounts reference doc](../reference/volume/) for more information.

Expand All @@ -53,11 +53,11 @@ You can connect to databases or middleware running in the cluster, such as MySQL

** When connected to a Kubernetes cluster via Telepresence, can I access cloud-based services and data stores via their DNS name?**

You can connect to cloud-based data stores and services that are directly addressable within the cluster (e.g. when using an [ExternalName](https://kubernetes.io/docs/concepts/services-networking/service/#externalname) Service type), such as AWS RDS, Google pub-sub, or Azure SQL Database.
You can connect to cloud-based data stores and services that are directly addressable within the cluster (e.g. when using an [ExternalName](https://kubernetes.io/docs/concepts/services-networking/service/#externalname) Service type), such as AWS RDS, Google pub-sub, or Azure SQL Database.

** What types of ingress does Telepresence support for the preview URL functionality?**

The preview URL functionality should work with most ingress configurations, including straightforward load balancer setups.
The preview URL functionality should work with most ingress configurations, including straightforward load balancer setups.

Telepresence will discover/prompt during first use for this info and make its best guess at figuring this out and ask you to confirm or update this.

Expand All @@ -71,31 +71,31 @@ Telepresence will discover/prompt during first use for this info and make its be

** Will Telepresence be able to intercept workloads running on a private cluster or cluster running within a virtual private cloud (VPC)?**

Yes. The cluster has to have outbound access to the internet for the preview URLs to function correctly, but it doesn’t need to have a publicly accessible IP address.
Yes. The cluster has to have outbound access to the internet for the preview URLs to function correctly, but it doesn’t need to have a publicly accessible IP address.

The cluster must also have access to an external registry in order to be able to download the traffic-manager and traffic-agent images that are deployed when connecting with Telepresence.

** Why does running Telepresence require sudo access for the local daemon?**

The local daemon needs sudo to create iptable mappings. Telepresence uses this to create outbound access from the laptop to the cluster.
The local daemon needs sudo to create iptable mappings. Telepresence uses this to create outbound access from the laptop to the cluster.

On Fedora, Telepresence also creates a virtual network device (a TUN network) for DNS routing. That also requires root access.

** What components get installed in the cluster when running Telepresence?**

A single `traffic-manager` service is deployed in the `ambassador` namespace within your cluster, and this manages resilient intercepts and connections between your local machine and the cluster.
A single `traffic-manager` service is deployed in the `ambassador` namespace within your cluster, and this manages resilient intercepts and connections between your local machine and the cluster.

A Traffic Agent container is injected per pod that is being intercepted. The first time a workload is intercepted all pods associated with this workload will be restarted with the Traffic Agent automatically injected.

** How can I remove all of the Telepresence components installed within my cluster?**

You can run the command `telepresence uninstall --everything` to remove the `traffic-manager` service installed in the cluster and `traffic-agent` containers injected into each pod being intercepted.
You can run the command `telepresence uninstall --everything` to remove the `traffic-manager` service installed in the cluster and `traffic-agent` containers injected into each pod being intercepted.

Running this command will also stop the local daemon running.

** What language is Telepresence written in?**

All components of the Telepresence application and cluster components are written using Go.
All components of the Telepresence application and cluster components are written using Go.

** How does Telepresence connect and tunnel into the Kubernetes cluster?**

Expand All @@ -117,8 +117,8 @@ More authentication mechanisms and identity provider support will be added soon.

** Is Telepresence open source?**

Yes it is! You can find its source code on [GitHub.](https://github.com/telepresenceio/telepresence)
Yes it is! You can find its source code on [GitHub](https://github.com/telepresenceio/telepresence).

** How do I share my feedback on Telepresence?**

Your feedback is always appreciated and helps us build a product that provides as much value as possible for our community. You can chat with us directly on our [feedback page](https://www.getambassador.io/feedback/), or you can [join our Slack channel](https://a8r.io/Slack) to share your thoughts.
Your feedback is always appreciated and helps us build a product that provides as much value as possible for our community. You can chat with us directly on our [feedback page](https://www.getambassador.io/feedback/), or you can [join our Slack channel](https://a8r.io/Slack) to share your thoughts.
59 changes: 56 additions & 3 deletions howtos/intercepts.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ description: "Start using Telepresence in your own environment. Follow these ste
---

import Alert from '@material-ui/lab/Alert';
import QSTabs from '../quick-start/qs-tabs'
import Platform from '@src/components/Platform';
import QSCards from '../quick-start/qs-cards'

# Intercept a service in your own environment
Expand All @@ -24,11 +24,12 @@ import QSCards from '../quick-start/qs-cards'
<Alert severity="info">

For a detailed walk-though on creating intercepts using our sample
app, follow the [quick start guide](../../quick-start/qs-node/).
app, follow the [quick start guide](../../quick-start/demo-node/).

</Alert>

## Prerequisites

You’ll need [`kubectl`](https://kubernetes.io/docs/tasks/tools/install-kubectl/) or `oc` installed
and set up
([Linux](https://kubernetes.io/docs/tasks/tools/install-kubectl-linux/#verify-kubectl-configuration) /
Expand All @@ -47,7 +48,59 @@ copy of that service on your laptop.

## 1. Install the Telepresence CLI {#1-install}

<QSTabs/>
<Platform.TabGroup>
<Platform.MacOSTab>

```shell
# Install via brew:
brew install datawire/blackbird/telepresence

# OR install manually:
# 1. Download the latest binary (~60 MB):
sudo curl -fL https://app.getambassador.io/download/tel2/darwin/amd64/$dlVersion$/telepresence -o /usr/local/bin/telepresence

# 2. Make the binary executable:
sudo chmod a+x /usr/local/bin/telepresence
```

</Platform.MacOSTab>
<Platform.GNULinuxTab>

```shell
# 1. Download the latest binary (~50 MB):
sudo curl -fL https://app.getambassador.io/download/tel2/linux/amd64/$dlVersion$/telepresence -o /usr/local/bin/telepresence

# 2. Make the binary executable:
sudo chmod a+x /usr/local/bin/telepresence
```

</Platform.GNULinuxTab>
<Platform.WindowsTab>

```powershell
# Windows is in Developer Preview, here is how you can install it:
# Make sure you run the following from Powershell as Administrator
# 1. Download the latest windows zip containing telepresence.exe and its dependencies (~50 MB):
curl -fL https://app.getambassador.io/download/tel2/windows/amd64/$dlVersion$/telepresence.zip -o telepresence.zip
# 2. Unzip the zip file to a suitable directory + cleanup zip
Expand-Archive -Path telepresence.zip
Remove-Item 'telepresence.zip'
cd telepresence
# 3. Run the install-telepresence.ps1 to install telepresence's dependencies. It will install telepresence to
# C:\telepresence by default, but you can specify a custom path $path with -Path $path
Set-ExecutionPolicy Bypass -Scope Process
.\install-telepresence.ps1
# 4. Remove the unzipped directory
cd ..
Remove-Item telepresence
# 5. Close your current Powershell and open a new one. Telepresence should now be usable as telepresence.exe
```

</Platform.WindowsTab>
</Platform.TabGroup>

## 2. Test Telepresence {#2-test}

Expand Down
17 changes: 9 additions & 8 deletions howtos/outbound.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ import Alert from '@material-ui/lab/Alert';

While preview URLs are a powerful feature, there are other options to use Telepresence for proxying traffic between your laptop and the cluster.

<Alert severity="info"> We'll assume below that you have the <a href="../../quick-start/qs-node/">quick start</a> sample web app running in your cluster so that we can test accessing the <code>verylargejavaservice</code> service. That service can be substituted however for any service you are running.</Alert>
<Alert severity="info"> We'll assume below that you have the <a href="../../quick-start/demo-node/">quick start</a> sample web app running in your cluster so that we can test accessing the <code>web-app</code> service. That service can be substituted however for any service you are running.</Alert>

## Proxying outbound traffic

Expand All @@ -20,7 +20,7 @@ Connecting to the cluster starts the background daemon on your machine and insta

```
$ telepresence connect
Launching Telepresence Daemon v2.1.4 (api v3)
Launching Telepresence Daemon v2.3.7 (api v3)
Need root privileges to run "/usr/local/bin/telepresence daemon-foreground /home/<user>/.cache/telepresence/logs '' ''"
[sudo] password:
Connecting to traffic manager...
Expand All @@ -32,11 +32,11 @@ Connecting to the cluster starts the background daemon on your machine and insta
```
$ telepresence status
Root Daemon: Running
Version : v2.1.4 (api 3)
Version : v2.3.7 (api 3)
Primary DNS : ""
Fallback DNS: ""
User Daemon: Running
Version : v2.1.4 (api 3)
Version : v2.3.7 (api 3)
Ambassador Cloud : Logged out
Status : Connected
Kubernetes server : https://<cluster public IP>
Expand All @@ -45,14 +45,15 @@ Connecting to the cluster starts the background daemon on your machine and insta
Intercepts : 0 total
```

1. Now try to access your service by name with `curl verylargejavaservice.default:8080`. Telepresence will route the request to the cluster, as if your laptop is actually running in the cluster.
1. Now try to access your service by name with `curl web-app.emojivoto:80`. Telepresence will route the request to the cluster, as if your laptop is actually running in the cluster.

```
$ curl verylargejavaservice.default:8080
<!DOCTYPE HTML>
$ curl web-app.emojivoto:80
<!DOCTYPE html>
<html>
<head>
<title>Welcome to the EdgyCorp WebApp</title>
<meta charset="UTF-8">
<title>Emoji Vote</title>
...
```

Expand Down
6 changes: 3 additions & 3 deletions howtos/preview-urls.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ Preview URLs are protected behind authentication via Ambassador Cloud, ensuring
* You will need a service running in your cluster that you would like to intercept.

<Alert severity="info">
Need a sample app to try with preview URLs? Check out the <a href="../../quick-start/qs-node/">quick start</a>. It has a multi-service app to install in your cluster with instructions to create a preview URL for that app.
Need a sample app to try with preview URLs? Check out the <a href="../../quick-start/demo-node/">quick start</a>. It has a multi-service app to install in your cluster with instructions to create a preview URL for that app.
</Alert>

## Creating a preview URL
Expand Down Expand Up @@ -123,11 +123,11 @@ Need a sample app to try with preview URLs? Check out the <a href="../../quick-
7. Share with a teammate.

You can collaborate with teammates by sending your preview URL to
them. They will be asked to log in to Ambassador Cloud if they are
them. They will be asked to log in to Ambassador Cloud if they are
not already. Upon login they must select the same identity
provider and org as you are using; that is how they are authorized
to access the preview URL (see the [list of supported identity
providers](../../faqs/#idps)). When they visit the preview URL,
providers](../../faqs/#idps)). When they visit the preview URL,
they will see the intercepted service running on your laptop.

<Alert severity="success">
Expand Down
99 changes: 93 additions & 6 deletions install/index.md
View file
Original file line number Diff line number Diff line change
@@ -1,12 +1,62 @@
import QSTabs from '../quick-start/qs-tabs'
import OldVersionTabs from './old-version-tabs'
import NightlyVersionTabs from './nightly-version-tabs'
import Platform from '@src/components/Platform';

# Install

Install Telepresence by running the commands below for your OS.

<QSTabs/>
<Platform.TabGroup>
<Platform.MacOSTab>

```shell
# Install via brew:
brew install datawire/blackbird/telepresence

# OR install manually:
# 1. Download the latest binary (~60 MB):
sudo curl -fL https://app.getambassador.io/download/tel2/darwin/amd64/$dlVersion$/telepresence -o /usr/local/bin/telepresence

# 2. Make the binary executable:
sudo chmod a+x /usr/local/bin/telepresence
```

</Platform.MacOSTab>
<Platform.GNULinuxTab>

```shell
# 1. Download the latest binary (~50 MB):
sudo curl -fL https://app.getambassador.io/download/tel2/linux/amd64/$dlVersion$/telepresence -o /usr/local/bin/telepresence

# 2. Make the binary executable:
sudo chmod a+x /usr/local/bin/telepresence
```

</Platform.GNULinuxTab>
<Platform.WindowsTab>

```powershell
# Windows is in Developer Preview, here is how you can install it:
# Make sure you run the following from Powershell as Administrator
# 1. Download the latest windows zip containing telepresence.exe and its dependencies (~50 MB):
curl -fL https://app.getambassador.io/download/tel2/windows/amd64/$dlVersion$/telepresence.zip -o telepresence.zip
# 2. Unzip the zip file to a suitable directory + cleanup zip
Expand-Archive -Path telepresence.zip
Remove-Item 'telepresence.zip'
cd telepresence
# 3. Run the install-telepresence.ps1 to install telepresence's dependencies. It will install telepresence to
# C:\telepresence by default, but you can specify a custom path $path with -Path $path
Set-ExecutionPolicy Bypass -Scope Process
.\install-telepresence.ps1
# 4. Remove the unzipped directory
cd ..
Remove-Item telepresence
# 5. Close your current Powershell and open a new one. Telepresence should now be usable as telepresence.exe
```

</Platform.WindowsTab>
</Platform.TabGroup>

## <img class="os-logo" src="../images/logo.png"/> What's Next?

Expand All @@ -27,10 +77,47 @@ version of Telepresence is released.

Use these URLs to download the most recent nightly build.

<NightlyVersionTabs/>
<Platform.TabGroup>
<Platform.MacOSTab>

```
https://app.getambassador.io/download/tel2/darwin/amd64/nightly/telepresence
```

</Platform.MacOSTab>
<Platform.GNULinuxTab>

```
https://app.getambassador.io/download/tel2/linux/amd64/nightly/telepresence
```

</Platform.GNULinuxTab>
</Platform.TabGroup>

## Installing older versions of Telepresence

Use these URLs to download an older version for your OS (including older nightly builds), replacing `x.y.z` with the versions you want.

<OldVersionTabs/>
<Platform.TabGroup>
<Platform.MacOSTab>

```
https://app.getambassador.io/download/tel2/darwin/amd64/x.y.z/telepresence
```

</Platform.MacOSTab>
<Platform.GNULinuxTab>

```
https://app.getambassador.io/download/tel2/linux/amd64/x.y.z/telepresence
```

</Platform.GNULinuxTab>
<Platform.WindowsTab>

```
https://app.getambassador.io/download/tel2/windows/amd64/x.y.z/telepresence
```

</Platform.WindowsTab>
</Platform.TabGroup>
Loading

0 comments on commit b970065

Please sign in to comment.