Deploy Consul Enterprise on Kubernetes

This topic describes how to install Consul Enterprise on Kubernetes using the Helm chart. It assumes you are storing your license as a Kubernetes Secret. If you would like to store the enterprise license in Vault, reference Store Enterprise license in Vault.

Requirements

Find the license file that you received in your welcome email. It should have a .hclic extension. You will use the contents of this file to create a Kubernetes secret before installing the Helm chart.

Note

If you cannot find your `.hclic` file, please contact your sales team or Technical Account Manager.

Create Kubernetes secret

Export an environment variable named secret with the contents of your Enterprise license file.

$ secret=$(cat 1931d1f4-bdfd-6881-f3f5-19349374841f.hclic)

Create a Kubernetes secret named consul-ent-license and key key with the value of the license file.

$ kubectl create secret generic consul-ent-license --from-literal="key=${secret}"

Configure Helm chart

In your values.yaml, change the value of global.image to one of the enterprise release tags. Enterprise images end with -ent.

global:
  image: 'hashicorp/consul-enterprise:1.20.0-ent'

Define your Consul Enterprise secret.

If you are using Consul v1.10+, add the name and key of the secret you just created to server.enterpriseLicense.

global:
  image: 'hashicorp/consul-enterprise:1.20.0-ent'
  enterpriseLicense:
    secretName: 'consul-ent-license'
    secretKey: 'key'

If you are using a Consul version older than 1.10, use the following configuration with the name and key of the secret you just created. These values are required on top of your normal configuration.

You must set server.enterpriseLicense.enableLicenseAutoload to false.

global:
  image: 'hashicorp/consul-enterprise:1.8.3-ent'
  enterpriseLicense:
    secretName: 'consul-ent-license'
    secretKey: 'key'
    enableLicenseAutoload: false

Install Consul Enterprise

Now, install Consul Enterprise on your Kubernetes cluster using the updated Helm chart.

$ helm install --wait hashicorp hashicorp/consul --values values.yaml

Note

If you experience errors when deploying or upgrading Consul in a K8s namespace different than the default consul, refer to the following list of technical constraints.

Consul cannot automatically detect its target K8s namespace, and needs it explicitly listed with -namespace in the parameters of Helm or the consul-k8s tool.
Consul needs its target K8s namespace added to the connectInjector.k8sAllowNamspaces Helm chart value. For more information, refer to this specific setting in the Consul Helm chart reference.

Verify installation

Once the cluster is up, you can verify the nodes are running Consul Enterprise by using the consul license get command.

First, forward your local port 8500 to the Consul servers so you can run consul commands locally against the Consul servers in Kubernetes.

$ kubectl port-forward service/hashicorp-consul-server 8500:8500

In a separate tab, run the consul license get command.

$ consul license get
License is valid
License ID: 1931d1f4-bdfd-6881-f3f5-19349374841f
Customer ID: b2025a4a-8fdd-f268-95ce-1704723b9996
Expires At: 2020-03-09 03:59:59.999 +0000 UTC
Datacenter: *
Package: premium
Licensed Features:
        Automated Backups
        Automated Upgrades
        Enhanced Read Scalability
        Network Segments
        Redundancy Zone
        Advanced Network Federation

List the Consul servers. Notice the +ent in the Build column, indicating that the servers are running Consul Enterprise.

$ consul members
Node                                       Address           Status  Type    Build      Protocol  DC   Segment
hashicorp-consul-server-0                  10.60.0.187:8301  alive   server  1.10.0+ent  2         dc1  <all>
hashicorp-consul-server-1                  10.60.1.229:8301  alive   server  1.10.0+ent  2         dc1  <all>
hashicorp-consul-server-2                  10.60.2.197:8301  alive   server  1.10.0+ent  2         dc1  <all>

ACLs enabled

If the commands return the following error message, your Consul deployment likely has ACLs enabled.

Error getting license: invalid character 'r' looking for beginning of value

You need to specify your ACL token when running the license get command. First, assign the ACL token to the CONSUL_HTTP_TOKEN environment variable:

$ export CONSUL_HTTP_TOKEN=$(kubectl get secrets/hashicorp-consul-bootstrap-acl-token --template='{{.data.token | base64decode }}')

Now, the token will be used when running Consul commands.

$ consul license get
License is valid
License ID: 1931d1f4-bdfd-6881-f3f5-19349374841f
Customer ID: b2025a4a-8fdd-f268-95ce-1704723b9996
Expires At: 2020-03-09 03:59:59.999 +0000 UTC
Datacenter: *
Package: premium
Licensed Features:
        Automated Backups
        Automated Upgrades
        Enhanced Read Scalability
        Network Segments
        Redundancy Zone
        Advanced Network Federation