From 7678b8ec85dee1951a39e7c1e26cea9aa7d9b5a9 Mon Sep 17 00:00:00 2001 From: mattmcclure-dw <73489204+mattmcclure-dw@users.noreply.github.com> Date: Mon, 26 Apr 2021 10:57:32 -0400 Subject: [PATCH] (from getambassador.io) initial --- reference/cluster-config.md | 31 ++++++++++++++++++------------- reference/docker-run.md | 32 ++++++++++++++++++++------------ 2 files changed, 38 insertions(+), 25 deletions(-) diff --git a/reference/cluster-config.md b/reference/cluster-config.md index 89b53beef5..39297b9988 100644 --- a/reference/cluster-config.md +++ b/reference/cluster-config.md @@ -78,31 +78,36 @@ license configuration is required to use selective intercepts. ### Create a License -First, go to [Ambassador Cloud](https://auth.datawire.io/redirects/settings/teams) and -select *Licenses* for the team you want to create the license for. You -can generate a new license if one doesn't already exist by clicking *Generate New License*. +1. Go to [the teams setting page in Ambassador Cloud](https://auth.datawire.io/redirects/settings/teams) and +select *Licenses* for the team you want to create the license for. -You will be prompted for the Cluster ID of your cluster. To find it, ensure your -kubeconfig context is using the cluster you want to create a license for, then -run this command: +2. Generate a new license (if one doesn't already exist) by clicking *Generate New License*. + +3. You will be prompted for your Cluster ID. Ensure your +kubeconfig context is using the cluster you want to create a license for then +run this command to generate the Cluster ID: ``` $ telepresence current-cluster-id + Cluster ID: ``` +4. Click *Generate API Key* to finish generating the license. + ### Add License to Cluster -On the licenses page, download the license file associated with your cluster. -Then, use the following command to generate the license secret: +1. On the licenses page, download the license file associated with your cluster. - ``` - $ telepresence license -f +2. Use this command to generate a Kubernetes Secret config using the license file: + ``` + $ telepresence license -f + apiVersion: v1 data: - hostDomain: - license: + hostDomain: + license: kind: Secret metadata: creationTimestamp: null @@ -110,6 +115,6 @@ Then, use the following command to generate the license secret: namespace: ambassador ``` -Save the output as a YAML file and apply the Secret to your +3. Save the output as a YAML file and apply it to your cluster with `kubectl`. Once applied, you will be able to use selective intercepts with the `--preview-url=false` flag (since use of preview URLs requires a connection to Ambassador Cloud). diff --git a/reference/docker-run.md b/reference/docker-run.md index 0e490ad2f5..15c4f539a7 100644 --- a/reference/docker-run.md +++ b/reference/docker-run.md @@ -1,23 +1,31 @@ --- -Description: "How telepresence intercept can run a Docker container with configured environment and volume mounts." +Description: "How a Telepresence intercept can run a Docker container with configured environment and volume mounts." --- # Using Docker for intercepts -The Telepresence intercept command can automatically run a Docker container which has been configured with the environment and volume mounts of the intercepted service. This is done using the option `--docker-run`. +If you want your intercept to go to a Docker container on your laptop, use the `--docker-run` option. It creates the intercept, runs your container in the foreground, then automatically ends the intercept when the container exits. -`telepresence intercept [service] --port [port] --docker-run -- [arguments]` +`telepresence intercept --port --docker-run -- ` -This command will intercept a service and start `docker run` in the foreground. The intercept ends when the run ends. +The `--` separates flags intended for `telepresence intercept` from flags intended for `docker run`. -Telepresence will automatically pass some relevant flags to Docker in order to connect the container with the intercept. Those flags are combined with the arguments given after `--` on the command line (the `--` separates flags intended for `telepresence intercept` from flags intended for `docker run`). +## Example -The `--port` flag can specify an additional port when `--docker-run` is used so that the local and container port can be different. This is done using `--port [local port]:[container port]`. The container port will default to the local port when using the `--port [port]` syntax +Imagine you are working on a new version of a your frontend service. It is running in your cluster as a Deployment called `frontend-v1`. You use Docker on your laptop to build an improved version of the container called `frontend-v2`. To test it out, use this command to run the new container on your laptop and start an intercept of the cluster service to your local container. -The flags that telepresence will pass (invisibly) to `docker run` are: +`telepresence intercept frontend-v1 --port 8000 --docker-run -- frontend-v2` -- `--dns-search tel2-search` Enables single label name lookups in intercepted namespaces. -- `--env-file [file]` Loads the intercepted environment. -- `--name intercept-{intercept name}-{intercept port}` Names the Docker container. This flag is omitted if explicitly given on the command line. -- `-p [port:container-port]` The local port for the intercept and the container port. -- `-v [local mount dir:docker mount dir]` Volume mount specification. See CLI help for `--mount` and `--docker-mount` flags for more info. +## Ports + +The `--port` flag can specify an additional port when `--docker-run` is used so that the local and container port can be different. This is done using `--port :`. The container port will default to the local port when using the `--port ` syntax. + +## Flags + +Telepresence will automatically pass some relevant flags to Docker in order to connect the container with the intercept. Those flags are combined with the arguments given after `--` on the command line. + +- `--dns-search tel2-search` Enables single label name lookups in intercepted namespaces +- `--env-file ` Loads the intercepted environment +- `--name intercept--` Names the Docker container, this flag is omitted if explicitly given on the command line +- `-p ` The local port for the intercept and the container port +- `-v ` Volume mount specification, see CLI help for `--mount` and `--docker-mount` flags for more info