Telepresence Quick Start - Java
Contents
Prerequisites
You’ll need kubectl
or oc
installed
and set up
(Linux /
macOS /
Windows)
to use a Kubernetes cluster, preferably an empty test cluster. This
document uses kubectl
in all example commands, but OpenShift
users should have no problem substituting in the oc
command instead.
If you have used Telepresence previously, please first reset your Telepresence deployment with:
telepresence uninstall --everything
.
1. Install the Telepresence CLI
GNU/Linux
# 1. Download the latest binary (~50 MB):sudo curl -fL https://app.getambassador.io/download/tel2/linux/amd64/latest/telepresence -o /usr/local/bin/telepresence# 2. Make the binary executable:sudo chmod a+x /usr/local/bin/telepresence
macOS
# Intel Macs# Install via brew:brew install datawire/blackbird/telepresence# OR install manually:# 1. Download the latest binary (~60 MB):sudo curl -fL https://app.getambassador.io/download/tel2/darwin/amd64/latest/telepresence -o /usr/local/bin/telepresence# 2. Make the binary executable:sudo chmod a+x /usr/local/bin/telepresence# Apple silicon Macs# Install via brew:brew install datawire/blackbird/telepresence-arm64# OR Install manually:# 1. Download the latest binary (~60 MB):sudo curl -fL https://app.getambassador.io/download/tel2/darwin/arm64/latest/telepresence -o /usr/local/bin/telepresence# 2. Make the binary executable:sudo chmod a+x /usr/local/bin/telepresence
Windows
# To install Telepresence, run the following commands# from PowerShell as Administrator.# 1. Download the latest windows zip containing telepresence.exe and its dependencies (~50 MB):Invoke-WebRequest https://app.getambassador.io/download/tel2/windows/amd64/latest/telepresence.zip -OutFile telepresence.zip# 2. Unzip the telepresence.zip file to the desired directory, then remove the zip file:Expand-Archive -Path telepresence.zip -DestinationPath telepresenceInstaller/telepresenceRemove-Item 'telepresence.zip'cd telepresenceInstaller/telepresence# 3. Run the install-telepresence.ps1 to install telepresence's dependencies. It will install telepresence to# C:\telepresence by default, but you can specify a custom path by passing in -Path C:\my\custom\pathpowershell.exe -ExecutionPolicy bypass -c " . '.\install-telepresence.ps1';"# 4. Remove the unzipped directory:cd ../..Remove-Item telepresenceInstaller -Recurse -Confirm:$false -Force# 5. Telepresence is now installed and you can use telepresence commands in PowerShell.
2. Test Telepresence
Telepresence connects your local workstation to a remote Kubernetes cluster.
Connect to the cluster:
telepresence connect
Terminal$ telepresence connectLaunching Telepresence Daemon...Connected to context default (https://<cluster-public-IP>)Test that Telepresence is working properly by connecting to the Kubernetes API server:
curl -ik https://kubernetes.default
Terminal$ curl -ik https://kubernetes.defaultHTTP/1.1 401 UnauthorizedCache-Control: no-cache, privateContent-Type: application/jsonWww-Authenticate: Basic realm="kubernetes-master"Date: Tue, 09 Feb 2021 23:21:51 GMTContent-Length: 165{"kind": "Status","apiVersion": "v1","metadata": {},"status": "Failure","message": "Unauthorized","reason": "Unauthorized","code": 401}%
3. Install a sample Java application
Your local workstation may not have the compute or memory resources necessary to run all the services in a multi-service application. In this example, we’ll show you how Telepresence can give you a fast development loop, even in this situation.
Start by installing a sample application that consists of multiple services:
kubectl apply -f https://raw.githubusercontent.com/datawire/edgey-corp-java/main/k8s-config/edgey-corp-web-app-no-mapping.yaml
Terminal$ kubectl apply -f https://raw.githubusercontent.com/datawire/edgey-corp-java/main/k8s-config/edgey-corp-web-app-no-mapping.yamldeployment.apps/dataprocessingservice createdservice/dataprocessingservice created...Give your cluster a few moments to deploy the sample application.
Use
kubectl get pods
to check the status of your pods:Terminal$ kubectl get podsNAME READY STATUS RESTARTS AGEverylargedatastore-855c8b8789-z8nhs 1/1 Running 0 78sverylargejavaservice-7dfddbc95c-696br 1/1 Running 0 78sdataprocessingservice-5f6bfdcf7b-qvd27 1/1 Running 0 79sOnce all the pods are in a
Running
state, go to the frontend service in your browser at http://verylargejavaservice.default:8080.You should see the EdgyCorp WebApp with a green title and green pod in the diagram.
4. Set up a local development environment
You will now download the repo containing the services' code and run the DataProcessingService service locally. This version of the code has the UI color set to blue instead of green.
Clone the web app’s GitHub repo:
git clone https://github.com/datawire/edgey-corp-java.git
Terminal$ git clone https://github.com/datawire/edgey-corp-java.gitCloning into 'edgey-corp-java'......Change into the repo directory, then into DataProcessingService:
cd edgey-corp-java/DataProcessingService/
Start the Maven server.
mvn spring-boot:run
Terminal$ mvn spring-boot:run...g.d.DataProcessingServiceJavaApplication : Started DataProcessingServiceJavaApplication in 1.408 seconds (JVM running for 1.684)In a new terminal window, curl the service running locally to confirm it’s set to blue:
curl localhost:3000/color
Terminal$ curl localhost:3000/color"blue"
5. Intercept all traffic to the service
Next, we’ll create an intercept. An intercept is a rule that tells Telepresence where to send traffic. In this example, we will send all traffic destined for the DataProcessingService to the version of the DataProcessingService running locally instead:
Start the intercept with the
intercept
command, setting the service name and port:telepresence intercept dataprocessingservice --port 3000
Terminal$ telepresence intercept dataprocessingservice --port 3000Using Deployment dataprocessingserviceinterceptedIntercept name: dataprocessingserviceState : ACTIVEWorkload kind : DeploymentDestination : 127.0.0.1:3000Intercepting : all TCP connectionsGo to the frontend service again in your browser. Since the service is now intercepted it can be reached directly by its service name at http://verylargejavaservice:8080. You will now see the blue elements in the app.
6. Make a code change
We’ve now set up a local development environment for the DataProcessingService, and we’ve created an intercept that sends traffic in the cluster to our local environment. We can now combine these two concepts to show how we can quickly make and test changes.
Open
edgey-corp-java/DataProcessingService/src/main/resources/application.properties
in your editor and changeapp.default.color
on line 2 fromblue
toorange
. Save the file then stop and restart your Java server.Now, visit http://verylargejavaservice:8080 again in your browser. You will now see the orange elements in the application.
7. Create a Preview URL
Create a personal intercept with a preview URL; meaning that only traffic coming from the preview URL will be intercepted, so you can easily share the services you’re working on with your teammates.
Clean up your previous intercept by removing it:
telepresence leave dataprocessingservice
Log in to Ambassador Cloud, a web interface for managing and sharing preview URLs:
Terminal$ telepresence loginLaunching browser authentication flow...<web browser opens, log in and choose your organization>Login successful.If you are in an environment where Telepresence cannot launch a local browser for you to interact with, you will need to pass the
--apikey
flag totelepresence login
.Start the intercept again:
telepresence intercept dataprocessingservice --port 3000
You will be asked for your ingress layer 3 address; specify the front end service:verylargejavaservice.default
Then when asked for the port, type8080
, for "use TLS", typen
and finally confirm the layer 5 hostname.shell$ telepresence intercept dataprocessingservice --port 3000To create a preview URL, telepresence needs to know how requests enteryour cluster. Please Select the ingress to use.1/4: What's your ingress' IP address?You may use an IP address or a DNS name (this is usually a"service.namespace" DNS name).[default: dataprocessingservice.default]: verylargejavaservice.default2/4: What's your ingress' TCP port number?[default: 80]: 80803/4: Does that TCP port on your ingress use TLS (as opposed to cleartext)?[default: n]:4/4: If required by your ingress, specify a different hostname(TLS-SNI, HTTP "Host" header) to be used in requests.[default: verylargejavaservice.default]:Using Deployment dataprocessingserviceinterceptedIntercept name : dataprocessingserviceState : ACTIVEWorkload kind : DeploymentDestination : 127.0.0.1:3000Intercepting : HTTP requests that match all of:header("x-telepresence-intercept-id") ~= regexp("86cb4a70-c7e1-1138-89c2-d8fed7a46cae:dataprocessingservice")Preview URL : https://<random-subdomain>.preview.edgestack.meLayer 5 Hostname: verylargejavaservice.defaultWait a moment for the intercept to start; it will also output a preview URL. Go to this URL in your browser, it will be the orange version of the app.
Now go again to http://verylargejavaservice:8080, it’s still green.
Normal traffic coming to your app gets the green cluster service, but traffic coming from the preview URL goes to your laptop and gets the orange local service!
What's Next?
Collaborating
Use preview URLS to collaborate with your colleagues and others outside of your organization.
Outbound Sessions
While connected to the cluster, your laptop can interact with services as if it was another pod in the cluster.
FAQs
Learn more about uses cases and the technical implementation of Telepresence.