(from getambassador.io) Merge pull request #592 from datawire/donnyyu…

…ng/add-replica-sets

Docs for supporting replica sets in telepresence

faqs.md

@@ -12,7 +12,7 @@ Telepresence enables you to connect your local development machine seamlessly to
 
 Ultimately, this empowers you to develop services locally and still test integrations with dependent services or data stores running in the remote cluster. 
 
-You can “intercept” any requests made to a target Kubernetes deployment, and code and debug your associated service locally using your favourite local IDE and in-process debugger. You can test your integrations by making requests against the remote cluster’s ingress and watching how the resulting internal traffic is handled by your service running locally.
+You can “intercept” any requests made to a target Kubernetes workload, and code and debug your associated service locally using your favourite local IDE and in-process debugger. You can test your integrations by making requests against the remote cluster’s ingress and watching how the resulting internal traffic is handled by your service running locally.
 
 By using the preview URL functionality you can share access with additional developers or stakeholders to the application via an entry point associated with your intercept and locally developed service. You can make changes that are visible in near real-time to all of the participants authenticated and viewing the preview URL. All other viewers of the application entrypoint will not see the results of your changes.
 
@@ -57,7 +57,7 @@ You can connect to databases or middleware running in the cluster, such as MySQL
 
 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. 
 
-** Will Telepresence be able to intercept deployments running on a private cluster or cluster running within a virtual private cloud (VPC)?**
+** 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. 
 
@@ -73,7 +73,7 @@ On Fedora, Telepresence also creates a virtual network device (a TUN network) fo
 
  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 deployment is intercepted all pods associated with this deployment will be restarted with the Traffic Agent automatically injected.
+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?**
 

howtos/intercepts.md

@@ -125,10 +125,11 @@ In this section, we will go through the steps required for you to intercept all
    ```
    $ telepresence intercept example-service --port 8080:http --env-file ~/example-service-intercept.env
 
-     Using deployment example-service
+     Using Deployment example-service
      intercepted
          Intercept name: example-service
          State         : ACTIVE
+         Workload kind : Deployment
          Destination   : 127.0.0.1:8080
          Intercepting  : all TCP connections
    ```
@@ -216,10 +217,11 @@ be routed to your cluster as usual.
 
             [default: ambassador.ambassador]: dev-environment.edgestack.me
 
-     Using deployment example-service
+     Using Deployment example-service
      intercepted
          Intercept name   : example-service
          State            : ACTIVE
+         Workload kind    : Deployment
          Destination      : 127.0.0.1:8080
          Service Port Name: http
          Intercepting     : HTTP requests that match all of:

howtos/outbound.md

@@ -12,7 +12,7 @@ While preview URLs are a powerful feature, there are other options to use Telepr
 
 ## Proxying Outbound Traffic
 
-Connecting to the cluster instead of running an intercept will allow you to access cluster deployments as if your laptop was another pod in the cluster. You will be able to access other Kubernetes services using `<service name>.<namespace>`, for example by curling a service from your terminal. A service running on your laptop will also be able to interact with other services on the cluster by name.
+Connecting to the cluster instead of running an intercept will allow you to access cluster workloads as if your laptop was another pod in the cluster. You will be able to access other Kubernetes services using `<service name>.<namespace>`, for example by curling a service from your terminal. A service running on your laptop will also be able to interact with other services on the cluster by name.
 
 Connecting to the cluster starts the background daemon on your machine and installs the [Traffic Manager pod](../../reference/architecture/) into the cluster of your current `kubectl` context.  The Traffic Manager handles the service proxying.
 

quick-start/qs-go.md

@@ -210,10 +210,11 @@ Next, we’ll create an intercept. An intercept is a rule that tells Telepresenc
   ```
   $ telepresence intercept dataprocessingservice --port 3000
 
-    Using deployment dataprocessingservice
+    Using Deployment dataprocessingservice
     intercepted
         Intercept name: dataprocessingservice
         State         : ACTIVE
+        Workload kind : Deployment
         Destination   : 127.0.0.1:3000
         Intercepting  : all TCP connections
   ```
@@ -287,10 +288,11 @@ Create preview URLs to do selective intercepts, meaning only traffic coming from
       
              [default: verylargejavaservice.default]:
       
