From b922da7db3c5ccaf7484fede7eaf4064be54164a Mon Sep 17 00:00:00 2001 From: trujillo-adam Date: Fri, 18 Feb 2022 14:46:29 -0800 Subject: [PATCH] additional information about service and node ids --- .../content/docs/security/acl/acl-roles.mdx | 298 ++++++++++++++++-- .../content/docs/security/acl/acl-system.mdx | 13 +- 2 files changed, 272 insertions(+), 39 deletions(-) diff --git a/website/content/docs/security/acl/acl-roles.mdx b/website/content/docs/security/acl/acl-roles.mdx index 00da0bbd7c..e97869f2b2 100644 --- a/website/content/docs/security/acl/acl-roles.mdx +++ b/website/content/docs/security/acl/acl-roles.mdx @@ -70,65 +70,231 @@ Roles may contain the following table describe the attributes: -Service identities are methods for linking services that participate in a Consul service mesh to a policy. -They are configurations added to a role that specifies a services that participate in a Consul service mesh and links them to a policy. -Service identities are templates that provide privileges to _be discovered_ and to _discover other healthy service instances_ in a service mesh. -See [Service Mesh](/docs/connect) for additional information about Consul service mesh. +You can specify a service identity when configuring roles or linking tokens to policies. Service identities are used during the authorization process to automatically generate a policy for the service(s) specifed. The policy will be linked to the role or token so that the service(s) can _be discovered_ and _discover other healthy service instances_ in a service mesh. See [Service Mesh](/docs/connect) for additional information about Consul service mesh. Service identities enable you to quickly construct policies for services, rather than creating identical polices for each service. -They are usable -on both tokens and roles and are composed of the following elements: +### Service Identity Specification -- **Service Name** - The name of the service. -- **Datacenters** - A list of datacenters the effective policy is valid within. (Optional) +Use the following syntax to define a service identity: -Suitable policies tend to all look nearly identical so a service identity is a policy -template to aid in avoiding boilerplate policy creation. + + -During the authorization process, the configured service identity is automatically -applied as a policy with the following preconfigured [ACL -rules](/docs/acl/acl-system#acl-rules-and-scope): +```json +{ + "ServiceIdentities": [ + { + "ServiceName": "", + "Datacenters": [""] + } + ] +} +``` + + + + +```hcl +"ServiceIdentities" = { + "ServiceName" = "" + "Datacenters" = [""] +} +``` + + + + +- `ServiceIdentities`: Declares a service identity block. +- `ServiceIdentities.ServiceName`: String value that specifies the name of the service you want to associate with the policy. +- `ServiceIdentitites.Datacenters`: Array that specifies the names of datacenters in which the service identity applies. This field is optional. + +Refer to the the [API documentation for roles](/api/acl/roles#sample-payload) for additional information and examples. + +-> **Scope for Namespace and Admin Partition** - In Consul Enterprise, service identities inherit the namespace or admin partition scope of the corresponding ACL token or role. + +The following policy is generated for each service when a service identity is declared: ```hcl # Allow the service and its sidecar proxy to register into the catalog. -service "" { +service "" { + policy = "write" +} +service "-sidecar-proxy" { + policy = "write" +} + +# Allow for any potential upstreams to be resolved. +service_prefix "" { + policy = "read" +} +node_prefix "" { + policy = "read" +} + +``` + +Refer to the [rules reference](/docs/security/acl/acl-rules) for information about the rules in the policy. + +### Example + +The following role configuration contains service identities for the `web` and `db` services. Note that the `db` service is also scoped to the `dc1` datacenter so that the policy will only be applied to instances of `db` in `dc1`. + + + + +```hcl +"Description" = "Showcases all input parameters" +"Name" = "example-role" +"Policies" = { + "ID" = "783beef3-783f-f41f-7422-7087dc272765" +} +"Policies" = { + "Name" = "node-read" +} +"ServiceIdentities" = { + "ServiceName" = "web" +} +"ServiceIdentities" = { + "Datacenters" = ["dc1"] + "ServiceName" = "db" +} +``` + + + + +```json +{ + "Name": "example-role", + "Description": "Showcases all input parameters", + "Policies": [ + { + "ID": "783beef3-783f-f41f-7422-7087dc272765" + }, + { + "Name": "node-read" + } + ], + "ServiceIdentities": [ + { + "ServiceName": "web" + }, + { + "ServiceName": "db", + "Datacenters": ["dc1"] + } + ], + "NodeIdentities": [ + { + "NodeName": "node-1", + "Datacenter": "dc2" + } + ] +} +``` + + + + +During the authorization process, the following policies for the `web` and `db` services will be generated and linked to the token: + + + +```hcl +# Allow the service and its sidecar proxy to register into the catalog. +service "web" { policy = "write" } -service "-sidecar-proxy" { +service "web-sidecar-proxy" { policy = "write" } # Allow for any potential upstreams to be resolved. service_prefix "" { - policy = "read" + policy = "read" } node_prefix "" { - policy = "read" + policy = "read" } ``` -The [API documentation for roles](/api/acl/roles#sample-payload) has some -examples of using a service identity. + --> **Service Scope for Namespace and Admin Partition** - Service identity rules in Consul Enterprise are scoped to the namespace or admin partition within which the corresponding ACL token or role resides. +Per the `ServiceIdentitites.Datacenters` configuration, the `db` policy is scoped to resources in the `dc1` datacenter. + + + +```hcl +# Allow the service and its sidecar proxy to register into the catalog. +service "db" { + policy = "write" +} +service "db-sidecar-proxy" { + policy = "write" +} + +# Allow for any potential upstreams to be resolved. +service_prefix "" { + policy = "read" +} +node_prefix "" { + policy = "read" +} +``` + + ## Node Identities --> Added in Consul 1.8.1 + -An ACL node identity is an [ACL policy](/docs/acl/acl-system#policies) template for expressing a link to a policy -suitable for use as an [Consul `agent` token](/docs/agent/options#acl_tokens_agent). They are usable -on both tokens and roles and are composed of the following elements: +You can specify a node identity when configuring roles or linking tokens to policies. Node identities are used during the authorization process to automatically generate a policy for the node(s) specifed. In most cases, "node" refers to a Consul agent. -- **Node Name** - The name of the node to grant access to. -- **Datacenter** - The datacenter that the node resides within. +You can specify the token linked to the policy in the [`acl_tokens_agent`](/docs/agent/options#acl_tokens_agent) field when configuring the agent. Node identities enable you to quickly construct policies for nodes, rather than creating identical polices for each node. -During the authorization process, the configured node identity is automatically -applied as a policy with the following preconfigured [ACL -rules](/docs/acl/acl-system#acl-rules-and-scope): +### Node Identity Specification + +Use the following syntax to define a node identity: + + + + +```json +{ + "NodeIdentities": [ + { + "NodeName": "", + "Datacenters": [""] + } + ] +} +``` + + + + +```hcl +"NodeIdentities" = { + "NodeName" = "" + "Datacenters" = [""] +} +``` + + + + +- `NodeIdentities`: Declares a node identity block. +- `NodeIdentities.ServiceName`: String value that specifies the name of the node you want to associate with the policy. +- `NodeIdentitites.Datacenters`: Array that specifies the names of datacenters in which the node identity applies. This field is optional. + +Refer to the the [API documentation for roles](/api/acl/roles#sample-payload) for additional information and examples. + +-> **Consul Enterprise Namespacing** - Node Identities can only be applied to tokens and roles in the `default` namespace. The generated policy rules allow for `service:read` permissions on all services in all namespaces. + +The following policy is generated for each node when a node identity is declared: ```hcl # Allow the agent to register its own node in the Catalog and update its network coordinates -node "" { +node "" { policy = "write" } @@ -140,5 +306,73 @@ service_prefix "" { } ``` --> **Consul Enterprise Namespacing** - Node Identities can only be applied to tokens and roles in the `default` namespace. -The synthetic policy rules allow for `service:read` permissions on all services in all namespaces. +Refer to the [rules reference](/docs/security/acl/acl-rules) for information about the rules in the policy. + +### Example + +The following role configuration contains a node identity for `node-1`. Note that the node identity is also scoped to the `dc2` datacenter. As a result, the policy will only be applied to nodes named `node-1` in `dc2`. + + + + +```hcl +"Description" = "Showcases all input parameters" +"Name" = "example-role" +"NodeIdentities" = { + "Datacenter" = "dc2" + "NodeName" = "node-1", +} +"Policies" = { + "ID" = "783beef3-783f-f41f-7422-7087dc272765" +} +"Policies" = { + "Name" = "node-read" +} +``` + + + + +```json +{ + "Name": "example-role", + "Description": "Showcases all input parameters", + "Policies": [ + { + "ID": "783beef3-783f-f41f-7422-7087dc272765" + }, + { + "Name": "node-read" + } + ], + "NodeIdentities": [ + { + "NodeName": "node-1", + "Datacenter": "dc2" + } + ] +} +``` + + + + +During the authorization process, the following policy will be generated and linked to the token: + + + +```hcl +# Allow the agent to register its own node in the Catalog and update its network coordinates +node "node-1" { + policy = "write" +} + +# Allows the agent to detect and diff services registered to itself. This is used during +# anti-entropy to reconcile difference between the agents knowledge of registered +# services and checks in comparison with what is known in the Catalog. +service_prefix "" { + policy = "read" +} +``` + + diff --git a/website/content/docs/security/acl/acl-system.mdx b/website/content/docs/security/acl/acl-system.mdx index b4bfb5705b..9d2b6189ad 100644 --- a/website/content/docs/security/acl/acl-system.mdx +++ b/website/content/docs/security/acl/acl-system.mdx @@ -69,21 +69,20 @@ Refer to the [Roles](/docs/security/acl/acl-roles) topic for additional informat ## Service Identities -An ACL service identity is an ACL policy template for expressing a link to a policy suitable for use in a [service mesh](/docs/connect). +Service identities are configuration blocks that you can add to role configurations or specify when linking tokens to policies. The are used during the authorization process to automatically generate a policy for the service(s) specifed. The policy will be linked to the role or token so that the service(s) can _be discovered_ and _discover other healthy service instances_ in a service mesh. -Services participating in the service mesh will need privileges to both _be discovered_ and to _discover other healthy service instances_. Suitable -policies tend to all look nearly identical so a service identity is a policy template to aid in avoiding boilerplate policy creation. +Service identities enable you to quickly construct policies for services, rather than creating identical polices for each service. -Service identities can be used in tokens and roles. Refer to the following topics for additional information about service identities: +Refer to the following topics for additional information about service identities: - [Service Identities](/docs/security/acl/acl-roles#service-identities) - [API documentation for roles](/api/acl/roles#sample-payload) ## Node Identities -A node identity is a template that can be configured in tokens and roles. -They link nodes to policies suitable for use as an [Consul `agent` token](/docs/agent/options#acl_tokens_agent). -During the authorization process, the configured node identity is automatically applied as a policy. +Node identities are configuration blocks that you can add to role configurations or specify when linking tokens to policies. The are used during the authorization process to automatically generate a policy for the node(s) specifed. You can specify the token linked to the policy in the [`acl_tokens_agent`](/docs/agent/options#acl_tokens_agent) field when configuring the agent. + +Node identities enable you to quickly construct policies for nodes, rather than creating identical polices for each service. Refer to the following topics for additional information about node identities: