For the most part, Telepresence doesn't require any special
configuration in the cluster and can be used right away in any
cluster (as long as the user has adequate RBAC permissions
and the cluster's server version is
1.19.0 or higher).
Helm Chart configuration
Some cluster specific configuration can be provided when installing or upgrading the Telepresence cluster installation using Helm. Once installed, the Telepresence client will configure itself from values that it receives when connecting to the Traffic manager.
See the Helm chart README for a full list of available configuration settings.
To add configuration, create a yaml file with the configuration values and then use it executing
telepresence helm install [--upgrade] --values <values yaml>
It is possible for the Traffic Manager to automatically push config to all connecting clients. To learn more about this, please see the client config docs
agent structure of the Helm chart configures the behavior of the Telepresence agents.
Application Protocol Selection
agent.appProtocolStrategy is relevant when using personal intercepts and controls how telepresence selects the application protocol to use
when intercepting a service that has no
service.ports.appProtocol declared. The port's
appProtocol is always trusted if it is present.
Valid values are:
|The Telepresence Traffic Agent will probe the intercepted container to check whether it supports http2. This is the default.|
|Telepresence will make an educated guess about the protocol based on the name of the service port|
|Telepresence will use http|
|Telepresence will use http2|
portName is used, Telepresence will determine the protocol by the name of the port:
<protocol>[-suffix]. The following protocols
|Plaintext HTTP/1.1 traffic|
|Plaintext HTTP/2 traffic|
|TLS Encrypted HTTP (1.1 or 2) traffic|
|Same as http2|
The application protocol strategy can also be configured on a workstation. See Intercepts for more info.
agent.envoy structure contains three values:
|Log level used by the Envoy proxy. Defaults to "warning"|
|Port used by the Envoy server. Default 18000.|
|Port used for Envoy administration. Default 19000.|
agent.image structure contains the following values:
|Registry used when downloading the image. Defaults to "docker.io/datawire".|
|The name of the image. Retrieved from Ambassador Cloud if not set.|
|The tag of the image. Retrieved from Ambassador Cloud if not set.|
agent.LogLevel controls the log level of the traffic-agent. See Log Levels for more info.
agent.initResources will be used as the
resources element when injecting traffic-agents and init-containers.
In this example, other applications in the cluster expect to speak TLS to your intercepted application (perhaps you're using a service-mesh that does mTLS).
In order to use
--mechanism=http (or any features that imply
--mechanism=http) you need to tell Telepresence about the TLS
certificates in use.
Tell Telepresence about the certificates in use by adjusting your workload's Pod template to set a couple of annotations on the intercepted Pods:
getambassador.io/inject-terminating-tls-secretannotation (optional) names the Kubernetes Secret that contains the TLS server certificate to use for decrypting and responding to incoming requests.
When Telepresence modifies the Service and workload port definitions to point at the Telepresence Agent sidecar's port instead of your application's actual port, the sidecar will use this certificate to terminate TLS.
getambassador.io/inject-originating-tls-secretannotation (optional) names the Kubernetes Secret that contains the TLS client certificate to use for communicating with your application.
You will need to set this if your application expects incoming requests to speak TLS (for example, your code expects to handle mTLS itself instead of letting a service-mesh sidecar handle mTLS for it, or the port definition that Telepresence modified pointed at the service-mesh sidecar instead of at your application).
If you do set this, you should to set it to the same client certificate Secret that you configure the Ambassador Edge Stack to use for mTLS.
It is only possible to refer to a Secret that is in the same Namespace as the Pod. The Secret will be mounted into the traffic agent's container.
type: kubernetes.io/tls Secrets and
type: istio.io/key-and-cert Secrets; as well as
Secrets that it detects to be formatted as one of those types.
If your cluster is on an isolated network such that it cannot communicate with Ambassador Cloud, then some additional configuration is required to acquire a license key in order to use personal intercepts.
Create a license
Log in and Go to the teams setting page in Ambassador Cloud and select Telepresence Licenses for the team you want to create the license for.
Generate a new license (if one doesn't already exist) by clicking Generate New License.
You will be prompted for your Cluster ID. Ensure your kubeconfig context is using the cluster you want to create a license for then run this command to generate the Cluster ID:
Click Generate API Key to finish generating the license.
On the licenses page, download the license file associated with your cluster.
Add license to cluster
There are two separate ways you can add the license to your cluster: manually creating and deploying the license secret or having the helm chart manage the secret
You only need to do one of the two options.
Manual deploy of license secret
Use this command to generate a Kubernetes Secret config using the license file:
Save the output as a YAML file and apply it to your cluster with
When deploying the
traffic-managerchart, you must add the additional values when running
helm installby putting the following into a file (for the example we'll assume it's called license-values.yaml)
Install the helm chart into the cluster
Ensure that you have the docker image for the Smart Agent (datawire/ambassador-telepresence-agent:1.11.0) pulled and in a registry your cluster can pull from.
Have users use the
imagesconfig key keys so telepresence uses the aforementioned image for their agent.
Helm chart manages the secret
Get the jwt token from the downloaded license file
Create the following values file, substituting your real jwt token in for the one used in the example below. (for this example we'll assume the following is placed in a file called license-values.yaml)
Install the helm chart into the cluster
Users will now be able to use preview intercepts with the
--preview-url=false flag. Even with the license key, preview URLs
cannot be used without enabling direct communication with Ambassador
Cloud, as Ambassador Cloud is essential to their operation.
If using Helm to install the server-side components, see the chart's README to learn how to configure the image registry and license secret.
Have clients use the skipLogin key to ensure the cli knows it is operating in an air-gapped environment.
Telepresence uses a Mutating Webhook to inject the Traffic Agent sidecar container and update the port definitions. This means that an intercepted workload (Deployment, StatefulSet, ReplicaSet) will remain untouched and in sync as far as GitOps workflows (such as ArgoCD) are concerned.
The injection will happen on demand the first time an attempt is made to intercept the workload.
If you want to prevent that the injection ever happens, simply add the
annotation to your workload template's annotations:
Service Name and Port Annotations
Telepresence will automatically find all services and all ports that will connect to a workload and make them available for an intercept, but you can explicitly define that only one service and/or port can be intercepted.
Ignore Certain Volume Mounts
telepresence.getambassador.io/inject-ignore-volume-mounts can be used to make the injector ignore certain volume mounts denoted by a comma-separated string. The specified volume mounts from the original container will not be appended to the agent sidecar container.
Note on Numeric Ports
targetPort of your intercepted service is pointing at a port number, in addition to
injecting the Traffic Agent sidecar, Telepresence will also inject an
initContainer that will
reconfigure the pod's firewall rules to redirect traffic to the Traffic Agent.
If you need to use numeric ports without the aforementioned capabilities, you can manually install the agent
For example, the following service is using a numeric port, so Telepresence would inject an initContainer into it: