Merge pull request #403 from yidongnan/docs/kubernetes

Document setup for kubernetes

Author: yidongnan

docs/en/client/configuration.md

@@ -52,29 +52,31 @@ grpc.client.__name__.address=static://localhost:9090
 There are a number of supported schemes, that you can use to determine the target server (Priorities 0 (low) - 10
 (high)):
 
-- `static` (Prio 4):
-  A simple static list of IPs (both v4 and v6), that can be use connect to the server (Supports `localhost`).
+- `static` (Prio 4): \
+  A simple static list of IPs (both v4 and v6), that can be use connect to the server (Supports `localhost`). \
   Example: `static://192.168.1.1:8080,10.0.0.1:1337`
-- [`dns`](https://github.com/grpc/grpc-java/blob/master/core/src/main/java/io/grpc/internal/DnsNameResolver.java#L66) (Prio 5):
+- [`dns`](https://github.com/grpc/grpc-java/blob/master/core/src/main/java/io/grpc/internal/DnsNameResolver.java#L66)
+  (Prio 5): \
   Resolves all addresses that are bound to the given DNS name. The addresses will be cached and will only be refreshed
-  if an existing connection is shutdown/fails. More options such as `SVC` lookups (useful for kubernetes) can be enabled
-  via system properties.
-  Example: `dns:///example.my.company`
-- `discovery` (Prio 6):
+  if an existing connection is shutdown/fails. \
+  Example: `dns:///example.my.company` \
+  Notice: There is also a `dns` resolver that is included in grpclb, that has a higher priority (`6`) than the default
+  one and also supports `SVC` lookups. See also [Kubernetes Setup](../kubernetes.md).
+- `discovery` (Prio 6): \
   (Optional) Uses spring-cloud's `DiscoveryClient` to lookup appropriate targets. The connections will be refreshed
   automatically during `HeartbeatEvent`s. Uses the `gRPC.port` metadata to determine the port, otherwise uses the
-  service port.
+  service port. \
   Example: `discovery:///service-name`
-- `self` (Prio 0):
+- `self` (Prio 0): \
   The self address or scheme is a keyword that is available, if you also use `grpc-server-spring-boot-starter` and
   allows you to connect to the server without specifying the own address/port. This is especially useful for tests
-  where you might want to use random server ports to avoid conflicts.
+  where you might want to use random server ports to avoid conflicts. \
   Example: `self` or `self:self`
-- `in-process`:
+- `in-process`: \
   This is a special scheme that will bypass the normal channel factory and will use the `InProcessChannelFactory`
-  instead. Use it to connect to the [`InProcessServer`](../server/configuration.md#enabling-the-inprocessserver).
+  instead. Use it to connect to the [`InProcessServer`](../server/configuration.md#enabling-the-inprocessserver). \
   Example: `in-process:foobar`
-- *custom*:
+- *custom*: \
   You can define custom
   [`NameResolverProvider`s](https://javadoc.io/page/io.grpc/grpc-all/latest/io/grpc/NameResolverProvider.html) those
   will be picked up, by either via Java's `ServiceLoader` or from spring's application context and registered in

docs/en/index.md

@@ -27,5 +27,6 @@ customization you need for your project.
 - [Version Overview](versions.md)
 - [Spring Boot Actuator / Metrics Support](actuator.md)
 - [Brave-Tracing / Spring Cloud Sleuth Support](brave.md)
+- [Kubernetes Setup](kubernetes.md)
 - [Benchmarking](benchmarking.md)
 - [Contributing](contributions.md)

docs/en/kubernetes.md

@@ -0,0 +1,70 @@
+# Kubernetes Setup
+
+The following section assumes that you have at least some knowledge about deploying an application to Kubernetes.
+For more details refer to the [official documentation](https://kubernetes.io/docs/home/)
+
+Kubernetes (or more precisely most of kubernetes DNS provider's) expose enough information for grpc-java to resolve
+the addresses of services that run inside the cluter. Should also work for OKD/OpenShift.
+
+There are a few things you should keep in mind here though.
+
+1. Inside your (target's) deployment, make sure that you expose the port specified by `grpc.server.port`
+   (defaults to `9090`)
+
+````yaml
+[...]
+    spec:
+      containers:
+      - name: my-grpc-server-app
+        image: ...
+        ports:
+        - name: grpc # Use whatever name you want
+          containerPort: 9090 # Use the same as `grpc.server.port` (prefer 80, 443 or 9090)
+[...]
+````
+
+> **Note:** Container ports can be re-used by other deployments/pods, unless you use `hostPort`s.
+> So there is no reason not to use a default one.
+
+2. Inside your (target's) service definition, you should map that port to your preferred port.
+
+````yaml
+apiVersion: v1
+kind: Service
+metadata:
+  name: my-grpc-server-app # This name is important
+  namespace: example # This name might be important
+spec:
+  selector:
+    app: my-grpc-server-app
+  ports:
+    - name: grpclb # The name is important, if you wish to use DNS-SVC-Lookups (must be grpclb)
+      port: 1234 # Remember this port number, unless you use DNS-SVC-Lookups (prefer 80, 443 or 9090)
+      targetPort: grpc # Use the port name from the deployment (or just the port number)
+````
+
+> **Note:** Service ports can be re-used by other services, unless you use `hostPort`s.
+> So there is no reason not to use a default one.
+
+3. Inside your client application config, configure the channel address to refer to the service name:
+
+````properties
+## Choose your matching variant
+# Same namespace (target port=80 or derived by DNS-SVC)
+grpc.clients.my-grpc-server-app.address=dns:///my-grpc-server-app
+# Same namespace (different port)
+grpc.clients.my-grpc-server-app.address=dns:///my-grpc-server-app:1234
+# Different namespace
+grpc.clients.my-grpc-server-app.address=dns:///my-grpc-server-app.example:1234
+# Different cluster
+grpc.clients.my-grpc-server-app.address=dns:///my-grpc-server-app.example.svc.cluster.local:1234
+# Format
+grpc.clients.my-grpc-server-app.address=dns:///<serviceName>[.<namespace>[.<clusterAddress>]][:<service-port>]
+````
+
+> **Note:** DNS-SVC lookups require the `grpclb` dependency to be present and the service's port name to be `grpclb`.
+> Refer to grpc's official docs for more details.
+
+----------
+
+[<- Back to Index](index.md)