consul/website/content/docs/enterprise/admin-partitions.mdx

---
layout: docs
page_title: Consul Enterprise Admin Partitions
description: Consul Enterprise enables you to create paritions that can be administrated across namespaces.
---

# Consul Enterprise Admin Partitions

<EnterpriseAlert>
  This feature requires{' '}
  <a href="https://www.hashicorp.com/products/consul/">Consul Enterprise</a>{' '}
  with the Governance and Policy module.
</EnterpriseAlert>

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.

-> **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.

The `default` admin partition is special in that it may contain namespaces and other entities that are replicated between datacenters. The `default` partition must also contain the Consul servers.  

-> **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.

### Namespaces

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.

### Cross-datacenter Replication

Only resources in the default admin partition will be replicated to secondary datacenters. Non-default partitions are currently not supported in secondary datacenters.

### DNS Queries

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`](/docs/connect/config-entries/proxy-defaults) configurations are scoped to a specific partition. Services registered in the partition will use the partition's `proxy-defaults` values.

### Cross-partition Networking

You can configure services to be discoverable and accessible by downstream services in any partition within the datacenter. Specify the upstream services that you want to be available for discovery by configuring the `partition-exports` configuration entry in the partition where the services are registered. Refer to the [`partition-exports` documentation](/docs/connect/config-entries/partition-exports) for details.

Additionally, the `upstreams` configuration for proxies in the source partition must specify the name of the destination partition so that listeners can be created. Refer to the [Upstream Configuration Reference](/docs/connect/registration/service-registration#upstream-configuration-reference) for additional information.

## Requirements

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

### Versions

* Consul 1.11.0 and newer

### Security Configurations

* The agent token used by the client agent will need to allow `node:write` in the admin partition.
* The `write` permission for `proxy-defaults` requires `mesh:write`. See [Admin Partition Rules](/docs/security/acl/acl-rules#admin-partition-rules) for additional information.
* The `write` permissions for ingress and terminating gateways require `mesh:write` privileges.
* Wildcards (`*`) are not supported when creating intentions for admin partitions, but you can use a wildcard to specify services within a partition.
* 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

* In client agent configurations, the admin partition name should be specified in the agent configuration:

  ```hcl
  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 on Kubernetes clusters. The following requirements must be met to create admin partitions on Kubernetes:

* Two or more Kubernetes clusters. Consul servers must be deployed on one of the clusters. The other clusters should run Consul clients.
* A Consul Enterprise license must be installed on each instance of Consul.
* The helm chart for consul-k8s v0.34.1 or greater.
* Consul 1.11.0-ent-alpha or greater.
* All Consul clients in the VPC must be able to communicate with the Consul servers. 
* VPC firewall rules should be implemented that enable clients to communicate with the Consul servers in the `default` partition. The server nodes should be deployed to a single cluster.

## Usage

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 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. 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 a different 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. 

