diff --git a/website/source/docs/acl/acl-rules.html.md b/website/source/docs/acl/acl-rules.html.md index 44abde6df6df..72a949aaae41 100644 --- a/website/source/docs/acl/acl-rules.html.md +++ b/website/source/docs/acl/acl-rules.html.md @@ -561,3 +561,69 @@ session "admin" { Session rules are segmented by the node name they apply to. In the example above, the rules allow read-only access to sessions on node name with the empty prefix, allow creating sessions on the node named "app", and deny all access to any sessions on the "admin" node. + +#### Namespacing + +<%= enterprise_alert :consul %> + +[Consul Enterprise](https://www.hashicorp.com/consul.html) 1.7.0 adds support for Namespacing of many +Consul resources. Rules can then be defined to only to apply to apply to specific namespaces. + +A Namespace specific rule would look like this: + +```hcl +namespace_prefix "" { + + # grant service:read for all services in all namespaces + service_prefix "" { + policy = "read" + } + + # grant node:read for all nodes in all namespaces + node_prefix "" { + policy = "read" + } +} + +namespace "foo" { + # grants permission to manage ACLs only for the foo namespace + acl = "write" + + # grants write permissions to the KV for namespace foo + key_prefix "" { + policy = "write" + } + + # grants write permissions for sessions for namespace foo + session_prefix "" { + policy = "write" + } + + # grants service:write for all services in the foo namespace + service_prefix "" { + policy = "write" + } + + # grants node:read for all nodes + node_prefix "" { + policy = "read" + } +} +``` + +There are some restrictions to the rules that can be contained within a `namespace` or `namespace_prefix` rule that +targets a non-`default` namespace. + +1. `operator` rules are not allowed. +2. `event` rules are not allowed. +3. `keyring` rules are not allowed. +4. `query` rules are not allowed. +5. `node` rules that attempt to grant `write` privileges are not allowed. + +In general all of the above are permissions that only an operator should have and thus granting these permissions can +only be targeted at the default namespace. + +-> **Implicit Namespacing:** Rules defined in a policy which itself resides in a namespace other than `default`, will +be implicitly namespaced. Therefore the restrictions defined here will apply to all rules within the policy including +those which are not enclosed in a `namespace` rule. Additionally, these policies will be prevented from defining rules +that would target any other namespace explicitly. diff --git a/website/source/docs/acl/acl-system.html.md b/website/source/docs/acl/acl-system.html.md index 37b24469630a..f59a643c2aa3 100644 --- a/website/source/docs/acl/acl-system.html.md +++ b/website/source/docs/acl/acl-system.html.md @@ -63,6 +63,9 @@ An ACL policy is a named set of rules and is composed of the following elements: * **Description** - A human readable description of the policy. (Optional) * **Rules** - Set of rules granting or denying permissions. See the [Rule Specification](/docs/acl/acl-rules.html#rule-specification) documentation for more details. * **Datacenters** - A list of datacenters the policy is valid within. +* **Namespace** - **Enterprise Only** - The namespace this policy resides within. (Added in Consul Enterprise 1.7.0) + +-> **Consul Enterprise Namespacing** - Rules defined in a policy in any namespace other than `default` will be [restricted](/docs/acl/acl-rules.html#namespacing) to being able to grant a subset of the overall permissions and only affecting that single namespace. #### Builtin Policies @@ -70,6 +73,9 @@ An ACL policy is a named set of rules and is composed of the following elements: and will be assigned the reserved ID of `00000000-0000-0000-0000-000000000001`. This policy can be renamed but modification of anything else including the rule set and datacenter scoping will be prevented by Consul. +* **Namespace Management** - **Enterprise Only** - Every Namespace created will have a policy injected with the name `namespace-management`. This policy gets injected with a randomized UUID and maybe be managed like any other user-defined policy +within the Namespace. (Added in Consul Enterprise 1.7.0) + ### ACL Service Identities -> Added in Consul 1.5.0 @@ -111,6 +117,9 @@ node_prefix "" { The [API documentation for roles](/api/acl/roles.html#sample-payload) has some examples of using a service identity. +-> **Consul Enterprise Namespacing** - Service Identity rules will be scoped to the single Namespace that +the corresponding ACL Token or Role resides within. + ### ACL Roles -> Added in Consul 1.5.0 @@ -121,8 +130,11 @@ of the following elements: * **ID** - The role's auto-generated public identifier. * **Name** - A unique meaningful name for the role. * **Description** - A human readable description of the role. (Optional) -* **Policy Set** - The list of policies that are applicable for the role. +* **Policy Set** - The list of policies that are applicable for the role. * **Service Identity Set** - The list of service identities that are applicable for the role. +* **Namespace** - **Enterprise Only** - The namespace this policy resides within. (Added in Consul Enterprise 1.7.0) + +-> **Consul Enterprise Namespacing** - Roles may only link to policies defined in the same Namespace as the role itself. ### ACL Tokens @@ -138,6 +150,10 @@ elements: * **Locality** - Indicates whether the token should be local to the datacenter it was created within or created in the primary datacenter and globally replicated. * **Expiration Time** - The time at which this token is revoked. (Optional; Added in Consul 1.5.0) +* **Namespace** - **Enterprise Only** - The namespace this policy resides within. (Added in Consul Enterprise 1.7.0) + +-> **Consul Enterprise Namespacing** - Tokens may only link to policies and roles defined in the same Namespace as +the token itself. #### Builtin Tokens @@ -210,6 +226,9 @@ Consul datacenters, and does not allow modification of any state. Constructing rules from these policies is covered in detail on the [ACL Rules](/docs/acl/acl-rules.html) page. +-> **Consul Enterprise Namespacing** - In addition to directly linked policies, roles and service identities, Consul Enterprise +will include the ACL policies and roles defined in the [Namespaces definition](/docs/enterprise/namespaces/index.html#namespace-definition). (Added in Consul Enterprise 1.7.0) + ## Configuring ACLs ACLs are configured using several different configuration options. These are marked diff --git a/website/source/docs/commands/namespace.html.md.erb b/website/source/docs/commands/namespace.html.md.erb new file mode 100644 index 000000000000..3acb1a509bfd --- /dev/null +++ b/website/source/docs/commands/namespace.html.md.erb @@ -0,0 +1,73 @@ +--- +layout: "docs" +page_title: "Commands: Namespace" +sidebar_current: "docs-commands-namespace" +description: > + The namespace command provides management of Consul Enterprise namespaces. +--- + +<%= enterprise_alert :consul %> + +# Consul Namespace + +Command: `consul namespace` + + +The `namespace` command provides management of Consul Enterprise namespaces. This was added in Consul Enterprise 1.7.0. + +If ACLs are enabled then a token with operator privileges may be required in order to use this command. Write +requests are forwarded to the leader in the primary datacenter. Therefore these commands can be run against +any agent in any datacenter. + +## Usage + +Usage: `consul namespace ` + +For the exact documentation for your Consul version, run `consul namespace -h` to view the complete list of subcommands. + +```text +Usage: consul namespace [options] [args] + + This command has subcommands for interacting with Consul Enterprise + Namespaces. Here are some simple examples. More detailed + examples are available in the subcommands or the documentation. + + ... + +Subcommands: + delete Delete a Namespace + list List all Namespaces + read Read a Namespace + write Create or update a Namespace +``` + +For more information, examples, and usage about a subcommand, click on the name +of the subcommand in the sidebar. + +## Namespace Definition + +## Basic Examples + +Create or update a Namespace: + +```sh +$ consul namespace write ns1.hcl +``` + +Read a Namespace: + +```sh +$ consul namespace read ns1 +``` + +List all Namespaces: + +```sh +$ consul namespace list +``` + +Delete a Namespace: + +```sh +$ consul namespace delete ns1 +``` diff --git a/website/source/docs/commands/namespace/delete.html.md.erb b/website/source/docs/commands/namespace/delete.html.md.erb new file mode 100644 index 000000000000..3c3153705068 --- /dev/null +++ b/website/source/docs/commands/namespace/delete.html.md.erb @@ -0,0 +1,31 @@ +--- +layout: "docs" +page_title: "Commands: Namespace Delete" +sidebar_current: "docs-commands-namespace-delete" +--- + +<%= enterprise_alert :consul %> + +# Consul Namespace Delete + +Command: `consul namespace delete` + +This `namespace delete` command deletes a namespace. This was added in Consul Enterprise 1.7.0. If +ACLs are enabled then this command will require a token with `operator:write` privileges. + +## Usage + +Usage: `consul namespace delete ` + +#### API Options + +<%= partial "docs/commands/http_api_options_client" %> +<%= partial "docs/commands/http_api_options_server" %> + +## Examples + +Delete a Namespace: + +```sh +$ consul namespace delete "team-1" +``` diff --git a/website/source/docs/commands/namespace/list.html.md.erb b/website/source/docs/commands/namespace/list.html.md.erb new file mode 100644 index 000000000000..f5968f544e8e --- /dev/null +++ b/website/source/docs/commands/namespace/list.html.md.erb @@ -0,0 +1,98 @@ +--- +layout: "docs" +page_title: "Commands: Namespace List" +sidebar_current: "docs-commands-namespace-list" +--- + +<%= enterprise_alert :consul %> + +# Consul Namespace List + +Command: `consul namespace list` + +This `namespace list` command lists all namespace configurations. This was added in Consul Enterprise 1.7.0. If +ACLs are enabled then this command will require a token with `operator:read` privileges or any `read` privileges +within the target namespaces. The results will be filtered based on the ACL token and therefore it is possible to +see a partial list. + +## Usage + +Usage: `consul namespace list` + +#### API Options + +<%= partial "docs/commands/http_api_options_client" %> +<%= partial "docs/commands/http_api_options_server" %> + +#### Command Options + +* `-format=` - How to output the results. The choices are: pretty or json + +* `-meta` - Indicates that namespace metadata such as the raft indices should be + shown for the namespace + +## Examples + +List Namespaces: + +```sh +$ consul namespace list +default: + Description: + Builtin Default Namespace +foo: + Description: + Example Namespace +team-1: + Description: + +``` + +Showing Raft Metadata: + +```sh +$ consul namespace list -meta +default: + Description: + Builtin Default Namespace + Create Index: 4 + Modify Index: 4 +foo: + Description: + Example Namespace + Create Index: 352 + Modify Index: 352 +team-1: + Description: + Create Index: 339 + Modify Index: 344 + +``` + +JSON Format: + +```sh +$ consul namespace list -format=json +[ + { + "Name": "default", + "Description": "Builtin Default Namespace", + "CreateIndex": 4, + "ModifyIndex": 4 + }, + { + "Name": "foo", + "Description": "Example Namespace", + "Meta": { + "team-id": "574407f3-8b26-4c84-8e51-028bb8cbdd37" + }, + "CreateIndex": 352, + "ModifyIndex": 352 + }, + { + "Name": "team-1", + "CreateIndex": 339, + "ModifyIndex": 344 + } +] +``` diff --git a/website/source/docs/commands/namespace/read.html.md.erb b/website/source/docs/commands/namespace/read.html.md.erb new file mode 100644 index 000000000000..b9e28346ac23 --- /dev/null +++ b/website/source/docs/commands/namespace/read.html.md.erb @@ -0,0 +1,66 @@ +--- +layout: "docs" +page_title: "Commands: Namespace Read" +sidebar_current: "docs-commands-namespace-read" +--- + +<%= enterprise_alert :consul %> + +# Consul Namespace Read + +Command: `consul namespace read` + +This `namespace read` command reads a namespaces configuration. This was added in Consul Enterprise 1.7.0. If +ACLs are enabled then this command will require a token with `operator:read` privileges or any `read` privileges +within the target namespace. + +## Usage + +Usage: `consul namespace read ` + +#### API Options + +<%= partial "docs/commands/http_api_options_client" %> +<%= partial "docs/commands/http_api_options_server" %> + +#### Command Options + +* `-format=` - How to output the results. The choices are: pretty or json + +* `-meta` - Indicates that namespace metadata such as the raft indices should be + shown for the namespace + +## Examples + +Read a Namespace: + +```sh +$ consul namespace read "team-1" +Name: team-1 +Description: +``` + +Showing Raft Metadata: + +```sh +$ consul namespace read -meta "team-1" +Name: team-1 +Description: +Create Index: 339 +Modify Index: 344 +``` + +JSON Format: + +```sh +$ consul namespace read -format=json foo +{ + "Name": "foo", + "Description": "Example Namespace", + "Meta": { + "team-id": "574407f3-8b26-4c84-8e51-028bb8cbdd37" + }, + "CreateIndex": 352, + "ModifyIndex": 352 +} +``` diff --git a/website/source/docs/commands/namespace/write.html.md.erb b/website/source/docs/commands/namespace/write.html.md.erb new file mode 100644 index 000000000000..4e6717f1d26a --- /dev/null +++ b/website/source/docs/commands/namespace/write.html.md.erb @@ -0,0 +1,74 @@ +--- +layout: "docs" +page_title: "Commands: Namespace Write" +sidebar_current: "docs-commands-namespace-write" +--- + +<%= enterprise_alert :consul %> + +# Consul Namespace Write + +Command: `consul namespace write` + +This `namespace write` command creates or updates a namespaces configuration. This was added in Consul Enterprise 1.7.0. + +## Usage + +Usage: `consul namespace write ` + +The `` must either be a file path or `-` to indicate that +the definition should be read from stdin. The definition can be in either JSON +or HCL format. + +#### API Options + +<%= partial "docs/commands/http_api_options_client" %> +<%= partial "docs/commands/http_api_options_server" %> + +#### Command Options + +* `-format=` - How to output the results. The choices are: pretty or json + +* `-meta` - Indicates that namespace metadata such as the raft indices should be + shown for the namespace + +## Examples + +Create a new Namespace: + +```sh +$ consul namespace write - <<< 'Name = "team-1"' +Name: team-1 +Description: +``` + +Showing Raft Metadata: + +```sh +$ consul namespace write -meta - <<< 'Name = "team-1"' +Name: team-1 +Description: +Create Index: 339 +Modify Index: 344 +``` + +JSON Format: + +```sh +$ cat ns.hcl +Name = "foo" +Description = "Example Namespace" +Meta { + team-id = "574407f3-8b26-4c84-8e51-028bb8cbdd37" +} +$ consul namespace write -format=json ns.hcl +{ + "Name": "foo", + "Description": "Example Namespace", + "Meta": { + "team-id": "574407f3-8b26-4c84-8e51-028bb8cbdd37" + }, + "CreateIndex": 352, + "ModifyIndex": 352 +} +``` diff --git a/website/source/docs/enterprise/namespaces/index.html.md b/website/source/docs/enterprise/namespaces/index.html.md new file mode 100644 index 000000000000..1b68dcdd96ce --- /dev/null +++ b/website/source/docs/enterprise/namespaces/index.html.md @@ -0,0 +1,104 @@ +--- +layout: "docs" +page_title: "Consul Enterprise Namespaces" +sidebar_current: "docs-enterprise-namespaces" +description: |- + Consul Enterprise enables data isolation with Namespaces. +--- + +# Consul Enterprise Namespaces + +With [Consul Enterprise](https://www.hashicorp.com/consul.html) v1.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. + +## Namespace Definition + +Namespaces are managed exclusively through the [HTTP API](/api/namespaces.html) and the [Consul CLI](/docs/commands/namespace.html). +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: + +JSON: + +```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: + +```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" +} +``` + +### Fields + +-`Name` `(string: )` - 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: )` - This fields is a nested JSON/HCL object to contain the Namespaces + ACL configuration. + + - `PolicyDefaults` `(array)` - 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. + + - `RoleDefaults` `(array)` - 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. + +- `Meta` `(map: )` - Specifies arbitrary KV metadata to associate with + this namespace.