[NET-5327] Templated policies api/cli docs

hashicorp · Oct 20, 2023 · b66c7d0 · b66c7d0
1 parent 6ffcf28
commit b66c7d0
Show file tree

Hide file tree

Showing 25 changed files with 736 additions and 37 deletions.
diff --git a/website/content/api-docs/acl/auth-methods.mdx b/website/content/api-docs/acl/auth-methods.mdx
@@ -13,8 +13,10 @@ The `/acl/auth-method` endpoints [create](#create-an-auth-method),
 [list](#list-auth-methods) and [delete](#delete-an-auth-method)
 ACL auth methods in Consul.
 
-For more information on how to setup ACLs, please check
-the [ACL tutorial](/consul/tutorials/security/access-control-setup-production).
+For more information on how to setup ACLs, refer to the following resources: 
+
+- [Access control list (ACL) overview](/consul/docs/security/acl)
+- [ACL tutorial](/consul/tutorials/security/access-control-setup-production)
 
 ## Create an Auth Method
 
@@ -439,7 +441,7 @@ listing and must be retrieved by the [auth method reading endpoint](#read-an-aut
 ]
 ```
 
-## Methods to Specify Namespace <EnterpriseAlert inline />
+## Methods to specify namespace <EnterpriseAlert inline />
 
 Auth method create, read, update, and delete endpoints
 support several methods for specifying the namespace of the auth method resource.

diff --git a/website/content/api-docs/acl/binding-rules.mdx b/website/content/api-docs/acl/binding-rules.mdx
@@ -13,8 +13,10 @@ The `/acl/binding-rule` endpoints [create](#create-a-binding-rule),
 [list](#list-binding-rules) and [delete](#delete-a-binding-rule) ACL binding
 rules in Consul.
 
-For more information on how to setup ACLs, please check
-the [ACL tutorial](/consul/tutorials/security/access-control-setup-production).
+For more information on how to setup ACLs, refer to the following resources: 
+
+- [Access control list (ACL) overview](/consul/docs/security/acl)
+- [ACL tutorial](/consul/tutorials/security/access-control-setup-production)
 
 ## Create a Binding Rule
 
@@ -57,9 +59,9 @@ The corresponding CLI command is [`consul acl binding-rule create`](/consul/comm
   ```
 
 - `BindType` `(string: <required>)` - Specifies the way the binding rule
-  affects a token created at login.
+  affects a token created at login. You can specify one of the following:
 
-  - `BindType=service` - The computed bind name value is used as an
+  - `service` - The computed bind name value is used as an
     `ACLServiceIdentity.ServiceName` field in the token that is created.
 
     <CodeBlockConfig heading="Equivalent payload for Consul token API endpoint">
@@ -78,7 +80,7 @@ The corresponding CLI command is [`consul acl binding-rule create`](/consul/comm
 
     </CodeBlockConfig>
 
-  - `BindType=node` - The computed bind name value is used as an
+  - `node` - The computed bind name value is used as an
     `ACLNodeIdentity.NodeName` field in the token that is created.
 
     <CodeBlockConfig heading="Equivalent payload for Consul token API endpoint">
@@ -98,7 +100,7 @@ The corresponding CLI command is [`consul acl binding-rule create`](/consul/comm
 
     </CodeBlockConfig>
 
-  - `BindType=role` - The computed bind name value is used as a `RoleLink.Name`
+  - `role` - The computed bind name value is used as a `RoleLink.Name`
     field in the token that is created. This binding rule will only apply if a
     role with the given name exists at login-time. If it does not then this
     rule is ignored.
@@ -118,6 +120,29 @@ The corresponding CLI command is [`consul acl binding-rule create`](/consul/comm
     ```
 
     </CodeBlockConfig>
+
+  - `templated-policy` - The bind name value is used as an
+    `ACLTemplatedPolicy.TemplateName` field in the token that is created. The computed 
+    `BindVars` values are used for `ACLTemplatedPolicy.TemplateVariables` field.
+
+    <CodeBlockConfig heading="Equivalent payload for Consul token API endpoint">
+
+    ```json
+    {
+      "AccessorID": "<token accessor ID>",
+      "SecretID": "<token secret ID>",
+      "TemplatedPolicies": [
+        {
+          "TemplateName": "<template name>",
+          "TemplateVariables": {
+            "Name": "<name>"
+          }
+        }
+      ]
+    }
+    ```
+
+    </CodeBlockConfig>
 
 - `BindName` `(string: <required>)` - The name to bind to a token at
   login-time. What it binds to can be adjusted with different values of the
@@ -129,6 +154,20 @@ The corresponding CLI command is [`consul acl binding-rule create`](/consul/comm
   prefixed-${serviceaccount.name}
   ```
 
+- `BindVars` `(<ACLTemplatedPolicyVariables>)` - Specifies the templated policy
+  variables when `BindType` field is set to `templated-policy`. Consul populates
+  the `TemplatedPolicies.TemplateVariables` field with the computed `BindVars` values
+  in the token it creates. You can specify either a plain text string or templated 
+  string using [HIL syntax](https://github.com/hashicorp/hil).
+  Consul interpolates templated strings with values that are usable by the `Selector` syntax. 
+  For example:
+
+  ```
+    "BindVars": {
+      "Name": "prefixed-${serviceaccount.name}"
+    }
+  ```
+
 - `Namespace` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the binding rule you create.
   This field takes precedence over the `ns` query parameter,
   one of several [other methods to specify the namespace](#methods-to-specify-namespace).
@@ -270,9 +309,9 @@ The corresponding CLI command is [`consul acl binding-rule update`](/consul/comm
   ```
 
 - `BindType` `(string: <required>)` - Specifies the way the binding rule
-  affects a token created at login.
+  affects a token created at login. You can specify one of the following:
 
-  - `BindType=service` - The computed bind name value is used as an
+  - `service` - The computed bind name value is used as an
     `ACLServiceIdentity.ServiceName` field in the token that is created.
 
     <CodeBlockConfig heading="Equivalent payload for Consul token API endpoint">
@@ -291,7 +330,7 @@ The corresponding CLI command is [`consul acl binding-rule update`](/consul/comm
 
     </CodeBlockConfig>
 
-  - `BindType=node` - The computed bind name value is used as an
+  - `node` - The computed bind name value is used as an
     `ACLNodeIdentity.NodeName` field in the token that is created.
 
     <CodeBlockConfig heading="Equivalent payload for Consul token API endpoint">
@@ -311,7 +350,7 @@ The corresponding CLI command is [`consul acl binding-rule update`](/consul/comm
 
     </CodeBlockConfig>
 
-  - `BindType=role` - The computed bind name value is used as a `RoleLink.Name`
+  - `role` - The computed bind name value is used as a `RoleLink.Name`
     field in the token that is created. This binding rule will only apply if a
     role with the given name exists at login-time. If it does not then this
     rule is ignored.
@@ -331,6 +370,30 @@ The corresponding CLI command is [`consul acl binding-rule update`](/consul/comm
     ```
 
     </CodeBlockConfig>
+
+  - `templated-policy` - Consul populates the `TemplatedPolicies.TemplateName` with
+    the value specified in the `BindName` field in the token that is created. Consul 
+    also populates the `TemplatedPolicies.TemplateVariables` field with the computed 
+    `BindVars` values.
+
+    <CodeBlockConfig heading="Equivalent payload for Consul token API endpoint">
+
+    ```json
+    {
+      "AccessorID": "<token accessor ID>",
+      "SecretID": "<token secret ID>",
+      "TemplatedPolicies": [
+        {
+          "TemplateName": "<template name>",
+          "TemplateVariables": {
+            "Name": "<name>"
+          }
+        }
+      ]
+    }
+    ```
+
+    </CodeBlockConfig>
 
 - `BindName` `(string: <required>)` - The name to bind to a token at
   login-time. What it binds to can be adjusted with different values of the
@@ -342,6 +405,20 @@ The corresponding CLI command is [`consul acl binding-rule update`](/consul/comm
   prefixed-${serviceaccount.name}
   ```
 
+- `BindVars` `(<ACLTemplatedPolicyVariables>)` - Specifies the templated policy
+  variables when the `BindType` field is set to `templated-policy`. Consul 
+  populates the  `TemplatedPolicies.TemplateVariables` field with the computed 
+  `BindVars` values  in the token it creates. You can specify either a plain text
+  string or templated string using [HIL syntax](https://github.com/hashicorp/hil). 
+  Consul interpolates templated strings with values that are usable by the `Selector` 
+  syntax. For example:
+
+  ```
+    "BindVars": {
+      "Name": "prefixed-${serviceaccount.name}"
+    }
+  ```
+
 - `Namespace` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the binding rule you update.
   This field takes precedence over the `ns` query parameter,
   one of several [other methods to specify the namespace](#methods-to-specify-namespace).
@@ -486,7 +563,7 @@ $ curl --request GET http://127.0.0.1:8500/v1/acl/binding-rules
 ]
 ```
 
-## Methods to Specify Namespace <EnterpriseAlert inline />
+## Methods to specify namespace <EnterpriseAlert inline />
 
 Binding rule create, read, update, and delete endpoints
 support several methods for specifying the namespace of the auth method resource

diff --git a/website/content/api-docs/acl/index.mdx b/website/content/api-docs/acl/index.mdx
@@ -8,8 +8,10 @@ description: The /acl endpoints manage the Consul's ACL system.
 
 The `/acl` endpoints are used to manage ACL tokens and policies in Consul, [bootstrap the ACL system](#bootstrap-acls) and [check ACL replication status](#check-acl-replication). There are additional pages for managing [tokens](/consul/api-docs/acl/tokens) and [policies](/consul/api-docs/acl/policies) with the `/acl` endpoints.
 
-For more information on how to setup ACLs, please check
-the [ACL tutorial](/consul/tutorials/security/access-control-setup-production).
+For more information on how to setup ACLs, refer to the following resources: 
+
+- [Access control list (ACL) overview](/consul/docs/security/acl)
+- [ACL tutorial](/consul/tutorials/security/access-control-setup-production)
 
 ## Bootstrap ACLs
 
@@ -506,7 +508,7 @@ $ curl \
 }
 ```
 
-## Methods to Specify Namespace <EnterpriseAlert inline />
+## Methods to specify namespace <EnterpriseAlert inline />
 
 Some ACL endpoints support several methods for specifying the namespace of the resource
 with the following order of precedence:

diff --git a/website/content/api-docs/acl/policies.mdx b/website/content/api-docs/acl/policies.mdx
@@ -380,7 +380,7 @@ retrieved by the [policy reading endpoint](#read-a-policy)
 ]
 ```
 
-## Methods to Specify Namespace <EnterpriseAlert inline />
+## Methods to specify namespace <EnterpriseAlert inline />
 
 ACL policy endpoints
 support several methods for specifying the namespace of the ACL policy resources

diff --git a/website/content/api-docs/acl/roles.mdx b/website/content/api-docs/acl/roles.mdx
@@ -11,8 +11,10 @@ description: The /acl/role endpoints manage Consul's ACL Roles.
 The `/acl/role` endpoints [create](#create-a-role), [read](#read-a-role),
 [update](#update-a-role), [list](#list-roles) and [delete](#delete-a-role) ACL roles in Consul.
 
-For more information on how to setup ACLs, please check
-the [ACL tutorial](/consul/tutorials/security/access-control-setup-production).
+For more information on how to setup ACLs, refer to the following resources: 
+
+- [Access control list (ACL) overview](/consul/docs/security/acl)
+- [ACL tutorial](/consul/tutorials/security/access-control-setup-production)
 
 ## Create a Role
 
@@ -55,9 +57,17 @@ The corresponding CLI command is [`consul acl role create`](/consul/commands/acl
   linking roles internally by IDs, Consul enables policy renaming without
   breaking tokens.
 
+- `TemplatedPolicies` `(list of maps)` - The list of [templated policies](/consul/docs/security/acl#templated-policies)
+  that should be applied to the role.
+
+    - `TemplateName` `(string: <required>)` - The templated policy name.
+
+    - `TemplateVariables` `(map of strings|maps: <optional>)` - The templated policy variables. Not all templated policies
+      require variables.
+
 - `ServiceIdentities` `(array<ServiceIdentity>)` - The list of [service
   identities](/consul/docs/security/acl#service-identities) that should be
-  applied to the role. Added in Consul 1.5.0.
+  applied to the role.
 
   - `ServiceName` `(string: <required>)` - The name of the service. The name
     must be no longer than 256 characters, must start and end with a lowercase
@@ -71,7 +81,7 @@ The corresponding CLI command is [`consul acl role create`](/consul/commands/acl
 
 - `NodeIdentities` `(array<NodeIdentity>)` - The list of [node
   identities](/consul/docs/security/acl#node-identities) that should be
-  applied to the role. Added in Consul 1.8.1.
+  applied to the role.
 
   - `NodeName` `(string: <required>)` - The name of the node. The name
     must be no longer than 256 characters, must start and end with a lowercase
@@ -99,6 +109,17 @@ The corresponding CLI command is [`consul acl role create`](/consul/commands/acl
       "Name": "node-read"
     }
   ],
+  "TemplatedPolicies": [
+     {
+      "TemplateName": "builtin/service",
+      "TemplateVariables": {
+        "Name": "api"
+      }
+    },
+    {
+      "TemplateName": "builtin/dns"
+    }
+  ],
   "ServiceIdentities": [
     {
       "ServiceName": "web"
@@ -153,6 +174,19 @@ $ curl --request PUT \
       "Datacenter": "dc2"
     }
   ],
+  "TemplatedPolicies": [
+    {
+      "TemplateID": "00000000-0000-0000-0000-000000000003",
+      "TemplateName": "builtin/service",
+      "TemplateVariables": {
+        "Name": "api"
+      }
+    },
+    {
+      "TemplateID": "00000000-0000-0000-0000-000000000005",
+      "TemplateName": "builtin/dns"
+    }
+  ],
   "Hash": "mBWMIeX9zyUTdDMq8vWB0iYod+mKBArJoAhj6oPz3BI=",
   "CreateIndex": 57,
   "ModifyIndex": 57
@@ -223,6 +257,19 @@ $ curl --request GET http://127.0.0.1:8500/v1/acl/role/aa770e5b-8b0b-7fcf-e5a1-8
       "Datacenter": "dc2"
     }
   ],
+  "TemplatedPolicies": [
+    {
+      "TemplateID": "00000000-0000-0000-0000-000000000003",
+      "TemplateName": "builtin/service",
+      "TemplateVariables": {
+        "Name": "api"
+      }
+    },
+    {
+      "TemplateID": "00000000-0000-0000-0000-000000000005",
+      "TemplateName": "builtin/dns"
+    }
+  ],
   "Hash": "mBWMIeX9zyUTdDMq8vWB0iYod+mKBArJoAhj6oPz3BI=",
   "CreateIndex": 57,
   "ModifyIndex": 57
@@ -293,6 +340,19 @@ $ curl --request GET http://127.0.0.1:8500/v1/acl/role/name/example-role
       "Datacenter": "dc2"
     }
   ],
+  "TemplatedPolicies": [
+    {
+      "TemplateID": "00000000-0000-0000-0000-000000000003",
+      "TemplateName": "builtin/service",
+      "TemplateVariables": {
+        "Name": "api"
+      }
+    },
+    {
+      "TemplateID": "00000000-0000-0000-0000-000000000005",
+      "TemplateName": "builtin/dns"
+    }
+  ],
   "Hash": "mBWMIeX9zyUTdDMq8vWB0iYod+mKBArJoAhj6oPz3BI=",
   "CreateIndex": 57,
   "ModifyIndex": 57
@@ -379,6 +439,11 @@ The corresponding CLI command is [`consul acl role update`](/consul/commands/acl
       "NodeName": "node-1",
       "Datacenter": "dc2"
     }
+  ],
+  "TemplatedPolicies": [
+    {
+      "TemplateName": "builtin/dns"
+    }
   ]
 }
 ```
@@ -414,6 +479,12 @@ $ curl --request PUT \
       "Datacenter": "dc2"
     }
   ],
+  "TemplatedPolicies": [
+    {
+      "TemplateID": "00000000-0000-0000-0000-000000000005",
+      "TemplateName": "builtin/dns"
+    }
+  ],
   "Hash": "OtZUUKhInTLEqTPfNSSOYbRiSBKm3c4vI2p6MxZnGWc=",
   "CreateIndex": 14,
   "ModifyIndex": 28
@@ -550,7 +621,7 @@ $ curl --request GET http://127.0.0.1:8500/v1/acl/roles
 ]
 ```
 
-## Methods to Specify Namespace <EnterpriseAlert inline />
+## Methods to specify namespace <EnterpriseAlert inline />
 
 ACL role endpoints
 support several methods for specifying the namespace of the ACL role resources