Register and discover services within namespaces

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

Any service that is not registered to a namespace is added to the default namespace. All services are added to namespaces in Consul version 1.7 and later.

By the end of this tutorial, 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.

Prerequisites

To complete this tutorial, you will need a Consul Enterprise version 1.13.1 cluster or newer.

You should also have at least one namespace configured. Review the Setup Secure Namespaces tutorial for a complete example or use the below example for a quick setup.

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

$ consul namespace write app-team.hcl

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

$ consul namespace write app-team.json

Name: app-team
Description:
   Namespace for app-team managing the production dashboard application

Register services in namespaces

You register services in a namespace by adding namespace information to the registration. This should not disrupt your existing workflow. The namespace information can be added to the registration using one of the following methods.

• add the namespace option to the service registration file.
• use 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 service registration

To register a service in the default namespace, use your existing registration workflow; you do not need to add namespace information as long as a namespace ACL token isn't provided. 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
  connect {
    sidecar_service {}
  }
}

Next, register the service using the Consul CLI.

$ consul services register mysql.hcl

App-team namespace service registration

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 tutorial, 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"
  connect {
    sidecar_service {
      proxy {
        upstreams = [
          {
            destination_name = "counting"
            local_bind_port  = 5000
         }
        ]
      }
    }
  }
}

Next register the service.

$ consul services register wordpress.hcl

Discover services

Finally, you will discover your services using the Consul CLI, UI, DNS interface, and HTTP API.

Consul CLI

To get a list of services in the default namespace use the consul catalog CLI command.

$ consul catalog services

consul
mysql
mysql-sidecar-proxy

Notice that the command does not list services that are registered in the app-team namespace.

Add the -namespace flag to discover services within a user-created namespace.

$ consul catalog services -namespace app-team

wordpress
wordpress-sidecar-proxy

Notice that the command does not list services that are registered in the default namespace. To discover all services in the catalog, you will need to query all Consul namespaces individually.

Consul UI

You can also view namespace 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.

DNS interface

Next, use dig to discover the location of wordpress service instance.

$ dig @127.0.0.1 -p 8600 wordpress.service.app-team.dc1.consul

; <<>> DiG 9.10.3-P4-Debian <<>> @127.0.0.1 -p 8600 wordpress.service.app-team.dc1.consul
; (1 server found)
;; global options: +cmd
;; Got answer:
;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 43384
;; flags: qr aa rd; QUERY: 1, ANSWER: 1, AUTHORITY: 0, ADDITIONAL: 1
;; WARNING: recursion requested but not available

;; OPT PSEUDOSECTION:
; EDNS: version: 0, flags:; udp: 4096
;; QUESTION SECTION:
;wordpress.service.app-team.dc1.consul. IN A

;; ANSWER SECTION:
wordpress.service.app-team.dc1.consul. 0 IN A 172.20.20.14

;; Query time: 0 msec
;; SERVER: 127.0.0.1#8600(127.0.0.1)
;; WHEN: Thu Feb 06 20:12:49 GMT 2020
;; MSG SIZE  rcvd: 82

In the output, the query returns one answer.

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

$ dig @127.0.0.1 -p 8600 wordpress.service.consul

; <<>> DiG 9.10.3-P4-Debian <<>> @127.0.0.1 -p 8600 wordpress.service.consul
; (1 server found)
;; global options: +cmd
;; Got answer:
;; ->>HEADER<<- opcode: QUERY, status: NXDOMAIN, id: 11916
;; flags: qr aa rd; QUERY: 1, ANSWER: 0, AUTHORITY: 1, ADDITIONAL: 1
;; WARNING: recursion requested but not available

;; OPT PSEUDOSECTION:
; EDNS: version: 0, flags:; udp: 4096
;; QUESTION SECTION:
;wordpress.service.consul.  IN  A

;; AUTHORITY SECTION:
consul.     0 IN  SOA ns.consul. hostmaster.consul. 1581013077 3600 600 86400 0

;; Query time: 0 msec
;; SERVER: 127.0.0.1#8600(127.0.0.1)
;; WHEN: Thu Feb 06 18:17:57 GMT 2020
;; MSG SIZE  rcvd: 103

The output returns 0 answers, the wordpress service does not exist in the default namespace.

Consul HTTP API

Finally, use the Consul HTTP API to discover more information about the wordpress service. To discover service information within a namespace, add the ns= query parameter to the query.

$ curl http://127.0.0.1:8500/v1/catalog/service/wordpress?ns=app-team | jq

[
  {
    "ID": "8c6a99a4-c701-ec84-18cc-127e862b0d16",
    "Node": "agent-one",
    "Address": "172.20.20.14",
    "Datacenter": "dc1",
    "TaggedAddresses": {
      "lan": "172.20.20.14",
      "lan_ipv4": "172.20.20.14",
      "wan": "172.20.20.14",
      "wan_ipv4": "172.20.20.14"
    },
    "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": 34,
    "ModifyIndex": 34
  }
]

The HTTP API is more verbose than the DNS interface; it allows you to discover the service locations and additional metadata.

Next steps

In this tutorial, 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, UI, and HTTP API to discover services in both namespaces.

For a complete example on service and sidecar proxy registration, review the Secure Service Communication with Consul Service Mesh and Envoy.