Kubernetes Auto-join for Consul

We're releasing HashiCorp Consul + Kubernetes features every week.

This week we're showcasing the auto-join feature to enable nodes running inside and outside of Kubernetes to join a Consul cluster running on Kubernetes. Rather than joining with a static IP address or DNS entry, the auto-join feature uses the Kubernetes API to discover pods running Consul agents and joins those pods.


To learn more about the Kubernetes auto-join provider for Consul, watch the video below or scroll down to read more. The video below shows a non-Kubernetes node automatically joining a Consul cluster running within Kubernetes.

»Auto-join for Kubernetes

Auto-join is a feature that enables Consul to use cloud or platform APIs for finding other Consul agents to join. This solves the problem of having to know the IP address of the initial set of agents to join a cluster. In the case of cloud APIs, hosts can often be tagged with specific values that Consul can use to filter hosts to find running Consul agents.

The Kubernetes auto-join provider uses the Kubernetes API to discover pods running Consul agents that can be joined. This feature can be used by agents both inside and outside of Kubernetes, but is particularly useful for agents running outside of Kubernetes because they cannot use standard Kubernetes service discovery to find the pods.

$ consul agent -retry-join 'provider=k8s label_selector="app=consul,component=server"'

The -retry-join flag above will cause the agent to query Kubernetes for pods labeled with app=consul,component=server and attempt to join those pods using the pod or host IP. If no pods are found, Consul will retry periodically.

Consul authenticates with Kubernetes using a standard kubeconfig file used for authenticating with kubectl. It automatically searches standard locations for this file. This allows the Kubernetes auto-join feature to work with all major hosted Kubernetes offerings.

The Kubernetes auto-join provider supports many configuration options. See the full reference documentation of available configuration options for more information.


The Kubernetes auto-join provider is available in Consul 1.2.3 and later. To learn more, see the auto-join documentation.

We have more exciting Consul + Kubernetes integrations being released in the coming weeks. Please read the Consul and Kubernetes announcement blog post to learn more.

Sign up for the latest HashiCorp news

By submitting this form, you acknowledge and agree that HashiCorp will process your personal information in accordance with the Privacy Policy.