5 min • read

Telepresence Quick Start - Go

This guide provides you with a hands-on tutorial with Telepresence and Golang. To go through this tutorial, the only thing you'll need is a computer that runs Docker Desktop >=20.10.7. We'll give you a pre-configured remote Kubernetes cluster and a Docker container to run locally.

If you don't have Docker Desktop already installed, go to the Docker download page and install Docker.

1. Get a free remote cluster

Telepresence connects your local workstation with a remote Kubernetes cluster. In this tutorial, you'll start with a pre-configured, remote cluster.

  1. Get a Free Remote Cluster
    Sign in to Ambassador Cloud to activate your demo cluster.
  2. Go to the Service Catalog to see all the services deployed on your cluster.The Service Catalog gives you a consolidated view of all your services across development, staging, and production. After exploring the Service Catalog, continue with this tutorial to test the application in your demo cluster.
Wait! The rest of this quick start requires a remote Kubernetes cluster. Before continuing, activate a free demo cluster in step 1 above.

2. Try the Emojivoto application

The remote cluster is running the Emojivoto application, which consists of four services. Test out the application:

  1. Go to the Emojivoto webapp and vote for some emojis.

  2. Now, click on the 🍩 emoji. You'll see that a bug is present, and voting 🍩 doesn't work.

3. Run the Docker container

