luxolus/open-consul
2
0
Fork 0
Code Issues 1 Pull requests Packages Releases Wiki Activity
open-consul/website/source/docs/platform/k8s/out-of-cluster-nodes.html.md
Iryna Shustava e51e5c0901
Clarify minimum perms required for k8s auto-join
2019-12-06 12:57:47 -08:00

2.2 KiB
Raw Blame History

layout page_title sidebar_current description
docs Out-of-Cluster Nodes - Kubernetes docs-platform-k8s-ooc-nodes 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.

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 token in the kubeconfig file needs to have permissions to list pods in the namespace where Consul servers are deployed.

The auto-join string below will join a Consul server cluster that is started using the official Helm chart:

$ 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 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.