(from getambassador.io) Updating docs for Telepresence 2.2.

History-rewritten-by: Luke Shumaker <[email protected]>

concepts/devworkflow.md

@@ -1,7 +1,7 @@
 # The changing development workflow
 
-A changing workflow is one of the main challenges for developers adopting Kubernetes. Software development itself isn’t the challenge. Developers can continue to [code using the languages and tools with which they are most productive and comfortable](https://www.getambassador.io/resources/kubernetes-local-dev-toolkit/). That’s the beauty of containerized development.
+A changing workflow is one of the main challenges for developers adopting Kubernetes. Software development itself isn’t the challenge. Developers can continue to [code using the languages and tools with which they are most productive and comfortable](/resources/kubernetes-local-dev-toolkit/). That’s the beauty of containerized development.
 
-However, the cloud-native, Kubernetes-based approach to development means adopting a new development workflow and development environment. Beyond the basics, such as figuring out how to containerize software, [how to run containers in Kubernetes](https://www.getambassador.io/docs/kubernetes/latest/concepts/appdev/), and how to deploy changes into containers, for example, Kubernetes adds complexity before it delivers efficiency. The promise of a “quicker way to develop software” applies at least within the traditional aspects of the inner dev loop, where the single developer codes, builds and tests their software. But both within the inner dev loop and once code is pushed into version control to trigger the outer dev loop, the developer experience changes considerably from what many developers are used to. 
+However, the cloud-native, Kubernetes-based approach to development means adopting a new development workflow and development environment. Beyond the basics, such as figuring out how to containerize software, [how to run containers in Kubernetes](/docs/kubernetes/latest/concepts/appdev/), and how to deploy changes into containers, for example, Kubernetes adds complexity before it delivers efficiency. The promise of a “quicker way to develop software” applies at least within the traditional aspects of the inner dev loop, where the single developer codes, builds and tests their software. But both within the inner dev loop and once code is pushed into version control to trigger the outer dev loop, the developer experience changes considerably from what many developers are used to. 
 
 In this new paradigm, new steps are added to the inner dev loop, and more broadly, the developer begins to share responsibility for the full life cycle of their software. Inevitably this means taking new workflows and tools on board to ensure that the full life cycle continues full speed ahead. 

concepts/faster.md

@@ -1,10 +1,10 @@
 # Making the remote local: Faster feedback, collaboration and debugging
 
-With the goal of achieving [fast, efficient development](https://www.getambassador.io/use-case/local-kubernetes-development/), developers need a set of approaches to bridge the gap between remote Kubernetes clusters and local development, and reduce time to feedback and debugging.
+With the goal of achieving [fast, efficient development](/use-case/local-kubernetes-development/), developers need a set of approaches to bridge the gap between remote Kubernetes clusters and local development, and reduce time to feedback and debugging.
 
 ## How should I set up a Kubernetes development environment?
 
-[Setting up a development environment](https://www.getambassador.io/resources/development-environments-microservices/) for Kubernetes can be much more complex than the set up for traditional web applications. Creating and maintaining a Kubernetes development environment relies on a number of external dependencies, such as databases or authentication. 
+[Setting up a development environment](/resources/development-environments-microservices/) for Kubernetes can be much more complex than the set up for traditional web applications. Creating and maintaining a Kubernetes development environment relies on a number of external dependencies, such as databases or authentication. 
 
 While there are several ways to set up a Kubernetes development environment, most introduce complexities and impediments to speed. The dev environment should be set up to easily code and test in conditions where a service can access the resources it depends on. 
 

doc-links.yml

@@ -42,6 +42,8 @@
               link: /reference/config
             - title: Cluster-side configuration
               link: /reference/cluster-config
+            - title: Using docker for intercepts
+              link: /reference/docker-run
             - title: Environment Variables
               link: /reference/environment
             - title: Intercepts

reference/client.md

@@ -20,6 +20,6 @@ A list of all CLI commands and flags is available by running `telepresence help`
 | `status` | Shows the current connectivity status |
 | `quit` | Quits the local daemon, stopping all intercepts and outbound traffic to the cluster|
 | `list` | Lists the current active intercepts |
-| `intercept` | Intercepts a service, run followed by the service name to be intercepted and what port to proxy to your laptop: `telepresence intercept <service name> --port <TCP port>`. This command can also start a process so you can run a local instance of the service you are intercepting. For example the following will intercept the hello service on port 8000 and start a Python web server: `telepresence intercept hello --port 8000 -- python3 -m http.server 8000` |
+| `intercept` | Intercepts a service, run followed by the service name to be intercepted and what port to proxy to your laptop: `telepresence intercept <service name> --port <TCP port>`. This command can also start a process so you can run a local instance of the service you are intercepting. For example the following will intercept the hello service on port 8000 and start a Python web server: `telepresence intercept hello --port 8000 -- python3 -m http.server 8000`. A special flag `--docker-run` can be used to run the local instance [in a docker container](docker-run). |
 | `leave` | Stops an active intercept: `telepresence leave hello` | 
 | `uninstall` | Uninstalls Telepresence from your cluster, using the `--agent` flag to target the Traffic Agent for a specific workload, the `--all-agents` flag to remove all Traffic Agents from all workloads, or the `--everything` flag to remove all Traffic Agents and the Traffic Manager.

reference/cluster-config.md

@@ -66,3 +66,44 @@ those Secrets.
 Telepresence understands `type: kubernetes.io/tls` Secrets and
 `type: istio.io/key-and-cert` Secrets; as well as `type: Opaque`
 Secrets that it detects to be formatted as one of those types.
+
+# Air Gapped Cluster
+
+If your cluster is air-gapped (e.g. it does not have access to the
+internet and therefore cannot connect to Ambassador Cloud), but you'd like
+to use selective intercepts, this is possible but requires some minimal
+configuration.
+
+## 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. From this page you
+can generate a new license if one doesn't already exist.
+
+To get the Cluster ID of your cluster, ensure your kubeconfig context is using
+the cluster you want to create a license for, then run the following command:
+  ```
+  $ telepresence current-cluster-id
+    Cluster ID: <some UID>
+  ```
+
+## Add License to Cluster
+The page above shows all licenses that have been generated, select the one
+that is associated with your cluster and download that license.
+Then use the following command to generate the license secret:
+  ```
+  $ telepresence license -f <downloadedLicenseFile>
+
+    apiVersion: v1
+    data:
+      hostDomain: <base64 encoded value>
+      license: <other base64 encoded value>
+    kind: Secret
+    metadata:
+      creationTimestamp: null
+      name: systema-license
+      namespace: ambassador
+  ```
+
+From there, you can apply that secret to your cluster (it will go in the ambassador
+namespace).  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).

reference/docker-run.md

@@ -0,0 +1,23 @@
+---
+Description: "How telepresence intercept can run a docker container with configured environment and volume mounts."
+---
+
+# Running intercepts in docker
+
+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`.
+
+`telepresence intercept [service] --port [port] --docker-run -- [arguments]`
+
+This command will intercept a service and start `docker run` in the foreground. The intercept ends when the run ends.
+
+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`).
+
+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
+
+The flags that telepresence will pass (invisibly) to `docker run` are:
+
+- `--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.