Skip to content

walkthrough: grpcserver

In this walkthrough, you'll

  • Deploy a grpc service to an existing EKS cluster
  • Send a test message to the hosted service over TLS

Prerequsites

The following resources are required prior to deployment:

  • EKS cluster
  • aws-load-balancer-controller
  • external-dns

See echo_server.md and external_dns.md for setup instructions for those resources.

Create an ACM certificate

NOTE: An ACM certificate is required for this demo as the application uses the grpc.secure_channel method.

If you already have an ACM certificate (including wildcard certificates) for the domain you would like to use in this example, you can skip this step.

  • Request a certificate for a domain you own using the steps described in the official AWS ACM documentation.
  • Once the status for the certificate is "Issued" continue to the next step.

Deploy the grpcserver manifests

  1. Deploy all the manifests from GitHub.

    kubectl apply -f https://raw.githubusercontent.com/kubernetes-sigs/aws-load-balancer-controller/main/docs/examples/grpc/grpcserver-namespace.yaml
kubectl apply -f https://raw.githubusercontent.com/kubernetes-sigs/aws-load-balancer-controller/main/docs/examples/grpc/grpcserver-service.yaml
kubectl apply -f https://raw.githubusercontent.com/kubernetes-sigs/aws-load-balancer-controller/main/docs/examples/grpc/grpcserver-deployment.yaml

  2. Confirm that all resources were created.

    kubectl get -n grpcserver all

    You should see the pod, service, and deployment.

    NAME                             READY   STATUS    RESTARTS   AGE
pod/grpcserver-5455b7d4d-jshk5   1/1     Running   0          35m

NAME                 TYPE        CLUSTER-IP   EXTERNAL-IP   PORT(S)     AGE
service/grpcserver   ClusterIP   None         <none>        50051/TCP   77m

NAME                         READY   UP-TO-DATE   AVAILABLE   AGE
deployment.apps/grpcserver   1/1     1            1           77m

NAME                                   DESIRED   CURRENT   READY   AGE
replicaset.apps/grpcserver-5455b7d4d   1         1         1       35m

Customize the ingress for grpcserver

  1. Download the grpcserver ingress manifest.

    wget https://raw.githubusercontent.com/kubernetes-sigs/aws-load-balancer-controller/main/docs/examples/grpc/grpcserver-ingress.yaml

  2. Change the domain name from grpcserver.example.com to your desired domain.

  3. The example manifest assumes that you have tagged your subnets for the aws-load-balancer-controller. Otherwise add your subnets using the alb.ingress.kubernetes.io/subnets annotation.

  4. Deploy the ingress resource for grpcserver.

    kubectl apply -f grpcserver-ingress.yaml

  5. Wait a few minutes for the ALB to provision and for DNS to update.

  6. Check the aws-load-balancer-controller logs to ensure the ALB is created. Also ensure that external-dns creates a DNS record that points your domain to the ALB.

    kubectl logs -n kube-system --tail -1 -l app.kubernetes.io/name=aws-load-balancer-controller | grep 'grpcserver\/grpcserver'
kubectl logs -n kube-system --tail -1 -l app.kubernetes.io/name=external-dns | grep 'YOUR_DOMAIN_NAME'

  7. Next check that your ingress shows the correct ALB address and custom domain name.

    kubectl get ingress -n grpcserver grpcserver

    You should see similar to the following.

    NNAME         CLASS    HOSTS              ADDRESS     PORTS    AGE
grpcserver     alb   YOUR_DOMAIN_NAME   ALB-DNS-NAME   80      90m

  8. Finally, test your secure gRPC service by running the greeter client, substituting YOUR_DOMAIN_NAME for the domain you used in the ingress manifest.

    docker run --rm -it --env BACKEND=YOUR_DOMAIN_NAME placeexchange/grpc-demo:latest python greeter_client.py

    You should see the following response. 

    Greeter client received: Hello, you!