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


The following resources are required prior to deployment:

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

See and 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
    kubectl apply -f
    kubectl apply -f
  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.

  2. Change the domain name from 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 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 | grep 'grpcserver\/grpcserver'
    kubectl logs -n kube-system --tail -1 -l | 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

    You should see the following response.

    Greeter client received: Hello, you!