Consul Enterprise Admin Partitions

This topic provides and overview of admin partitions, which are entities that define one or more administrative boundaries for single Consul deployments.

Introduction

Admin partitions exist a level above namespaces in the identity hierarchy. They contain one or more namespaces and allow multiple independent tenants to share a Consul server cluster. As a result, admin partitions enable you to define administrative and communication boundaries between services managed by separate teams or belonging to separate stakeholders. They can also segment production and non-production services within the Consul deployment.

As of Consul v1.11, every datacenter contains a single administrative partition named default when created. With Consul Enterprise, operators have the option of creating multiple partitions within a single datacenter.

There are tutorials available to help you get started with admin partitions.

• Multi-Tenancy with Administrative Partitions
• Multi Cluster Applications with Consul Enterprise Admin Partitions

Default Admin Partition

Each Consul cluster will have a default admin partition named default. The default partition must contain the Consul servers. The default admin partition is different from other partitions that may be created because the namespaces and resources in this partition are replicated between datacenters when they are federated.

Any resource created without specifying an admin partition will inherit the partition of the ACL token used to create the resource.

Naming Admin Partitions

Only characters that are valid in DNS names can be used to name admin partitions. Names must also begin with a lowercase letter.

Namespaces

When an admin partition is created, it will include the default namespace. You can create additional namespaces within the partition. Resources created within a namespace are not shared across partitions.

Cross-datacenter Replication

Only resources in the default admin partition will be replicated to secondary datacenters (also see Known Limitations).

DNS Queries

When queried, the DNS interface returns results for a single admin partition. The query may explicitly specify the admin partition to use in the lookup. If you do not specify an admin partition in the query, the lookup uses the admin partition of the Consul agent that received the query. Server agents always exist within the default admin partition. Client agents are configured to operate within a specific admin partition.

By default, Consul on Kubernetes uses Consul dataplanes instead of client agents to manage communication between service instances. But to use the Consul DNS for service discovery, you must start a Consul client in client admin partitions.

Service Mesh Configurations

The partition in which proxy-defaults and mesh configurations are created define the scope of the configurations. Services registered in a partition will use the proxy-defaults and mesh configurations that have been created in the partition.

Cross-partition Networking

You can configure services to be discoverable by downstream services in any partition within the datacenter. Specify the upstream services that you want to be available for discovery by configuring the exported-services configuration entry in the partition where the services are registered. Refer to the exported-services documentation for details. Additionally, the requests made by downstream applications must have the correct DNS name for the Virtual IP Service lookup to occur. Service Virtual IP lookups allow for communications across Admin Partitions when using Transparent Proxy. Refer to the Service Virtual IP Lookups for Consul Enterprise for additional information.

Cluster Peering

You can use cluster peering between two admin partitions to connect clusters owned by different operators. Without Consul Enterprise, cluster peering is limited to the default partitions in each datacenter. Enterprise users can establish cluster peering connections between any two admin partitions as long as the partitions are in separate datacenters. It is not possible to establish cluster peering connections between two partitions in a single datacenter.

Requirements

Your Consul configuration must meet the following requirements to use admin partitions.

Versions

• Consul 1.11.1 and newer

General Networking Requirements

All Consul clients must be able to initiate Gossip, HTTPS, and RPC connections to the servers. All servers must also be able to initiate Gossip connections to the clients.

For Consul on Kubernetes, a dedicated partition Kubernetes LoadBalancer service is deployed to allow communication from clients to servers for admin partitions support (refer to Kubernetes Requirements for additional information).

For other runtimes, refer to the documentation for your infrastructure environment for instructions on how to allow communication on the following ports:

• 443 (HTTPS API requests)
• 8300 (RPC)
• 8301 (Gossip)
• 8502 (gRPC from Consul Dataplane)

Security Configurations

• The agent token used by the client agent must allow node:write in the admin partition.
• The write permission for proxy-defaults requires mesh:write. See Admin Partition Rules for additional information.
• The write permissions for ingress and terminating gateways require mesh:write privileges.
• Wildcards (*) are not supported for the partition field when creating intentions for admin partitions. The partition name must be explicitly specified.
• With the exception of the default admin partition, ACL rules configured for admin partitions are isolated, so policies defined in partitions outside of the default partition can only reference their local partition.

Agent Configurations

