docs: adding new guide for namespaces and service discovery (#6788)
This commit is contained in:
kaitlincarter-hc
GitHub
parent
0d96039426
commit
34b812642e
|
|
@ -0,0 +1,207 @@
|
|||
---
|
||||
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.
|
||||
|
||||
|
||||
|
||||
### 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.
|
||||
Loading…
Reference in New Issue