Verify that your Consul deployment meets the [Kubernetes Requirements](#kubernetes-requirements) before proceeding.

1. Update the firewall rules so that pods containing Consul clients and pods containing Consul servers can send and receive traffic. Refer to your virtual cloud provider's documentation for instructions on how to configure firewall rules. 
1. Create the license secret in each cluster, e.g.:

  ```shell-session
  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.

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

  <CodeTabs heading="server.yaml">
  <CodeBlockConfig lineNumbers>

  ```yaml
  global:
    enableConsulNamespaces: true
    tls:
      enabled: true
    image: hashicorp/consul-enterprise:1.11.0-ent-beta3
    adminPartitions:
      enabled: true
    enterpriseLicense:
      secretName: consul-ent-license
      secretKey: key
  server:
    exposeGossipAndRPCPorts: true
  connectInject:
    enabled: true
    transparentProxy:
      defaultEnabled: false
  consulNamespaces:
      mirroringK8S: true
  controller:
    enabled: true
  ```
  </CodeBlockConfig>
  </CodeTabs>
  
  Note that the `transparentProxy` configuration is disabled. This is to enable multi-cluster networking.

1. Start the Consul server(s) using the custom configuration file:
  ```shell-session
    helm install server hashicorp/consul -f server.yaml
  ```
1. 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 `LoadBalancer` type. The IP address is where clients that across your partitions will communicate with servers in this cluster.

  ```shell-session
  kubectl get service
  NAME                                  TYPE           CLUSTER-IP       EXTERNAL-IP       PORT(S)                                                                   AGE
  kubernetes                           ClusterIP      10.8.0.1      <none>            443/TCP                                                                   77m
  server-consul-connect-injector-svc   ClusterIP      10.8.13.188   <none>            443/TCP                                                                   76s
  server-consul-controller-webhook     ClusterIP      10.8.14.178   <none>            443/TCP                                                                   77s
  server-consul-dns                    ClusterIP      10.8.6.6      <none>            53/TCP,53/UDP                                                             77s
  server-consul-partition-service      LoadBalancer   10.8.1.186    34.135.103.67     8501:31130/TCP,8301:31587/TCP,8300:30378/TCP                              76s
  server-consul-server                 ClusterIP      None          <none>            8501/TCP,8301/TCP,8301/UDP,8302/TCP,8302/UDP,8300/TCP,8600/TCP,8600/UDP   76s
  server-consul-ui                     ClusterIP      10.8.0.218    <none>            443/TCP                                                                   77s
  ```
1. Get the Kubernetes authentication method URL for the workload cluster:

  ```shell-session
  kubectl config view -o "jsonpath={.clusters[?(@.name=='<workload-cluster-name>')].cluster.server}"
  ```
  Use the IP address printed to the console to configure the `k8sAuthMethodHost` parameter in the workload configuration file for your client nodes. 

1. 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 and the Kubernetes authentication method IP address from the previous steps have been applied:

  <CodeTabs heading="clients.yaml">
  <CodeBlockConfig lineNumbers>

  ```yaml
  global:
  enabled: false
  enableConsulNamespaces: true
  image: hashicorp/consul-enterprise:1.11.0-ent-beta3
  adminPartitions:
    enabled: true
    name: "clients"
  tls:
    enabled: true
    caCert:
      secretName: consul-consul-ca-cert
      secretKey: tls.crt
    caKey:
      secretName: consul-consul-ca-key
      secretKey: tls.key
  enterpriseLicense:
    secretName: license
    secretKey: key
  externalServers:
    enabled: true
    hosts: [ "34.135.103.67" ]
    tlsServerName: server.dc1.consul
    k8sAuthMethodHost: "104.154.156.146"
  client:
    enabled: true
    exposeGossipPorts: true
    join: [ "34.135.103.67" ]
  connectInject:
    enabled: true
    consulNamespaces:
      mirroringK8S: true
  controller:
    enabled: true
  meshGateway:
    enabled: true
  ```
  </CodeBlockConfig>
  </CodeTabs>

1. Copy the server certificate to the workload cluster.

  ```shell-session
  kubectl get secret server-consul-ca-cert --context <server-context> -o yaml | kubectl apply --context <client-context> -f -
  ```

1. Copy the server key to the workload cluster.

  ```shell-session
  kubectl get secret server-consul-ca-key --context <server-context> -o yaml | kubectl apply --context <client-context> -f -
  ```
1. Start the workload client clusters:

  ```shell-session
    helm install client hashicorp/consul -f client.yaml
  ```

### CLI Usage

You can use create and manage admin partitions through the CLI. Refer to the [admin partition CLI documentation](/commands/admin-partition) for details.

## Known Limitations

* Gossip between nodes in different admin partitions must be constrained. You can accomplish this with through the use of [network segments](network-segments).
* Cross-partition communication is not currently supported.
* Partitions can only be created in the primary datacenter.