Search the Docs

Telepresence Quick Start - Go

Contents

Prerequisites
1. Install the Telepresence CLI
2. Test Telepresence
3. Install a sample Go 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 installed and setup to use a Kubernetes cluster, preferably an empty test cluster.

If you have used Telepresence previously, please first reset your Telepresence deployment with: telepresence uninstall --everything.

1. Install the Telepresence CLI

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

2. Test Telepresence

Telepresence connects your local workstation to a remote Kubernetes cluster.

  1. Connect to the cluster:
    telepresence connect

    $ telepresence connect
    Launching Telepresence Daemon
    ...
    Connected to context default (https://<cluster-public-IP>)
  2. Test that Telepresence is working properly by connecting to the Kubernetes API server:
    curl -ik https://kubernetes.default

    $ 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
    }%

3. Install a sample Go 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.

  1. Start by installing a sample application that consists of multiple services:
    kubectl apply -f https://raw.githubusercontent.com/datawire/edgey-corp-go/main/k8s-config/edgey-corp-web-app-no-mapping.yaml

    $ kubectl apply -f https://raw.githubusercontent.com/datawire/edgey-corp-go/main/k8s-config/edgey-corp-web-app-no-mapping.yaml
    deployment.apps/dataprocessingservice created
    service/dataprocessingservice created
    ...
  2. 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
  3. Once all the pods are in a Running state, go to the frontend service in your browser at http://verylargejavaservice.default:8080.

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

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

    $ git clone https://github.com/datawire/edgey-corp-go.git
    Cloning into 'edgey-corp-go'...
    remote: Enumerating objects: 441, done.
    ...
  2. Change into the repo directory, then into DataProcessingService:
    cd edgey-corp-go/DataProcessingService/

  3. You will use Fresh to support auto reloading of the Go server, which we'll use later. Confirm it is installed by running:
    go get github.com/pilu/fresh
    Then start the Go server:
    $GOPATH/bin/fresh

    $ go get github.com/pilu/fresh
    $ $GOPATH/bin/fresh
    ...
    10:23:41 app | Welcome to the DataProcessingGoService!
  4. In a new terminal window, curl the service running locally to confirm it’s set to blue:
    curl localhost:3000/color

    $ 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:

  1. 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
    State : ACTIVE
    Destination : 127.0.0.1:3000
    Intercepting: all connections
  2. 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.

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.

  1. Open edgey-corp-go/DataProcessingService/main.go in your editor and change var color string from blue to orange. Save the file and the Go server will auto reload.

  2. 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 preview URLs to do selective intercepts, meaning only traffic coming from the preview URL will be intercepted, so you can easily share the services you’re working on with your teammates.

  1. Clean up your previous intercept by removing it:
    telepresence leave dataprocessingservice

  2. Login to Ambassador Cloud, a web interface for managing and sharing preview URLs:
    telepresence login

    This opens your browser; login with your GitHub account and choose your org.

    $ telepresence login
    Launching browser authentication flow...
    <browser opens, login with GitHub>
    Login successful.
  3. Start the intercept again:
    telepresence intercept dataprocessingservice --port 3000
    You will be asked for your ingress; specify the front end service: verylargejavaservice.default
    Then when asked for the port, type 8080.
    Finally, type n for “Use TLS”.

    $ telepresence intercept dataprocessingservice --port 3000
    Confirm the ingress to use for preview URL access
    Ingress service.namespace ? verylargejavaservice.default
    Port ? 8080
    Use TLS y/n ? n
    Using deployment dataprocessingservice
    intercepted
    State : ACTIVE
    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
  4. 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.

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

Questions?

We’re here to help. If you have questions, join our Slack or contact us.