Deploy a gRPC-based application on an Amazon EKS cluster and access it with an Application Load Balancer
Created by Kirankumar Chandrashekar (AWS) and Huy Nguyen (AWS)
Code repository: grpc-traffic-on-alb-to-eks | Environment: PoC or pilot | Technologies: Containers & microservices; Content delivery; Web & mobile apps |
Workload: All other workloads | AWS services: Amazon EKS; Elastic Load Balancing (ELB) |
Summary
This pattern describes how to host a gRPC-based application on an Amazon Elastic Kubernetes Service (Amazon EKS) cluster and securely access it through an Application Load Balancer.
gRPC
This pattern shows you how to host a gRPC-based application that runs on Kubernetes pods on Amazon EKS. The gRPC client connects to an Application Load Balancer through the HTTP/2 protocol with an SSL/TLS encrypted connection. The Application Load Balancer forwards traffic to the gRPC application that runs on Amazon EKS pods. The number of gRPC pods can be automatically scaled based on traffic by using the Kubernetes Horizontal Pod Autoscaler. The Application Load Balancer's target group performs health checks on the Amazon EKS nodes, evaluates if the target is healthy, and forwards traffic only to healthy nodes.
Prerequisites and limitations
Prerequisites
An active AWS account.
Docker
, installed and configured on Linux, macOS, or Windows. AWS Command Line Interface (AWS CLI) version 2, installed and configured on Linux, macOS, or Windows.
eksctl
, installed and configured on Linux, macOS, or Windows. kubectl
, installed and configured to access resources on your Amazon EKS cluster. For more information, see Installing or updating kubectl in the Amazon EKS documentation.gRPCurl
, installed and configured. A new or existing Amazon EKS cluster. For more information, see Getting started with Amazon EKS.
Your computer terminal configured to access the Amazon EKS cluster. For more information, see Configure your computer to communicate with your cluster in the Amazon EKS documentation.
AWS Load Balancer Controller, provisioned in the Amazon EKS cluster.
An existing DNS host name with a valid SSL or SSL/TLS certificate. You can obtain a certificate for your domain by using AWS Certificate Manager (ACM) or uploading an existing certificate to ACM. For more information about these two options, see Requesting a public certificate and Importing certificates into AWS Certificate Manager in the ACM documentation.
Architecture
The following diagram shows the architecture implemented by this pattern.
![Architecture for gRPC-based application on Amazon EKS](/images/prescriptive-guidance/latest/patterns/images/pattern-img/abf727c1-ff8b-43a7-923f-bce825d1b459/images/281936fa-bc43-4b4e-a343-ba1eab97df38.png)
The following diagram shows a workflow where SSL/TLS traffic is received from a gRPC client that offloads to an Application Load Balancer. Traffic is forwarded in plaintext to the gRPC server because it comes from a virtual private cloud (VPC).
![Workflow for sending SSL/TLS traffic to a gRPC server](/images/prescriptive-guidance/latest/patterns/images/pattern-img/abf727c1-ff8b-43a7-923f-bce825d1b459/images/09e0c3f6-0c39-40b7-908f-8c4c693a5f02.png)
Tools
AWS services
AWS Command Line Interface (AWS CLI) is an open-source tool that helps you interact with AWS services through commands in your command line shell.
Elastic Load Balancing distributes incoming application or network traffic across multiple targets. For example, you can distribute traffic across Amazon Elastic Compute Cloud (Amazon EC2) instances, containers, and IP addresses in one or more Availability Zones.
Amazon Elastic Container Registry (Amazon ECR) is a managed container image registry service that’s secure, scalable, and reliable.
Amazon Elastic Kubernetes Service (Amazon EKS) helps you run Kubernetes on AWS without needing to install or maintain your own Kubernetes control plane or nodes.
Tools
eksctl
is a simple CLI tool for creating clusters on Amazon EKS. kubectl
is a command line utility for running commands against Kubernetes clusters. AWS Load Balancer Controller helps you manage AWS Elastic Load Balancers for a Kubernetes cluster.
gRPCurl
is a command line tool that helps you interact with gRPC services.
Code repository
The code for this pattern is available in the GitHub grpc-traffic-on-alb-to-eks
Epics
Task | Description | Skills required |
---|---|---|
Create an Amazon ECR repository. | Sign in to the AWS Management Console, open the Amazon ECR console You can also create an Amazon ECR repository with AWS CLI by running the following command:
| Cloud administrator |
Build the Docker image. |
| DevOps engineer |
Push the Docker image to Amazon ECR. |
| DevOps engineer |
Task | Description | Skills required |
---|---|---|
Modify the values in the Kubernetes manifest file. |
| DevOps engineer |
Deploy the Kubernetes manifest file. | Deploy the
| DevOps engineer |
Task | Description | Skills required |
---|---|---|
Record the FQDN for the Application Load Balancer. |
| DevOps engineer |
Task | Description | Skills required |
---|---|---|
Test the gRPC server. | Use gRPCurl to test the endpoint by running the following command:
Note: Replace | DevOps engineer |
Test the gRPC server using a gRPC client. | In the The following code sample shows the response from the gRPC server for the client's request:
This shows that the client can talk to the server and that the connection is successful. | DevOps engineer |
Task | Description | Skills required |
---|---|---|
Remove the DNS record. | Remove the DNS record that points to the Application Load Balancer's FQDN that you created earlier. | Cloud administrator |
Remove the load balancer. | On the Amazon EC2 console | Cloud administrator |
Delete the Amazon EKS cluster. | Delete the Amazon EKS cluster by using
| AWS DevOps |
Related resources
Additional information
Sample ingress resource:
--- apiVersion: networking.k8s.io/v1 kind: Ingress metadata: annotations: alb.ingress.kubernetes.io/healthcheck-protocol: HTTP alb.ingress.kubernetes.io/ssl-redirect: "443" alb.ingress.kubernetes.io/backend-protocol-version: "GRPC" alb.ingress.kubernetes.io/listen-ports: '[{"HTTP": 80}, {"HTTPS":443}]' alb.ingress.kubernetes.io/scheme: internet-facing alb.ingress.kubernetes.io/target-type: ip alb.ingress.kubernetes.io/certificate-arn: arn:aws:acm:<AWS-Region>:<AccountId>:certificate/<certificate_ID> alb.ingress.kubernetes.io/healthcheck-protocol: HTTP labels: app: grpcserver environment: dev name: grpcserver namespace: grpcserver spec: ingressClassName: alb rules: - host: grpc.example.com # <----- replace this as per your host name for which the SSL certtficate is available in ACM http: paths: - backend: service: name: grpcserver port: number: 9000 path: / pathType: Prefix
Sample deployment resource:
apiVersion: apps/v1 kind: Deployment metadata: name: grpcserver namespace: grpcserver spec: selector: matchLabels: app: grpcserver replicas: 1 template: metadata: labels: app: grpcserver spec: containers: - name: grpc-demo image: <your_aws_account_id>.dkr.ecr.us-east-1.amazonaws.com/helloworld-grpc:1.0 #<------- Change to the URI that the Docker image is pushed to imagePullPolicy: Always ports: - name: grpc-api containerPort: 9000 env: - name: POD_IP valueFrom: fieldRef: fieldPath: status.podIP restartPolicy: Always
Sample output:
NAME CLASS HOSTS Address PORTS AGE grpcserver <none> <DNS-HostName> <ELB-address> 80 27d