mirror of https://github.com/hashicorp/consul
209 lines
6.5 KiB
Plaintext
209 lines
6.5 KiB
Plaintext
|
---
|
|||
|
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
|
|||
|
<output should show one service>
|
|||
|
```
|
|||
|
|
|||
|
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
|
|||
|
<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.
|