status-im
/
consul
mirror of https://github.com/status-im/consul.git
2
0
Fork 0
Code Issues Projects Releases Wiki Activity

additional information about service and node ids

This commit is contained in:
trujillo-adam 2022-02-18 14:46:29 -08:00
parent cb08988096
commit b922da7db3
2 changed files with 272 additions and 39 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

298
website/content/docs/security/acl/acl-roles.mdx
View File

@ -70,65 +70,231 @@ Roles may contain the following table describe the attributes:
<!-- -> Added in Consul 1.5.0 # Remove and lean on versioning?-->
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.
<CodeTabs>
<CodeBlockConfig>
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": "<service name>",
"Datacenters": ["<datacenter name>"]
}
]
}
```
</CodeBlockConfig>
<CodeBlockConfig>
```hcl
"ServiceIdentities" = {
"ServiceName" = "<service name>"
"Datacenters" = ["<datacenter name>"]
}
```
</CodeBlockConfig>
</CodeTabs>
- `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 Name>" {
service "<service name>" {
policy = "write"
}
service "<service name>-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`.
<CodeTabs>
<CodeBlockConfig filename="example-role.hcl">
```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"
}
```
</CodeBlockConfig>
<CodeBlockConfig filename="example-role.json">
```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"
}
]
}
```
</CodeBlockConfig>
</CodeTabs>
During the authorization process, the following policies for the `web` and `db` services will be generated and linked to the token:
<CodeBlockConfig filename="web-policy.hcl">
```hcl
# Allow the service and its sidecar proxy to register into the catalog.
service "web" {
policy = "write"
}
service "<Service Name>-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.
</CodeBlockConfig>
-> **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.
<CodeBlockConfig filename="db-policy.hcl">
```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"
}
```
</CodeBlockConfig>
## Node Identities
-> Added in Consul 1.8.1
<!-- -> Added in Consul 1.8.1 -- remove and lean on doc version? -->
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:
<CodeTabs>
<CodeBlockConfig>
```json
{
"NodeIdentities": [
{
"NodeName": "<node name>",
"Datacenters": ["<datacenter name>"]
}
]
}
```
</CodeBlockConfig>
<CodeBlockConfig>
```hcl
"NodeIdentities" = {
"NodeName" = "<node name>"
"Datacenters" = ["<datacenter name>"]
}
```
</CodeBlockConfig>
</CodeTabs>
- `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 Name>" {
node "<node name>" {
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`.
<CodeTabs>
<CodeBlockConfig filename="example-role.hcl">
```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"
}
```
</CodeBlockConfig>
<CodeBlockConfig filename="example-role.json">
```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"
}
]
}
```
</CodeBlockConfig>
</CodeTabs>
During the authorization process, the following policy will be generated and linked to the token:
<CodeBlockConfig filename="node-1-policy.hcl">
```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"
}
```
</CodeBlockConfig>

13
website/content/docs/security/acl/acl-system.mdx
View File

@ -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: