Start explaining rules

docs/pages/reference/workload-identity/identity-attributes.mdx → docs/pages/reference/workload-identity/attributes.mdx

@@ -1,6 +1,6 @@
 ---
-title: Identity Attributes
-description: Information about the identity attributes that can be used in WorkloadIdentity templates and rules.
+title: Workload Identity Attributes
+description: Information about the attributes that can be used in templating and rules in the WorkloadIdentity resource.
 ---
 
 Attributes are features of an identity which you can use with the

docs/pages/reference/workload-identity/workload-identity-resource.mdx

@@ -12,6 +12,8 @@ It supports templating using attributes of the workload, such as the name of the
 Kubernetes namespace or service account, which allows the WorkloadIdentity
 resource to be used in a generic way for multiple distinct workloads.
 
+## Configuration
+
 ```yaml
 kind: workload_identity
 version: v1
@@ -111,7 +113,34 @@ spec:
 
 ## Templating
 
-The following fields support templating:
+The WorkloadIdentity resource supports templating in certain fields, this allows
+you to customise elements of the workload identity credential issued to
+workloads with attested attributes.
+
+For example, you can use templating to insert the name of the Kubernetes
+namespace and service account into the SPIFFE ID of the workload identity
+credential:
+
+```yaml
+kind: workload_identity
+version: v1
+metadata:
+  name: my-kubernetes-workload
+spec:
+  spiffe:
+    id: /k8s/{{ workload.kubernetes.namespace }}/{{ workload.kubernetes.service_account }}
+```
+
+Would result in a SPIFFE ID of `spiffe://example.teleport.sh/k8s/default/foo`
+for a workload running in the `default` namespace with the service account `foo`.
+
+When an attribute is specified in a template, this value must be present in the
+attributes of the workload in order for the workload identity credential to be
+issued. For example, if `workload.kubernetes.namespace` is used in a template,
+then a workload that is not running in Kubernetes would not be issued a
+credential.
+
+The following fields within the WorkloadIdentity resource support templating:
 
 - `spec.spiffe.id`
 - `spec.spiffe.hint`
@@ -120,8 +149,46 @@ The following fields support templating:
 - `spec.spiffe.x509.subject_template.organization`
 - `spec.spiffe.x509.subject_template.organizational_unit`
 
+You can find a full list of the supported attributes on the
+[Attributes reference](./attributes.mdx) page.
+
 ## Rules
 
+By default, a WorkloadIdentity resource can be used to issue a credential by any
+User or Bot that holds a role that with `workload_identity_labels` that match
+the labels on the WorkloadIdentity resource.
+
+However, you can further restrict the issuance of credentials based on the
+attributes of the workload using the rules mechanism.
+
+Each rule consists of a set of conditions, and all conditions within that rule
+must pass in order for the rule to be considered a pass. If you specify
+multiple rules, then at least one rule must pass in order for the
+WorkloadIdentity to be allowed to be issued.
+
+For example, to restrict the issuance of a credential to only workloads running
+in the `default` namespace with the service account `foo`:
+
+```yaml
+kind: workload_identity
+version: v1
+metadata:
+  name: rules-example
+spec:
+  spiffe:
+    id: /my-awesome-workload
+  rules:
+    allow:
+    - conditions:
+      - attribute: workload.kubernetes.namespace
+        eq:
+          value: default
+      - attribute: workload.kubernetes.service_account
+        eq:
+          value: foo
+```
+
+
 ## Infrastructure as Code
 
 In addition to the YAML representation which can be managed with `tctl`, the