119 lines
4.1 KiB
Plaintext
119 lines
4.1 KiB
Plaintext
---
|
|
layout: docs
|
|
page_title: Namespaces (Enterprise)
|
|
description: >-
|
|
Namespaces reduce operational challenges in large deployments. Learn how to define a namespace so that multiple users or teams can access and use the same datacenter without impacting each other.
|
|
---
|
|
|
|
# Consul Enterprise Namespaces
|
|
|
|
<EnterpriseAlert>
|
|
|
|
This feature requires
|
|
HashiCorp Cloud Platform (HCP) or self-managed Consul Enterprise.
|
|
Refer to the [enterprise feature matrix](/docs/enterprise#consul-enterprise-feature-availability) for additional information.
|
|
|
|
</EnterpriseAlert>
|
|
|
|
With Consul Enterprise 1.7.0+, data for different users or teams
|
|
can be isolated from each other with the use of namespaces. Namespaces help reduce operational challenges
|
|
by removing restrictions around uniqueness of resource names across distinct teams, and enable operators
|
|
to provide self-service through delegation of administrative privileges.
|
|
|
|
For more information on how to use namespaces with Consul Enterprise please review the following tutorials:
|
|
|
|
- [Register and Discover Services within Namespaces](https://learn.hashicorp.com/tutorials/consul/namespaces-share-datacenter-access?utm_source=docs) - Register multiple services within different namespaces in Consul.
|
|
- [Setup Secure Namespaces](https://learn.hashicorp.com/tutorials/consul/namespaces-secure-shared-access?utm_source=docs) - Secure resources within a namespace and delegate namespace ACL rights via ACL tokens.
|
|
|
|
## Namespace Definition
|
|
|
|
Namespaces are managed exclusively through the [HTTP API](/api-docs/namespaces) and the [Consul CLI](/commands/namespace).
|
|
The HTTP API accepts only JSON formatted definitions while the CLI will parse either JSON or HCL.
|
|
|
|
An example namespace definition looks like the following:
|
|
|
|
<CodeTabs>
|
|
|
|
```json
|
|
{
|
|
"Name": "team-1",
|
|
"Description": "Namespace for Team 1",
|
|
"ACLs": {
|
|
"PolicyDefaults": [
|
|
{
|
|
"ID": "77117cf6-d976-79b0-d63b-5a36ac69c8f1"
|
|
},
|
|
{
|
|
"Name": "node-read"
|
|
}
|
|
],
|
|
"RoleDefaults": [
|
|
{
|
|
"ID": "69748856-ae69-d620-3ec4-07844b3c6be7"
|
|
},
|
|
{
|
|
"Name": "ns-team-2-read"
|
|
}
|
|
]
|
|
},
|
|
"Meta": {
|
|
"foo": "bar"
|
|
}
|
|
}
|
|
```
|
|
|
|
```hcl
|
|
Name = "team-1"
|
|
Description = "Namespace for Team 1"
|
|
ACLs {
|
|
PolicyDefaults = [
|
|
{
|
|
ID = "77117cf6-d976-79b0-d63b-5a36ac69c8f1"
|
|
},
|
|
{
|
|
Name = "node-read"
|
|
}
|
|
]
|
|
RoleDefaults = [
|
|
{
|
|
"ID": "69748856-ae69-d620-3ec4-07844b3c6be7"
|
|
},
|
|
{
|
|
"Name": "ns-team-2-read"
|
|
}
|
|
]
|
|
}
|
|
Meta {
|
|
foo = "bar"
|
|
}
|
|
```
|
|
|
|
</CodeTabs>
|
|
|
|
### Fields
|
|
|
|
- `Name` `(string: <required>)` - The namespaces name must be a valid DNS hostname label.
|
|
|
|
- `Description` `(string: "")` - This field is intended to be a human readable description of the
|
|
namespace's purpose. It is not used internally.
|
|
|
|
- `ACLs` `(object: <optional>)` - This fields is a nested JSON/HCL object to contain the namespaces
|
|
ACL configuration.
|
|
|
|
- `PolicyDefaults` `(array<ACLLink>)` - A list of default policies to be applied to all tokens
|
|
created in this namespace. The ACLLink object can contain an `ID` and/or `Name` field. When the
|
|
policies ID is omitted Consul will resolve the name to an ID before writing the namespace
|
|
definition internally. Note that all policies linked in a namespace definition must be defined
|
|
within the `default` namespace, and the ACL token used to create or edit the
|
|
namespace must have [`acl:write` access](/docs/security/acl/acl-rules#acl-resource-rules) to the linked policy.
|
|
|
|
- `RoleDefaults` `(array<ACLLink>)` - A list of default roles to be applied to all tokens
|
|
created in this namespace. The ACLLink object can contain an `ID` and/or `Name` field. When the
|
|
roles' ID is omitted Consul will resolve the name to an ID before writing the namespace
|
|
definition internally. Note that all roles linked in a namespace definition must be defined
|
|
within the `default` namespace, and the ACL token used to create or edit the
|
|
namespace must have [`acl:write` access](/docs/security/acl/acl-rules#acl-resource-rules) to the linked role.
|
|
|
|
- `Meta` `(map<string|string>: <optional>)` - Specifies arbitrary KV metadata to associate with
|
|
this namespace.
|