docs(esc): expand aws-secrets provider page

[jkodroff]

Expands the aws-secrets ESC provider page to close the content gaps in #19460, leaning on the already-refreshed aws-login page instead of duplicating login docs.

Changes

• Static-credentials and version-pinning (versionId/versionStage) examples
• New "Required IAM permissions" section (secretsmanager:GetSecretValue + KMS decrypt) with a sample policy
• Security note: use a dedicated, least-privilege role just for secret retrieval
• Note on defining the OIDC login once in a base environment and importing it
• Secrets-specific Troubleshooting section (access denied, secret not found, KMS decrypt)
• Cross-links to aws-login; trimmed the redundant OIDC validation walkthrough
• Headings to sentence case, bullets to dashes

Closes #19460

[github-actions]

Pre-merge Review — Last updated 2026-06-16T21:52:00Z

Tip

Summary: This PR expands the aws-secrets ESC provider reference page (content/docs/esc/providers/secrets/aws-secrets.md) from two basic examples into a comprehensive guide: it adds a login-input intro, version-pinning and static-credentials examples, a "Required IAM permissions" section with a sample policy, and a "Troubleshooting" section. It parallels the other secrets-provider pages under content/docs/esc/providers/secrets/ but is now the most detailed page in that family. The wrongness that would block a reader is concrete and copy-pasteable: incorrect IAM actions or ARN formats, wrong AWS staging-label semantics (AWSCURRENT/AWSPREVIOUS), or broken cross-links to the aws-login/OIDC/imports pages — readers lift these policies and YAML blocks directly. Passes run: external + in-repo claim verification (24 claims against AWS docs and sibling pages), a cross-sibling read of all 8 peer provider pages, code-example structural checks, a frontmatter/alias sweep, and the Hugo build (skipped — content-only change).

Review confidence:

Dimension	Level	Notes
mechanics	HIGH
facts	HIGH
cross-sibling consistency	HIGH	Read all 8 peer pages; no contradictions. The ## Examples (plural) + sentence-case H3 headings diverge from siblings' singular ## Example, but that's justified — the page now carries four examples.
code correctness	HIGH

Investigation log

• Cross-sibling reads: 8 of 8 siblings
• External claim verification: 20 of 24 claims verified (0 unverifiable, 0 contradicted) · 4 specialists (numerical, cross-reference, capability, framing); 0 cross-specialist corroborations · routed: 0 inline, 7 Pass 1, 0 Pass 2, 17 Pass 3 (verified 13, contradicted 0, unverifiable 4).
• Cited-claim spot-checks: not run (no cited claims)
• Frontmatter sweep: ran on body + meta_desc
• Temporal-trigger sweep: not run (no trigger words)
• Code execution: not run (no static/programs/ change)
• Code-examples checks: ran (3 specialists: structural, existence, body-code-coverage); 0 findings
• Editorial-balance pass: not run (not under content/blog/)

🚨 Outstanding	⚠️ Low-confidence	💡 Pre-existing	✅ Resolved
0	0	0	0

🔍 Verification trail

24 claims extracted · 20 verified · 0 unverifiable · 0 contradicted