• The admin partition name should be specified in client agent configurations:

  partition = "<NAME>"
  

• The anti-entropy sync will use the configured admin partition name when registering the node.

Kubernetes Requirements

One of the primary use cases for admin partitions is for enabling a service mesh across multiple Kubernetes clusters. The following requirements must be met to create admin partitions on Kubernetes:

• If you are deploying Consul servers on Kubernetes, then ensure that the Consul servers are deployed within the same Kubernetes cluster. Consul servers may be deployed external to Kubernetes and configured using the externalServers stanza.
• Workloads deployed on the same Kubernetes cluster as the Consul Servers must use the default partition. If the workloads are required to run on a non-default partition, then the clients must be deployed in a separate Kubernetes cluster.
• A Consul Enterprise license must be installed on each Kubernetes cluster.
• The helm chart for consul-k8s v0.39.0 or greater.
• Consul 1.11.1-ent or greater.
• A designated Kubernetes LoadBalancer service must be exposed on the Consul server cluster. This enable the following communication channels to the Consul servers:
  • RPC on port 8300
  • Gossip on port 8301
  • HTTPS API requests on port 443 API requests
• Mesh gateways must be deployed as a Kubernetes LoadBalancer service on port 443 across all Kubernetes clusters.
• Cross-partition networking must be implemented as described in Cross-Partition Networking.

Usage

This section describes how to deploy Consul admin partitions to Kubernetes clusters. Refer to the admin partition CLI documentation for information about command line usage.

Deploying Consul with Admin Partitions on Kubernetes

The expected use case is to create admin partitions on Kubernetes clusters. This is because many organizations prefer to use cloud-managed Kubernetes offerings to provision separate Kubernetes clusters for individual teams, business units, or environments. This is opposed to deploying a single, large Kubernetes cluster. Organizations encounter problems, however, when they attempt to use a service mesh to enable multi-cluster use cases, such as administration tasks and communication between nodes.

The following procedure will result in an admin partition in each Kubernetes cluster. The Consul clients running in the cluster with servers will be in the default partition. Another partition called clients will also be created.

Prepare to install Consul across multiple Kubernetes clusters

Verify that your Consul deployment meets the Kubernetes Requirements before proceeding.

1. Verify that your VPC is configured to enable connectivity between the pods running workloads and Consul servers. Refer to your virtual cloud provider's documentation for instructions on configuring network connectivity.

2. Set environment variables to use with shell commands.

   $ export HELM_RELEASE_SERVER=server
   $ export HELM_RELEASE_CLIENT=client
   $ export SERVER_CONTEXT=<context for server, run `kubectl config current-context` for cluster provisioned for servers>
   $ export CLIENT_CONTEXT=<context for workload partition, run `kubectl config current-context` for cluster provisioned for workload partition>
   

3. Create the license secret in server cluster.

   $ kubectl create --context ${SERVER_CONTEXT} namespace consul
   $ kubectl create secret --context ${SERVER_CONTEXT} --namespace consul generic license --from-file=key=./path/to/license.hclic
   

4. Create the license secret in the non-default partition cluster for your workloads. This step must be repeated for every additional non-default partition cluster.

   $ kubectl create --context ${CLIENT_CONTEXT} namespace consul
   $ kubectl create secret --context ${CLIENT_CONTEXT} --namespace consul generic license --from-file=key=./path/to/license.hclic
   

Install the Consul server cluster

1. Set your context to the server cluster.

   $ kubectl config use-context ${SERVER_CONTEXT}
   

2. Create a server configuration values file to override the default Consul Helm chart settings:

   server.yaml

   YAML

   global:
     enableConsulNamespaces: true
     tls:
       enabled: true
     image: hashicorp/consul-enterprise:1.16.3-ent
     adminPartitions:
       enabled: true
     acls:
       manageSystemACLs: true
     enterpriseLicense:
       secretName: license
       secretKey: key
   meshGateway:
     enabled: true
   

   Refer to the Helm Chart Configuration reference for details about the parameters you can specify in the file.

3. Install the Consul server(s) using the values file created in the previous step:

   $ helm install ${HELM_RELEASE_SERVER} hashicorp/consul --version "1.0.0" --create-namespace --namespace consul --values server.yaml
   

