Feature flagging infra

[lichtie]

Proposed changes

I've added a blog post about using Pulumi ESC to establish feature flagging practices for your infrastructure

Unreleased product version (optional)

Related issues (optional)

[claude]

Documentation Review

I've reviewed PR #16755 and found several issues that need to be addressed before publication.

Critical Issues

1. Missing trailing newline (index.md:200)

The blog post file does not end with a newline. Per AGENTS.md and STYLE-GUIDE.md, all Markdown files must end with a newline.

Fix: Add a newline at the end of the file.

2. Missing <!--more--> break (index.md:~18)

The blog post should include a <!--more--> break after the first paragraph to control what appears on the blog home page. Currently, the break appears after line 18, but should ideally appear earlier to create a more concise preview.

Current:

One of Pulumi's foundational benefits is that it allows you to manage your [infrastructure as software](https://www.pulumi.com/what-is/what-is-infrastructure-as-software/) with rich programming languages, robust testing, and CI/CD patterns that you'd use with your application code. This post will cover applying another classic software development technique to your infrastructure: feature flagging. You can use feature flags to control change rollout, reduce the risk of new releases, and speed up the development of your infrastructure, the same way you do with your applications.

The examples in this post range from simply creating a flag and using it in a Lambda function to fully integrating with LaunchDarkly to build a comprehensive flagging system for your infrastructure.

<!--more-->

Consider moving the break to after the first paragraph for a more concise preview on the blog home page.

Content & Style Issues

3. Code example context (index.md:30-36)

The first code example appears without sufficient context. Readers need to understand where this code lives (e.g., "In your Pulumi program:") before seeing the TypeScript code.

Suggestion: Add a brief intro sentence before the code block explaining where this code should be placed.

4. Passive voice usage (index.md:38)

"The Lambda function uses the LaunchDarkly SDK key passed through environment variables" - This sentence uses passive voice. Per the style guide for documentation, avoid passive voice when possible.

Suggested revision:

The Lambda function evaluates the flag at runtime using the LaunchDarkly SDK key from environment variables, allowing you to toggle behavior without redeploying code.

5. Repetitive language (index.md:46-48)

The warning note states "you'll want to deploy" which is unnecessarily indirect.

Suggested revision:

Before deploying this code, deploy either example 03 (for [ESC Only](https://github.com/Elisabeth-Team/feature-flagging/tree/main/03-esc-with-webhook-for-updating)) or example 04 (for [ESC and LaunchDarkly](https://github.com/Elisabeth-Team/feature-flagging/tree/main/04-flag-driven-infrastructure)) to ensure the environment is created and available.

6. Inconsistent capitalization (index.md:65)

"deployment settings" should be a proper link with the product name capitalized as "Deployment Settings" if it refers to a Pulumi Cloud feature.

Verify if this is the correct product terminology and capitalize accordingly.

7. Missing context for config structure (index.md:52-58)

The code shows accessing flags from config but doesn't explain the expected config structure. Readers might not know how to structure their stack configuration.

Suggestion: Add a brief explanation or example of the expected config format in Pulumi.yaml or via ESC.

8. Webhook security note (index.md:92-94, 138-140)

The warning about "some risk" is vague. Be specific about what risks exist (e.g., accidental infrastructure changes, unauthorized access if webhook not secured).

Suggested revision:

Automatically triggering deployments carries risk. Changes to flag values will immediately trigger infrastructure updates, which could cause unintended modifications or downtime if flags are changed accidentally. Consider leaving out the webhook and deploying manually if your infrastructure requires manual approval gates.

9. Table formatting (index.md:181-192)

The comparison table is well-structured, but the "Example Use Case" row could benefit from more concrete examples that directly relate to the technical differences.

Documentation Coverage

✅ Good news: The blog post links to comprehensive ESC documentation for most features mentioned:

• ESC Connect / fn::open::external is well-documented in content/docs/esc/integrations/dynamic-secrets/external.md
• Webhooks are covered in the docs
• Deployment settings are documented

⚠️ Gap identified: While the post demonstrates a sophisticated pattern of feature-flagging infrastructure, there's no dedicated guide in content/docs/esc/guides/ that covers this specific use case of feature flagging with ESC. Consider creating:

• A guide at content/docs/esc/guides/feature-flagging.md that provides a more detailed, step-by-step tutorial
• This would help SEO and provide a canonical reference for this pattern

Positive Observations

• Well-structured content: The progressive complexity from simple flags to full LaunchDarkly integration is excellent
• Strong technical depth: The code examples are realistic and useful
• Good use of diagrams: The Mermaid diagrams effectively illustrate the automation flows
• Appropriate use of notes callouts: Info and warning callouts are used effectively
• Clear comparison table: The ESC vs LaunchDarkly comparison helps readers choose the right approach

Pre-Publication Checklist

Before merging, ensure you've completed:

• Fix missing trailing newline
• Add <!--more--> break after first paragraph (verify preview on blog home page)
• Test meta_image appears correctly using Twitter card validator
• Verify all GitHub repo links are accessible
• Reach out in #blogs to coordinate with Marketing
• Consider creating supporting documentation in content/docs/esc/guides/

---

Please mention me (@claude) if you'd like help implementing any of these suggestions or if you need clarification on any feedback.

[pulumi-bot]

Your site preview for commit bf593be is ready! 🎉

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

[pulumi-bot]

Your site preview for commit 5613e85 is ready! 🎉

http://www-testing-pulumi-docs-origin-pr-16755-5613e85f.s3-website.us-west-2.amazonaws.com.

[pulumi-bot]

Your site preview for commit c31b559 is ready! 🎉

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

[pulumi-bot]

Your site preview for commit 58820cb is ready! 🎉

http://www-testing-pulumi-docs-origin-pr-16755-58820cbc.s3-website.us-west-2.amazonaws.com.

[pulumi-bot]

Your site preview for commit f826316 is ready! 🎉

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