esc: external provider

[nyobe]

Proposed changes

Add docs & announcement blog post for custom 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)

Deployable adapter example: pulumi/examples#2213

[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.

[pulumi-bot]

Your site preview for commit 4e384db is ready! 🎉

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

[pulumi-bot]

Your site preview for commit 3766db0 is ready! 🎉

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

[pulumi-bot]

Your site preview for commit 8258ff5 is ready! 🎉

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

[pulumi-bot]

Your site preview for commit b319b77 is ready! 🎉

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

[pulumi-bot]

Your site preview for commit 9c65ad4 is ready! 🎉

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

[claude]

Documentation Review

I've reviewed PR #16589 which adds documentation for the ESC external provider feature. The content is well-written and comprehensive. Here are my findings:

✅ Strengths

• Clear, well-structured documentation for both the dynamic secrets external provider and rotated secrets external rotator
• Excellent technical depth with security requirements and JWT validation details
• Complete Python example implementations that demonstrate best practices
• Good cross-referencing between related docs (blog post links to doc pages)
• Proper frontmatter and menu configuration for all new pages

📝 Issues Found

Blog Post

Line 3: Future date

date: 2025-12-01

The date is set to December 2025, which appears to be a typo. Based on the PR context ("To release with...") and feature flag mention, this should likely be:

• January 2025 (2025-01-XX) if releasing soon
• Or keep the current format if this is intentionally scheduled for December 2025

Line 36: Extra space before period

When you open this environment, ESC makes an authenticated POST request to your adapter. 

There's a trailing space after "adapter." before the period (visible in the diff). This should be removed.

Line 61: Incomplete sentence in alt text context
The phrase "maintains both current and previous credentials during transitions" could be clearer. Consider: "maintains both current and previous credentials during rotation transitions"

Documentation Files

content/docs/esc/integrations/dynamic-secrets/external.md

Line 28-29: Inconsistent list punctuation
The "When to Use" list items don't have ending periods. For consistency with other documentation, consider adding them:

- You need to integrate a custom or proprietary secret management system.
- You have specific business logic for secret fetching.
- Your secret source is behind a firewall or requires custom networking.

Line 124: Link format

[JWKS](https://api.pulumi.com/oidc/.well-known/jwks)

The URL appears to have "/oidc/" in the path but line 106 and the Python example (line 157) use https://api.pulumi.com/.well-known/jwks.json (without "/oidc/" and with ".json"). These should be consistent. Verify the correct URL.

content/docs/esc/integrations/rotated-secrets/external.md

Line 27-29: Inconsistent list punctuation
Same issue as the dynamic secrets doc - the "When to Use" list should have consistent punctuation:

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

Line 210: Schedule recommendation clarity

Configure your rotation schedule to be less frequent than your application's configuration refresh interval.

This is important guidance but could be more prominent. Consider making this a warning callout using the notes shortcode:

{{% notes type="warning" %}}
Configure your rotation schedule to be less frequent than your application's configuration refresh interval. For example, if your app fetches configuration every 5 minutes, rotate no more than once per hour.
{{% /notes %}}

✓ Verified

• All internal links resolve correctly
• Menu weights updated consistently (other providers set to weight: 2, external set to weight: 99)
• Aliases added correctly for both new external provider docs
• Proper sentence case in H2+ headings
• Code examples use proper fenced code blocks with language tags
• Tables are well-formatted and complete
• No spelling or grammar errors detected
• Content follows the STYLE-GUIDE.md conventions

📋 Summary

The documentation is production-ready after addressing the date and minor style/consistency issues above. The technical content is accurate and comprehensive.

---

If you'd like me to review these changes again after updates, mention @claude in a comment.

[pulumi-bot]

Your site preview for commit a9874e1 is ready! 🎉

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

[pulumi-bot]

Your site preview for commit b9dec7a is ready! 🎉

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

[pulumi-bot]

Your site preview for commit a7791f6 is ready! 🎉

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