Create IDP best practices section and four factors conceptual doc #15479

thoward · 2025-07-08T18:58:02Z

No description provided.

pulumi-bot · 2025-07-08T19:03:52Z

Your site preview for commit cd543c9 is ready! 🎉

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

meagancojocar · 2025-07-14T17:14:38Z

content/docs/idp/best-practices/_index.md

+
+## Patterns
+
+Coming soon: Common architectural patterns and design approaches for organizing your infrastructure code and workflows.


Should we wait to review until there are no TODOs? Or are we supposed to review the IA?

Oh, I can leave those sections out of this page until (at least some of) the patterns/blueprints are complete. The goal of this PR is to get review of the Four Factors page and publish that, with follow up being the patterns and blueprints sections in the next PRs.

pulumi-bot · 2025-07-16T02:40:46Z

Your site preview for commit 86ecdf9 is ready! 🎉

http://www-testing-pulumi-docs-origin-pr-15479-86ecdf9d.s3-website.us-west-2.amazonaws.com.

content/docs/idp/best-practices/four-factors.md

kramhuber · 2025-07-16T22:13:26Z

content/docs/idp/well-architected/_index.md

+
+This section provides proven patterns and ready-to-use blueprints that help you implement well-architected solutions with Pulumi IDP. These resources follow industry best practices and have been validated in production environments.
+
+## Patterns


I can't speak to these -- will defer to @jkodroff

I'm working through this PR sequentially so IDK if this will be relevant, but if the number of suggested changes become too great, we can just reduce this to something like 3 patterns to get things out the door and moving.

Co-authored-by: Mark <[email protected]>

content/docs/idp/best-practices/four-factors.md

pulumi-bot · 2025-07-17T17:22:52Z

Your site preview for commit 4865b57 is ready! 🎉

http://www-testing-pulumi-docs-origin-pr-15479-4865b574.s3-website.us-west-2.amazonaws.com.

pulumi-bot · 2025-07-17T17:24:13Z

Your site preview for commit dba7557 is ready! 🎉

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

content/docs/idp/best-practices/four-factors.md

pulumi-bot · 2025-07-17T17:39:27Z

Your site preview for commit 19b6767 is ready! 🎉

http://www-testing-pulumi-docs-origin-pr-15479-19b67670.s3-website.us-west-2.amazonaws.com.

pulumi-bot · 2025-07-17T17:40:36Z

Your site preview for commit 0bd4591 is ready! 🎉

http://www-testing-pulumi-docs-origin-pr-15479-0bd4591c.s3-website.us-west-2.amazonaws.com.

jkodroff

On the whole, there's a lot of really good content in here, but I think we need to pare down the scope of the PR in order to get this launched.

The granularity and depth of the patterns are really good IMO. I think this is gonna genuinely help people use the product without getting too detailed at a level where a CSA or similar is going to be necessary to handle all the details.

My top-level suggestions:

Move the ESC stuff out of scope into another PR (and we can debate whether to put here or in the ESC section of the docs out of band).
Compress the docs nav.

jkodroff · 2025-07-10T15:29:47Z

content/docs/idp/best-practices/four-factors.md

+Consider a developer who needs to deploy a new web site hosted in a S3 bucket. Here's how the four factors collaborate:
+
+- **Template**: The developer starts with a `web-site` template that scaffolds a new project with the necessary structure and dependencies.
+


These blank lines should be removed so that this is a single ul.

jkodroff · 2025-07-21T17:38:41Z

content/docs/idp/well-architected/blueprints/_index.md

I don't think this page should be present if it's just "coming soon". Just move the patterns up a level. We can always alias them later if stuff moves.

jkodroff · 2025-07-21T17:46:17Z

content/docs/idp/best-practices/four-factors.md

I don't think we need separate menus for Best Practices and Well-Architected. To me, they are the same concept, so we can just pick one.

On the whole tho, I find this to be a very useful, first-principles kind of doc. I would put this first under Best Practices/Well-Architected (whichever we choose - the former seems to be less AWS-specific, which is likely better for our position as a cloud-agnostic tool).

jkodroff · 2025-07-21T17:49:18Z

content/docs/idp/well-architected/_index.md

+
+This section provides proven patterns and ready-to-use blueprints that help you implement well-architected solutions with Pulumi IDP. These resources follow industry best practices and have been validated in production environments.
+
+## Patterns


I'm working through this PR sequentially so IDK if this will be relevant, but if the number of suggested changes become too great, we can just reduce this to something like 3 patterns to get things out the door and moving.

jkodroff · 2025-07-21T17:51:32Z

content/docs/idp/well-architected/patterns/components-using-other-components.md

+
+## When to use this pattern
+
+- **Complex architectures**: When you need to combine multiple infrastructure patterns


Suggested change

- **Complex architectures**: When you need to combine multiple infrastructure patterns

- **Integrated architectures**: When you need to combine multiple types of infrastructure

Or something like that. "Complex" has a negative connotation.

jkodroff · 2025-07-21T18:57:10Z

