website: document k8s go-discover (#4666)

This adds documentation for the `k8s` go-discover provider that will be part of 1.2.3.

website/source/docs/agent/cloud-auto-join.html.md

@@ -326,3 +326,40 @@ $ consul agent -retry-join "provider=packet auth_token=token project=uuid url=..
 - `auth_token` (required) -  the authentication token for packet
 - `url` (optional) - 		 a REST URL for packet
 - `address_type` (optional) - the type of address to check for in this provider  ("private_v4", "public_v4" or "public_v6".                                   Defaults to "private_v4")
+
+
+### Kubernetes (k8s)
+
+The Kubernetes provider finds the IP addresses of pods with the matching
+[label or field selector](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/).
+This is useful for non-Kubernetes agents that are joining a server cluster
+running within Kubernetes.
+
+The pod IP is used by default, which requires that the agent connecting can
+network to the pod IP. The `host_network` boolean can be set to true to use
+the host IP instead, but this requires the agent ports (Gossip, RPC, etc.)
+to be exported to the host as well.
+
+By default, no port is specified. This causes Consul to use the default
+gossip port (default behavior with all join requests). The pod may specify
+the `consul.hashicorp.com/auto-join-port` annotation to set the port. The value
+may be an integer or a named port.
+
+```sh
+$ consul agent -retry-join "provider=k8s label_selector=\"app=consul,component=server\""
+```
+
+```json
+{
+        "retry-join": ["provider=k8s label_selector=..."]
+}
+```
+
+- `provider` (required)	-	the name of the provider ("k8s" is the provider here)
+- `kubeconfig` (optional) 	- 	path to the kubeconfig file. If this isn't
+  set, then in-cluster auth will be attempted. If that fails, the default
+  kubeconfig paths are tried (`$HOME/.kube/config`).
+- `namespace` (optional) -  the namespace to search for pods. If this isn't
+  set, it defaults to all namespaces.
+- `label_selector` (optional) - the label selector for matching pods.
+- `field_selector` (optional) - the field selector for matching pods.

website/source/docs/platform/k8s/out-of-cluster-nodes.html.md

@@ -0,0 +1,50 @@
+---
+layout: "docs"
+page_title: "Out-of-Cluster Nodes - Kubernetes"
+sidebar_current: "docs-platform-k8s-ooc-nodes"
+description: |-
+  Non-Kubernetes nodes can join a Consul cluster running within Kubernetes. These are considered "out-of-cluster" nodes.
+---
+
+# Out-of-Cluster Nodes
+
+Non-Kubernetes nodes can join a Consul cluster running within Kubernetes.
+These are considered "out-of-cluster" nodes.
+
+## Auto-join
+
+The recommended way to join a cluster running within Kubernetes is to
+use the ["k8s" cloud auto-join provider](/docs/agent/cloud-auto-join.html#kubernetes-k8s-).
+
+The auto-join provider dynamically discovers IP addresses to join using
+the Kubernetes API. It authenticates with Kubernetes using a standard
+`kubeconfig` file. This works with all major hosted Kubernetes offerings
+as well as self-hosted installations.
+
+The auto-join string below will join a Consul server cluster that is
+started using the [official Helm chart](/docs/platform/k8s/helm.html):
+
+```sh
+$ consul agent -retry-join 'provider=k8s label_selector="app=consul,component=server"'
+```
+
+By default, Consul will join the default Gossip port. Pods may set an
+annotation `consul.hashicorp.com/auto-join-port` to an integer value or
+a named port to specify the port for the auto-join to return. This enables
+different pods to have different exposed ports.
+
+## Networking
+
+Consul typically requires a fully connected network. Therefore, out-of-cluster
+nodes joining a cluster running within Kubernetes must be able to communicate
+to pod IPs or Kubernetes node IPs via the network.
+
+-> **Consul Enterprise customers** may use
+[network segments](/docs/enterprise/network-segments/index.html) to
+enable non-fully-connected topologies. However, out-of-cluster nodes must still
+be able to communicate with the server pod or host IP addresses.
+
+The auto-join provider discussed above will use pod IPs by default. The
+`host_network=true` setting may be set to use host IPs, however all the ports
+Consul requires must be exposed via a `hostPort`. If no ports are exposed via
+`hostPort`, the pod will not be discovered.

website/source/layouts/docs.erb

@@ -305,6 +305,9 @@
           <li<%= sidebar_current("docs-platform-k8s-helm") %>>
             <a href="/docs/platform/k8s/helm.html">Helm Chart</a>
           </li>
+          <li<%= sidebar_current("docs-platform-k8s-ooc-nodes") %>>
+            <a href="/docs/platform/k8s/out-of-cluster-nodes.html">Out-of-Cluster Nodes</a>
+          </li>
           <li<%= sidebar_current("docs-platform-k8s-dns") %>>
             <a href="/docs/platform/k8s/dns.html">Consul DNS</a>
           </li>