# Telepresence

[Telepresence](https://telepresence.io/) is a tool
that allows for local development of microservices running in a remote
Kubernetes cluster.

This chart manages the server-side components of Telepresence so that an
operations team can give limited access to the cluster for developers to work on
their services.

## Install

The telepresence binary embeds the helm chart, so the easiest way to install is:

```sh
$ telepresence helm install [--set x=y | --values <values file>]
```

## Configuration

The following tables lists the configurable parameters of the Telepresence chart and their default values.

| Parameter                                            | Description                                                                                                                                                         | Default                                                                     |
|------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------|
| affinity                                             | Define the `Node` Affinity and Anti-Affinity for the Traffic Manager.                                                                                               | `{}`                                                                        |
| agent.appProtocolStrategy                            | The strategy to use when determining the application protocol to use for intercepts                                                                                 | `http2Probe`                                                                |
| agent.image.name                                     | The name of the injected agent image                                                                                                                                | `""`                                                                        |
| agent.image.pullPolicy                               | Pull policy in the webhook for the traffic agent image                                                                                                              | `IfNotPresent`                                                              |
| agent.image.tag                                      | The tag for the injected agent image                                                                                                                                | `""` (Defined in `appVersion` Chart.yaml)                                   |
| agent.image.registry                                 | The registry for the injected agent image                                                                                                                           | `ghcr.io/telepresenceio`                                                    |
| agent.initResources                                  | The resources for the injected init container                                                                                                                       |                                                                             |
| agent.logLevel                                       | The logging level for the traffic-agent                                                                                                                             | defaults to logLevel                                                        |
| agent.mountPolicies                                  | The policies for the agents. Key is either volume name or path prefix starting with '/'                                                                             | `/tmp`: Local                                                               |
| agent.resources                                      | The resources for the injected agent container                                                                                                                      |                                                                             |
| agent.securityContext                                | The security context to use for the injected agent container                                                                                                        | defaults to the securityContext of the first container of the app           |
| agent.initSecurityContext                            | The security context to use for the injected init container                                                                                                         | `{}
`         
| agent.initContainer.enabled                            | Whether to enable/disable injection of the initContainer                                                                                                        | true
| agentInjector.certificate.accessMethod               | Method used by the agent injector to access the certificate (watch or mount).                                                                                       | `watch`                                                                     |
| agentInjector.certificate.certmanager.commonName     | The common name of the generated Certmanager certificate.                                                                                                           | `agent-injector`                                                            |
| agentInjector.certificate.certmanager.duration       | The certificate validity duration. (optional value)                                                                                                                 | `2160h0m0s`                                                                 |
| agentInjector.certificate.certmanager.issuerRef.kind | The Issuer kind to use to generate the self signed certificate. (Issuer of ClusterIssuer)                                                                           | `Issuer`                                                                    |
| agentInjector.certificate.certmanager.issuerRef.name | The Issuer name to use to generate the self signed certificate.                                                                                                     | `telepresence`                                                              |
| agentInjector.certificate.method                     | Method used when generating the certificate used for mutating webhook (helm, supplied, or certmanager).                                                             | `helm`                                                                      |
| agentInjector.certificate.regenerate                 | Whether the certificate used for the mutating webhook should be regenerated.                                                                                        | `false`                                                                     |
| agentInjector.enabled                                | Enable/Disable the agent-injector and its webhook.                                                                                                                  | `true`                                                                      |
| agentInjector.name                                   | Name to use with objects associated with the agent-injector.                                                                                                        | `agent-injector`                                                            |
| agentInjector.injectPolicy                           | Determines when an agent is injected, possible values are `OnDemand` and `WhenEnabled`                                                                              | `OnDemand`                                                                  |
| agentInjector.secret.name                            | The name of the secret the agent-injector webhook uses for authorization with the kubernetes api will expose.                                                       | `mutator-webhook-tls`                                                       |
| agentInjector.service.type                           | Type of service for the agent-injector.                                                                                                                             | `ClusterIP`                                                                 |
| agentInjector.webhook.admissionReviewVersions:       | List of supported admissionReviewVersions.                                                                                                                          | `["v1"]`                                                                    |
| agentInjector.webhook.failurePolicy:                 | Action to take on unexpected failure or timeout of webhook.                                                                                                         | `Ignore`                                                                    |
| agentInjector.webhook.name                           | The name of the agent-injector webhook                                                                                                                              | `agent-injector-webhook`                                                    |
| ~~agentInjector.webhook.namespaceSelector~~:         | The namespaceSelector used by the agent-injector webhook when the traffic-manager is not namespaced.  Deprecated, use top level `namespaces` or `namespaceSelector` | {}                                                                          |
| agentInjector.webhook.port:                          | Port for the service that provides the admission webhook                                                                                                            | `443`                                                                       |
| agentInjector.webhook.reinvocationPolicy:            | Specify if the webhook may be called again after the initial webhook call. Possible values are `Never` and `IfNeeded`.                                              | `IfNeeded`                                                                  |
| agentInjector.webhook.servicePath:                   | Path to the service that provides the admission webhook                                                                                                             | `/traffic-agent`                                                            |
| agentInjector.webhook.sideEffects:                   | Any side effects the admission webhook makes outside of AdmissionReview.                                                                                            | `None`                                                                      |
| agentInjector.webhook.timeoutSeconds:                | Timeout of the admission webhook                                                                                                                                    | `5`                                                                         |
| apiPort                                              | The port used by the Traffic Manager gRPC API                                                                                                                       | 8081                                                                        |
| client.connectionTTL                                 | Deprecated: using grpc.connectionTTL                                                                                                                                | `24h`                                                                       |
| client.dns.excludeSuffixes                           | Suffixes for which the client DNS resolver will always fail (or fallback in case of the overriding resolver)                                                        | `[".com", ".io", ".net", ".org", ".ru"]`                                    |
| client.dns.includeSuffixes                           | Suffixes for which the client DNS resolver will always attempt to do a lookup. Includes have higher priority than excludes.                                         | `[]`                                                                        |
| client.routing.allowConflictingSubnets               | Allow the specified subnets to be routed even if they conflict with other routes on the local machine.                                                              | `[]`                                                                        |
| client.routing.alsoProxySubnets                      | The virtual network interface of connected clients will also proxy these subnets                                                                                    | `[]`                                                                        |
| client.routing.neverProxySubnets                     | The virtual network interface of connected clients never proxy these subnets                                                                                        | `[]`                                                                        |
| clientRbac.create                                    | Create RBAC resources for non-admin users with this release.                                                                                                        | `false`                                                                     |
| ~~clientRbac.namespaced~~                            | Restrict the users to specific namespaces. Deprecated and no longer used.                                                                                           | `false`                                                                     |
| clientRbac.namespaces                                | The namespaces to give users access to.                                                                                                                             | Traffic Manager's namespaces (unless dynamic)                               |
| clientRbac.subjects                                  | The user accounts to tie the created roles to.                                                                                                                      | `{}`                                                                        |
| grpc.connectionTTL                                   | The time that the traffic-manager will retain a client connection without any sign of life from the workstation                                                     | `24h`                                                                       |
| grpc.maxReceiveSize                                  | Max size of a gRCP message                                                                                                                                          | `4Mi`                                                                       |
| hooks.busybox.image                                  | The name of the image to use for busybox.                                                                                                                           | `busybox`                                                                   |
| hooks.busybox.imagePullSecrets                       | The `Secret` storing any credentials needed to access the image in a private registry.                                                                              | `[]`                                                                        |
| hooks.busybox.registry                               | The registry to download the image from.                                                                                                                            | `docker.io`                                                                 |
| hooks.busybox.tag                                    | Override the version of busybox to be installed.                                                                                                                    | `latest`                                                                    |
| hooks.curl.registry                                  | The repository to download the image from.                                                                                                                          | `docker.io`                                                                 |
| hooks.curl.image                                     | The name of the image to use for curl.                                                                                                                              | `curlimages/curl`                                                           |
| hooks.curl.imagePullSecrets                          | The `Secret` storing any credentials needed to access the image in a private registry.                                                                              | `[]`                                                                        |
| hooks.curl.pullPolicy                                | Pull policy used when pulling the curl image.                                                                                                                       | `IfNotPresent`                                                              |
| hooks.curl.tag                                       | Override the version of busybox to be installed.                                                                                                                    | `latest`                                                                    |
| hooks.podSecurityContext                             | The Kubernetes SecurityContext for the chart hooks `Pod`                                                                                                            | `{}`                                                                        |
| image.registry                                       | The repository to download the image from. Set `TELEPRESENCE_REGISTRY=image.registry` locally if changing this value.                                               | `ghcr.io/telepresenceio`                                                    |
| hooks.resources                                      | Define resource requests and limits for the chart hooks                                                                                                             | `{}`                                                                        |
| hooks.securityContext                                | The Kubernetes SecurityContext for the chart hooks `Container`                                                                                                      | securityContext                                                             |
| image.imagePullSecrets                               | The `Secret` storing any credentials needed to access the image in a private registry.                                                                              | `[]`                                                                        |
| image.name                                           | The name of the image to use for the traffic-manager                                                                                                                | `tel2`                                                                      |
| image.pullPolicy                                     | How the `Pod` will attempt to pull the image.                                                                                                                       | `IfNotPresent`                                                              |
| image.tag                                            | Override the version of the Traffic Manager to be installed.                                                                                                        | `""` (Defined in `appVersion` Chart.yaml)                                   |
| livenessProbe                                        | Define livenessProbe for the Traffic Manger.                                                                                                                        | `{}`                                                                        |
| logLevel                                             | Define the logging level of the Traffic Manager                                                                                                                     | `debug`                                                                     |
| managerRbac.create                                   | Create RBAC resources for traffic-manager with this release.                                                                                                        | `true`                                                                      |
| ~~managerRbac.namespaced~~                           | Whether the traffic manager should be restricted to specific namespaces. Deprecated and no longer used.                                                             | `false`                                                                     |
| ~~managerRbac.namespaces~~                           | Which namespaces the traffic manager should be restricted to. Deprecated, use top level `namespaces` or `namespaceSelector`                                         | `[]`                                                                        |
| maxNamespaceSpecificWatchers                         | Threshold controlling when the traffic-manager switches from using watchers for each managed namespace to using cluster-wide watchers.                              | `10`                                                                        |
| namespaces                                           | Declares a fixed set of managed namespaces. Mutually exclusive to `namespaceSelector`                                                                               | `[]`                                                                        |
| namespaceSelector                                    | Declares the managed namespace using `matchLabels` and `matchExpressions`. Mutually exclusive to `namespaces`                                                       | `{}`                                                                        |
| nodeSelector                                         | Define which `Node`s you want to the Traffic Manager to be deployed to.                                                                                             | `{}`                                                                        |
| podAnnotations                                       | Annotations for the Traffic Manager `Pod`                                                                                                                           | `{}`                                                                        |
| podLabels                                            | Labels for the Traffic Manager `Pod`                                                                                                                                | `{}`                                                                        |
| podCIDRs                                             | Verbatim list of CIDRs that the cluster uses for pods. Only valid together with `podCIDRStrategy: environment`                                                      | `[]`                                                                        |
| podCIDRStrategy                                      | Define the strategy that the traffic-manager uses to discover what CIDRs the cluster uses for pods                                                                  | `auto`                                                                      |
| podSecurityContext                                   | The Kubernetes SecurityContext for the `Pod`                                                                                                                        | `{}`                                                                        |
| priorityClassName                                    | Name of the existing priority class to be used                                                                                                                      | `""`                                                                        |
| rbac.only                                            | Only create the RBAC resources and omit the traffic-manger.                                                                                                         | `false`                                                                     |
| readinessProbe                                       | Define readinessProbe for the Traffic Manger.                                                                                                                       | `{}`                                                                        |
| resources                                            | Define resource requests and limits for the Traffic Manger.                                                                                                         | `{}`                                                                        |
| schedulerName                                        | Specify a scheduler for Traffic Manager `Pod` and hooks `Pod`.                                                                                                      |                                                                             |
| securityContext                                      | The Kubernetes SecurityContext for the `Deployment`                                                                                                                 | `{"readOnlyRootFilesystem": true, "runAsNonRoot": true, "runAsUser": 1000}` |
| service.type                                         | The type of `Service` for the Traffic Manager.                                                                                                                      | `ClusterIP`                                                                 |
| telepresenceAPI.port                                 | The port on agent's localhost where the Telepresence API server can be found                                                                                        |                                                                             |
| timeouts.agentArrival                                | The time that the traffic-manager will wait for the traffic-agent to arrive                                                                                         | `30s`                                                                       |
| tolerations                                          | Define tolerations for the Traffic Manager to ignore `Node` taints.                                                                                                 | `[]`                                                                        |
| workloads.argoRollouts.enabled                       | Enable/Disable the argo-rollouts integration.                                                                                                                       | `false`                                                                     |
| workloads.deployments.enabled                        | Enable/Disable the support for Deployments.                                                                                                                         | `true`                                                                      |
| workloads.replicaSets.enabled                        | Enable/Disable the support for ReplicaSets.                                                                                                                         | `true`                                                                      |
| workloads.statefulSets.enabled                       | Enable/Disable the support for StatefulSets.                                                                                                                        | `true`                                                                      |

### RBAC

Telepresence requires a cluster for installation but restricted RBAC roles can
be used to give users access to create intercepts if they are not cluster
admins.

The chart gives you the ability to create these RBAC roles for your users and
give access to the entire cluster or restrict to certain namespaces.

You can also create a separate release for managing RBAC by setting
`Values.rbac.only: true`.

### Namespace-scoped traffic manager

Telepresence's Helm chart supports installing a Traffic Manager at the namespace scope.
You might want to do this if you have multiple namespaces, say representing multiple different environments, and would like their Traffic Managers to be isolated from one another.
To do this, set `managerRbac.namespaced=true` and `managerRbac.namespaces={a,b,c}` to manage namespaces `a`, `b` and `c`.

**NOTE** Do not install namespace-scoped traffic managers and a cluster-scoped traffic manager in the same cluster!

#### Namespace collision detection

The Telepresence Helm chart will try to prevent namespace-scoped Traffic Managers from managing the same namespaces.
It will do this by creating a ConfigMap, called `traffic-manager-claim`, in each namespace that a given install manages.

So, for example, suppose you install one Traffic Manager to manage namespaces `a` and `b`, as:

```bash
$ telepresence helm install --namespace a --set 'managerRbac.namespaced=true' --set 'managerRbac.namespaces={a,b}'
```

You might then attempt to install another Traffic Manager to manage namespaces `b` and `c`:

```bash
$ telepresence helm install --namespace c --set 'managerRbac.namespaced=true' --set 'managerRbac.namespaces={b,c}'
```

This would fail with an error:

```
Error: rendered manifests contain a resource that already exists. Unable to continue with install: ConfigMap "traffic-manager-claim" in namespace "b" exists and cannot be imported into the current release: invalid ownership metadata; annotation validation error: key "meta.helm.sh/release-namespace" must equal "c": current value is "a"
```

To fix this error, fix the overlap either by removing `b` from the first install, or from the second.

#### Pod CIDRs

The traffic manager is responsible for keeping track of what CIDRs the cluster uses for the pods. The Telepresence client uses this
information to configure the network so that it provides access to the pods. In some cases, the traffic-manager will not be able to retrieve
this information, or will do it in a way that is inefficient. To remedy this, the strategy that the traffic manager uses can be configured
using the `podCIDRStrategy`.

| Value          | Meaning                                                                                                                   |
| -------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `auto`         | First try `nodePodCIDRs` and if that fails, try `coverPodIPs`                                                             |
| `coverPodIPs`  | Obtain all IPs from the `podIP` and `podIPs` of all `Pod` resource statuses and calculate the CIDRs needed to cover them. |
| `environment`  | Pick the CIDRs from the traffic manager's `POD_CIDRS` environment variable. Use `podCIDRs` to set that variable.          |
| `nodePodCIDRs` | Obtain the CIDRs from the`podCIDR` and `podCIDRs` of all `Node` resource specifications.                                  |
