Consul Enterprise namespaces are a powerful way to isolate teams within a single Consul datacenter, but they’re not just about access control; they fundamentally change how Consul services and configurations are discovered.
Let’s see this in action. Imagine we have two teams, frontend and backend, and we want to isolate them.
First, we need to create the namespaces themselves. On your Consul Enterprise UI, navigate to "Namespaces" and click "Create Namespace."
For the frontend team, we’d create a namespace named frontend.
For the backend team, we’d create a namespace named backend.
Now, when a service is registered, it gets associated with a namespace. Let’s say we register a webapp service for the frontend team. Using the Consul API or CLI, this registration would look something like this:
consul services register -namespace=frontend -name=webapp -port=80
Similarly, for the backend team’s api service:
consul services register -namespace=backend -name=api -port=5000
The magic happens during service discovery. By default, a service registered in a specific namespace can only see other services within that same namespace. If the webapp service in the frontend namespace needs to talk to the api service in the backend namespace, it won’t see it by default.
To enable cross-namespace communication, we need to configure a "namespace policy." In the Consul UI, under "Policies," you’d create a new policy. Let’s call it frontend-to-backend-access. This policy would grant read access to the backend namespace for services within the frontend namespace.
The policy document might look like this:
{
"Name": "frontend-to-backend-access",
"Description": "Allow frontend services to discover backend services",
"Rules": {
"service": {
"read": [
{
"Namespace": "backend",
"Node": "*",
"Service": "*"
}
]
}
}
}
This policy then needs to be attached to the frontend namespace. In the Consul UI, navigate to the frontend namespace settings, go to "Policies," and attach the frontend-to-backend-access policy.
With this in place, the webapp service, running within the frontend namespace, can now discover the api service in the backend namespace. The service discovery mechanism, when querying for api, will now be aware of the api service in the backend namespace due to the attached policy.
The core problem namespaces solve is multi-tenancy within a single Consul cluster, preventing accidental or intentional cross-team service interference and simplifying management by grouping resources logically. Internally, Consul treats services and configurations within different namespaces as distinct entities, even if they share the same datacenter. When a client or API call is made, Consul’s ACL system checks the identity of the caller and the target resource against the policies associated with the caller’s namespace and any explicitly granted cross-namespace permissions.
What most people don’t realize is that namespaces also apply to other Consul resources, not just services. This includes KV store entries, intentions, and even mesh gateways. If you register a KV key like config/webapp in the frontend namespace, it’s only visible to services within the frontend namespace unless explicitly allowed by a policy. This comprehensive isolation extends to securing configurations and inter-service communication.
The next logical step after establishing namespaces is to explore how to secure communication between these isolated services using Consul’s built-in mutual TLS capabilities.