---
page_title: Setup Consul namespaces on VMs
description: |-
  Delegate administrative privileges to namespace operators and remove resource uniqueness restrictions using Consul Enterprise namespace and Access Control Lists (ACLS).
---

# Setup Consul namespaces on VMs

This page describes the process to setup secure namespaces in Consul when your cluster runs on VMs.

<Note title="Enterprise Only">

 The namespace functionality demonstrated here
requires HashiCorp Cloud Platform (HCP) or self-managed
[Consul Enterprise](https://www.hashicorp.com/products/consul/pricing/).
If you've purchased or wish to try out Consul Enterprise, refer to
[how to access Consul Enterprise](/consul/docs/enterprise#access-consul-enterprise).

</Note>

Namespaces provide separation for teams within a single organization enabling
them to share access to one or more Consul datacenters without conflict. This
allows teams to deploy services without name conflicts and create more granular
access to the datacenter with namespaced ACLs. Additionally, namespaces with
ACLs allows you to delegate access control to specific resources within the
datacenter including services, Connect service mesh proxies, key/value pairs, and sessions.

This tutorial has two main sections, configuring namespaces and creating ACL tokens
within a namespace. You must configure namespaces before creating namespace
tokens.

## Prerequisites

To complete this tutorial you will need:

- A Consul Enterprise version 1.13.1 cluster or newer with
  ACLs enabled. For more information, see the
  [Secure Consul with Access Control Lists guide](/consul/tutorials/security/access-control-setup-production).

- An ACL token with `operator=write` and `acl=write` privileges, or an ACL
  token with the built-in global management policy. See the 
  [Consul ACL policies documentation](/consul/docs/security/acl/acl-policies#built-in-policies)
  for more information.

<Tip>

 The content of this tutorial also applies to Consul clusters hosted on HashiCorp Cloud (HCP).

</Tip>

## Configure namespaces

First, you will create two namespaces that allow you to separate the datacenter
for two teams. Each namespace will have an operator responsible for managing
data and access within their namespace. The namespace operator will only have
access to view and update data and access in their namespace. This allows for
complete isolation of data between teams.

To configure and manage namespaces, you will need one super-operator who has
visibility into the entire datacenter. It will be their responsibility to set up
namespaces. To complete this tutorial, you should be the super-operator.

### Create namespace definitions

You will need to create two files to define the namespaces for the `app-team` and `db-team`.

<Tabs>
<Tab heading="HCL">

<CodeBlockConfig filename="app-team.hcl">

```hcl
name = "app-team",
description = "Namespace for app-team managing the production dashboard application"
```

</CodeBlockConfig>

<CodeBlockConfig filename="db-team.hcl">

```hcl
name = "db-team",
description = "Namespace for db-team managing the production counting application"
```

</CodeBlockConfig>

</Tab>
<Tab heading="JSON">

<CodeBlockConfig filename="app-team.json">

```json
{
  "name": "app-team",
  "description": "Namespace for app-team managing the production dashboard application"
}
```

</CodeBlockConfig>

<CodeBlockConfig filename="db-team.json">

```json
{
  "name": "db-team",
  "description": "Namespace for db-team managing the production counting application"
}
```

</CodeBlockConfig>

</Tab>
</Tabs>

These namespace definitions are for minimal configuration, with only the name
and description. Learn more about namespace options in the
[documentation](/consul/docs/multi-tenant/namespace#namespace-definition).

### Initialize the namespaces

Use the Consul CLI to create each namespace by providing Consul with the namespace definition files. You will need `operator=write` privileges.

<Note>

 the example refers to the JSON files to load the configuration. If you decided to use HCL to configure your namespaces, change the file extension to `hcl`.

</Note>

```shell-session
$ consul namespace write app-team.json
```

```plaintext hideClipboard
Name: app-team
Description:
   Namespace for app-team managing the production dashboard application
```

After successfully creating the app-team namespace, create the db-team namespace.

```shell-session
$ consul namespace write db-team.json
```

```plaintext hideClipboard
Name: db-team
Description:
   Namespace for db-team managing the production counting application
```

Finally, ensure both namespaces were created successfully by viewing all
namespaces. You will need `operator=read` privileges, which are included with
the `operator=write` privileges, a requirement from the prerequisites.

```shell-session
$ consul namespace list
```

```plaintext hideClipboard
app-team:
   Description:
      Namespace for app-team managing the production dashboard application
db-team:
   Description:
      Namespace for db-team managing the production counting application
default:
   Description:
      Builtin Default Namespace
```

Alternatively, you can view each namespace with the `consul namespace read <namespace>`
command. After you create a namespace, you can update or delete it
using the Consul [CLI](/consul/commands/namespace).

## Delegate token management with namespaces

Next, you will delegate token management to multiple operators. One of the key
benefits of namespaces is the ability to delegate responsibilities of token
management to more operators. This allows you to provide unrestricted access to
portions of the datacenter, ideally to one or a few operators per namespace.

The namespace operators are then responsible for managing access to services,
Consul KV, and other resources within their namespaces. Namespaces do not have
any impact on compute or other node resources. Additionally, the namespace
operator should further delegate service-access privileges to developers or
end-users. This is consistent with the current ACL management workflow. Before
namespaces, only one or a few operators managed tokens for an entire datacenter.

Namespace operators will only be aware of data within their namespaces, unless
they are intentionally given access otherwise. Without global privileges, they
will not be able to locate other namespaces.

Note, nodes are not namespaced, so namespace-operators will be able to locate all
the agents in the datacenter.

## Create namespace management tokens

First, the super-operator should use the [built-in
namespace-policy](/consul/docs/security/acl/acl-policies#built-in-policies)
to create a token for each of the namespace operators. Note, the
namespace-management policy ultimately grants unrestricted privileges for their
namespace. You will need `acl=write` privileges to create namespace tokens.

```shell-session
$ consul acl token create \
      -namespace app-team \
      -description "App Team Administrator" \
      -policy-name "namespace-management"
```

If the command is successful, Consul will return the token information.

```plaintext hideClipboard
AccessorID:       3cbb3a83-6b11-00fb-5eae-7384746a9e7b
SecretID:         6877ad53-53ca-8061-00a7-55759955a870
Namespace:        app-team
Description:      App Team Administrator
Local:            false
Create Time:      2019-12-11 16:19:44.057622 -0600 CST
Policies:
   da57f91d-efeb-bfe2-f0e9-685e0ce99bde - namespace-management
```

```shell-session
$ consul acl token create \
      -namespace db-team \
      -description "DB Team Administrator" \
      -policy-name "namespace-management"
```

Both token should be generated successfully before continuing.

```plaintext hideClipboard
AccessorID:       838e5883-65f7-6ae9-20f6-8af3b895a6c4
SecretID:         0c3aeb84-5497-67ea-9ad0-57db99d24d8a
Namespace:        db-team
Description:      DB Team Administrator
Local:            false
Create Time:      2019-12-11 16:37:56.668698 -0600 CST
Policies:
   0d8ab5f1-b63c-7014-94b7-0b96e6b417f8 - namespace-management
```

### Default namespace policy privileges

Most importantly, the default policy grants privileges to create tokens, which
enables the holders to grant themselves any additional privileges needed for any
operation within their namespace. The namespace-policy includes the following
privileges.

```hcl
acl = "write"

key_prefix "" {
  policy = "write"
}

node_prefix "" {
  # node policy is restricted to read within a namespace
  policy = "read"
}

session_prefix "" {
  policy = "write"
}

service_prefix "" {
  policy = "write"
  intentions = "write"
}
```

### View namespace management tokens

To view tokens within a namespace, you will need to use the `-namespace` command-line flag.

```shell-session
$ consul acl token list -namespace app-team
```

The output will return all tokens in the namespace. In this tutorial example, there is only one.

```plaintext hideClipboard
AccessorID:       a5b8e5b2-96b0-86ee-10d3-3836e9c69380
Namespace:        app-team
Description:      App Team Administrator
Local:            false
Create Time:      2020-02-06 17:57:49.574545525 +0000 UTC
Legacy:           false
Policies:
   7140ad92-ed31-4779-2835-1f5d2ed347cd - namespace-management
```

If no flag is provided the command will return the tokens in the global namespace, if you
have the correct privileges.

## Create a developer token

Now that you have a management token for each namespace, you can create tokens
that restrict privileges for end-users, only providing the minimum necessary
privileges for their role. In this example you will give the developers on the
db-team the ability to register their own services and allow or deny
communication between services in their team’s namespace with intentions.

<Note>

 Depending on your company’s security model you may want to delegate
intentions management to a different set of users than service registration.

</Note>

### Use the db-team operator token

To ensure the db-team operator token, created previously in this tutorial, has the
correct privileges set it as the environment variable.

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

If any of the following commands fail with a permission error, than the token
was not created correctly.

### Create the policy

Create a HCL file named `db-developer-policy.hcl` and paste in the following.

<CodeBlockConfig filename="db-developer-policy.hcl">

```hcl
service_prefix "" {
  policy = "write"
  intention = "write"
}
```

</CodeBlockConfig>

This policy allows writing services and intentions for those services.

Using the Consul CLI, create the policy using the policy file.

```shell-session
$ consul acl policy create \
  -name developer-policy \
  -description "Write services and intentions" \
  -namespace db-team \
  -rules @db-developer-policy.hcl
```

### Create the token

Using the developer policy defined previously, create a token for the
developer in the db-team namespace.

```shell-session
$ consul acl token create \
  -description "DB developer token" \
  -namespace db-team \
  -policy-name developer-policy
```

The output will provide token information, including the namespace
where the token is located.

```plaintext hideClipboard
AccessorID:       db7ad943-e08b-0fed-4282-41a8b189a740
SecretID:         aa63ba44-bd88-0b0c-5475-34141fe6874c
Namespace:        db-team
Description:      DB developer token
Local:            false
Create Time:      2020-02-06 21:33:22.562854069 +0000 UTC
Policies:
   acb579f8-51b7-cb90-cd5b-f26a54b15715 - developer-policy
```

## Next steps

In this tutorial, you learned how to create namespaces and how to secure the
resources within a namespace. You created management tokens for two namespaces
and then a developer token for the db-team.

Note, the super-operator can also create policies that can be shared by all
namespaces. Shared policies are universal and should be created in the `default`
namespace.

Continue onto the [Register and Discover Services within Namespaces](/consul/tutorials/namespaces/namespaces-share-datacenter-access) tutorial to
learn how to register services within a namespace.

### Namespace inheritance with tokens

A token's namespace can be inherited during CLI and API requests related to services,
intentions, Consul KV, checks, and ACLs. This means that if you register a
service with a token in the app-team namespace, the service will be registered
in that namespace without having to specify it explicitly. In the tutorial you did
not use namespace inheritance from the token, since you explicitly used the
namespace flag.

<Note>

 Services registered with service definition configuration files must
have both the ACL token and namespace name defined in the [service definition
configuration file](/consul/docs/fundamentals/config-entry),
as these files are parsed prior to resolving the token.

</Note>