...s/idp/well-architected/patterns/cost-control-using-components-policies-constrained-inputs.md

+
+This pattern combines Pulumi components with constrained input types and policies to control infrastructure costs. By limiting available options and enforcing cost-related policies, organizations can prevent expensive configurations while maintaining developer productivity.
+
+## When to use this pattern


Suggest reducing this to a sentence since all of these points fundamentally about saving scrilla on your bill-a.

jkodroff · 2025-07-21T19:10:17Z

content/docs/idp/well-architected/patterns/one-esc-environment-per-service.md

Ignoring this one for now b/c I think the scope of the PR overall is too large, and we should discuss whether these belong under ESC.

jkodroff · 2025-07-21T19:10:31Z

content/docs/idp/well-architected/patterns/one-esc-environment-per-team.md

jkodroff · 2025-07-21T19:12:02Z

content/docs/idp/well-architected/patterns/policies-as-tests.md

This one feels like a stretch. To me this is just "using policies normally, as intended". I think a more useful use case would be something like "using policies to ensure components are used instead of raw resources" or "ensuring only supported versions of components are being used" (to force upgrade paths).

jkodroff · 2025-07-21T19:13:40Z

content/docs/idp/well-architected/patterns/security-updates-using-components.md

+    description: "Ensure all components are using minimum required versions for security",
+    enforcementLevel: "mandatory",
+    validateResource: validateResourceOfType(aws.rds.Instance, (instance, args, reportViolation) => {
+      const componentVersion = instance.tags?.ComponentVersion;


This indicates to me that we need some metadata for policies that specifically apply to components, or a cleaner way to implement this use case.

create IDP best practices section and four factors conceptual doc

cd543c9

thoward requested review from jkodroff, kramhuber and meagancojocar July 8, 2025 18:58

thoward temporarily deployed to testing July 8, 2025 18:58 — with GitHub Actions Inactive

thoward requested a review from automagic July 8, 2025 18:59

meagancojocar reviewed Jul 14, 2025

View reviewed changes

add initial patterns and well-architected section

86ecdf9

thoward temporarily deployed to testing July 16, 2025 02:35 — with GitHub Actions Inactive

kramhuber reviewed Jul 16, 2025

View reviewed changes

Update content/docs/idp/best-practices/four-factors.md

4865b57

Co-authored-by: Mark <[email protected]>

thoward temporarily deployed to testing July 17, 2025 17:16 — with GitHub Actions Inactive

thoward commented Jul 17, 2025

View reviewed changes

content/docs/idp/best-practices/four-factors.md Outdated Show resolved Hide resolved

Update content/docs/idp/best-practices/four-factors.md

dba7557

thoward temporarily deployed to testing July 17, 2025 17:17 — with GitHub Actions Inactive

thoward commented Jul 17, 2025

View reviewed changes

content/docs/idp/best-practices/four-factors.md Outdated Show resolved Hide resolved

thoward commented Jul 17, 2025

View reviewed changes

content/docs/idp/best-practices/four-factors.md Outdated Show resolved Hide resolved

Apply suggestions from code review

19b6767

thoward temporarily deployed to testing July 17, 2025 17:32 — with GitHub Actions Inactive

Update four-factors.md

0bd4591

thoward temporarily deployed to testing July 17, 2025 17:34 — with GitHub Actions Inactive

jkodroff requested changes Jul 21, 2025

View reviewed changes


		## Patterns

		Coming soon: Common architectural patterns and design approaches for organizing your infrastructure code and workflows.


		This section provides proven patterns and ready-to-use blueprints that help you implement well-architected solutions with Pulumi IDP. These resources follow industry best practices and have been validated in production environments.

		## Patterns

		Consider a developer who needs to deploy a new web site hosted in a S3 bucket. Here's how the four factors collaborate:

		- Template: The developer starts with a `web-site` template that scaffolds a new project with the necessary structure and dependencies.


		## When to use this pattern

		- Complex architectures: When you need to combine multiple infrastructure patterns

	- Complex architectures: When you need to combine multiple infrastructure patterns
	- Integrated architectures: When you need to combine multiple types of infrastructure


		This pattern combines Pulumi components with constrained input types and policies to control infrastructure costs. By limiting available options and enforcing cost-related policies, organizations can prevent expensive configurations while maintaining developer productivity.

		## When to use this pattern

Create IDP best practices section and four factors conceptual doc #15479

Are you sure you want to change the base?

Create IDP best practices section and four factors conceptual doc #15479

Conversation

thoward commented Jul 8, 2025

Uh oh!

pulumi-bot commented Jul 8, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

thoward Jul 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

pulumi-bot commented Jul 16, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

pulumi-bot commented Jul 17, 2025

Uh oh!

pulumi-bot commented Jul 17, 2025

Uh oh!

Uh oh!

Uh oh!

pulumi-bot commented Jul 17, 2025

Uh oh!

pulumi-bot commented Jul 17, 2025

Uh oh!

jkodroff left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

thoward Jul 15, 2025 •

edited

Loading