-      Using deployment dataprocessingservice
+      Using Deployment dataprocessingservice
       intercepted
           Intercept name  : dataprocessingservice
           State           : ACTIVE
+          Workload kind   : Deployment
           Destination     : 127.0.0.1:3000
           Intercepting    : HTTP requests that match all of:
             header("x-telepresence-intercept-id") ~= regexp("86cb4a70-c7e1-1138-89c2-d8fed7a46cae:dataprocessingservice")

quick-start/qs-java.md

@@ -204,10 +204,11 @@ Next, we’ll create an intercept. An intercept is a rule that tells Telepresenc
   ```
   $ telepresence intercept dataprocessingservice --port 3000
 
-    Using deployment dataprocessingservice
+    Using Deployment dataprocessingservice
     intercepted
         Intercept name: dataprocessingservice
         State         : ACTIVE
+        Workload kind : Deployment
         Destination   : 127.0.0.1:3000
         Intercepting  : all TCP connections
   ```
@@ -281,10 +282,11 @@ Create preview URLs to do selective intercepts, meaning only traffic coming from
       
              [default: verylargejavaservice.default]:
       
-      Using deployment dataprocessingservice
+      Using Deployment dataprocessingservice
       intercepted
           Intercept name  : dataprocessingservice
           State           : ACTIVE
+          Workload kind   : Deployment
           Destination     : 127.0.0.1:3000
           Intercepting    : HTTP requests that match all of:
             header("x-telepresence-intercept-id") ~= regexp("86cb4a70-c7e1-1138-89c2-d8fed7a46cae:dataprocessingservice")

quick-start/qs-node.md

@@ -194,10 +194,11 @@ Next, we’ll create an intercept. An intercept is a rule that tells Telepresenc
   ```
   $ telepresence intercept dataprocessingservice --port 3000
     
-    Using deployment dataprocessingservice
+    Using Deployment dataprocessingservice
     intercepted
         Intercept name: dataprocessingservice
         State         : ACTIVE
+        Workload kind : Deployment
         Destination   : 127.0.0.1:3000
         Intercepting  : all TCP connections
   ```
@@ -275,10 +276,11 @@ Create preview URLs to do selective intercepts, meaning only traffic coming from
     
            [default: verylargejavaservice.default]:
     
-    Using deployment dataprocessingservice
+    Using Deployment dataprocessingservice
     intercepted
         Intercept name  : dataprocessingservice
         State           : ACTIVE
+        Workload kind   : Deployment
         Destination     : 127.0.0.1:3000
         Intercepting    : HTTP requests that match all of:
           header("x-telepresence-intercept-id") ~= regexp("86cb4a70-c7e1-1138-89c2-d8fed7a46cae:dataprocessingservice")

quick-start/qs-python-fastapi.md

@@ -195,10 +195,11 @@ Next, we’ll create an intercept. An intercept is a rule that tells Telepresenc
   ```
   $ telepresence intercept dataprocessingservice --port 3000
 
-    Using deployment dataprocessingservice
+    Using Deployment dataprocessingservice
     intercepted
         Intercept name: dataprocessingservice
         State         : ACTIVE
+        Workload kind : Deployment
         Destination   : 127.0.0.1:3000
         Intercepting  : all TCP connections
   ```
@@ -272,10 +273,11 @@ Create preview URLs to do selective intercepts, meaning only traffic coming from
       
              [default: verylargejavaservice.default]:
       
-      Using deployment dataprocessingservice
+      Using Deployment dataprocessingservice
       intercepted
           Intercept name  : dataprocessingservice
           State           : ACTIVE
+          Workload kind   : Deployment
           Destination     : 127.0.0.1:3000
           Intercepting    : HTTP requests that match all of:
             header("x-telepresence-intercept-id") ~= regexp("86cb4a70-c7e1-1138-89c2-d8fed7a46cae:dataprocessingservice")

quick-start/qs-python.md

@@ -206,10 +206,11 @@ Next, we’ll create an intercept. An intercept is a rule that tells Telepresenc
   ```
   $ telepresence intercept dataprocessingservice --port 3000
 
-    Using deployment dataprocessingservice
+    Using Deployment dataprocessingservice
     intercepted
         Intercept name: dataprocessingservice
         State         : ACTIVE
+        Workload kind : Deployment
         Destination   : 127.0.0.1:3000
         Intercepting  : all TCP connections
   ```
