traefik/docs/user-guide/grpc.md

184 lines
4.2 KiB
Markdown
Raw Normal View History

2018-05-28 09:46:03 +00:00
# gRPC examples
2017-09-16 08:56:02 +00:00
2018-05-28 09:46:03 +00:00
## With HTTP (h2c)
This section explains how to use Traefik as reverse proxy for gRPC application.
2018-10-17 14:24:04 +00:00
### Traefik configuration
2018-05-28 09:46:03 +00:00
2018-10-17 14:24:04 +00:00
At last, we configure our Traefik instance to use both self-signed certificates.
2018-05-28 09:46:03 +00:00
```toml
defaultEntryPoints = ["https"]
[entryPoints]
[entryPoints.http]
address = ":80"
[entryPoints.http]
[api]
[file]
[backends]
[backends.backend1]
[backends.backend1.servers.server1]
# Access on backend with h2c
url = "h2c://backend.local:8080"
[frontends]
[frontends.frontend1]
backend = "backend1"
[frontends.frontend1.routes.test_1]
rule = "Host:frontend.local"
```
2017-09-16 08:56:02 +00:00
!!! warning
2018-05-28 09:46:03 +00:00
For provider with label, you will have to specify the `traefik.protocol=h2c`
### Conclusion
2018-10-17 14:24:04 +00:00
We don't need specific configuration to use gRPC in Traefik, we just need to use `h2c` protocol, or use HTTPS communications to have HTTP2 with the backend.
2018-05-28 09:46:03 +00:00
## With HTTPS
This section explains how to use Traefik as reverse proxy for gRPC application with self-signed certificates.
2017-09-16 08:56:02 +00:00
![gRPC architecture](/img/grpc.svg)
2017-09-16 08:56:02 +00:00
2018-05-28 09:46:03 +00:00
### gRPC Server certificate
In order to secure the gRPC server, we generate a self-signed certificate for backend url:
```bash
openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout ./backend.key -out ./backend.cert
```
That will prompt for information, the important answer is:
```
Common Name (e.g. server FQDN or YOUR name) []: backend.local
```
### gRPC Client certificate
2017-09-16 08:56:02 +00:00
Generate your self-signed certificate for frontend url:
```bash
2017-10-02 09:34:03 +00:00
openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout ./frontend.key -out ./frontend.cert
2017-09-16 08:56:02 +00:00
```
with
```
Common Name (e.g. server FQDN or YOUR name) []: frontend.local
```
2018-10-17 14:24:04 +00:00
### Traefik configuration
2017-09-16 08:56:02 +00:00
2018-10-17 14:24:04 +00:00
At last, we configure our Traefik instance to use both self-signed certificates.
2017-09-16 08:56:02 +00:00
```toml
defaultEntryPoints = ["https"]
2018-05-28 09:46:03 +00:00
# For secure connection on backend.local
rootCAs = [ "./backend.cert" ]
2017-09-16 08:56:02 +00:00
[entryPoints]
[entryPoints.https]
address = ":4443"
[entryPoints.https.tls]
# For secure connection on frontend.local
[[entryPoints.https.tls.certificates]]
certFile = "./frontend.cert"
keyFile = "./frontend.key"
[api]
2017-09-16 08:56:02 +00:00
[file]
[backends]
[backends.backend1]
[backends.backend1.servers.server1]
2018-05-28 09:46:03 +00:00
# Access on backend with HTTPS
url = "https://backend.local:8080"
2017-09-16 08:56:02 +00:00
[frontends]
[frontends.frontend1]
backend = "backend1"
[frontends.frontend1.routes.test_1]
rule = "Host:frontend.local"
```
2017-10-10 10:14:03 +00:00
!!! warning
2018-05-28 09:46:03 +00:00
With some backends, the server URLs use the IP, so you may need to configure `insecureSkipVerify` instead of the `rootCAS` to activate HTTPS without hostname verification.
2017-10-10 10:14:03 +00:00
2018-05-28 09:46:03 +00:00
### A gRPC example in go (modify for https)
2017-09-16 08:56:02 +00:00
2018-05-28 09:46:03 +00:00
We use the gRPC greeter example in [grpc-go](https://github.com/grpc/grpc-go/tree/master/examples/helloworld)
2017-09-16 08:56:02 +00:00
2018-05-28 09:46:03 +00:00
!!! warning
In order to use this gRPC example, we need to modify it to use HTTPS
2017-09-16 08:56:02 +00:00
2018-05-28 09:46:03 +00:00
So we modify the "gRPC server example" to use our own self-signed certificate:
2017-09-16 08:56:02 +00:00
```go
// ...
2018-05-28 09:46:03 +00:00
// Read cert and key file
BackendCert, _ := ioutil.ReadFile("./backend.cert")
BackendKey, _ := ioutil.ReadFile("./backend.key")
// Generate Certificate struct
cert, err := tls.X509KeyPair(BackendCert, BackendKey)
2017-09-16 08:56:02 +00:00
if err != nil {
2018-05-28 09:46:03 +00:00
log.Fatalf("failed to parse certificate: %v", err)
2017-09-16 08:56:02 +00:00
}
2018-05-28 09:46:03 +00:00
// Create credentials
creds := credentials.NewServerTLSFromCert(&cert)
// Use Credentials in gRPC server options
serverOption := grpc.Creds(creds)
var s *grpc.Server = grpc.NewServer(serverOption)
2017-09-16 08:56:02 +00:00
defer s.Stop()
2017-10-02 09:34:03 +00:00
pb.RegisterGreeterServer(s, &server{})
2017-09-16 08:56:02 +00:00
err := s.Serve(lis)
// ...
```
2018-10-17 14:24:04 +00:00
Next we will modify gRPC Client to use our Traefik self-signed certificate:
2017-09-16 08:56:02 +00:00
```go
// ...
// Read cert file
2017-10-02 09:34:03 +00:00
FrontendCert, _ := ioutil.ReadFile("./frontend.cert")
2017-09-16 08:56:02 +00:00
// Create CertPool
roots := x509.NewCertPool()
roots.AppendCertsFromPEM(FrontendCert)
// Create credentials
credsClient := credentials.NewClientTLSFromCert(roots, "")
// Dial with specific Transport (with credentials)
2017-10-02 09:34:03 +00:00
conn, err := grpc.Dial("frontend.local:4443", grpc.WithTransportCredentials(credsClient))
2017-09-16 08:56:02 +00:00
if err != nil {
2017-10-02 09:34:03 +00:00
log.Fatalf("did not connect: %v", err)
2017-09-16 08:56:02 +00:00
}
defer conn.Close()
2017-10-02 09:34:03 +00:00
client := pb.NewGreeterClient(conn)
2017-09-16 08:56:02 +00:00
name := "World"
2017-10-02 09:34:03 +00:00
r, err := client.SayHello(context.Background(), &pb.HelloRequest{Name: name})
2017-09-16 08:56:02 +00:00
// ...
```