177 lines
32 KiB
Markdown
177 lines
32 KiB
Markdown
|
# 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. |
|