Skip to content

Commit 2023afc

Browse files
xWinkShawn Kaplan
xWink
and
Shawn Kaplan
authored
Added GRPCRoute docs (#364)
* Added GRPCRoute docs --------- Co-authored-by: Shawn Kaplan <kapshawn@amazon.com>
1 parent abbd1e9 commit 2023afc

File tree

2 files changed

+200
-0
lines changed

2 files changed

+200
-0
lines changed

‎docs/grpc.md‎

Lines changed: 127 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,127 @@
1+
# GRPCRoute Support
2+
3+
## What is `GRPCRoute`?
4+
5+
The `GRPCRoute` is a custom resource defined in the Gateway API that specifies how gRPC traffic should be routed.
6+
It allows you to set up routing rules based on various match criteria, such as service names and methods.
7+
With `GRPCRoute`, you can ensure that your gRPC traffic is directed to the appropriate backend services in a
8+
Kubernetes environment.
9+
10+
For a detailed reference on `GRPCRoute` from the Gateway API, please check the official
11+
[Gateway API documentation](https://gateway-api.sigs.k8s.io/references/spec/#networking.x-k8s.io/v1alpha2.GRPCRoute).
12+
13+
## Setting up a HelloWorld gRPC Server
14+
15+
In this section, we'll walk you through deploying a simple "HelloWorld" gRPC server and setting up the required
16+
routing rules using the Gateway API.
17+
18+
### Deploying the Necessary Resources
19+
20+
1. **Apply the Gateway Configuration**:
21+
22+
This YAML file contains the definition for a gateway with an HTTPS listener.
23+
```
24+
kubectl apply -f examples/my-hotel-gateway-multi-listeners.yaml
25+
```
26+
27+
2. **Deploy the gRPC Server**:
28+
29+
Deploy the example gRPC server which will respond to the SayHello gRPC request.
30+
```
31+
kubectl apply -f examples/greeter-grpc-server.yaml
32+
```
33+
34+
3. **Set Up the gRPC Route**:
35+
36+
This YAML file contains the `GRPCRoute` resource which directs the gRPC traffic to our example server.
37+
```
38+
kubectl apply -f examples/greeter-grpc-route.yaml
39+
```
40+
41+
4. **Verify the Deployment**:
42+
43+
Check to make sure that our gRPC server pod is running and get its name.
44+
```
45+
kubectl get pods -A
46+
```
47+
48+
### Testing the gRPC Server
49+
50+
1. **Access the gRPC Server Pod**:
51+
52+
Copy the name of the pod running the `greeter-grpc-server` and use it to access the pod's shell.
53+
```
54+
kubectl exec -it <name-of-grpc-server-pod> -- bash
55+
```
56+
57+
2. **Prepare the Test Client**:
58+
59+
Inside the pod shell, create a test client by pasting the provided Go code.
60+
```bash
61+
cat << EOF > test.go
62+
package main
63+
64+
import (
65+
"crypto/tls"
66+
"log"
67+
"os"
68+
69+
"golang.org/x/net/context"
70+
"google.golang.org/grpc"
71+
"google.golang.org/grpc/credentials"
72+
pb "google.golang.org/grpc/examples/helloworld/helloworld"
73+
)
74+
75+
func main() {
76+
if len(os.Args) < 3 {
77+
log.Fatalf("Usage: %s <address> <port>", os.Args[0])
78+
}
79+
80+
address := os.Args[1] + ":" + os.Args[2]
81+
82+
// Create a connection with insecure TLS (no server verification).
83+
creds := credentials.NewTLS(&tls.Config{
84+
InsecureSkipVerify: true,
85+
})
86+
conn, err := grpc.Dial(address, grpc.WithTransportCredentials(creds))
87+
if err != nil {
88+
log.Fatalf("did not connect: %v", err)
89+
}
90+
defer conn.Close()
91+
c := pb.NewGreeterClient(conn)
92+
93+
// Contact the server and print out its response.
94+
name := "world"
95+
if len(os.Args) > 3 {
96+
name = os.Args[3]
97+
}
98+
r, err := c.SayHello(context.Background(), &pb.HelloRequest{Name: name})
99+
if err != nil {
100+
log.Fatalf("could not greet: %v", err)
101+
}
102+
log.Printf("Greeting: %s", r.Message)
103+
}
104+
EOF
105+
```
106+
107+
3. **Run the Test Client**:
108+
109+
Execute the test client, making sure to replace `<SERVICE DNS>` with the VPC Lattice service DNS and `<PORT>`
110+
with the port your Lattice listener uses (in this example, we use 443).
111+
```bash
112+
go run test.go <SERVICE DNS> <PORT>
113+
```
114+
115+
### Expected Output
116+
117+
If everything is set up correctly, you should see the following output:
118+
119+
```
120+
Greeting: Hello world
121+
```
122+
123+
This confirms that our gRPC request was successfully routed through VPC Lattice and processed by our `greeter-grpc-server`.
124+
125+
---
126+
127+
We hope this guide helps you get started with using `GRPCRoute` in the EKS Controller project!

‎docs/reference/grpc-route.md‎

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
# GRPCRoute API Reference
2+
3+
## Introduction
4+
5+
With integration of the Gateway API, the EKS Controller project supports `GRPCRoute`.
6+
This allows you to specifically define and manage the routing of gRPC traffic within your Kubernetes cluster.
7+
8+
### GRPCRoute Key Features & Limitations:
9+
10+
**Features**:
11+
12+
- **Routing Traffic**: Enables routing gRPC traffic to servers within your Kubernetes cluster.
13+
- **Service and Method Matching**: The `GRPCRoute` allows for matching by:
14+
- An exact gRPC service and method.
15+
- An exact gRPC service without specifying a method.
16+
- All gRPC services and methods.
17+
- **Header Matching**: Enables matching based on specific headers in the gRPC request.
18+
19+
**Limitations**:
20+
21+
- **Listener Protocol**: The `GRPCRoute` sectionName must refer to an HTTPS listener in the parent `Gateway`.
22+
- **Service Export**: The `GRPCRoute` does not support integration with `ServiceExport`.
23+
- **Method Matches**: One method match is allowed within a single rule.
24+
- **Header Matches Limit**: A maximum of 5 header matches per rule is supported.
25+
- **No Method Without Service**: Matching only by a gRPC method without specifying a service is not supported.
26+
- **Case Insensitivity**: All method matches are currently case-insensitive.
27+
28+
## Example Configuration:
29+
30+
Here is a sample configuration that demonstrates how to set up a `GRPCRoute` for a HelloWorld gRPC service:
31+
32+
```yaml
33+
apiVersion: gateway.networking.k8s.io/v1alpha2
34+
kind: GRPCRoute
35+
metadata:
36+
name: greeter-grpc-route
37+
spec:
38+
parentRefs:
39+
- name: my-hotel
40+
sectionName: https
41+
rules:
42+
- matches:
43+
- headers:
44+
- name: testKey1
45+
value: testValue1
46+
backendRefs:
47+
- name: greeter-grpc-server
48+
kind: Service
49+
port: 50051
50+
weight: 10
51+
- matches:
52+
- method:
53+
service: helloworld.Greeter
54+
method: SayHello
55+
backendRefs:
56+
- name: greeter-grpc-server
57+
kind: Service
58+
port: 443
59+
```
60+
61+
In this example:
62+
63+
- The `GRPCRoute` is named `greeter-grpc-route` and is associated with a parent gateway named `my-hotel` that has
64+
a section named `https`.
65+
- The first routing rule is set up to forward traffic to a backend service named `greeter-grpc-server` on port `50051`.
66+
The rule also specifies a header match condition, where traffic must have a header with the name `testKey1` and
67+
value `testValue1` for the routing rule to apply.
68+
- The second rule matches gRPC traffic for the service `helloworld.Greeter` and method `SayHello`, forwarding it to
69+
the `greeter-grpc-server` on port `443`.
70+
71+
---
72+
73+
This `GRPCRoute` documentation provides a detailed introduction, feature set, and a basic example of how to configure and use the resource within the EKS Controller project. For in-depth details and specifications, you can refer to the official [Gateway API documentation](https://gateway-api.sigs.k8s.io/references/spec/#networking.x-k8s.io/v1alpha2.GRPCRoute).

0 commit comments

Comments
 (0)