[Enterprise] Segment Your Datacenter with Namespaces

[Enterprise] Register and Discover Services within Namespaces

Namespaces allow multiple teams within the same organization to share the same Consul datacenter(s) by separating services, key/value pairs, and other Consul data per team. This provides operators with the ability to more easily run Consul as a service. Namespaces also enable operators to delegate ACL management.

Any service that is not registered in a namespace will be added to the default namespace. This means that all services are namespaced in Consul 1.7 and newer, even if the operator has not created any namespaces.

By the end of this guide, you will register two services in the Consul catalog: one in the default namespace and one in an operator-configured namespace. After you have registered the services, you will then use the Consul CLI, API and UI to discover all the services registered in the Consul catalog.


To complete this guide you will need at least a local dev agent running Consul Enterprise 1.7 or newer. Review the documentation for downloading the Enterprise binary. You can also use an existing Consul datacenter that is running Consul Enterprise 1.7 or newer.

You should have at least one namespace configured. Review the namespace management documentation to learn more about namespace.

First, create a JSON file with the namespace definitions for the app-team. The definitions can be JSON or HCL. Save the following configurations, which specify the name and description of the namespace.

   "name": "app-team",
   "description": "Namespace for app-team managing the production dashboard application"

Next, use the Consul CLI to create the namespace by providing Consul with the namespace definition file.

$ consul namespace write app-team.json

Register services in namespaces

You can register services in a namespace by using your existing workflow and adding namespace information to the registration. There are two ways to add a service to a namespace:

  • adding the namespace option to the service registration file.
  • using the namespace flag with the API or CLI at registration time.

If you would like to migrate an existing service into a new namespace, re-register the service with the new namespace information.

Default namespace

To register a service in the default namespace, use your existing registration workflow; you do not need to add namespace information. In the example below, you will register the mysql service in the default namespace.

First, create a service registration file for the MySQL service.

service {
  name = "mysql"
  port = 9003

Next, register the service using the Consul CLI by specifying the registration file.

$ consul services register mysql.hcl

App-team namespace

To register a service in a user-defined namespace, include the namespace in the registration file, or pass it with a flag at registration time. In this guide, we will include the namespace in the file.

First, create the service registration file named wordpress.hcl. Paste in the following registration, which includes the service name, port, and namespace.

service {
  name = "wordpress"
  port = 9003
  namespace = "app-team"

Next register the service.

$ consul services register wordpress.hcl

Discover services

You can discover namespaced services using all the usual methods for service discovery in Consul: the CLI, web UI, DNS interface, and HTTP API.

Consul CLI

To get a list of services in the default namespace use the consul catalog CLI command. You do not need to add the flag any discover services in the default namespace.

$ consul catalog services

Notice that you do not see services that are registered in the app-team namespace.

Add the -namespace flag to discover services within a user-created namespace. In the example below, you will use the -namespace flag with the CLI to discover all services registered in the app-team namespace.

$ consul catalog services -namespace app-team

Notice that you do not see services that are registered in the default namespace. To discover all services in the catalog, you will need to query all Consul namespaces.

$ consul catalog services

$ consul catalog services -namespace app-team

Consul UI

You can also view namespaced-services in the Consul UI. Select a namespace using the drop-down menu at the top of the top navigation. Then go to the “Services” tab to see the services within the namespace.

Before you select a namespace the UI will list the services in the default namespace.


DNS Interface

To discover the location of service instances, you can use the DNS interface.

$ dig @ -p 8600 wordpress.service.app-team.consul
<output should show one service>

If you don’t specify a namespace in the query, you will get results from the default namespace.

$ dig @ -p 8600 wordpress.service.consul
<output should show no services>


The Consul HTTP API is more verbose than the DNS API; it allows you to discover the service locations and additional metadata. To discover service information within a namespace, add the ns= query parameter to the call.

$ curl
    "ID": "d8b1f06f-d740-ee7b-3625-ece3d2fe3c91",
    "Node": "consul-server-0",
    "Address": "",
    "Datacenter": "dc1",
    "TaggedAddresses": {
      "lan": "",
      "wan": ""
    "NodeMeta": {
      "consul-network-segment": ""
    "ServiceKind": "",
    "ServiceID": "wordpress",
    "ServiceName": "wordpress",
    "ServiceTags": [],
    "ServiceAddress": "",
    "ServiceWeights": {
      "Passing": 1,
      "Warning": 1
    "ServiceMeta": {},
    "ServicePort": 9003,
    "ServiceEnableTagOverride": false,
    "ServiceProxy": {
      "MeshGateway": {},
      "Expose": {}
    "ServiceConnect": {},
    "Namespace": "app-team",
    "CreateIndex": 20,
    "ModifyIndex": 20


In this guide, you registered two services: the WordPress service in the app-team namespace and the MySQL service in the default namespace. You then used the Consul CLI to discover services in both namespaces.

You can use ACLs to secure access to data, including services, in namespaces. After ACLs are enabled, you will be able to restrict access to the namespaces and all the data registered in that namespace.