Create IDP best practices section and four factors conceptual doc #15479
+1,417
−1
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,36 @@ | ||
| --- | ||
| title: Best Practices | ||
| linktitle: Best Practices | ||
| menu: | ||
| idp: | ||
| parent: idp-home | ||
| identifier: idp-best-practices | ||
| weight: 30 | ||
| meta_desc: Best practices, patterns, and blueprints for building with Pulumi IDP | ||
| h1: Best Practices | ||
| description: <p>Best practices, patterns, and blueprints for building secure, scalable, and flexible developer workflows with Pulumi IDP.</p> | ||
| --- | ||
|
|
||
| This section provides guidance on how to effectively use Pulumi IDP to build internal developer platforms that enable your organization to deliver infrastructure at scale while maintaining security, compliance, and developer productivity. | ||
|
|
||
| ## Practices | ||
|
|
||
| Learn foundational approaches and methodologies for building with Pulumi IDP: | ||
|
|
||
| - [Four Factors: Templates, Components, Environments, and Policies](/docs/idp/best-practices/four-factors) | ||
|
|
||
| ## Patterns | ||
|
|
||
| Common architectural patterns and design approaches for organizing your infrastructure code and workflows. Examples include [one ESC environment per service](/docs/idp/well-architected/patterns/one-esc-environment-per-service), [composable environments](/docs/idp/well-architected/patterns/composable-environments), and [policies as tests](/docs/idp/well-architected/patterns/policies-as-tests). | ||
|
|
||
| [View all patterns →](/docs/idp/well-architected/patterns) | ||
|
|
||
| ## Blueprints | ||
|
|
||
| Coming soon: Ready-to-use examples and reference implementations for common use cases. | ||
|
|
||
| ## Additional Resources | ||
|
|
||
| - [Get Started with Pulumi IDP](/docs/idp/get-started) | ||
| - [Private Registry](/docs/idp/get-started/private-registry) | ||
| - [Workflows](/docs/idp/get-started/workflows) |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,122 @@ | ||
| --- | ||
| title: "Four Factors: Templates, Components, Environments, and Policies" | ||
| linktitle: "The Four Factors Framework" | ||
| meta_desc: A framework for building with Pulumi IDP using Templates, Components, Environments, and Policies | ||
| allow_long_title: true | ||
| menu: | ||
| idp: | ||
| parent: idp-best-practices | ||
| weight: 10 | ||
| --- | ||
|
|
||
| This guide introduces a framework for building with Pulumi IDP that leverages four key factors to create secure, scalable, and flexible developer workflows. By understanding and effectively combining these factors, platform teams can build robust internal developer platforms that enable developers to provision infrastructure efficiently while maintaining compliance and security. | ||
|
|
||
| ## Templates | ||
|
|
||
| [Templates](/docs/pulumi-cloud/developer-platforms/templates/) are user-configurable scaffolding that creates new instances of infrastructure resources. They serve as the entry point for developers to quickly bootstrap new projects or components with pre-configured settings and best practices baked in. | ||
|
|
||
| Key characteristics: | ||
|
|
||
| - **User-configurable**: Developers can customize templates through simple parameters | ||
| - **Stack creation**: Each time a template is used it creates one or more new, independent [Pulumi stacks](/docs/iac/concepts/stacks/) | ||
| - **Standardized starting point**: Ensures consistent project structure and configuration | ||
| - **Low barrier to entry**: Enables developers to get started quickly without deep infrastructure knowledge | ||
|
|
||
| Templates abstract away the complexity of initial setup while providing flexibility for customization based on specific use cases. | ||
|
|
||
| ## Components | ||
|
|
||
| [Components](/docs/iac/concepts/components/) are reusable building blocks that abstract and encapsulate business logic, set sensible defaults, limit inputs, and encode company standards. They represent the core infrastructure primitives that your organization uses repeatedly. | ||
|
|
||
| Key characteristics: | ||
|
|
||
| - **Business logic abstraction**: Hide complex infrastructure patterns behind simple interfaces | ||
| - **Sensible defaults**: Provide secure, compliant defaults out of the box | ||
| - **Limited inputs**: Reduce cognitive load by exposing only necessary configuration options | ||
| - **Company standards**: Encode organizational policies and best practices directly in code | ||
|
|
||
| Components enable platform teams to create opinionated infrastructure building blocks that developers can use confidently, knowing they follow organizational standards. | ||
|
|
||
| ## Environments | ||
|
|
||
| [Environments](/docs/esc/environments/) provide credentials and configuration for your needs through composable, secure configuration management. They ensure that the right secrets and settings are available to the right workloads at the right time. | ||
|
|
||
| Key characteristics: | ||
|
|
||
| - **Least privilege**: Provide only the credentials and configuration needed for specific contexts | ||
| - **Composable**: Mix and match environment configurations based on deployment context | ||
| - **Secure**: Centrally manage and rotate secrets without exposing them in code | ||
| - **Context-aware**: Automatically apply the right configuration based on environment (staging, production, etc.) | ||
|
|
||
| Environments eliminate the need for developers to manage complex credential and configuration scenarios while maintaining security best practices. | ||
|
|
||
| ## Policies | ||
|
|
||
| [Policies](/docs/iac/crossguard/) ensure continued compliance with company requirements through automated validation. They provide guardrails that prevent misconfigurations and enforce organizational standards across all infrastructure deployments. | ||
|
|
||
| Key characteristics: | ||
|
|
||
| - **Automated validation**: Continuously check infrastructure configurations against defined rules | ||
| - **Compliance assurance**: Prevent deployments that violate organizational policies | ||
| - **Consistent enforcement**: Apply the same rules across all environments and teams | ||
| - **Proactive prevention**: Catch issues before they reach production | ||
|
|
||
| Policies act as a safety net, ensuring that even as infrastructure scales and evolves, it remains compliant with organizational requirements. | ||
|
|
||
| ## Bringing It All Together | ||
|
|
||
| The power of Pulumi IDP comes from combining these four factors into cohesive developer workflows. Here's how they work together in practice: | ||
|
|
||
| ### Example: Deploying a Web Site | ||
|
|
||
| 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. | ||
|
|
||
|
There was a problem hiding this comment. These blank lines should be removed so that this is a single |
||
| - **Component**: The template uses a custom `TaggedBucket` component that automatically: | ||
|
|
||
| - Creates an S3 bucket with secure defaults and user provided content | ||
| - Applies required organizational tags (like `user:Stack`) | ||
| - Configures appropriate access policies | ||
|
|
||
| - **Environment**: Based on the stack name, different ESC environments are automatically applied: | ||
|
|
||
| - `staging` stack uses AWS credentials for `us-west-2` region | ||
| - `production` stack uses AWS credentials for `us-east-1` region | ||
|
|
||
| - **Policy**: Pulumi Crossguard policies automatically validate the deployment: | ||
|
|
||
| - Ensures the `user:Stack` tag is present on all resources | ||
| - Ensures access policies meet organizational security standards | ||
| - Blocks deployment if compliance requirements aren't met | ||
|
|
||
| ### Developer Experience | ||
|
|
||
| From the developer's perspective, they only need to: | ||
|
|
||
| 1. Create a new project from the web-site template | ||
| 2. Answer a few configuration questions | ||
| 3. Run `pulumi up` | ||
|
|
||
| Behind the scenes, the four factors work together to apply the correct environment configuration, use secure and compliant components, enforce organizational policies, and provide a consistent and reliable deployment experience. | ||
|
|
||
| ### Benefits | ||
|
|
||
| This approach delivers several key benefits: | ||
|
|
||
| - **Reduced complexity**: Developers don't need to understand the intricacies of infrastructure configuration | ||
| - **Consistent compliance**: Policies ensure all deployments meet organizational standards | ||
| - **Secure by default**: Components and environments provide secure defaults and credential management | ||
| - **Scalable governance**: Platform teams can update templates, components, and policies centrally | ||
|
|
||
| By leveraging these four factors together, organizations can create internal developer platforms that balance developer productivity with operational requirements, security, and compliance. | ||
|
|
||
| ## Learn More | ||
|
|
||
| To see how these four factors can be used together in some common use cases, check out our [patterns](/docs/idp/best-practices#patterns) and [blueprints](/docs/idp/best-practices#blueprints) library. | ||
|
|
||
| ### Additional Resources | ||
|
|
||
| - [Get Started with Pulumi IDP](/docs/idp/get-started) | ||
| - [Private Registry](/docs/idp/get-started/private-registry) | ||
| - [Workflows](/docs/idp/get-started/workflows) | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,41 @@ | ||
| --- | ||
| title: Well Architected Patterns and Blueprints | ||
| linktitle: Well Architected | ||
| menu: | ||
| idp: | ||
| parent: idp-home | ||
| identifier: idp-well-architected | ||
| weight: 40 | ||
| meta_desc: Well-architected patterns and blueprints for building secure, scalable, and flexible developer workflows with Pulumi IDP | ||
| h1: Well Architected Patterns and Blueprints | ||
| description: <p>Well-architected patterns and blueprints for building secure, scalable, and flexible developer workflows with Pulumi IDP.</p> | ||
| --- | ||
|
|
||
| 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 | ||
|
There was a problem hiding this comment. I can't speak to these -- will defer to @jkodroff There was a problem hiding this comment. 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. |
||
|
|
||
| Common architectural patterns and design approaches for organizing your infrastructure code and workflows: | ||
|
|
||
| - [IDP Pattern: One ESC environment per service](/docs/idp/well-architected/patterns/one-esc-environment-per-service) | ||
| - [IDP Pattern: One ESC environment per team](/docs/idp/well-architected/patterns/one-esc-environment-per-team) | ||
| - [IDP Pattern: One ESC environment per lifecycle stage](/docs/idp/well-architected/patterns/one-esc-environment-per-lifecycle-stage) | ||
| - [IDP Pattern: Composable environments](/docs/idp/well-architected/patterns/composable-environments) | ||
| - [IDP Pattern: Container-based apps, centrally managed container infra](/docs/idp/well-architected/patterns/container-based-apps-centrally-managed-infra) | ||
| - [IDP Pattern: Policies as tests](/docs/idp/well-architected/patterns/policies-as-tests) | ||
| - [IDP Pattern: Components using other Components](/docs/idp/well-architected/patterns/components-using-other-components) | ||
| - [IDP Pattern: Validating Component Inputs using Policy functions](/docs/idp/well-architected/patterns/validating-component-inputs-using-policy-functions) | ||
| - [IDP Pattern: Cost control using Components, Policies, and constrained inputs](/docs/idp/well-architected/patterns/cost-control-using-components-policies-constrained-inputs) | ||
| - [IDP Pattern: Security Updates using Components](/docs/idp/well-architected/patterns/security-updates-using-components) | ||
|
|
||
| ## Blueprints | ||
|
|
||
| Ready-to-use examples and reference implementations for common use cases. | ||
|
|
||
| Coming soon: Comprehensive blueprints that combine multiple patterns into complete solutions for specific scenarios. | ||
|
|
||
| ## Additional Resources | ||
|
|
||
| - [Get Started with Pulumi IDP](/docs/idp/get-started) | ||
| - [Best Practices](/docs/idp/best-practices) | ||
| - [Private Registry](/docs/idp/get-started/private-registry) | ||
|
There was a problem hiding this comment. 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. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,21 @@ | ||
| --- | ||
| title: IDP Blueprints | ||
| linktitle: Blueprints | ||
| menu: | ||
| idp: | ||
| parent: idp-well-architected | ||
| identifier: idp-blueprints | ||
| weight: 20 | ||
| meta_desc: Ready-to-use blueprints for building secure, scalable, and flexible developer workflows with Pulumi IDP | ||
| h1: IDP Blueprints | ||
| description: <p>Ready-to-use examples and reference implementations for common use cases with Pulumi IDP.</p> | ||
| --- | ||
|
|
||
| Coming soon: Comprehensive blueprints that combine multiple patterns into complete solutions for specific scenarios. | ||
|
|
||
| ## Additional Resources | ||
|
|
||
| - [Well Architected Patterns and Blueprints](/docs/idp/well-architected) | ||
| - [IDP Patterns](/docs/idp/well-architected/patterns) | ||
| - [Best Practices](/docs/idp/best-practices) | ||
| - [Get Started with Pulumi IDP](/docs/idp/get-started) |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,42 @@ | ||
| --- | ||
| title: IDP Patterns | ||
| linktitle: Patterns | ||
| menu: | ||
| idp: | ||
| parent: idp-well-architected | ||
| identifier: idp-patterns | ||
| weight: 10 | ||
| meta_desc: Well-architected patterns for building secure, scalable, and flexible developer workflows with Pulumi IDP | ||
| h1: IDP Patterns | ||
| description: <p>Common architectural patterns and design approaches for organizing your infrastructure code and workflows with Pulumi IDP.</p> | ||
| --- | ||
|
|
||
| This section provides proven patterns that help you implement well-architected solutions with Pulumi IDP. Each pattern includes a description, use cases, anti-patterns, and related patterns to help you choose the right approach for your specific needs. | ||
|
|
||
| ## Environment Patterns | ||
|
|
||
| - [IDP Pattern: One ESC environment per service](/docs/idp/well-architected/patterns/one-esc-environment-per-service) | ||
| - [IDP Pattern: One ESC environment per team](/docs/idp/well-architected/patterns/one-esc-environment-per-team) | ||
| - [IDP Pattern: One ESC environment per lifecycle stage](/docs/idp/well-architected/patterns/one-esc-environment-per-lifecycle-stage) | ||
| - [IDP Pattern: Composable environments](/docs/idp/well-architected/patterns/composable-environments) | ||
|
|
||
| ## Application Patterns | ||
|
|
||
| - [IDP Pattern: Container-based apps, centrally managed container infra](/docs/idp/well-architected/patterns/container-based-apps-centrally-managed-infra) | ||
|
|
||
| ## Governance Patterns | ||
|
|
||
| - [IDP Pattern: Policies as tests](/docs/idp/well-architected/patterns/policies-as-tests) | ||
| - [IDP Pattern: Validating Component Inputs using Policy functions](/docs/idp/well-architected/patterns/validating-component-inputs-using-policy-functions) | ||
| - [IDP Pattern: Cost control using Components, Policies, and constrained inputs](/docs/idp/well-architected/patterns/cost-control-using-components-policies-constrained-inputs) | ||
|
|
||
| ## Component Patterns | ||
|
|
||
| - [IDP Pattern: Components using other Components](/docs/idp/well-architected/patterns/components-using-other-components) | ||
| - [IDP Pattern: Security Updates using Components](/docs/idp/well-architected/patterns/security-updates-using-components) | ||
|
|
||
| ## Additional Resources | ||
|
|
||
| - [Well Architected Patterns and Blueprints](/docs/idp/well-architected) | ||
| - [Best Practices](/docs/idp/best-practices) | ||
| - [Get Started with Pulumi IDP](/docs/idp/get-started) |
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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).