diff --git a/docs/content/feature/grpc-proxy.md b/docs/content/feature/grpc-proxy.md new file mode 100644 index 000000000..e2e597a2c --- /dev/null +++ b/docs/content/feature/grpc-proxy.md @@ -0,0 +1,36 @@ +--- +title: "GRPC Proxy" +since: "1.5.10" +--- + +fabio can run a transparent GRPC proxy which dynamically forwards an incoming +RPC on a given port to services which advertise rpc service or method. To use GRPC +proxy support the service needs to advertise `urlprefix-/my.service/Method proto=grpc` in +Consul. In addition, fabio needs to be configured with a grpc listener: + +``` +fabio -proxy.addr ':1234;proto=grpc' +``` + +As per the HTTP/2 spec, the host header is not required, so host matching is not supported for GRPC proxying. + +GRPC proxy support can be combined with [Certificate Stores](/feature/certificate-stores/) to provide TLS termination on fabio. Configure `proxy.addr` with `proto=grpcs`. + +``` +fabio -proxy.cs 'cs=ssl;type=path;path=/etc/ssl' -proxy.addr ':1234;proto=grpcs;cs=ssl' +``` + +To support TLS upstream servers add the `proto=grpcs` option to the +`urlprefix-` tag. The current implementation uses the clientca specified in the [Certificate Store](/feature/certificate-stores/) for the listener. To disable certificate +validation for a target set the `tlsskipverify=true` option. + +``` +urlprefix-/foo proto=grpcs +urlprefix-/foo proto=grpcs tlsskipverify=true +``` + +For TLS upstream servers (when using the consul registry) fabio will direct your traffic to an advertised service IP. If your service certificate does not contain an IP SAN, the certificate verification will fail. You can set the override the server name in the tls config by setting `grpcservername=` in the `urlprefix-` tag. + +``` +urlprefix-/ proto=grpcs grpcservername=my.service.hostname +``` \ No newline at end of file diff --git a/docs/content/quickstart/_index.md b/docs/content/quickstart/_index.md index 3bc0f6cd2..a1bdd47d8 100644 --- a/docs/content/quickstart/_index.md +++ b/docs/content/quickstart/_index.md @@ -46,6 +46,13 @@ and you need to add a separate `urlprefix-` tag for every `host/path` prefix the # TCP examples urlprefix-:3306 proto=tcp # route external port 3306 + + # GRPC/S examples + urlprefix-/my.service/Method proto=grpc # method specific route + urlprefix-/my.service proto=grpc # service specific route + urlprefix-/my.service proto=grpcs # TLS upstream + urlprefix-/my.service proto=grpcs grpcservername=my.service # TLS upstream with servername override + urlprefix-/my.service proto=grpcs tlsskipverify=true # TLS upstream and self-signed cert ``` 5. Start fabio without a config file diff --git a/docs/content/ref/proxy.addr.md b/docs/content/ref/proxy.addr.md index b11603997..1dc972436 100644 --- a/docs/content/ref/proxy.addr.md +++ b/docs/content/ref/proxy.addr.md @@ -18,6 +18,8 @@ The supported protocols are: * `http` for HTTP based protocols * `https` for HTTPS based protocols +* `grpc` for GRPC based protocols +* `grpcs` for GRPC+TLS based protocols * `tcp` for a raw TCP proxy with or witout TLS support * `tcp+sni` for an SNI aware TCP proxy @@ -76,6 +78,12 @@ to the destination without decrypting the traffic. # HTTPS listener on port 443 with certificate source and TLS options proxy.addr = :443;cs=some-name;tlsmin=tls10;tlsmax=tls11;tlsciphers="0xc00a,0xc02b" + + # GRPC listener on port 8888 + proxy.addr = :8888;proto=grpc + + # GRPCS listener on port 8888 with certificate source + proxy.addr = :8888;proto=grpcs;cs=some-name # TCP listener on port 1234 with port routing proxy.addr = :1234;proto=tcp