mirror of https://github.com/hashicorp/consul
209 lines
6.6 KiB
Markdown
209 lines
6.6 KiB
Markdown
---
|
||
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](/docs/enterprise#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-session
|
||
$ 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-session
|
||
$ 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-session
|
||
$ 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-session
|
||
$ 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-session
|
||
$ 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-session
|
||
$ 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.
|
||
|
||
|
||
|
||
### 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-session
|
||
$ dig 127.0.0.1 -p 8500 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.
|
||
|
||
```shell-session
|
||
$ dig 127.0.0.1 -p 8500 wordpress.service.consul
|
||
<output should show no services>
|
||
```
|
||
|
||
### 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
|
||
<output shows one service>
|
||
```
|
||
|
||
## 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.
|