4. After the server starts, get the external IP address for partition service so that it can be added to the client configuration (externalServers.hosts). The IP address is used to bootstrap connectivity between servers and workload pods on the non-default partition cluster.

   $ kubectl get services --selector="app=consul,component=server" --namespace consul --output jsonpath="{range .items[*]}{@.status.loadBalancer.ingress[*].ip}{end}"
   34.135.103.67
   

5. Get the Kubernetes authentication method URL for the non-default partition cluster running your workloads:

   $ kubectl config view --output "jsonpath={.clusters[?(@.name=='${CLIENT_CONTEXT}')].cluster.server}"
   

   Use the IP address printed to the console to configure the externalServers.k8sAuthMethodHost parameter in the workload configuration file for your non-default partition cluster running your workloads.

6. Copy the server certificate to the non-default partition cluster running your workloads.

   $ kubectl get secret ${HELM_RELEASE_SERVER}-consul-ca-cert --context ${SERVER_CONTEXT} -n consul --output yaml | kubectl apply --namespace consul --context ${CLIENT_CONTEXT} --filename -
   

7. Copy the server key to the non-default partition cluster running your workloads:

   $ kubectl get secret ${HELM_RELEASE_SERVER}-consul-ca-key --context ${SERVER_CONTEXT} --namespace consul --output yaml | kubectl apply --namespace consul --context ${CLIENT_CONTEXT} --filename -
   

8. If ACLs were enabled in the server configuration values file, copy the token to the non-default partition cluster running your workloads:

   $ kubectl get secret ${HELM_RELEASE_SERVER}-consul-partitions-acl-token --context ${SERVER_CONTEXT} --namespace consul --output yaml | kubectl apply --namespace consul --context ${CLIENT_CONTEXT} --filename -
   

Install on the non-default partition clusters running workloads

1. Switch to the workload non-default partition clusters running your workloads:

   $ kubectl config use-context ${CLIENT_CONTEXT}
   

2. Create a configuration for each non-default admin partition.

   client.yaml

   YAML

   global:
     name: consul
     enabled: false
     enableConsulNamespaces: true
     image: hashicorp/consul-enterprise:1.16.3-ent
     adminPartitions:
       enabled: true
       name: clients
     tls:
       enabled: true
       caCert:
         secretName: server-consul-ca-cert # See step 6 from `Install Consul server cluster`
         secretKey: tls.crt
       caKey:
         secretName: server-consul-ca-key # See step 7 from `Install Consul server cluster`
         secretKey: tls.key
     acls:
       manageSystemACLs: true
       bootstrapToken:
         secretName: server-consul-partitions-acl-token # See step 8 from `Install Consul server cluster`
         secretKey: token
     enterpriseLicense:
       secretName: license
       secretKey: key
   externalServers:
     enabled: true
     hosts: [34.135.103.67] # See step 4 from `Install Consul server cluster`
     tlsServerName: server.dc1.consul
     k8sAuthMethodHost: https://104.154.156.146 # See step 5 from `Install Consul server cluster`
   meshGateway:
     enabled: true
   

3. Install the non-default partition clusters running your workloads:

   $ helm install ${HELM_RELEASE_CLIENT} hashicorp/consul --version "1.0.0" --create-namespace --namespace consul --values client.yaml
   

Verifying the Deployment

You can log into the Consul UI to verify that the partitions appear as expected.

1. Set your context to the server cluster.

   $ kubectl config use-context ${SERVER_CONTEXT}
   

2. If ACLs are enabled, you will need the partitions ACL token, which can be read from the Kubernetes secret. The token is an encoded string that must be decoded in base64, e.g.:

   $ kubectl get secret --namespace consul --context ${SERVER_CONTEXT} --template "{{ .data.token | base64decode }}" ${HELM_RELEASE_SERVER}-consul-bootstrap-acl-token
   

   The example command gets the secret from the default partition cluster, decodes the secret, and prints the token to the console.

3. Open the Consul UI in a browser using the external IP address and port number described in a previous step (see step 4).

4. Click Log in and enter the decoded token when prompted.

You will see the default and clients partitions available in the Admin Partition drop-down menu.

Known Limitations

• Only the default admin partition is supported when federating multiple Consul datacenters in a WAN.
• Admin partitions have no theoretical limit. We intend to conduct a large-scale test to identify a recommended max in the future.