docs(aws): restore dropped access section and document missing fields (#6517)

* docs(aws): restore dropped access section and document missing fields

The provider pages embed the shared AWS Access section via an mkdocs snippet
include. #5783 renamed snippets/provider-aws-access.md to provider/aws-access.md
without updating the two includes, so with pymdownx check_paths defaulting to
false the auth section (IRSA, EKS Pod Identity, custom endpoints, STS session
tags) silently stopped rendering on the Secrets Manager and Parameter Store
pages. Repoint both includes to provider/aws-access.md.

Also document spec.provider.aws fields that had no documentation
(additionalRoles, externalID, sessionTags, transitiveTagKeys,
auth.secretRef.sessionTokenSecretRef, prefix), and correct the dataFrom note:
BatchGetSecretValue is used with a path prefix or a tags-only filter, while a
name search without a path falls back to ListSecrets.

Signed-off-by: Alexander Chernov <alexander@chernov.it>

* docs(aws): point AGENTS.md transclusion note at the current auth-doc path

Signed-off-by: Alexander Chernov <alexander@chernov.it>

* docs(aws): switch shared auth transclusion to {% include %}

Addresses review feedback on #6517: use the macros plugin ({% include %})
instead of pymdownx snippets (--8<--) so transclusion is portable across
static site generators and the repo uses one include mechanism throughout.

The macros include_dir is docs/snippets, so the shared AWS auth content moves
there. docs/provider/aws-access.md stays as a thin {% include %} wrapper to
keep its nav entry, and the two service pages include the same snippet.
exclude_docs keeps the markdown partial from rendering as a standalone page.
AGENTS.md guidance updated to describe {% include %} rather than the scissors.

Signed-off-by: Alexander Chernov <alexander@chernov.it>

* docs(aws): link to auth page instead of transcluding it

The AWS auth section was transcluded in full into both aws-secrets-manager and
aws-parameter-store, so it rendered three times (its own page plus each service
page). Keep aws-access.md as a normal standalone page like every other provider
and have the service pages link to it instead.

This supersedes the previous wrapper approach: the snippet copy under
docs/snippets and the mkdocs exclude_docs entry it required are removed. Verified
with a local mkdocs build: all page URLs preserved (including /provider/aws-access/),
the auth content renders once, and the service-page links resolve to the auth page.

Signed-off-by: Alexander Chernov <alexander@chernov.it>

* dot

Signed-off-by: Alexander Chernov <alexander@chernov.it>

* remove dot

Signed-off-by: Alexander Chernov <alexander@chernov.it>

---------

Signed-off-by: Alexander Chernov <alexander@chernov.it>
Co-authored-by: Jean-Philippe Evrard <jean-philippe.evrard+rochepub@external.roche.com>

AGENTS.md

@@ -18,7 +18,7 @@ Multi-module repo: `apis/`, `runtime/`, `e2e/`, and each `providers/v1/*/` have
 
 - `make reviewable` is the gate for PRs. Run it, not individual checks.
 - Helm chart is the source of truth for deploy manifests. `make manifests` generates static YAML from it.
-- Provider docs use MkDocs snippet transclusion (`--8<--`). Auth docs are shared across providers via `docs/snippets/`.
+- Provider docs `{% include %}` reusable YAML snippets from `docs/snippets/` (`macros` plugin). AWS authentication is documented once on the standalone `docs/provider/aws-access.md` page; the per-service pages (`aws-secrets-manager.md`, `aws-parameter-store.md`) link to it rather than transcluding it.
 - CRD tests use snapshot testing. Run `make test.crds.update` to update snapshots after CRD changes.
 - `make update-deps` updates dependencies across all modules at once.
 - Add a `git notes add HEAD` entry on every non-trivial commit. Record key design decisions, trade-offs, and gotchas. Queryable via `git notes show <sha>`.
@@ -215,7 +215,7 @@ pattern, but expect to be the first.
 ### Documentation
 
 - Generator docs live at `docs/api/generator/<name>.md`.
-- YAML snippets in `docs/snippets/<name>-...yaml`, transcluded via `--8<--`.
+- YAML snippets in `docs/snippets/<name>-...yaml`, transcluded via `{% include %}` (macros plugin).
 - Nav entry goes under `Reference: -> API: -> Generators:` in `hack/api-docs/mkdocs.yml`. Append at the bottom.
 
 ### Manual checklist after bootstrap

docs/provider/aws-access.md

@@ -52,8 +52,14 @@ spec:
           secretAccessKeySecretRef:
             name: awssm-secret
             key: secret-access-key
+          # optional: only when using temporary (STS) credentials
+          sessionTokenSecretRef:
+            name: awssm-secret
+            key: session-token
 ```
 
+The optional `sessionTokenSecretRef` supplies an AWS session token alongside the access key and secret, which is required when the credentials are temporary (STS) rather than long-lived.
+
 **NOTE:** In case of a `ClusterSecretStore`, Be sure to provide `namespace` in `accessKeyIDSecretRef`, `secretAccessKeySecretRef` with the namespaces where the secrets reside.
 
 ### EKS Service Account credentials
@@ -95,6 +101,31 @@ spec:
 
 **NOTE:** In case of a `ClusterSecretStore`, Be sure to provide `namespace` for `serviceAccountRef` with the namespace where the service account resides.
 
+## Assuming Roles
+
+The optional `role` field makes ESO call `sts:AssumeRole` before accessing secrets, the recommended way to scope access per store. Two related fields refine role assumption:
+
+- `additionalRoles`: a chained list of Role ARNs the provider assumes sequentially *before* assuming `role`. Use it for cross-account role chaining.
+- `externalID`: the [external ID](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-user_externalid.html) passed when assuming `role`, for third-party trust scenarios.
+
+```yaml
+apiVersion: external-secrets.io/v1
+kind: SecretStore
+metadata:
+  name: team-b-store
+spec:
+  provider:
+    aws:
+      service: SecretsManager
+      region: eu-central-1
+      role: arn:aws:iam::222222222222:role/team-b
+      # optional: assume these roles in order first (e.g. cross-account hops)
+      additionalRoles:
+        - arn:aws:iam::111111111111:role/hop
+      # optional: external ID required by the target role's trust policy
+      externalID: my-external-id
+```
+
 ## EKS Pod Identity Setup
 
 In order to use EKS Pod Identity Agent, create a role like this:
@@ -261,6 +292,29 @@ Session tags will include the three automatically added tags, plus `env=producti
 
 **NOTE:** Custom tags with empty keys or empty values are silently ignored. Built-in tags (`esoNamespace`, `esoStoreName`, `esoStoreKind`) will always be included even when the sessionTagsPolicy is `Custom`. They cannot be overridden via `customSessionTags`.
 
+### Manually specified session tags
+
+Independent of `sessionTagsPolicy`, you can attach a fixed set of session tags to the assumed role with `spec.provider.aws.sessionTags`, and mark some of them transitive (kept across roles assumed afterwards in a chain) with `transitiveTagKeys`:
+
+```yaml
+apiVersion: external-secrets.io/v1
+kind: SecretStore
+metadata:
+  name: team-b-store
+spec:
+  provider:
+    aws:
+      service: SecretsManager
+      region: eu-central-1
+      role: arn:aws:iam::222222222222:role/team-b
+      sessionTags:
+        - key: cost-center
+          value: team-b
+      # keys whose tags persist across roles assumed afterwards (additionalRoles)
+      transitiveTagKeys:
+        - cost-center
+```
+
 ### Required IAM Permissions
 
 When session tags are enabled, the role trust policy must allow `sts:TagSession`:
@@ -277,3 +331,20 @@ When session tags are enabled, the role trust policy must allow `sts:TagSession`
   ]
 }
 ```
+
+## Prefix
+
+`spec.provider.aws.prefix` prepends a fixed string to every remote key the store resolves, for both reads and writes. No separator is added, so include any trailing delimiter yourself. For example, with `prefix: prod/`, a `remoteRef.key` of `db-password` resolves to `prod/db-password` in Secrets Manager or Parameter Store.
+
+```yaml
+apiVersion: external-secrets.io/v1
+kind: SecretStore
+metadata:
+  name: team-b-store
+spec:
+  provider:
+    aws:
+      service: SecretsManager
+      region: eu-central-1
+      prefix: prod/
+```

docs/provider/aws-parameter-store.md

@@ -180,4 +180,6 @@ You should see something similar to the following output:
 }
 ```
 
