backport of commit c1c258a70b (#22082)

Co-authored-by: Yoko Hyakuna <yoko@hashicorp.com>

website/content/docs/enterprise/sentinel/index.mdx

@@ -6,7 +6,13 @@ description: An overview of how Sentinel interacts with Vault Enterprise.
 
 # Overview
 
--> **Note**: This feature requires [Vault Enterprise Plus](https://www.hashicorp.com/products/vault/).
+<Note>
+
+Sentinel requires [Vault
+Enterprise](https://www.hashicorp.com/products/vault/pricing/) license, or an
+[HCP Vault Plus](/hcp/docs/vault/tiers-and-features#plus-tier) cluster.
+
+</Note>
 
 Vault Enterprise integrates HashiCorp Sentinel to provide a rich set of access
 control functionality. Because Vault is a security-focused product trusted with
@@ -42,22 +48,89 @@ Sentinel execution should be considered to be significantly slower than normal
 ACL policy checking. If high performance is needed, testing should be performed
 appropriately when introducing Sentinel policies.
 
+### Policy enforcement levels
+
+Sentinel policies have three enforcement levels to choose from.
+
+| Level          | Description                                                                |
+| -------------- | -------------------------------------------------------------------------- |
+| advisory       | The policy is allowed to fail. Can be used as a tool to educate new users. |
+| soft-mandatory | The policy must pass unless an override is specified.                      |
+| hard-mandatory | The policy must pass.                                       |
+
+
 ## Policy evaluation
 
-During evaluation, all policy types, if they exist, must grant access.
-Evaluation uses the following logic:
+Vault evaluates incoming requests against policies of all types that are
+applicable.
 
-1. If the request is unauthenticated, skip to step 3. Otherwise, evaluate the
-   token's ACL policies. These must grant access; as always, a failure to be
-   granted capabilities on a path via ACL policies denies the request.
-2. RGPs attached to the token are evaluated. All policies must pass according
+![Policy evaluation](/img/diagram-policy-evaluation-workflow_light.png#light-theme-only)
+![Policy evaluation](/img/diagram-policy-evaluation-workflow_dark.png#dark-theme-only)
+
+1. If the request is unauthenticated, skip to evaluating the EGPs. Otherwise,
+   evaluate the token's ACL policies. These must grant access; as always, a
+   failure to be granted capabilities on a path via ACL policies denies the
+   request.
+2. Evaluate RGPs attached to the client token. All policies must pass according
    to their enforcement level.
-3. EGPs set on the requested path, and any prefix-matching EGPs set on
-   less-specific paths, are evaluated. All policies must pass according to
-   their enforcement level.
+3. Evaluate EGPs set on the requested path, and any prefix-matching EGPs set on
+   less-specific paths, are evaluated. All policies must pass according to their
+   enforcement level.
 
 Any failure at any of these steps results in a denied request.
 
+### RGPs and namespaces
+
+Policies, auth methods, secrets engines, and tokens are locked into the
+[namespace](/vault/docs/enterprise/namespaces) they are created in. However,
+identity groups can pull in entities and groups from other namespaces.
+
+<Tip>
+
+Refer to the [Set up entities and groups section of the Secure Multi-Tenancy
+with Namespaces
+tutorial](/vault/tutorials/enterprise/namespaces#set-up-entities-and-groups) for
+a step-by-step instruction.
+
+</Tip>
+
+Consider the following scenario. 
+
+The training namespace is a child namespace of the education namespace. The "Sun
+Shine" entity created in the education namespace is a member of the "Tester"
+group which is defined in the training namespace. The group members inherit the
+group-level policy.
+
+![Relationship](/img/diagram-rgp-namespace_light.png#light-theme-only)
+![Relationship](/img/diagram-rgp-namespace_dark.png#dark-theme-only)
+
+While ACL policies and EGPs set rules on a specific path, an RGP does not
+specify a target path. RGPs are tied to tokens, identity entities, or identity
+groups that you can write rules without specifying a path.
+
+What if the deny-all RGP in the training namespace looked like:
+
+<CodeBlockConfig filename="deny-all.sentinel">
+
+```hcl
+precond = rule {
+   identity.entity.metadata.org_id is "A012345X"
+}
+
+main = rule when precond {
+   false
+}
+```
+
+</CodeBlockConfig>
+
+Vault checks the requesting token's entity metadata. If the `org_id` metadata
+exists and the value is `A012345X`, the request gets denied because the
+enforcement level is hard-mandatory. It does not matter if the request invokes a
+path starts with `/education` or `/education/training`, or even `/foo` because
+there is no path associated with the deny-all RGP.
+
+
 ## Policy overriding
 
 Vault supports normal Sentinel overriding behavior. Requests to override can be
@@ -83,7 +156,7 @@ necessary to pre-populate Identity entries or supply additional parameters with
 the request if you require more information to use MFA than the endpoint is
 able to glean from the original request alone.
 
-# Using sentinel
+# Using Sentinel
 
 ## Configuration