From 113f568509816bc0e86f2eaa63e366116022dfd1 Mon Sep 17 00:00:00 2001 From: Mitchell Hashimoto Date: Thu, 13 Sep 2018 07:12:27 -0700 Subject: [PATCH] website: document k8s go-discover (#4666) This adds documentation for the `k8s` go-discover provider that will be part of 1.2.3. --- .../source/docs/agent/cloud-auto-join.html.md | 37 ++++++++++++++ .../platform/k8s/out-of-cluster-nodes.html.md | 50 +++++++++++++++++++ website/source/layouts/docs.erb | 3 ++ 3 files changed, 90 insertions(+) create mode 100644 website/source/docs/platform/k8s/out-of-cluster-nodes.html.md diff --git a/website/source/docs/agent/cloud-auto-join.html.md b/website/source/docs/agent/cloud-auto-join.html.md index c91e306560..de30ff9e59 100644 --- a/website/source/docs/agent/cloud-auto-join.html.md +++ b/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. diff --git a/website/source/docs/platform/k8s/out-of-cluster-nodes.html.md b/website/source/docs/platform/k8s/out-of-cluster-nodes.html.md new file mode 100644 index 0000000000..529e633344 --- /dev/null +++ b/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. diff --git a/website/source/layouts/docs.erb b/website/source/layouts/docs.erb index 00c474f561..056c553e66 100644 --- a/website/source/layouts/docs.erb +++ b/website/source/layouts/docs.erb @@ -305,6 +305,9 @@ > Helm Chart + > + Out-of-Cluster Nodes + > Consul DNS