Merge commit '4e65bf2541477e412af8e738e8c26cc210831133' into lukeshu/…

…rel-2.3.3

Signed-off-by: Luke Shumaker <lukeshu@datawire.io>

doc-links.yml

@@ -6,6 +6,8 @@
        link: install/
      - title: Upgrade
        link: install/upgrade/
+     - title: Install Traffic Manager with Helm
+       link: install/helm/
      - title: Migrate from legacy Telepresence
        link: install/migrate-from-legacy/
  - title: Core concepts

faqs.md

@@ -73,7 +73,7 @@ Telepresence will discover/prompt during first use for this info and make its be
 
  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 containers that are deployed when connecting with Telepresence.
+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?**
 
@@ -83,13 +83,13 @@ On Fedora, Telepresence also creates a virtual network device (a TUN network) fo
 
 ** 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.
 

install/helm.md

@@ -0,0 +1,65 @@
+# Install with Helm
+
+[Helm](https://helm.sh) is a package manager for Kubernetes that automates the release and management of software on Kubernetes. The Telepresence Traffic Manager can be installed via a Helm chart with a few simple steps.
+
+## Before you begin
+
+The Telepresence Helm chart is hosted by Ambassador Labs and published at `https://app.getambassador.io`.
+
+Start by adding this repo to your Helm client with the following command:
+
+```
+helm repo add datawire  https://app.getambassador.io
+helm repo update
+```
+
+## Install with Helm
+
+When you run the Helm chart, it installs all the components required for the Telepresence Traffic Manager. 
+
+1. If you are installing the Telepresence Traffic Manager **for the first time on your cluster**, create the `ambassador` namespace in your cluster:
+
+   ```
+   kubectl create namespace ambassador
+   ```
+
+2. Install the Telepresenc Traffic Manager with the following command:
+
+   ```
+   helm install traffic-manager --namespace ambassador datawire/telepresence
+   ```
+
+For more details on what the Helm chart installs and what can be configured, take a look at the Helm chart [README](https://github.com/telepresenceio/telepresence/tree/release/v2/charts/telepresence).
+
+### Install into custom namespace
+
+The Helm chart supports being installed into any namespace, not necessarily `ambassador`. Simply pass a different `namespace` argument to `helm install`.
+For example, if you wanted to deploy the traffic manager to the `staging` namespace:
+
+```bash
+helm install traffic-manager --namespace custom-namespace datawire/telepresence
+```
+
+Note that users of telepresence will need to configure their kubeconfig to find this installation of the traffic manager:
+
+```yaml
+apiVersion: v1
+clusters:
+- cluster:
+    server: https://127.0.0.1
+    extensions:
+    - name: telepresence.io
+      extension:
+        manager:
+          namespace: custom-namespace
+  name: example-cluster
+```
+
+See [the kubeconfig documentation](../reference/config#manager) for more information.
+
+## Install RBAC only
+
+Telepresence Traffic Manager does require some [RBAC](../../refrence/rbac/) for the traffic-manager deployment itself, as well as for users.
+To make it easier for operators to introspect / manage RBAC separately, you can use `rbac.only=true` to
+only create the rbac-related objects.
+Additionally, you can use `clientRbac.create=true` and `managerRbac.create=true` to toggle which subset(s) of RBAC objects you wish to create.

install/migrate-from-legacy.md

@@ -76,7 +76,7 @@ by [creating an issue](https://github.com/telepresenceio/telepresence/issues) an
 
 ## Telepresence changes
 
-Telepresence installs a Traffic Manager in the cluster and Traffic Agents alongside workloads when performing intercepts (including
+Telepresence installs a traffic-manager in the cluster and Traffic Agents alongside workloads when performing intercepts (including
 with `--swap-deployment`) and leaves them.  If you use `--swap-deployment`, the intercept will be left once the process
 dies, but the agent will remain. There's no harm in leaving the agent running alongside your service, but when you
 want to remove them from the cluster, the following Telepresence command will help:
@@ -95,5 +95,5 @@ Flags:
   -n, --namespace string   If present, the namespace scope for this CLI request
 ```
 
-Since the new architecture deploys a Traffic Manager into the Ambassador namespace, please take a look at
+Since the new architecture deploys a traffic-manager into the Ambassador namespace, please take a look at
 our [rbac guide](../../reference/rbac) if you run into any issues with permissions while upgrading to Telepresence.

reference/config.md

@@ -50,7 +50,7 @@ These are the valid fields for the `logLevels` key:
 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.
 
 ### Values
-The current per-cluster configuration supports `dns` and `alsoProxy` keys.
+The current per-cluster configuration supports `dns`, `alsoProxy`, and `manager` keys.
 To add configuration, simply add a `telepresence.io` entry to the cluster in your kubeconfig like so:
 
 ```
@@ -63,6 +63,7 @@ clusters:
       extension:
         dns:
         also-proxy:
+        manager:
   name: example-cluster
 ```
 #### DNS
@@ -110,3 +111,22 @@ clusters:
         - 1.2.3.4/32
   name: example-cluster
 ```
+
+#### Manager
+
+The `manager` key contains configuration for finding the `traffic-manager` that telepresence will connect to. It supports one key, `namespace`, indicating the namespace where the traffic manager is to be found
+
+Here is an example kubeconfig that will instruct telepresence to connect to a manager in namespace `staging`:
+
+```yaml
+apiVersion: v1
+clusters:
+- cluster:
+    server: https://127.0.0.1
+    extensions:
+    - name: telepresence.io
+      extension:
+        manager:
+          namespace: staging
+  name: example-cluster
+```

reference/intercepts.md

@@ -125,3 +125,25 @@ intercepted
     Volume Mount Point: /var/folders/cp/2r22shfd50d9ymgrw14fd23r0000gp/T/telfs-921196036
     Intercepting      : all TCP connections
 ```
+
+## Port-forwarding an intercepted container's sidecars
+
+Sidecars are containers that sit in the same pod as an application container; they usually provide auxiliary functionality to an application, and can usually be reached at `localhost:${SIDECAR_PORT}`.
+For example, a common use case for a sidecar is to proxy requests to a database -- your application would connect to `localhost:${SIDECAR_PORT}`, and the sidecar would then connect to the database, perhaps augmenting the connection with TLS or authentication.
+
+When intercepting a container that uses sidecars, you might want those sidecars' ports to be available to your local application at `localhost:${SIDECAR_PORT}`, exactly as they would be if running in-cluster.
+Telepresence's `--to-pod ${PORT}` flag implements this behavior, adding port-forwards for the port given.
+
+```
+$ telepresence intercept <base name of intercept> --port=<local TCP port>:<servicePortIdentifier> --to-pod=<sidecarPort>
+Using Deployment <name of deployment>
+intercepted
+    Intercept name         : <full name of intercept>
+    State                  : ACTIVE
+    Workload kind          : Deployment
+    Destination            : 127.0.0.1:<local TCP port>
+    Service Port Identifier: <servicePortIdentifier>
+    Intercepting           : all TCP connections
+```
+
+If there are multiple ports that you need forwarded, simply repeat the flag (`--to-pod=<sidecarPort0> --to-pod=<sidecarPort1>`).

reference/rbac.md

@@ -2,7 +2,7 @@ import Alert from '@material-ui/lab/Alert';
 
 # Telepresence RBAC
 The intention of this document is to provide a template for securing and limiting the permissions of Telepresence.
-This documentation will not cover the full extent of permissions necessary to administrate Telepresence components in a cluster.  [Telepresence administration](/products/telepresence/) requires permissions for creating Namespaces, ServiceAccounts, ClusterRoles, ClusterRoleBindings, Secrets, Services, MutatingWebhookConfiguration, and for creating the `traffic-manager` [deployment](../architecture/#traffic-manager) which is typically done by a full cluster administrator.
+This documentation covers the full extent of permissions necessary to administrate Telepresence components in a cluster.
 
 There are two general categories for cluster permissions with respect to Telepresence.  There are RBAC settings for a User and for an Administrator described above.  The User is expected to only have the minimum cluster permissions necessary to create a Telepresence [intercept](../../howtos/intercepts/), and otherwise be unable to affect Kubernetes resources.
 
@@ -39,6 +39,14 @@ The Service Account token will be obtained by the cluster administrator after th
 
 After creating `config.yaml` in your current directory, export the file's location to KUBECONFIG by running `export KUBECONFIG=$(pwd)/config.yaml`.  You should then be able to switch to this context by running `kubectl config use-context my-context`.
 
+## Administrating Telepresence
+
+[Telepresence administration](/products/telepresence/) requires permissions for creating `Namespaces`, `ServiceAccounts`, `ClusterRoles`, `ClusterRoleBindings`, `Secrets`, `Services`, `MutatingWebhookConfiguration`, and for creating the `traffic-manager` [deployment](../architecture/#traffic-manager) which is typically done by a full cluster administrator.
+
+There are two ways to install the traffic-manager: Using `telepresence connect` and installing the [helm chart](../../install/helm/).
+
+By using `telepresence connect`, Telepresence will use your kubeconfig to create the objects mentioned above in the cluster if they don't already exist.  If you want the most introspection into what is being installed, we recommend using the helm chart to install the traffic-manager.
+
 ## Cluster-wide telepresence user access
 
 To allow users to make intercepts across all namespaces, but with more limited `kubectl` permissions, the following `ServiceAccount`, `ClusterRole`, and `ClusterRoleBinding` will allow full `telepresence intercept` functionality.

releaseNotes.yml

@@ -30,6 +30,33 @@ docDescription: >-
 changelog: https://github.com/telepresenceio/telepresence/blob/$branch$/CHANGELOG.md
 
 items:
+  - version: 2.3.3
+    date: 'TBD'
+    notes:
+      # Headliners
+      - type: feature
+        title: Traffic Manager Helm Chart
+        body: >-
+          We now support installing the Traffic Manager via Helm.
+          This will make it easy for operators to install and configure the
+          server-side components of Telepresence separately from the CLI
+          (which in turn allows for better separation of permissions).
+        image: ./telepresence-2.3.3-helm.png
+        docs: install/helm/
+      - type: feature
+        title: Traffic-manager in custom namespace
+        body: >-
+          As the traffic manager can now be installed in any namespace via helm,
+          telepresence can now be configured to look for the traffic manager in
+          a namespace other than <code>ambassador</code>. This can be configured
+          on a per-cluster basis.
+        image: ./telepresence-2.3.3-namespace-config.png
+        docs: reference/config
+      - title: intercept --to-pod
+        body: "telepresence intercept now supports a --to-pod flag that can be used to port-forward sidecars' ports from an intercepted pod"
+        image: ./telepresence-2.3.3-to-pod.png
+        docs: reference/intercept
+        type: feature
   - version: 2.3.2
     date: '2021-06-18'
     notes:
@@ -66,9 +93,9 @@ items:
 
       # RBAC changes
       - type: change
-        title: Traffic-manager needs new RBAC permissions
+        title: Traffic Manager needs new RBAC permissions
         body: >-
-          The traffic-manager requires <a href="reference/rbac">RBAC
+          The Traffic Manager requires <a href="reference/rbac">RBAC
           permissions</a> to list Nodes, Pods, and to create a dummy
           Service in the manager's namespace.
         docs: reference/routing/#subnets
@@ -78,7 +105,7 @@ items:
           The on-laptop client no longer requires <a
           href="reference/rbac">RBAC permissions</a> to list the Nodes
           in the cluster or to create Services, as that functionality
-          has been moved to the traffic-manager.
+          has been moved to the Traffic Manager.
 
       # Bugfixes
       - type: bugfix
@@ -133,7 +160,6 @@ items:
           Now it can be counted on that by the time the command has
           returned that all of the side-effects on the laptop have
           been cleaned up.
-
   - version: 2.3.1
     date: '2021-06-14'
     notes:

versions.yml

@@ -1,3 +1,4 @@
 version: "2.3.2"
 docsVersion: "2.3"
 branch: release/v2
+productName: "Telepresence"