9 min • read

Telepresence Quick Start - Java

Prerequisites
1. Install the Telepresence CLI
2. Test Telepresence
3. Install a sample Java application
4. Set up a local development environment
5. Intercept all traffic to the service
6. Make a code change
7. Create a Preview URL
What's next?

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.

Need a cluster? We provide free demo clusters preconfigured to follow this quick start. Switch over to that version of the guide here.

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/telepresence
Remove-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\path
powershell.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 connect
  Launching Telepresence Daemon
  ...
  Connected to context default (https://<cluster-public-IP>)
```
macOS users: If you receive an error when running Telepresence that the developer cannot be verified, open
System Preferences → Security & Privacy → General.
Click Open Anyway at the bottom to bypass the security block. Then retry the telepresence connect command.

Test that Telepresence is working properly by connecting to the Kubernetes API server: curl -ik https://kubernetes.default

Didn't work? Make sure you are using Telepresence 2.0.3 or greater, check with telepresence version and upgrade here if needed.

$ curl -ik https://kubernetes.default
  HTTP/1.1 401 Unauthorized
  Cache-Control: no-cache, private
  Content-Type: application/json
  Www-Authenticate: Basic realm="kubernetes-master"
  Date: Tue, 09 Feb 2021 23:21:51 GMT
  Content-Length: 165
  {
    "kind": "Status",
    "apiVersion": "v1",
    "metadata": {
    },
    "status": "Failure",
    "message": "Unauthorized",
    "reason": "Unauthorized",
    "code": 401
  }%

The 401 response is expected. What's important is that you were able to contact the API.

Congratulations! You’ve just accessed your remote Kubernetes API server, as if you were on the same network! With Telepresence, you’re able to use any tool that you have locally to connect to any service in the cluster.

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.

While Telepresence works with any language, this guide uses a sample app written in Java. We have versions in Python (FastAPI), Python (Flask), Go, and NodeJS if you prefer.

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

$ kubectl apply -f https://raw.githubusercontent.com/datawire/edgey-corp-java/main/k8s-config/edgey-corp-web-app-no-mapping.yaml
  deployment.apps/dataprocessingservice created
  service/dataprocessingservice created
  ...

Give your cluster a few moments to deploy the sample application.

Use kubectl get pods to check the status of your pods:

$ kubectl get pods
  NAME                                         READY   STATUS    RESTARTS   AGE
  verylargedatastore-855c8b8789-z8nhs          1/1     Running   0          78s
  verylargejavaservice-7dfddbc95c-696br        1/1     Running   0          78s
  dataprocessingservice-5f6bfdcf7b-qvd27       1/1     Running   0          79s

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

Congratulations, you can now access services running in your cluster by name from your laptop!

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.

Confirm first that nothing is running locally on port 3000! If curl localhost:3000 returns Connection refused then you should be good to go.

Clone the web app’s GitHub repo: git clone https://github.com/datawire/edgey-corp-java.git

$ git clone https://github.com/datawire/edgey-corp-java.git
  Cloning 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

Install Java and Maven first if needed.

$ 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"
```

Victory, your local Java server is running a-ok!

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

$ telepresence intercept dataprocessingservice --port 3000
  Using Deployment dataprocessingservice
  intercepted
      Intercept name: dataprocessingservice
      State         : ACTIVE
      Workload kind : Deployment
      Destination   : 127.0.0.1:3000
      Intercepting  : all TCP connections

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

The frontend’s request to DataProcessingService is being intercepted and rerouted to the Java server on your laptop!

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 change app.default.color on line 2 from blue to orange. 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.

We’ve just shown how we can edit code locally, and immediately see these changes in the cluster.
Normally, this process would require a container build, push to registry, and deploy.
With Telepresence, these changes happen instantly.

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 login
Launching 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 to telepresence 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, type 8080, for "use TLS", type n and finally confirm the layer 5 hostname.

  $ telepresence intercept dataprocessingservice --port 3000

    To create a preview URL, telepresence needs to know how requests enter 
        your 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.default

    2/4: What's your ingress' TCP port number?

           [default: 80]: 8080

    3/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 dataprocessingservice
    intercepted
        Intercept name  : dataprocessingservice
        State           : ACTIVE
        Workload kind   : Deployment
        Destination     : 127.0.0.1:3000
        Intercepting    : 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.me
        Layer 5 Hostname: verylargejavaservice.default

Wait 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!

The Preview URL now shows exactly what is running on your local laptop -- in a way that can be securely shared with anyone you work with.

Prerequisites
Install the Telepresence CLI
Test Telepresence
Install a sample Java application
Set up a local development environment
Intercept all traffic to the service
Make a code change
Create a Preview URL
What's Next?

Telepresence Quick Start - Java

Contents

Prerequisites

1. Install the Telepresence CLI

2. Test Telepresence

3. Install a sample Java application

4. Set up a local development environment

5. Intercept all traffic to the service

6. Make a code change

7. Create a Preview URL

What's Next?

Collaborating

Outbound Sessions

FAQs