hashicorp / consul-k8s

First-class support for Consul Service Mesh on Kubernetes
Mozilla Public License 2.0
662 stars 315 forks source link
consul gateway gateway-api helm helm-chart ingress kubernetes service-mesh servicemesh vault

Consul logo Consul on Kubernetes

We're looking for feedback on how folks are using Consul on Kubernetes. Please fill out our brief survey!


The consul-k8s-control-plane binary includes first-class integrations between Consul and Kubernetes. The project encapsulates multiple use cases such as syncing services, injecting Consul sidecars, and more. The Kubernetes integrations with Consul are documented directly on the Consul website.

This README will present a basic overview of use cases and installing the Helm charts, but for full documentation please reference the Consul website.

This project is versioned separately from Consul. Supported Consul versions for each feature will be noted below. By versioning this project separately, we can iterate on Kubernetes integrations more quickly and release new versions without forcing Consul users to do a full Consul upgrade.

We take Consul's security and our users' trust very seriously. If you believe you have found a security issue in Consul K8s, please responsibly disclose by contacting us at security@hashicorp.com.



consul-k8s is distributed in multiple forms:


The following pre-requisites must be met before installing Consul on Kubernetes.


The Consul K8s CLI is the easiest way to get up and running with Consul on Kubernetes. See Install Consul on K8s CLI for more details on installation, and refer to Consul on Kubernetes CLI Reference for more details on subcommands and a list of all available flags for each subcommand.

  1. Install the HashiCorp tap, which is a repository of all Homebrew packages for HashiCorp:

    brew tap hashicorp/tap
  1. Install the Consul K8s CLI with hashicorp/tap/consul formula.

    brew install hashicorp/tap/consul-k8s
  2. Issue the install subcommand to install Consul on Kubernetes:

    consul-k8s install 


The Helm chart is ideal for those who prefer to use Helm for automation for either the installation or upgrade of Consul on Kubernetes. The chart supports multiple use cases of Consul on Kubernetes, depending on the values provided. Detailed installation instructions for Consul on Kubernetes are found here.

  1. Add the HashiCorp Helm repository:

    helm repo add hashicorp https://helm.releases.hashicorp.com
  2. Ensure you have access to the Consul Helm chart and you see the latest chart version listed. If you have previously added the HashiCorp Helm repository, run helm repo update.

    helm search repo hashicorp/consul
  3. Now you're ready to install Consul! To install Consul with the default configuration using Helm 3.2 run the following command below. This will create a consul Kubernetes namespace if not already present, and install Consul on the dedicated namespace.

    helm install consul hashicorp/consul --set global.name=consul --create-namespace -n consul

Please see the many options supported in the values.yaml file. These are also fully documented directly on the Consul website.


You can find examples and complete tutorials on how to deploy Consul on Kubernetes using Helm on the HashiCorp Learn website.