@@ -283,10 +284,11 @@ Create preview URLs to do selective intercepts, meaning only traffic coming from
       
              [default: verylargejavaservice.default]:
       
-      Using deployment dataprocessingservice
+      Using Deployment dataprocessingservice
       intercepted
           Intercept name  : dataprocessingservice
           State           : ACTIVE
+          Workload kind   : Deployment
           Destination     : 127.0.0.1:3000
           Intercepting    : HTTP requests that match all of:
             header("x-telepresence-intercept-id") ~= regexp("86cb4a70-c7e1-1138-89c2-d8fed7a46cae:dataprocessingservice")

reference/architecture.md

@@ -36,7 +36,7 @@ URL, it forwards the request to the ingress service specified at the Preview URL
 ## Traffic Agent
 
 The Traffic Agent is a sidecar container that facilitates intercepts. When an intercept is started, the Traffic Agent
-container is injected into the deployment's pod(s). You can see the Traffic Agent's status by running `kubectl describe
+container is injected into the workload's pod(s). You can see the Traffic Agent's status by running `kubectl describe
 pod <pod-name>`.
 
 Depending on the type of intercept that gets created, the Traffic Agent will either route the incoming request to the

reference/client.md

@@ -22,4 +22,4 @@ A list of all CLI commands and flags is available by running `telepresence help`
 | `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` |
 | `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 deployment, the `--all-agents` flag to remove all Traffic Agents from all deployments, or the `--everything` flag to remove all Traffic Agents and the Traffic Manager.
+| `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/dns.md

@@ -46,10 +46,11 @@ Now we'll start an intercept against another service in the same namespace. Reme
 ```
 $ telepresence intercept dataprocessingservice --port 3000
   
-  Using deployment dataprocessingservice
+  Using Deployment dataprocessingservice
   intercepted
       Intercept name: dataprocessingservice
       State         : ACTIVE
+      Workload kind : Deployment
       Destination   : 127.0.0.1:3000
       Intercepting  : all TCP connections
   

reference/intercepts.md

@@ -8,26 +8,30 @@ In order to do this, it will prompt you for four options.  For the first, `Ingre
 
 Also because you're logged in, Telepresence will default to `--mechanism=http --http-match=auto` (or just `--http-match=auto`; `--http-match` implies `--mechanism=http`). If you hadn't been logged in it would have defaulted to `--mechanism=tcp`.  This tells it to do smart intercepts and only 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.  See `telepresence intercept --help` for information on using `--http-match` to customize which requests it intercepts.
 
+## Supported Workloads
+Kubernetes has various [workloads](https://kubernetes.io/docs/concepts/workloads/). Currently, telepresence supports intercepting Deployments and ReplicaSets.
+<Alert severity="info"> While many of our examples may use Deployments, they would also work on ReplicaSets </Alert>
+
 ## Specifying a namespace for an intercept
 
-The namespace of the intercepted deployment is specified using the `--namespace` option. When this option is used, and `--deployment` is not used, then the given name is interpreted as the name of the deployment and the name of the intercept will be constructed from that name and the namespace.
+The namespace of the intercepted workload is specified using the `--namespace` option. When this option is used, and `--workload` is not used, then the given name is interpreted as the name of the workload and the name of the intercept will be constructed from that name and the namespace.
 
 ```
 telepresence intercept hello --namespace myns --port 9000
 ```
 
-This will intercept a Deployment named "hello" and name the intercept
+This will intercept a workload named "hello" and name the intercept
 "hello-myns".  In order to remove the intercept, you will need to run
 `telepresence leave hello-mydns` instead of just `telepresence leave
 hello`.
 
-The name of the intercept will be left unchanged if the deployment is specified.
+The name of the intercept will be left unchanged if the workload is specified.
 
 ```
-telepresence intercept myhello --namespace myns --deployment hello --port 9000
+telepresence intercept myhello --namespace myns --workload hello --port 9000
 ```
 
-This will intercept a deployment named "hello" and name the intercept "myhello".
+This will intercept a workload named "hello" and name the intercept "myhello".
 
 ## Importing Environment Variables
 
@@ -52,10 +56,11 @@ This will output a header that you can set on your request for that traffic to b
 ```
 $ telepresence intercept <deployment name>  --port=<TCP port> --preview-url=false
   
