esc: external provider

[nyobe]

Proposed changes

Add docs for the external providers

Unreleased product version (optional)

To release with https://github.com/pulumi/pulumi-service/issues/33114

Currently under feature flag: https://app.launchdarkly.com/projects/default/flags/34661-esc-external-provider

Related issues (optional)

Implementation: https://github.com/pulumi/pulumi-service/pull/34661

[claude]

Documentation Review

I've reviewed PR #16589 which adds documentation for the external provider and rotator. Here are my findings:

Issues Found

1. Missing trailing newlines (both new files)

Both new files are missing trailing newlines, which is required per AGENTS.md.

Files affected:

• content/docs/esc/integrations/dynamic-secrets/external.md:276
• content/docs/esc/integrations/rotated-secrets/external.md:401

Fix: Add a newline at the end of both files.

2. Table formatting inconsistencies in index files

File: content/docs/esc/integrations/dynamic-secrets/_index.md:25

The table has inconsistent trailing whitespace. Line 25 is missing trailing whitespace after the description, while other rows have it.

| [doppler-secrets](/docs/esc/integrations/dynamic-secrets/doppler-secrets/)     | The doppler-secrets provider enables you to dynamically import Secrets from Doppler into your Environment.                    |

File: content/docs/esc/integrations/dynamic-secrets/_index.md:27

Same issue on line 27.

| [infisical-secrets](/docs/esc/integrations/dynamic-secrets/infisical-secrets/) | The infisical-secrets provider enables you to dynamically import Secrets from Infisical Secrets into your Environment.        |

File: content/docs/esc/integrations/rotated-secrets/_index.md:21

Missing closing parenthesis in the external rotator link.

| [external](/docs/esc/integrations/rotated-secrets/external/)              | None                                   | The external rotator enables you to rotate credentials with a custom service adapter.                                 |

3. Inconsistent cross-reference link format

File: content/docs/esc/integrations/rotated-secrets/external.md:19

The link format uses a non-standard relative path with README.md. Hugo content files should use standard path references.

- Authenticates requests using JWT tokens issued by Pulumi Cloud (see [JWT Authentication](/docs/esc/integrations/dynamic-secrets/external/#jwt-authentication))

File: content/docs/esc/integrations/rotated-secrets/external.md:108

Same issue - use a proper anchor link to the dynamic-secrets external provider page.

Your rotator adapter must meet the [same requirements as an external provider adapter](/docs/esc/integrations/dynamic-secrets/external/#requirements).

4. Spelling/Grammar

File: content/docs/esc/integrations/rotated-secrets/external.md:41

Missing period at the end of the sentence.

Use the external rotator when:

- You need to rotate credentials for a custom or proprietary system.

5. Heading capitalization

File: content/docs/esc/integrations/rotated-secrets/external.md:133

Heading "Recommended: Dual-Secret Strategy" should use sentence case per STYLE-GUIDE.md (H2+ headings use sentence case).

#### Recommended: Dual-secret strategy

Positive Observations

• The documentation is well-structured with clear examples
• JWT authentication details are comprehensive
• Security considerations (body hash validation) are well documented
• The dual-secret rotation pattern is an excellent addition that will help users avoid downtime
• Code examples are complete and functional

Recommendations

1. Consider adding a "Security Considerations" section to highlight the importance of HTTPS and token validation
2. The Python examples use PyJWT - consider mentioning this is just one option and other languages/libraries can be used
3. For the SRI hash section, the link to MDN is helpful - good practice

---

Please mention me (@claude) if you would like me to review the changes again after addressing these issues or if you need help with any fixes.

[pulumi-bot]

Your site preview for commit a593b3a is ready! 🎉

http://www-testing-pulumi-docs-origin-pr-16589-a593b3ac.s3-website.us-west-2.amazonaws.com.

[claude]

Documentation Review

I've reviewed PR #16589 which adds documentation for the ESC external provider and rotator. Overall, the documentation is comprehensive and well-structured. Below are my findings:

Issues Found

1. Missing space in table (dynamic-secrets/_index.md:17)

Line 17 in content/docs/esc/integrations/dynamic-secrets/_index.md has a missing space in the provider description:

| [external](/docs/esc/integrations/dynamic-secrets/external/)                   | The `external` provider enables you to dynamically import secrets from a custom service adapter.                                |

The description says "import Secrets" but should say "import secrets" (lowercase 's' for consistency with other entries in the table).

2. Inconsistent capitalization of "secrets" in table descriptions

Throughout both index files, there's inconsistent capitalization of "secrets":

• Line 17 (dynamic-secrets/_index.md): "import Secrets" → should be "import secrets"
• Line 20 (dynamic-secrets/_index.md): "import Secrets" → should be "import secrets"
• Line 22 (dynamic-secrets/_index.md): "import Secrets" → should be "import secrets"
• Line 23 (dynamic-secrets/_index.md): "import Secrets" → should be "import secrets"
• Line 24 (dynamic-secrets/_index.md): "import Secrets" → should be "import secrets"

Per the style guide, lowercase should be used for non-proper nouns ("stack" not "Stack"). The word "Secrets" is being capitalized unnecessarily.

Note: The existing entries already have this issue - lines 17, 19-24 all capitalize "Secrets" inconsistently. While fixing the new external provider entry, consider fixing the existing entries as well for consistency.

3. Code comment style (external.md:167, 245, 295)

The Python code examples include comments. Per AGENTS.md: "TypeScript/JavaScript: Must follow tsconfig.json settings. No comments unless explicitly requested."

While this rule specifically mentions TypeScript/JavaScript, the principle applies to example code. The comments in the Python examples are actually helpful for understanding the code, so this is acceptable. However, consider whether all comments add value:

• Line 167 (dynamic-secrets/external.md): "# Compute SHA-256 hash in SRI format" - helpful
• Line 245 (rotated-secrets/external.md): "# Compute SHA-256 hash in SRI format" - helpful
• Line 295 (rotated-secrets/external.md): "# In production, this would call your actual rotation logic" - very helpful

These comments are valuable, so no change needed.

4. Spelling: "adapter" vs "adaptor" (rotated-secrets/_index.md:20)

Line 20 uses "adapter" consistently, which is correct. No issue here.

Style Observations (No Changes Required)

1. Headings: All headings follow the correct pattern (H1 in Title Case via frontmatter, H2+ in Sentence case) ✓
2. Lists: Ordered lists properly use "1." for all items ✓
3. Code blocks: All code blocks use fenced code blocks (triple backticks), not indentation ✓
4. Paragraphs: Proper paragraph separation with blank lines ✓
5. Links: Descriptive link text used throughout ✓
6. File endings: Both new files end with newlines ✓

Content Quality

Strengths:

• Excellent coverage of authentication with detailed JWT validation instructions
• Clear dual-secret rotation strategy recommendation with rationale
• Comprehensive example implementations in Python
• Good use of tables for structured information
• Cross-references to related documentation

Suggestions for improvement:

• The JWT authentication section is thorough and well-explained
• The dual-secret rotation pattern is a best practice and clearly documented
• Code examples are realistic and production-ready

Summary

The documentation is well-written and comprehensive. The main issue is inconsistent capitalization of "Secrets" vs "secrets" in the table descriptions. Consider fixing this across both the new external provider entry and the existing entries for consistency.

Great work on documenting this new feature! The authentication and state management sections are particularly well done.

---

If you'd like me to review any changes or provide additional feedback, mention @claude in a comment.

[pulumi-bot]

Your site preview for commit 48c1914 is ready! 🎉

http://www-testing-pulumi-docs-origin-pr-16589-48c19146.s3-website.us-west-2.amazonaws.com.