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.
- Get a Free Remote Cluster
Sign in to Ambassador Cloud to activate your demo cluster. - 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.
2. Try the Emojivoto application
The remote cluster is running the Emojivoto application, which consists of four services. Test out the application:
Go to the Emojivoto webapp and vote for some emojis.
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.
Run the Docker container locally, by running this command inside your local terminal:
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-demoConnected 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-demoConnected 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#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.VoteDoughnutResolved 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/grpcSent 0 requests and received 0 responsesERROR:Code: UnknownMessage: ERRORIn 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.go3 import (4 "context"5 "fmt" // DELETE THIS LINE67 pb "github.com/buoyantio/emojivoto/emojivoto-voting-svc/gen/proto"and also replace the line
21
:go20 func (pS *PollServiceServer) VoteDoughnut(_ context.Context, _ *pb.VoteRequest) (*pb.VoteResponse, error) {21 return nil, fmt.Errorf("ERROR")22 }with
go20 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 orMenu -> 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.VoteDoughnutResolved method descriptor:rpc VoteDoughnut ( .emojivoto.v1.VoteRequest ) returns ( .emojivoto.v1.VoteResponse );Request metadata to send:(empty)Response headers received:content-type: application/grpcResponse contents:{}Response trailers received:(empty)Sent 0 requests and received 1 response
4. Telepresence intercept
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:8080Using Deployment votinginterceptedIntercept name : votingState : ACTIVEWorkload kind : DeploymentDestination : 127.0.0.1:8081Service Port Identifier: 8080Volume Mount Point : /tmp/telfs-XXXXXXXXXIntercepting : all TCP connectionsNow 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.
First leave the current intercept:
Terminal$ telepresence leave votingThen login to telepresence:
Terminal$ telepresence login --apikey $APIKEYCreate 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:8080To create a preview URL, telepresence needs to know how requests enteryour cluster. Please Confirm 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: ambassador.ambassador]:2/4: What's your ingress' 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 hostname(TLS-SNI, HTTP "Host" header) to be used in requests.[default: ambassador.ambassador]:If you access the Emojivoto webapp application on your remote cluster and vote for the 🍩 emoji, you'll see the bug is still present.
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!