Setup secure namespaces
Enterprise Only
The namespace functionality demonstrated here requires HashiCorp Cloud Platform (HCP) or self-managed Consul Enterprise. If you've purchased or wish to try out Consul Enterprise, refer to how to access Consul Enterprise.
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
andacl=write
privileges, or an ACL token with the built-in global management policy. See the Consul ACL policies documentation for more information.
Tip
The content of this tutorial also applies to Consul clusters hosted on HashiCorp Cloud (HCP).
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
.
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.
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
.
After successfully creating the app-team namespace, create the db-team namespace.
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.
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.
If the command is successful, Consul will return the token information.
Both token should be generated successfully before continuing.
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.
View namespace management tokens
To view tokens within a namespace, you will need to use the -namespace
command-line flag.
The output will return all tokens in the namespace. In this tutorial example, there is only one.
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.
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.
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.
This policy allows writing services and intentions for those services.
Using the Consul CLI, create the policy using the policy file.
Create the token
Using the developer policy defined previously, create a token for the developer in the db-team namespace.
The output will provide token information, including the namespace where the token is located.
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.
Note
Services registered with service definition configuration files must have both the ACL token and namespace name defined in the service definition configuration file, as these files are parsed prior to resolving the token.