---8<-- "snippets/provider-aws-access.md"
+## Authentication
+
+See [AWS Authentication](aws-access.md) for all supported methods: controller pod identity, IRSA, static credentials, session tokens, assuming roles, session tags, and remote key prefixes.

docs/provider/aws-secrets-manager.md

@@ -13,9 +13,10 @@ way users of the `SecretStore` can only access the secrets necessary.
 ```
 **NOTE:** In case of a `ClusterSecretStore`, Be sure to provide `namespace` in `accessKeyIDSecretRef` and `secretAccessKeySecretRef`  with the namespaces where the secrets reside.
 
-**NOTE:** When using `dataFrom` without a `path` defined, the provider will fall back to using `ListSecrets`. `ListSecrets`
-then proceeds to fetch each individual secret in turn. To use `BatchGetSecretValue` and avoid excessive API calls define
-a `path` prefix or use `Tags` filter.
+**NOTE:** `dataFrom` uses the more efficient `BatchGetSecretValue` API when you define a `path`
+prefix, or when you filter by `Tags` only (without a `name`). When you search by `name` without a
+`path`, the provider falls back to `ListSecrets` and then fetches each matching secret
+individually, which is more costly. Define a `path` prefix to reduce the number of API calls.
 
 ### IAM Policy
 
@@ -331,4 +332,6 @@ spec:
       version: "uuid/123e4567-e89b-12d3-a456-426614174000"
 ```
 
---8<-- "snippets/provider-aws-access.md"
+## Authentication
+
+See [AWS Authentication](aws-access.md) for all supported methods: controller pod identity, IRSA, static credentials, session tokens, assuming roles, session tags, and remote key prefixes.