The bug is present in the voting-svc service, you'll run that service locally. To save your time, we prepared a Docker container with this service running and all you'll need to fix the bug.

  1. Run the Docker container locally:

    GNU/Linux
    Terminal
    $ docker run -p8083:8083 --name voting-demo --cap-add=NET_ADMIN --device /dev/net/tun:/dev/net/tun --pull always --rm -it -e AMBASSADOR_API_KEY= -v $(if [[ "${XDG_CONFIG_HOME}" ]]; then echo "${XDG_CONFIG_HOME}"; else echo "$HOME/.config"; fi):/root/.host_config datawire/telepresence-emojivoto-go-demo
    Connected to context telepresence-demo (https://$DEMO_CLUSTER_IP)
    emoji : ready to intercept (traffic-agent not yet installed)
    web : ready to intercept (traffic-agent not yet installed)
    voting : ready to intercept (traffic-agent not yet installed)
    web-app-778477c59c: ready to intercept (traffic-agent not yet installed)
    root@/opt/emojivoto#
    macOS
    Terminal
    $ docker run -p8083:8083 --name voting-demo --cap-add=NET_ADMIN --device /dev/net/tun:/dev/net/tun --pull always --rm -it -e AMBASSADOR_API_KEY= -v ~/Library/Application\ Support:/root/.host_config datawire/telepresence-emojivoto-go-demo
    Connected to context telepresence-demo (https://$DEMO_CLUSTER_IP)
    emoji : ready to intercept (traffic-agent not yet installed)
    web : ready to intercept (traffic-agent not yet installed)
    voting : ready to intercept (traffic-agent not yet installed)
    web-app-778477c59c: ready to intercept (traffic-agent not yet installed)
    root@/opt/emojivoto#
    Windows
    Terminal
    $ IF %AppData%=="" (docker run -p8083:8083 --name voting-demo --cap-add=NET_ADMIN --device /dev/net/tun:/dev/net/tun --pull always --rm -it -e AMBASSADOR_API_KEY= -v %userprofile%\AppData\Roaming:/root/.host_config datawire/telepresence-emojivoto-go-demo) ELSE (docker run -p8083:8083 --name voting-demo --cap-add=NET_ADMIN --device /dev/net/tun:/dev/net/tun --pull always --rm -it -e AMBASSADOR_API_KEY= -v %AppData%:/root/.host_config datawire/telepresence-emojivoto-go-demo)
    Connected to context telepresence-demo (https://$DEMO_CLUSTER_IP)
    emoji : ready to intercept (traffic-agent not yet installed)
    web : ready to intercept (traffic-agent not yet installed)
    voting : ready to intercept (traffic-agent not yet installed)
    web-app-778477c59c: ready to intercept (traffic-agent not yet installed)
    root@/opt/emojivoto#
  2. The application is failing due to a little bug inside this service which uses gRPC to communicate with the others services. We can use grpcurl to test the gRPC endpoint and see the error by running:

    Terminal
    $ grpcurl -v -plaintext -import-path ./proto -proto Voting.proto localhost:8081 emojivoto.v1.VotingService.VoteDoughnut
    Resolved method descriptor:
    rpc VoteDoughnut ( .emojivoto.v1.VoteRequest ) returns ( .emojivoto.v1.VoteResponse );
    Request metadata to send:
    (empty)
    Response headers received:
    (empty)
    Response trailers received:
    content-type: application/grpc
    Sent 0 requests and received 0 responses
    ERROR:
    Code: Unknown
    Message: ERROR
  3. In order to fix the bug, use the Docker container's embedded IDE to fix this error. Go to http://localhost:8083 and open api/api.go. Remove the "fmt" package by deleting the line 5.

    go
    3 import (
    4 "context"
    5 "fmt" // DELETE THIS LINE
    6
    7 pb "github.com/buoyantio/emojivoto/emojivoto-voting-svc/gen/proto"

    and also replace the line 21:

    go
    20 func (pS *PollServiceServer) VoteDoughnut(_ context.Context, _ *pb.VoteRequest) (*pb.VoteResponse, error) {
    21 return nil, fmt.Errorf("ERROR")
    22 }

    with

    go
    20 func (pS *PollServiceServer) VoteDoughnut(_ context.Context, _ *pb.VoteRequest) (*pb.VoteResponse, error) {
    21 return pS.vote(":doughnut:")
    22 }

    Then save the file (Ctrl+s for Windows, Cmd+s for Mac or Menu -> File -> Save) and verify that the error is fixed now:

    Terminal
    $ grpcurl -v -plaintext -import-path ./proto -proto Voting.proto localhost:8081 emojivoto.v1.VotingService.VoteDoughnut
    Resolved method descriptor:
    rpc VoteDoughnut ( .emojivoto.v1.VoteRequest ) returns ( .emojivoto.v1.VoteResponse );
    Request metadata to send:
    (empty)
    Response headers received:
    content-type: application/grpc
    Response contents:
    {
    }
    Response trailers received:
    (empty)
    Sent 0 requests and received 1 response

4. Telepresence intercept

  1. Now the bug is fixed, you can use Telepresence to intercept all the traffic through our local service. Run the following command inside the container:

    Terminal
    $ telepresence intercept voting --port 8081:8080
    Using Deployment voting
    intercepted
    Intercept name : voting
    State : ACTIVE
    Workload kind : Deployment
    Destination : 127.0.0.1:8081
    Service Port Identifier: 8080
    Volume Mount Point : /tmp/telfs-XXXXXXXXX
    Intercepting : all TCP connections

    Now you can go back to Emojivoto webapp and you'll see that voting for 🍩 woks as expected.

You have created an intercept to tell Telepresence where to send traffic. The voting-svc traffic is now destined to the local Dockerized version of the service. This intercepts all the traffic to the local voting-svc service, which has been fixed with the Telepresence intercept.

5. Telepresence intercept with a preview URL

Preview URLs allows you to safely share your development environment. With this approach, you can try and test your local service more accurately because you have a total control about which traffic is handled through your service, all of this thank to the preview URL.

  1. First leave the current intercept:

    Terminal
    $ telepresence leave voting
  2. Then login to telepresence:

    Terminal
    $ telepresence login --apikey $APIKEY
  3. Create an intercept, which will tell Telepresence to send traffic to the service in our container instead of the service in the cluster. When prompted for ingress configuration, all default values should be correct as displayed below.

    Terminal
    $ telepresence intercept voting --port 8081:8080
    To create a preview URL, telepresence needs to know how cluster
    ingress works for this service. Please Select the ingress to use.
    1/4: What's your ingress' layer 3 (IP) address?
    You may use an IP address or a DNS name (this is usually a
    "service.namespace" DNS name).
    [default: ambassador.ambassador]:
    2/4: What's your ingress' layer 4 address (TCP port number)?
    [default: 80]:
    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 layer 5 hostname
    (TLS-SNI, HTTP "Host" header) to access this service.
    [default: ambassador.ambassador]:
  4. If you access the Emojivoto webapp application on your remote cluster and vote for the 🍩 emoji, you'll see the bug is still present.

  5. Vote for the 🍩 emoji using the Preview URL obtained in the previous step, and you will see that the bug is fixed, since traffic is being routed to the fixed version which is running locally.

What's Next?

You've intercepted a service in one of our demo clusters, now you can use Telepresence to intercept a service in your own environment!