• L20 in content/docs/esc/providers/secrets/aws-secrets.md "The best practice for aws-login is to define the login once in a base environment and import it wherever credentials are needed." → ✅ verified (evidence: The aws-login docs page states: "As a best practice, define aws-login once in its own environment and import it wherever credentials are needed, rather than repeating the login block in every environment."; source: content/docs/esc/providers/login/aws-login.md)
• L80 in content/docs/esc/providers/secrets/aws-secrets.md "The aws-secrets provider supports a versionId input to pin to a specific immutable secret version." → ✅ verified (evidence: The file at content/docs/esc/providers/secrets/aws-secrets.md explicitly documents versionId as an input under the "Pinning a secret version" section: "Use versionId to pin to a specific immutable version" and shows a YAML example wi…; source: repo:content/docs/esc/providers/secrets/aws-secrets.md)
• L80 in content/docs/esc/providers/secrets/aws-secrets.md "By default, aws-secrets returns the current version of each secret, identified by the AWSCURRENT staging label." → ✅ verified (evidence: The file at content/docs/esc/providers/secrets/aws-secrets.md contains the exact text in the "Pinning a secret version" section: "By default aws-secrets returns the current version of each secret (the AWSCURRENT staging label)."; source: repo:content/docs/esc/providers/secrets/aws-secrets.md)
• L80 in content/docs/esc/providers/secrets/aws-secrets.md "The AWSPREVIOUS staging label in AWS Secrets Manager refers to the value from before the most recent rotation." → ✅ verified (framing: strengthened — claim narrows 'previous current version of the secret' to 'value from before the most recent rotation'; the source's broader form (any AWSCURREN…; evidence: AWS official docs confirm: "AWSPREVIOUS, which indicates the previous current version of the secret. You can use this as the last known good version." It is automatically assigned to the version that AWSCURRENT was removed from, which in t…; source: https://docs.aws.amazon.com/secretsmanager/latest/apireference/API_DescribeSecret.html)
• L88 in content/docs/esc/providers/secrets/aws-secrets.md "roleArn: arn:aws:iam::123456789:role/esc-oidc" → ➖ not-a-claim (evidence: The text roleArn: arn:aws:iam::123456789:role/esc-oidc is a placeholder example value in a YAML code snippet (a documentation example ARN with a fake account ID 123456789). It is not a falsifiable factual assertion — it is a representa…; source: content/docs/esc/providers/secrets/aws-secrets.md L88 (regex match on example YAML snippet))
• L92 in content/docs/esc/providers/secrets/aws-secrets.md "region: us-west-1" → ✅ verified (evidence: us-west-1 is a valid, active AWS region code. AWS official docs confirm it in the default-enabled regions list: "us-west-1" corresponds to US West (N. California).; source: https://docs.aws.amazon.com/global-infrastructure/latest/regions/aws-regions.html)
• L98 in content/docs/esc/providers/secrets/aws-secrets.md "versionId: 01234567-89ab-cdef-0123-456789abcdef" → ➖ not-a-claim (evidence: The value 01234567-89ab-cdef-0123-456789abcdef is a conventional placeholder UUID (sequential hex digits in standard 8-4-4-4-12 format). AWS docs confirm versionId is "typically a UUID-type value with 32 hexadecimal digits." This is a do…; source: https://docs.aws.amazon.com/secretsmanager/latest/apireference/API_GetSecretValue.html)
• L99 in content/docs/esc/providers/secrets/aws-secrets.md "# Select by staging label (AWSCURRENT is the default):" → ✅ verified (evidence: AWS official docs confirm: "A secret always has a version labeled AWSCURRENT, and Secrets Manager returns that version by default when you retrieve the secret value." The AWS CLI reference also states: "If you don't specify either a Versio…; source: https://docs.aws.amazon.com/secretsmanager/latest/userguide/getting-started.html)
• L109 in content/docs/esc/providers/secrets/aws-secrets.md "The aws-login documentation for static credentials is located at /docs/esc/providers/login/aws-login/#static-credentials." → ✅ verified (evidence: The file content/docs/esc/providers/login/aws-login.md exists at the path matching /docs/esc/providers/login/aws-login/ and contains the section heading ### Static credentials, which generates the anchor #static-credentials, confir…; source: repo:content/docs/esc/providers/login/aws-login.md)
• L122 in content/docs/esc/providers/secrets/aws-secrets.md "region: us-west-1" → ✅ verified (evidence: us-west-1 is a valid, real AWS region code. AWS official docs confirm it in the list of enabled-by-default regions: "us-west-1" corresponds to US West (N. California).; source: https://docs.aws.amazon.com/global-infrastructure/latest/regions/aws-regions.html)
• L133 in content/docs/esc/providers/secrets/aws-secrets.md "The identity that aws-secrets logs in as must be allowed to call secretsmanager:GetSecretValue on the secret's ARN to read each secret referenced in get." (also L136) → ✅ verified (evidence: AWS official docs confirm: "Required permissions: secretsmanager:GetSecretValue" to call GetSecretValue on a secret, and identity-based policy examples show the action scoped to a specific secret ARN (e.g., `"Resource": "arn:aws:secretsman…; source: https://docs.aws.amazon.com/secretsmanager/latest/userguide/retrieving-secrets_cli.html; https://docs.aws.amazon.com/secretsmanager/latest/userguide/auth-and-access_iam-policies.html)
• L136 in content/docs/esc/providers/secrets/aws-secrets.md "If a secret is encrypted with a customer managed KMS key (CMK), the kms:Decrypt permission on the encryption key is also required." → ✅ verified (framing: strengthened — claim narrows the source's "customer-managed key" to "customer managed KMS key (CMK)"; source's broader form proves the claim as a subset.; evidence: The AWS Secrets Manager API reference for GetSecretValue states: "If the secret is encrypted using a customer-managed key instead of the AWS managed key aws/secretsmanager, then you also need kms:Decrypt permissions for that key."; source: https://docs.aws.amazon.com/secretsmanager/latest/apireference/API_GetSecretValue.html)
• L138 in content/docs/esc/providers/secrets/aws-secrets.md "AWS Secrets Manager appends a random six-character suffix to each secret's ARN." → ✅ verified (framing: strengthened — claim says suffix is on "each secret's ARN"; source specifies it is added "after the secret name at the end of the ARN", which is a more precise…; evidence: AWS official docs confirm: "Secrets Manager automatically adds a hyphen and six random characters after the secret name at the end of the ARN." (docs.aws.amazon.com/secretsmanager/latest/apireference/API_CreateSecret.html); source: https://docs.aws.amazon.com/secretsmanager/latest/apireference/API_CreateSecret.html)
• L142 in content/docs/esc/providers/secrets/aws-secrets.md "'Version': '2012-10-17'," → ✅ verified (evidence: AWS official IAM documentation confirms "Version": "2012-10-17" is the current and recommended policy language version: "This is the current version of the policy language, and you should always include a Version element and set it to 20…; source: https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_version.html)
• L147 in content/docs/esc/providers/secrets/aws-secrets.md "'Resource': 'arn:aws:secretsmanager:us-west-1:123456789012:secret:api-key-*'" → ✅ verified (evidence: The AWS Secrets Manager ARN format is arn:aws:secretsmanager:<Region>:<AccountId>:secret:SecretName. The claim uses us-west-1 (valid region), 123456789012 (standard AWS docs placeholder account ID), and secret:api-key-* (valid IAM…; source: https://docs.aws.amazon.com/secretsmanager/latest/userguide/getting-started.html)
• L152 in content/docs/esc/providers/secrets/aws-secrets.md "'Resource': 'arn:aws:kms:us-west-1:123456789012:key/'" → ➖ not-a-claim (framing: The ARN format used in the claim matches the official AWS KMS key ARN structure exactly; <key-id> is an explicit placeholder, making this a code-comment/exam…; evidence: The line is a documentation example showing the correct AWS KMS key ARN format (arn:aws:kms:<region>:<account-id>:key/<key-id>) with a placeholder <key-id> token. AWS docs confirm the canonical format: "arn:aws:kms:us-west-2:1111222233…; source: https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html)
• L164 in content/docs/esc/providers/secrets/aws-secrets.md "The page for configuring OpenID Connect (OIDC) between Pulumi Cloud and AWS is located at /docs/esc/guides/configuring-oidc/aws/." → ✅ verified (evidence: The file content/docs/esc/guides/configuring-oidc/aws.md exists and its front matter states title: AWS and h1: Configuring OpenID Connect for AWS, confirming the page at /docs/esc/guides/configuring-oidc/aws/ covers OIDC configurat…; source: repo:content/docs/esc/guides/configuring-oidc/aws.md)
• L167 in content/docs/esc/providers/secrets/aws-secrets.md "Rather than repeating the login block in every environment, define it once in a base environment and import it wherever you re…" → ✅ verified (evidence: The URL /docs/esc/concepts/imports/ resolves to content/docs/esc/concepts/imports.md, a live page covering ESC environment imports. The page explicitly describes how importing environments reduces duplication: "This reduces duplication…; source: repo:content/docs/esc/concepts/imports.md)
• L176 in content/docs/esc/providers/secrets/aws-secrets.md "roleArn: arn:aws:iam::123456789:role/esc-oidc" → ➖ not-a-claim (evidence: The text roleArn: arn:aws:iam::123456789:role/esc-oidc is a placeholder example value in a YAML code snippet (a documentation example ARN using the well-known dummy account ID 123456789). It is not a falsifiable factual assertion about…; source: content/docs/esc/providers/secrets/aws-secrets.md L176 (regex match on example ARN placeholder))
• L189 in content/docs/esc/providers/secrets/aws-secrets.md "region: us-west-1" → ✅ verified (evidence: us-west-1 is a valid, well-established AWS region code corresponding to US West (N. California), confirmed by multiple AWS sources: "USW1: us-west-1 (N. California)" and "North California has the code 'us-west-1' as it's the first design…; source: https://docs.aws.amazon.com/global-infrastructure/latest/regions/aws-regions.html)
• L200 in content/docs/esc/providers/secrets/aws-secrets.md "Login failures (assume-role errors, audience or subject mismatches) for aws-secrets are covered in the aws-login troubleshooting section at /docs/esc/prov…" → ✅ verified (evidence: The file content/docs/esc/providers/login/aws-login.mdcontains a## Troubleshooting` section that explicitly covers assume-role errors ("Not authorized to perform sts:AssumeRoleWithWebIdentity") and audience/subject mismatches ("Audien…; source: repo:content/docs/esc/providers/login/aws-login.md)
• L214 in content/docs/esc/providers/secrets/aws-secrets.md "A ResourceNotFoundException from AWS Secrets Manager can occur when the secretId doesn't match an existing secret, or when the secret lives in a different…" → ✅ verified (framing: strengthened — claim narrows the general "resource not found" error to two specific causes (wrong secretId, wrong region); both are confirmed by AWS docs as va…; evidence: The AWS official API reference confirms: "ResourceNotFoundException · Secrets Manager can't find the resource that you asked for." AWS ECS troubleshooting docs explicitly list both causes: the secret doesn't exist in Secrets Manager (wrong…; source: https://docs.aws.amazon.com/secretsmanager/latest/apireference/API_GetSecretValue.html; https://docs.aws.amazon.com/AmazonECS/latest/developerguide/resource-not-found-error.html)
• L216 in content/docs/esc/providers/secrets/aws-secrets.md "A pinned versionId or versionStage that doesn't exist in AWS Secrets Manager produces a ResourceNotFoundException." → ✅ verified (evidence: AWS SDK real-world errors confirm: "Secrets Manager can't find the specified secret value for VersionId: ..." and for a missing stage label both return ResourceNotFoundException. AWS official rotation docs also state `ResourceNotFoundExc…; source: client-secrets-manager failing when attempting to get 'AWSPENDING' secrets for rotation aws/aws-sdk-js-v3#7701; https://docs.aws.amazon.com/secretsmanager/latest/userguide/troubleshoot_rotation.html)
• L222 in content/docs/esc/providers/secrets/aws-secrets.md "An AccessDeniedException on kms:Decrypt occurs when the identity can call GetSecretValue but is not permitted to decrypt with the secret's KMS key, and r…" (also L224) → ✅ verified (framing: strengthened — the source's dual-policy requirement is most explicit in cross-account scenarios, but the claim generalizes it to all cases; for customer-manage…; evidence: AWS official docs confirm that GetSecretValue triggers kms:Decrypt, and an AccessDeniedException results when the identity lacks KMS decrypt permission. The AWS re:Post knowledge center shows resolution requires both an identity-based IAM…; source: https://repost.aws/knowledge-center/secrets-manager-cross-account-key)

🚨 Outstanding in this PR

No outstanding findings in this PR.

⚠️ Low-confidence

No low-confidence findings.

💡 Pre-existing issues in touched files (optional)

No pre-existing issues in touched files.

✅ Resolved since last review

No items resolved since the last review.

📜 Review history

• 2026-06-16T21:52:00Z — Expanded aws-secrets provider page; all 20 factual claims verified (0 contradicted/unverifiable), 8/8 siblings consistent, links and frontmatter clean — no blockers. (887d72d)

---

Need a re-review? Want to dispute a finding? Mention @claude and include #update-review.
(For ad-hoc questions or fixes, just @claude — no hashtag.)

[pulumi-bot]

Your site preview for commit 887d72d is ready! 🎉

http://www-testing-pulumi-docs-origin-pr-19733-887d72df.s3-website.us-west-2.amazonaws.com

[CamSoper]

@jkodroff You've got conflicts on this one