-  Using deployment <deployment name> 
+  Using Deployment <deployment name>
   intercepted
       Intercept name: <full name of intercept>
       State         : ACTIVE
+      Workload kind : Deployment
       Destination   : 127.0.0.1:<local TCP port>
       Intercepting  : HTTP requests that match all of:
         header("x-telepresence-intercept-id") ~= regexp("<uuid unique to you>:<full name of intercept>")
@@ -81,10 +86,11 @@ If you are trying to intercept a service that has multiple ports, you need to te
 
 ```
 telepresence intercept <base name of intercept> --port=<local TCP port>:<servicePortName>
-  Using deployment <name of deployment>
+  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 Name: <servicePortName>
       Intercepting     : all TCP connections
@@ -93,3 +99,20 @@ telepresence intercept <base name of intercept> --port=<local TCP port>:<service
 When intercepting a service that has multiple ports, the name of the service port that has been intercepted is also listed.
 
 If you want to change which port has been intercepted, you can create a new intercept the same way you did above and it will change which service port is being intercepted.
+
+## Creating an Intercept When Multiple Services Match your Workload
+
+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](../../../argo), it uses two services (that use the same labels) to manage traffic between a canary and a stable service.
+
+Fortunately, if you know which service you want to use when intercepting a workload, you can use the --service flag.  So in the aforementioned demo, if you wanted to use the `echo-stable` service when intercepting your workload, your command would look like this:
+```
+telepresence intercept echo-rollout-<generatedHash> --port <local TCP port> --service echo-stable
+  Using ReplicaSet echo-rollout-<generatedHash>
+  intercepted
+      Intercept name    : echo-rollout-<generatedHash>
+      State             : ACTIVE
+      Workload kind     : ReplicaSet
+      Destination       : 127.0.0.1:3000
+      Volume Mount Point: /var/folders/cp/2r22shfd50d9ymgrw14fd23r0000gp/T/telfs-921196036
+      Intercepting      : all TCP connections
+```

reference/rbac.md

@@ -0,0 +1,35 @@
+# RBAC
+
+## Necessary RBAC for Users
+
+To use telepresence, users will need to have at least the following permissions:
+```
+- apiGroups:
+  - ""
+  resources: ["pods"]
+  verbs: ["get", "list", "create", "watch", "delete"]
+- apiGroups:
+  - ""
+  resources: ["services"]
+  verbs: ["get", "list", "watch", "update"]
+- apiGroups:
+  - ""
+  resources: ["pods/portforward"]
+  verbs: ["create"]
+- apiGroups:
+  - "apps"
+  resources: ["deployments", "replicasets"]
+  verbs: ["get", "list", "update"]
+- apiGroups:
+  - "getambassador.io"
+  resources: ["hosts", "mappings"]
+  verbs: ["*"]
+- apiGroups:
+  - ""
+  resources: ["endpoints"]
+  verbs: ["get", "list", "watch"]
+- apiGroups:
+  - ""
+  resources: ["namespaces"]
+  verbs: ["get", "list", "watch"]
+```

reference/volume.md

@@ -14,10 +14,11 @@ Telepresence can set a random mount point for you by using `--mount=true` instea
 
 ```
 $ telepresence intercept <mysvc> --port <port> --mount=true -- /bin/bash
-Using deployment <mysvc>
+Using Deployment <mysvc>
 intercepted
     Intercept name    : <mysvc>
     State             : ACTIVE
+    Workload kind     : Deployment
     Destination       : 127.0.0.1:<port>
     Volume Mount Point: /var/folders/cp/2r22shfd50d9ymgrw14fd23r0000gp/T/telfs-988349784
     Intercepting      : all TCP connections

tutorial.md

@@ -143,10 +143,11 @@ Alternatively, you can use Telepresence's `intercept` command to proxy traffic b
 
          [default: verylargejavaservice.default]:
 
-  Using deployment dataprocessingservice
+  Using Deployment dataprocessingservice
   intercepted
       Intercept name  : dataprocessingservice
       State           : ACTIVE
+      Workload kind   : Deployment
       Destination     : 127.0.0.1:3000
       Intercepting    : HTTP requests that match all of:
         header("x-telepresence-intercept-id") ~= regexp("86cb4a70-c7e1-1138-89c2-d8fed7a46cae:dataprocessingservice")