»Consul Enterprise Admin Partitions
This feature requires Consul Enterprise with the Governance and Policy module.
This topic provides and overview of admin partitions, which are entities that define one or more administrative boundaries for single Consul deployments.
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.
Preexisting resource nodes and namespaces: Admin partitions were introduced in Consul 1.11. Resource nodes were not namespaced prior to 1.11. After upgrading to Consul 1.11 or later, all resource nodes will be namespaced.
»Default Admin Partition
Each Consul cluster will have at least one default admin partition (named
default). Any resource created without specifying an admin partition will inherit the partition of the ACL token.
default admin partition is special in that it may contain namespaces and other entities that are replicated between datacenters.
Preexisting resources and the
default partition: Admin partitions were introduced in Consul 1.11. After upgrading to Consul 1.11 or later, the
default partition will contain all resources created in previous versions.
»Naming Admin Partitions
Only characters that are valid in DNS names can be used to name admin partitions. Names must also start with a letter.
When an admin partition is created, it will include a
default namespace. You can create additional namespaces within the partition.
All namespaces must exist within an admin partition. By extension, the partition will also contain all namespaced resources.
Within a single datacenter, a namespace in one admin partition is logically separate from any other namespace with the same name in other admin partitions.
Only resources in the default admin partition will be replicated to secondary datacenters.
Client agents will be configured to operate within a specific admin partition. The DNS interface will only return results for the admin partition within the scope of the client.
»Service Mesh Configurations
Values specified for
proxy-defaults configurations are scoped to a specific partition. Services registered in the partition will use the partition's
Your Consul configuration must meet the following requirements to use admin partitions.
- Consul 1.11.0 and newer
- The agent token used by the client agent will need to allow
node:writein the admin partition.
mesh:write. See Admin Partition Rules for additional information.
writepermissions for ingress and terminating gateways require
- Wildcards (
*) are not supported when creating intentions for admin partitions, but you can use a wildcard to specify services within a partition.
In client agent configurations, the admin partition name should be specified in the agent configuration:
partition = "<NAME>"
The anti-entropy sync will use the configured admin partition name when registering the node.
One of the primary use cases for admin partitions is for enabling a service mesh on Kubernetes clusters. The following requirements must be met to create admin partitions on Kubernetes:
- Two or more Kubernetes clusters with Consul servers installed on one of them. The other clusters should run Consul clients.
- A Consul Enterprise license must be installed on each instance of Consul.
- The helm chart consul-k8s v0.34.1 or greater.
- Consul 1.11.0-ent-alpha or greater.
- All instances in the VPC must be able to communicate with each other.
- Pods must be able to communicate with each other (flat pod and node network). See step 3 in the Deploying Consul with Admin Partitions on Kubernetes section for additional information
This section describes how to deploy Consul admin partitions to Kubernetes clusters, as well as directs you to the CLI reference for interacting with the admin partitions API on the command line.
»Deploying Consul with Admin Partitions on Kubernetes
The expected use case 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. When these organizations attempt to use a service mesh to enable cross-cluster activities, such as administration tasks and communication between nodes, they encounter problems.
The following procedure will result in different admin partitions 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.
Verify that your Consul deployment meets the Kubernetes Requirements before proceeding.
- Update the firewall rules to ensure the pod network is flat. The following example for Google Kubernetes Engine (GKE) describes how to create a firewall rule that allows all pod and node network traffic to talk to the server and workload nodegroups:
Open the VPC Network > Firewall section and identify the rules associated with your clusters. The cluster name is a part of the rule.
gke-cluster-2-48d3bee6-nodelabels are the node names for the GKE clusters.
10.128.0.0/9IP range represents the node IP network. The IP range of the node VMs in the clusters are within this range.
10.4.0.0/14IP ranges are the pod IP ranges for the GKE clusters.
gke-cluster-2-48d3bee6-nodenode names in the target fields of the firewall rule.
10.4.0.0/14IP into the source fields. This will ensure that traffic from the nodes and the pods in each cluster can access the nodes and pods in the other.
Create the license secret in each cluster, e.g.:
kubectl create secret generic license --from-file=key=[license file path i.e. ./license.hclic]
This step must also be completed for each workload cluster.
Create a server configuration file to override the default Consul Helm chart settings:
global:enableConsulNamespaces: truetls: enabled: trueimage: hashicorp/consul-enterprise:1.11.0-ent-beta1adminPartitions: enabled: trueserver: exposeGossipAndRPCPorts: true enterpriseLicense: secretName: license secretKey: keyconnectInject: enabled: true transparentProxy: defaultEnabled: false consulNamespaces: mirroringK8S: truecontroller: enabled: true
Note that the
transparentProxyconfiguration is disabled. This is to enable multi-cluster networking.
Start the Consul server(s) using the custom configuration file:
helm install server hashicorp/consul -f server.yaml
After the server starts, get the external IP address for partition service so that it can be added to the client configuration. The partition service is a
LoadBalancertype. The IP address is where clients that across your partitions will communicate with servers in this cluster.
kubectl get serviceNAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGEkubernetes ClusterIP 10.96.0.1 <none> 443/TCP 3mservers-consul-connect-injector-svc ClusterIP 10.97.175.39 <none> 443/TCP 30sservers-consul-controller-webhook ClusterIP 10.100.22.99 <none> 443/TCP 30sservers-consul-dns ClusterIP 10.103.43.20 <none> 53/TCP,53/UDP 30sservers-consul-partition-service LoadBalancer 10.111.255.152 220.127.116.11 8501:30643/TCP,8301:30466/TCP,8300:30657/TCP 30sservers-consul-server ClusterIP None <none> 8501/TCP,8301/TCP,8301/UDP,8302/TCP,8302/UDP,8300/TCP,8600/TCP,8600/UDP 30sservers-consul-ui ClusterIP 10.106.240.55 <none> 443/TCP 30s
Create the workload configuration for client nodes in your cluster. Create a configuration for each admin partition. In the following example, the external IP address from the previous step has been applied:
global:enabled: falseenableConsulNamespaces: trueimage: hashicorp/consul-enterprise:1.11.0-ent-beta1adminPartitions: enabled: true name: "clients" // partition nametls: enabled: true caCert: secretName: consul-consul-ca-cert secretKey: tls.crt caKey: secretName: consul-consul-ca-key secretKey: tls.keyserver: enterpriseLicense: secretName: license secretKey: keyexternalServers: enabled: true hosts: "18.104.22.168" # Insert External IP of LoadBalancer here tlsServerName: server.dc1.consulclient: enabled: true exposeGossipPorts: true join: "22.214.171.124"connectInject: enabled: true consulNamespaces: mirroringK8S: truecontroller: enabled: true
Copy the server certificate to the workload cluster.
kubectl get secret server-consul-ca-cert --context server -o yaml | kubectl apply --context client -f -
Copy the server key to the workload cluster.
kubectl get secret consul-consul-ca-key --context server -o yaml | kubectl apply --context client -f -
Start the workload client clusters:
helm install client hashicorp/consul -f client.yaml
You can use create and manage admin partitions through the CLI. Refer to the admin partition CLI documentation for details.
- Gossip between nodes in different admin partitions must be constrained. You can accomplish this with through the use of network segments.
- Cross-partition communication is not currently supported.