Connecting to the cluster

Setting up the proxy

To use Telepresence with a cluster (Kubernetes or OpenShift, local or remote) you need to run a proxy inside the cluster. There are three ways of doing so.

Creating a new deployment

By using the --new-deployment option telepresence can create a new deployment for you. It will be deleted when the local telepresence process exits. This is the default if no deployment option is specified.

For example, this creates a Deployment called myserver:

This will create two Kubernetes objects, a Deployment and a Service, both named myserver. (On OpenShift a DeploymentConfig will be used instead of Deployment.) Or, if you don't care what your new Deployment is called, you can do:

If telepresence crashes badly enough (e.g. you used kill -9) you will need to manually delete the Deployment and Service that Telepresence created.

Swapping out an existing deployment

If you already have your code running in the cluster you can use the --swap-deployment option to replace the existing deployment with the Telepresence proxy. When the telepresence process exits it restores the earlier state of the Deployment (or DeploymentConfig on OpenShift).

If you have more than one container in the pods created by the deployment you can also specify the container name:

If telepresence crashes badly enough (e.g. you used kill -9) you will need to manually restore the Deployment.

Running Telepresence manually

You can also choose to run the Telepresence manually by starting a Deployment that runs the proxy in a pod.

The Deployment should only have 1 replica, and use the Telepresence different image:

You should apply this file to your cluster:

Next, you need to run the local Telepresence client on your machine, using --deployment to indicate the name of the Deployment object whose pod is running telepresence/datawire-k8s:

Telepresence will leave the deployment untouched when it exits.

Kubernetes contexts and namespaces

kubectl context

By default Telepresence uses whatever the current context is for kubectl. If you want to choose a specific context you can use the --context option to telepresence. For example:

You can choose any context listed in kubectl config get-contexts.

If you've set a namespace for the context then that namespace will be used to find/create the Deployment, but you can also choose a namespace explicitly, as shown in the next section.

Kubernetes namespaces

If you want to proxy to a Deployment in a non-default namespace you can pass the --namespace argument to Telepresence:

Cluster permissions

Telepresence uses kubectl or oc to manipulate your Kubernetes/OpenShift cluster. This means the user who invokes Telepresence needs the appropriate authorization. For Kubernetes, the following Role should be sufficient: