Register services into a namespace

This page describes how to to register a service into a particular Consul namespace.

Introduction

Namespaces allow multiple teams within an organization to share one or more Consul datacenters by separating the services, Consul KV data, and other Consul data of each team. This allows operators to more easily provide Consul as a service and enables them to delegate ACL management.

All Consul clusters have access to a default namespace, but using multiple namespaces requires a Consul Enterprise license. Consul registers services into the namespace declared in the service definition. If you do not specify a namespace, Consul registers the service into the default namespace.

Register a service into a namespace

You register a service into a namespace by using one of the following methods:

• Add the namespace attribute to the service registration file.
• Add the -namespace flag to the API call or CLI command during service registration.
• Use a namespace token to leverage namespace inheritance.

To migrate an existing service into a new namespace, register the service again and provide the namespace with either method shown.

Use the namespace attribute

Include a namespace attribute in the service registration file and set the value to a namespace that exists. Refer to the Service definition reference page for more information about registering services with the service block.

service {
  name = "db-service"
  port = 5432
  namespace = "db-team"

  # ...
}

Register the service with Consul by providing the service registration file.

$ consul services register db-service.hcl
Registered service: db-service

Use the -namespace flag

Include the -namespace flag when registering the service via the Consul CLI.

Refer to the CLI reference page for the services register command for more information and additional configuration options.

$ consul services register \
  -name=db-service \
  -port=5432 \
  -namespace=db-team

Use namespace inheritance

When you use a token scoped to a specific namespace to make CLI and API requests related to services, intentions, Consul KV, health checks, and ACLs, your request inherits the namespace information from the token. This means that if you use a token in the db-team namespace to register a service with Consul, the service is registered in that namespace without specifying it explicitly.

To create a namespace token, follow instructions in Delegate ACL token management with namespaces.

First set the token for the CLI.

$ export CONSUL_HTTP_TOKEN=<db-team namespace token here>

Then register the service without including the -namespace flag.

consul services register -name=db-service -port=5432
Registered service: db-service

Specify namespace in a Consul DNS query

Queries to Consul DNS can include datacenter or datacenter and namespace.