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:

telepresence --new-deployment myserver --run-shell

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:

telepresence --run-shell

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).

telepresence --swap-deployment myserver --run-shell

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

telepresence --swap-deployment myserver:containername --run-shell

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:

Kubernetes namespaces

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: