Virtual Event
Join us for the next HashiConf Digital October 12-15, 2020 Register for Free

Segment Services with Namespaces


Setup Secure Namespaces

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.


To execute the example commands in this tutorial, you will need a Consul 1.7 Enterprise datacenter with ACLs enabled. If you do not have an existing datacenter, you can use a single local agent.

You will also need an ACL token with operator=write and acl=write privileges or you can use a token with the built-in global management policy.

»[Optional] Configure Consul CLI

If you are using a non-local deployment, you can configure a local Consul binary to interact with the deployment. Set the CONSUL_HTTP_ADDR variable on your local machine or jumphost to the IP address of a client.


Note, this jumphost will need to use an ACL token to access the datacenter. The token's necessary privileges will depend on the operations, learn more about privileges by reviewing the ACL rule documentation. You can export the token with the CONSUL_HTTP_TOKEN variable. Additionally, if you have TLS encryption configured you will need to use valid certificates.

»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 JSON files to define the namespace for the app-team and db-team.

  "name": "app-team",
  "description": "Namespace for app-team managing the production dashboard application"
  "name": "db-team",
  "description": "Namespace for db-team managing the production counting application"

These namespace definitions are for minimal configuration, with only the name and description. Learn more about namespace options in the documentation.

»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.

$ consul namespace write app-team.json
Name: app-team
   Namespace for app-team managing the production dashboard application

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

$ consul namespace write db-team.json
Name: db-team
   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.

$ consul namespace list
      Namespace for app-team managing the production dashboard application
      Namespace for db-team managing the production counting application
      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.

»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 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.

$ 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.

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
   da57f91d-efeb-bfe2-f0e9-685e0ce99bde - namespace-management
$ consul acl token create \
      -namespace db-team \
      -description "DB Team Administrator" \
      -policy-name "namespace-management"

Both token should be generated successfully before continuing.

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
   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.

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.

$ consul acl token list -namespace app-team

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

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
   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.

»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.

$ 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.

service_prefix "" {
  policy = "write"
  intention = "write"

This policy allows writing services and intentions for those services.

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

$ 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.

$ 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.

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
   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 tutorial to learn how to register services within a namespace.

»Namespace inheritance with tokens

A token's namespace can be inherited during 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.