--- name: '[Enterprise] Register and Discover Services within Namespaces' content_length: 8 id: discovery-namespaces products_used: - Consul description: >- In this guide you will register and discover services within a namespace. level: Implementation --- !> **Warning:** This guide is a draft and has not been fully tested. !> **Warning:** Consul 1.7 is currently a beta release. 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](/consul/namespaces/secure-namespaces). 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. ## Perquisites To complete this guide you will need at least a [local dev agent](/consul/getting-started/install) running Consul Enterprise 1.7 or newer. Review the documentation for downloading the [Enterprise binary](https://www.consul.io/docs/enterprise/index.html#applied-after-bootstrapping). 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 or execute the following command to create a namespace. ```shell $ consul namespace create app-team ``` ## 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 and its sidecar proxy. ```hcl service { name = “mysql" port = 9003 connect {sidecar_proxy} } ``` Next, register the service and its sidecar proxy using the Consul CLI by specifying the registration file. ```shell $ 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 and port, and a sidecar proxy, along with the namespace. ```hcl service { name = “wordpress" port = 9003 connect {sidecar_proxy} namespace = "app-team" } ``` Next register the service and its sidecar proxy. ```shell $ consul services register wordpress.hcl -namespace app-team ``` ## 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. ```shell $ consul catalog services consul mysql mysql-proxy ``` Notice that you do not see services that are registered in the app-team namespace. Add the `-namepsace` 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. ```shell $ consul catalog services -namespace app-team consul wordpress wordpress-proxy ``` 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. ```shell $ consul catalog services consul mysql mysql-proxy $ consul catalog services -namespace app-team consul wordpress wordpress-proxy ``` ### 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. ![IMAGE FROM RFC! REPLACE ME AT BETA LAUNCH](/static/img/consul/namespaces/consul-namespace-dropdown.png) ### DNS Interface ~> **Note:** To default to the `namespace` parameter in the DNS query, you must set the `prefer_namespace` option to `true` in the [agent's configuration](). The new query structure will be, `service.namespace.consul`. This will disable the ability to query by datacenter only. However, you can add both namespace and datacenter to the query, `service.namespace.datacenter.consul`. To discover the location of service instances, you can use the DNS interface. ```shell $ dig 127.0.0.1 -p 8500 wordpress.service.app-team.consul ``` If you don’t specify a namespace in the query, you will get results from the default namespace. ```shell $ dig 127.0.0.1 -p 8500 wordpress.service.consul ``` ### Consul HTTP API 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. ```shell curl http://127.0.0.1:8500/v1/catalog/service/wordpress?ns=app-team ``` ## Summary 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.