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.

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.

• 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 for more information.

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.

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"

{
  "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
Description:
   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
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.

$ consul namespace list

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.

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

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

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