Expand ESC vs HashiCorp Vault comparison page

[djperlovsky]

Summary

Expands the existing ESC vs Vault comparison page to match the depth and SEO structure of the Terraform comparison page.

• Enhanced SEO metadata (title_tag, meta_desc)
• "At a Glance" section with quick bullet comparisons
• "What is" definition sections for both products
• Markdown feature comparison table (18 rows) with anchor links to deep-dive sections
• Expanded "Better Together" section with YAML example showing ESC pulling secrets from Vault
• 18 deep-dive sections covering architecture, developer experience, and security

Test plan

• make lint passes (0 errors)
• make serve renders page at /docs/esc/vs/vault/
• All 18 anchor links verified in rendered HTML
• No trailing whitespace, file ends with newline

[djperlovsky]

Waiting to review this with @alexleventer

[claude]

Docs review

Solid expansion overall. The deeper sections add real value over the prior page, and the markdown table is much easier to scan than the HTML version it replaced. A few issues to address before merge:

Heading case (must fix)

Per AGENTS.md, H2+ headings use sentence case.

content/docs/esc/vs/vault.md:29

## At a glance

content/docs/esc/vs/vault.md:66

## Feature by feature comparison

Misleading link (must fix)

content/docs/esc/vs/vault.md:171 — The paragraph describes ESC issuing OIDC-based dynamic credentials for AWS, Azure, and Google Cloud, but the link points to /docs/esc/guides/configuring-oidc/vault/, which is the guide for ESC authenticating to Vault via OIDC — a different feature entirely. This will confuse readers who click expecting AWS/Azure/GCP setup instructions.

Either drop the link or point it at the parent index, e.g.:

Pulumi ESC uses OIDC token exchange to generate short-lived credentials for AWS, Azure, and Google Cloud. When an environment is opened, ESC presents a signed JWT to the cloud provider's OIDC endpoint, which issues temporary credentials. No long-lived cloud credentials are stored anywhere. This approach aligns with zero-trust principles and significantly reduces the blast radius of a credential leak. For setup instructions, see the [OIDC configuration guides](/docs/esc/guides/configuring-oidc/).

"easy" / "simpler" — STYLE-GUIDE.md

Per STYLE-GUIDE.md line 32: "Avoid words like 'easy' or 'simple.' These judge difficulty and may alienate readers."

• Line 155: "…makes it easy to understand how environments relate to each other." → e.g., "…makes the relationships between environments explicit."
• Line 189: "This makes it easy to experiment without modifying shared environments." → e.g., "This lets developers experiment without modifying shared environments."
• Line 217: "…though ESC's model is simpler to configure for teams already using Pulumi Cloud." → e.g., "…though ESC's model requires less configuration for teams already using Pulumi Cloud."

Table / detail-section consistency

content/docs/esc/vs/vault.md:79 lists ESC built-in functions as "toJSON, fromJSON, fromBase64, etc." but the deep-dive at line 177 also includes toBase64 and toString. Worth aligning so a reader skimming the table sees the same set:

| [Built-in functions](#functions) | toJSON, fromJSON, toBase64, fromBase64, toString | No |

Minor / nits

• & vs and in headings and table cells (lines 73, 76, 77, 80, 81, 83). Google's style guide (the fallback per AGENTS.md) prefers "and" in prose. Worth normalizing for consistency with the rest of /docs/.
• Line 64: "see our [What is HashiCorp Vault?]…overview" — the new copy adds "our," which reads a bit promotional in a comparison page. Consider "see the [What is HashiCorp Vault?] overview."
• Section ordering: The Get started with Pulumi ESC CTA (line 125) sits between the table and the 18 deep-dive sections. Readers who hit the CTA may bounce before reaching the detail. Consider moving the CTA below the deep-dive sections, or replacing the post-CTA --- with a clearer "Read on for more detail" handoff. Worth a thought, not a blocker.
• Line 171: separately from the link issue above, the claim that Vault's OIDC-based cloud credential generation is "primarily supporting AWS" is fair, but the rest of that sentence ("…with IAM user or STS-based flows that still depend on stored access keys") conflates two things — Vault's AWS secrets engine can use IAM Instance Profile / IRSA / STS without long-lived stored keys. Consider softening to "…often relies on stored access keys."

---

If you'd like me to take another look after edits, mention @claude.

[pulumi-bot]

Your site preview for commit be91026 is ready! 🎉

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

[CamSoper]

content/docs/esc/vs/vault.md:207 -- only Go and Ruby are HashiCorp-maintained Vault SDKs (source); C#, Python, and Java are community libraries (VaultSharp, hvac, Spring Vault).

Both ESC and Vault provide SDKs for programmatic access. ESC offers TypeScript, Python, and Go SDKs, as well as a REST API. Vault provides Go and Ruby SDKs maintained by HashiCorp, alongside community libraries for C#, Python, and Java. Both platforms enable applications to retrieve secrets at runtime without relying on the CLI.

content/docs/esc/vs/vault.md:58 -- "Users have reduced configuration and secrets duplication by over 90%..." has no source. Either attribute it (Compostable AI is cited later in the page and may fit) or drop the sentence.

content/docs/esc/vs/vault.md:27, 43 vs :58, :147 -- "9+ providers" doesn't match the "9 dynamic secret providers" body text. The actual count under content/docs/esc/integrations/dynamic-secrets/ is 9; pick one phrasing and use it everywhere.

content/docs/esc/vs/vault.md:235-244 -- drop the "What teams are saying" block. Pull-quote testimonials are marketing copy and don't belong on a docs page. The case studies and GA blog are already linked inline at lines 143 and 155 where they back specific technical arguments; that's the right way to cite them here.

content/docs/esc/vs/vault.md:237-238 -- separately from the block above: even if the testimonial section stays in some form, the Zachary Cook quote needs to come out. He left Modivcare and now works at Pulumi, so attributing him with a Modivcare title on a /vs/ page reads as an arms-length customer endorsement when it isn't.

content/docs/esc/vs/vault.md:246-248 -- duplicate CTA. The {{< get-started-esc >}} shortcode at line 127 already covers this.

content/docs/esc/vs/vault.md:45 -- sentence case:

**Key differences**

[djperlovsky]

@CamSoper - thanks for taking a look but meant for this to be a draft as I didn't have time to dedicate towards making it prod ready (and just wanted to show something for a separate convo)! Will take you comments in and let you know when its ready

[CamSoper]

@djperlovsky Sorry about that! I had an itchy trigger finger on my pr-review skill 😆