---
layout: docs
page_title: Register services into a namespace
description: >-
  Learn how to register a service in a particular namespace and use Consul DNS to resolve it.
---

# Register services into a namespace

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

@include 'alerts/enterprise-alert.mdx'


## Introduction

Namespaces allow multiple teams within an organization to share one or more Consul datacenters by separating the services, [Consul KV data](/consul/docs/automate/kv), 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](/consul/docs/multi-tenant/namespace/vm/delegate-token-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](/consul/docs/reference/service) for more information about registering services with the `service` block.

<CodeBlockConfig filename="db-service.hcl" highlight="4">

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

  # ...
}
```

</CodeBlockConfig>

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

```shell-session
$ 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](/consul/commands/services/register) for more information and additional configuration options.

```shell-session
$ 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](/consul/docs/multi-tenant/namespace/vm/delegate-token-management#create-a-developer-token).

First set the token for the CLI.

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

Then register the service without including the `-namespace` flag.

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

<Note>

If you registered a service with a service definition file, you must
include both the ACL token and the namespace name in your request, as 
service definitions are parsed prior to resolving the token.

</Note>

## Specify namespace in a Consul DNS query

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

<Tabs>

<Tab heading="Format with datacenter only" group="datacenter-only">

`<service-name>.service.<datacenter>.consul`

</Tab>

<Tab heading="Format with datacenter and namespace" group="datacenter-and-namespace">

`<service-name>.service.<namespace>.<datacenter>.consul`

</Tab>

</Tabs>