Skip to content

Enhance documentation structure for Pulumi ESC getting started guides #16533

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Open
wants to merge 12 commits into
base: master
Choose a base branch
from
Open

Enhance documentation structure for Pulumi ESC getting started guides #16533

wants to merge 12 commits into from
+1,378 −1,090

Conversation

@CamSoper
Copy link
Contributor

@CamSoper CamSoper commented Nov 10, 2025 •
edited
Loading

This PR restructures the Pulumi ESC documentation to improve discoverability and user experience.

Key Changes

Getting Started:

  • Replaced 8-page tutorial with a single 5-minute quick start
  • Focused on essential first steps: create environment, add secret via web UI, retrieve via CLI
  • Added strong call-to-action directing users to IaC integration guide

New Guides Section:

  • Created dedicated /docs/esc/guides/ with 6 self-contained guides:
    • Integrate with Pulumi IaC
    • Managing secrets
    • Running commands with ESC
    • Setting up OIDC
    • Importing environments
    • External secrets integration

Concepts Enhancement:

  • Expanded concepts/_index.md with structured explanations of core concepts
  • Improved organization around environments, sources, targets, and management

Navigation & SEO:

  • Updated menu weights for better navigation flow (Guides before Environments)
  • All aliases properly configured to preserve search rankings and external links
  • Git history preserved via git mv for moved content

Link Fixes:

  • Fixed broken anchor links in external-secrets.md
  • Updated internal documentation links to point to new guide locations

Fixes #15784

@claude

This comment was marked as resolved.

Sign in to view
@pulumi-bot
Copy link
Collaborator

pulumi-bot commented Nov 10, 2025

Your site preview for commit 13344f3 is ready! 🎉

http://www-testing-pulumi-docs-origin-pr-16533-13344f39.s3-website.us-west-2.amazonaws.com.

@pulumi-bot
Copy link
Collaborator

pulumi-bot commented Nov 11, 2025

Your site preview for commit 3950013 is ready! 🎉

http://www-testing-pulumi-docs-origin-pr-16533-3950013c.s3-website.us-west-2.amazonaws.com.

@pulumi-bot
Copy link
Collaborator

pulumi-bot commented Nov 11, 2025

Your site preview for commit 6f7f4e3 is ready! 🎉

http://www-testing-pulumi-docs-origin-pr-16533-6f7f4e3a.s3-website.us-west-2.amazonaws.com.

@CamSoper
Add guides for Pulumi ESC, including managing secrets, integrating wi…
c4e9c68 
…th Pulumi IaC, and setting up OIDC

- Introduced new "Get Started"
- Created a new index page for guides on Pulumi ESC.
- Added detailed guides for integrating external secrets from AWS, Azure, and GCP.
- Introduced a guide on importing environments to share configuration across teams.
- Developed a guide on managing secrets, including storing and retrieving them.
- Added instructions for running commands with `esc run` to inject secrets into scripts.
- Created a guide for setting up OIDC to generate dynamic cloud credentials.
- Updated references in existing documentation to point to new guides.
@pulumi-bot
Copy link
Collaborator

pulumi-bot commented Nov 11, 2025

Your site preview for commit c4e9c68 is ready! 🎉

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

@pulumi-bot
Copy link
Collaborator

pulumi-bot commented Nov 12, 2025

Your site preview for commit 7b45727 is ready! 🎉

http://www-testing-pulumi-docs-origin-pr-16533-7b457276.s3-website.us-west-2.amazonaws.com.

@CamSoper
Add script to add borders to PNG images in markdown files
8e964bf 
- Created a new script `add_borders.py` that adds 1px #CCCCCC borders to PNG images referenced in markdown files.
- Implemented functionality to check for existing borders and avoid duplication.
- Added metadata to processed images to track border addition.
- Included a `Pipfile` for dependency management, requiring `pillow` and `click`.
- Added command-line interface for user interaction, supporting dry-run mode.
@pulumi-bot
Copy link
Collaborator

pulumi-bot commented Nov 14, 2025

Your site preview for commit 8e964bf is ready! 🎉

http://www-testing-pulumi-docs-origin-pr-16533-8e964bf0.s3-website.us-west-2.amazonaws.com.

@CamSoper
Enhance "Create your first environment" section: improve clarity and …
e4fbcbe 
…formatting of steps, update YAML example, and refine secret handling explanation
@CamSoper
Refactor configuration retrieval in examples: update to use 'region' …
d99adb9 
…and 'apiKey' instead of 'myEnvironment' and 'myPassword' across multiple languages
@pulumi-bot
Copy link
Collaborator

pulumi-bot commented Nov 14, 2025

Your site preview for commit d99adb9 is ready! 🎉

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

@CamSoper
Refine documentation for ESC integration: streamline environment edit…
f61e64a 
…ing instructions and enhance clarity on using CLI and Pulumi Cloud console
@pulumi-bot
Copy link
Collaborator

pulumi-bot commented Nov 15, 2025

Your site preview for commit f61e64a is ready! 🎉

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

@CamSoper
Enhance documentation for environment imports: add introductory notes…
c834300 
…, clarify import modes, and update related guides for better user guidance
@CamSoper CamSoper marked this pull request as ready for review November 17, 2025 21:38
@claude

This comment was marked as resolved.

Sign in to view
@pulumi-bot
Copy link
Collaborator

pulumi-bot commented Nov 17, 2025

Your site preview for commit c834300 is ready! 🎉

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

@pulumi-bot
Copy link
Collaborator

pulumi-bot commented Nov 17, 2025

Your site preview for commit e24307f is ready! 🎉

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

@pgavlin
Copy link
Member

pgavlin commented Nov 17, 2025

screenshots are a bit low-res/blurry and might be out-of-date with respect to styling (the editor has a light background for me):

Screenshot 2025-11-17 at 3 18 38 PM

@CamSoper
Copy link
Contributor Author

CamSoper commented Nov 17, 2025 •
edited
Loading

screenshots are a bit low-res/blurry and might be out-of-date with respect to styling (the editor has a light background for me):

Screenshot 2025-11-17 at 3 18 38 PM

The blurriness is because the CSS is scaling the image to the content width. That's an issue across docs, and I'm going to make a docs-wide fix as soon as I figure out what the best way to address it is without breaking something else. Here's what the images look like at 100% scale.

I too have a different UI--When I'm logged on to the pulumi org. There's a dark mode/light mode toggle in the settings for us, but I didn't see it in any of my other profiles, so it seemed logical to assume that we have a feature flag turned on that's not available for everyone.

@pgavlin
Copy link
Member

pgavlin commented Nov 18, 2025

That still reads as fuzzy to me:

Screenshot 2025-11-17 at 4 25 50 PM

I wonder if it's a difference in DPI or something?

I too have a different UI--When I'm logged on to the pulumi org
...
it seemed logical to assume that we have a feature flag turned on that's not available for everyone

That makes sense. The feature flag must have logic along the lines of "this user is a member of some org for which the feature is enabled" s.t. it applies across the user's sessions regardless of what org has been chosen. I wasn't 100% sure since my personal environments were also getting the light background. Thanks for double-checking!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Improve Pulumi ESC Getting Started

4 participants

@CamSoper @pulumi-bot @pgavlin