Run Code Locally with Telepresence (Experimental)
Estimated Time: 10 minutes
- Telepresence (this guide was tested with v0.102)
- Kubectl (tested with v1.15.2)
- Nodejs (tested with v10.15.3)
By default, Kelda enables local development by syncing local files into the Kubernetes cluster, and restarting the code after each sync.
Telepresence sets up a network proxy so that local code seems like it's running within the Kubernetes cluster. The local process can make requests to other services in the cluster, and services in the cluster can make requests to the local code.
This guide shows how Telepresence can be used with Kelda. Kelda handles booting all the dependencies in an easy to use development sandbox, while Telepresence allows you to directly control how your development code is run.
Using Telepresence with Your Own Service
To use Telepresence with your services, just boot your dependencies with
dev, and use Telepresence to swap out the deployment that you'd like to
If you don't need to code sync any of your services, start Kelda with
Telepresence has multiple approaches to proxying, so check out their docs to see what's best for you.
The Sock Shop example below uses the following Telepresence command.
telepresence --context $(kelda config get-context) \ --namespace $(kelda config get-namespace) \ --expose 8079 \ --swap-deployment front-end \ --run npm start
|context||The kubectl context that Telepresence uses to connect to the cluster. This must match the context used by Kelda.|
|namespace||The namespace that Telepresence connects to. This must match the namespace used by Kelda.|
|expose||The port to expose to the cluster. The frontend exposes 8079 because that's the port it listens on.|
|swap-deployment||The deployment to replace in the Kubernetes cluster. This deployment should be created by Kelda before it's replaced.|
|run||The command to proxy.|
Try It Out
To quickly experience what developing with Telepresence is like, we will make a code change to the example Sock Shop application.
Install the Kelda CLI
Run the following snippet to download Kelda:
curl -fsSL 'https://kelda.io/install.sh' | sh
You should see the following output:
Downloading the latest Kelda release... ################################################################# 100.0% The latest Kelda release has been downloaded to the current working directory. Please install Kelda to your desired location, or use the snippet below to install it to /usr/local/bin. sudo cp ./kelda /usr/local/bin
Use the provided snippet to install Kelda into
Download the Kelda examples repository
This repository contains a script that we'll use to connect to the demo cluster, as well as the source code and Kelda config for Sock Shop.
git clone https://github.com/kelda-inc/examples
Connect to the Kelda demo cluster
You must run this command again for each new terminal you open.
use-demo-cluster.shscript in the root directory of the examples repository. This will modify your local
kubectlsettings so that it points at the Kelda demo cluster.
If the script succeeded, your terminal prompt should now start with
[kelda-demo]. If your prompt didn't update, then you might have ran the script directly rather than via the
Develop with Telepresence
We're now ready to test a change to the Sock Shop frontend.
Configure Kelda to work on the Sock Shop project
The following command creates a file in your home directory that's required for the
keldacommands to work.
Most users can just use the defaults by hitting [Enter] for each prompt.
In the root directory of the examples repository, run:
If the command succeeded, you should see something like:
Wrote config to /Users/kevin/.kelda.yaml
Boot the Sock Shop services
Run the following command to boot the Sock Shop services in the Kubernetes cluster.
--no-syncflag is used to tell Kelda that nothing should be run in development mode. Telepresence will handle swapping out the frontend service because we use the
kelda dev --no-sync
Wait for of all the services to become
Ready. The first run may take several minutes while all the services boot.
Start the Sock Shop Front End via Telepresence
You must install the Telepresence CLI before continuing.
Run the following commands in a new terminal. Telepresence will swap out the
front-enddeployment created in step (2) with the network proxy, and run the
node server.jscommand locally.
source use-demo-cluster.sh cd golang-sock-shop/front-end telepresence --context $(kelda config get-context) --namespace $(kelda config get-namespace) --expose 8079 --swap-deployment front-end --run npm start
You should see something like
T: Setup complete. Launching your command. Using the redis based session manager App now running in development mode on port 8079
If you get an error about 'package.json' not existing..
You're likely running Telepresence from the wrong directory.
Make sure that you're running Telepresence from the
View the Sock Shop homepage
kelda devUI shows that the tunnel is "Up", open http://localhost:8080 in your browser. This usually takes around 30 seconds.
There should be various socks with prices at the bottom of the page.
If the page looks like it's only partially loaded, Telepresence's DNS resolution may be broken.
See below for more information.
When you access
localhost:8080, Telepresence proxies the request to your local instance of the frontend. The local node server also makes requests to the
catalogueservice running in the cluster.
Change the number of socks on the homepage
Uncomment line 187 of
numResultsis set to 1.
The Node service run by Telepresence will serve the updated
index.htmlwhen the homepage is reloaded.
View the change in your browser
Reload http://localhost:8080. There should now only be one item under "Hot This Week".
Exit Telepresence by entering
Ctrl + cinto the terminal window where Telepresence is running.
Exit Kelda by entering
Ctrl + cinto the terminal window where the Kelda CLI is running.
Delete your development namespace
kelda deleteto delete your development namespace so that it stops consuming resources in the remote cluster.
The Telepresence integration with Kelda is still experimental. We're continuing to improve the experience of using Kelda with Telepresence.
DNS Resolution Failures
Telepresence has an issue where DNS resolution occasionally fails on Mac.
If this happens during the Sock Shop demo, the front end server logs will show
that requests to
/cart are returning
500, rather than
Flushing the DNS cache fixes this issue temporarily.
Multiple Telepresence Deployments
Telepresence doesn't always remove the deployment it created for proxying.
If this happens, recreate the development environment with
kelda delete, or
manually delete the deployment with
kubectl delete deployment <deployment
Modifying Kubernetes Manifests While Running Telepresence
Changing the Kubernetes manifests for a service being proxied by Telepresence will wipe out the active Telepresence session. If this happens, you should Ctrl-C the Telepresence process, and start it again.