Pulumi Blog: Architecture

Automatic Diagram Generation for Always-Accurate Diagrams

Elisabeth Lichtie — Mon, 22 Sep 2025 00:00:00 +0000

Architecture diagrams are one of the most tedious aspects of infrastructure management. Teams spend countless hours manually creating and updating visual representations of their systems, only to see them become outdated the moment infrastructure changes.

When you manage your infrastructure as code, you can automatically generate accurate, up-to-date diagrams directly from your IaC definitions and state. Pulumi’s preview capabilities let you anticipate exactly what changes will result from code modifications before deployment, providing the perfect foundation for automated diagramming workflows.

In this post, we’ll explore three practical approaches to automating diagram generation in your CI/CD pipeline:

Native Pulumi diagramming: Using Pulumi’s built-in diagramming capabilities to generate basic architecture diagrams that you can retrieve from GitHub Actions’ artifact archive
AI-powered diagramming: Leveraging the Claude app with Mermaid and Pulumi preview to generate detailed diagrams and automatically add them to pull requests for infrastructure changes
Pulumi Neo for enterprise diagramming: Using Pulumi’s AI-powered platform for organization-wide diagramming patterns, project-level and organization-level views, and intelligent customization for different stakeholders

These approaches eliminate manual diagramming work while ensuring your documentation stays current with your actual infrastructure, from simple automation to enterprise-scale intelligent diagramming.

Native Pulumi diagramming with GitHub Actions

Pulumi’s built-in pulumi stack graph command generates architecture diagrams directly from your deployed infrastructure state. This approach provides a reliable foundation for automated diagramming since it reflects your actual deployed resources rather than just the code.

Complete example: View the full working example on GitHub.

Here’s a complete GitHub Actions workflow that deploys infrastructure and automatically generates diagrams:

name: Pulumi Deploy & Diagram

on:
 push:
 branches: [main]

jobs:
 deploy:
 name: Deploy & Generate Diagram
 runs-on: ubuntu-latest
 steps:
 - uses: actions/checkout@v4

 - name: Setup Node.js
 uses: actions/setup-node@v4
 with:
 node-version: "20"
 cache: "npm"

 - name: Install dependencies
 run: npm ci

 - uses: pulumi/actions@v5
 with:
 command: up
 stack-name: dev
 env:
 PULUMI_ACCESS_TOKEN: ${{ secrets.PULUMI_ACCESS_TOKEN }}

 - name: Install Pulumi CLI
 run: |
 curl -fsSL https://get.pulumi.com | sh
 echo "$HOME/.pulumi/bin" >> $GITHUB_PATH

 - name: Generate Architecture Diagram
 run: pulumi stack graph architecture.dot --stack dev
 env:
 PULUMI_ACCESS_TOKEN: ${{ secrets.PULUMI_ACCESS_TOKEN }}

 - name: Install Graphviz
 run: sudo apt-get update && sudo apt-get install -y graphviz

 - name: Generate PNG from DOT file
 run: dot -Tpng architecture.dot -o architecture.png

 - name: Upload Architecture Diagrams
 uses: actions/upload-artifact@v4
 with:
 name: architecture-diagrams
 path: |
 architecture.dot
 architecture.png

How the workflow works

This workflow follows a straightforward pattern that ensures your diagrams always reflect your deployed infrastructure:

Deploy first: The workflow uses the official pulumi/actions@v5 action to deploy your infrastructure changes. This ensures the state reflects your latest code.
Generate diagram from state: The pulumi stack graph command reads your deployed stack’s state and generates a DOT format file containing the resource relationships and dependencies.
Convert to visual format: Graphviz converts the DOT file into a PNG image that’s easy to view and share.
Archive as artifacts: Both the raw DOT file and the rendered PNG are uploaded as GitHub Actions artifacts, making them downloadable from the workflow run.

Key advantages and limitations

Highest accuracy: Since diagrams are generated from deployed state rather than code, they reflect your actual infrastructure including any drift or manual changes. This is the biggest advantage of the native approach.

Zero maintenance: Once set up, diagrams update automatically with every deployment without any manual intervention.

Multiple formats: The DOT format can be converted to various output formats (PNG, SVG, PDF) depending on your needs.

Audit trail: Each workflow run preserves the diagram as an artifact, creating a visual history of your infrastructure changes.

However, this approach has some limitations:

Fixed styling: You’re locked into Pulumi’s diagram style and layout algorithms, with limited customization options.

Basic aesthetics: The generated diagrams are functional but not always aesthetically polished compared to hand-crafted or AI-generated alternatives.

Technical focus: Diagrams show all resources and relationships, which can be overwhelming for non-technical stakeholders who need higher-level architectural views.

Accessing your diagrams

After each workflow run, you can download the generated diagrams from the Actions tab in your repository. Click on any workflow run, scroll to the “Artifacts” section, and download the architecture-diagrams package.

For a more sophisticated setup, you could extend this workflow to automatically commit diagrams back to your repository, post them to Slack, or integrate them with your documentation system.

AI-powered diagramming with Claude and Mermaid

The second approach leverages Claude’s ability to analyze Pulumi preview output and generate aesthetically pleasing, contextually relevant diagrams using Mermaid syntax. This method addresses the styling limitations of native Pulumi diagrams while maintaining accuracy through pulumi preview integration.

Complete example: View the full working example on GitHub.

The automated workflow

This approach uses two GitHub Actions workflows working together:

Auto-comment workflow (auto-pr-comment.yml):

name: Auto PR Comment

on:
 pull_request:
 types: [opened]
 paths:
 - 'index.ts'
 - 'Pulumi.yaml'
 - 'Pulumi.*.yaml'

jobs:
 comment:
 if: github.actor != 'claude-code[bot]'
 runs-on: ubuntu-latest
 permissions:
 contents: read
 pull-requests: write
 steps:
 - name: Comment on PR
 uses: actions/github-script@v7
 with:
 github-token: ${{ secrets.PERSONAL_ACCESS_TOKEN }}
 script: |
 github.rest.issues.createComment({
 issue_number: context.issue.number,
 owner: context.repo.owner,
 repo: context.repo.repo,
 body: '@claude update the diagrams to reflect any infrastructure changes.'
 })

Claude integration workflow (claude.yml):

name: Claude Code

on:
 issue_comment:
 types: [created]
 pull_request_review_comment:
 types: [created]

jobs:
 claude:
 if: contains(github.event.comment.body, '@claude')
 runs-on: ubuntu-latest
 permissions:
 contents: write
 pull-requests: write
 issues: write
 steps:
 - name: Checkout repository
 uses: actions/checkout@v4

 - name: Run Claude Code
 uses: anthropics/claude-code-action@beta
 env:
 PULUMI_ACCESS_TOKEN: ${{ secrets.PULUMI_ACCESS_TOKEN }}
 with:
 anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
 allowed_tools: "Bash(npm install),Bash(pulumi stack select prod),Bash(pulumi preview --json),Bash(npx mmdc)"
 custom_instructions: |
 ## Pulumi Infrastructure Diagramming Assistant

 ### Step 1: Analyze Infrastructure State
 - Run `npm install` and `pulumi stack select prod`
 - Execute `pulumi preview --json` to get detailed resource plan
 - Parse JSON output to understand resource relationships and changes

 ### Step 2: Generate/Update Diagrams
 Update Mermaid diagram files in `/diagrams/`:
 - aws-infrastructure.mmd: Technical AWS resource diagram
 - c4-context.mmd: System context diagram
 - c4-container.mmd: Container-level view
 - c4-component.mmd: Component-level architecture

 ### Step 3: Generate SVG Files
 Convert .mmd files to .svg using mmdc CLI

How the AI approach works

Automatic triggering: When a pull request with infrastructure changes is opened, the auto-comment workflow adds a @claude mention, triggering Claude’s analysis.
Infrastructure analysis: Claude runs pulumi preview --json to get detailed information about planned infrastructure changes, including resource relationships and dependencies.
Intelligent diagram generation: Claude analyzes the preview output and updates multiple Mermaid diagrams:
- AWS infrastructure diagram: Technical view showing resources, networking, and data flow
- C4 diagrams: Context, container, and component views for different stakeholder needs
Visual rendering: The mmdc CLI converts Mermaid syntax to SVG files for immediate viewing.
PR integration: Updated diagrams are committed directly to the pull request branch, making them visible in code review.

Example generated diagram

Here’s a sample of the AWS infrastructure diagram that Claude generates:

graph TB
subgraph VPC["myVpc - CIDR: 10.0.0.0/16"]
subgraph PublicSubnet["myPublicSubnet - CIDR: 10.0.1.0/24"]
EC2["myInstance<br/>Type: t2.micro<br/>AMI: Latest Amazon Linux 2"]
end
IGW["myInternetGateway<br/>Internet connectivity"]
SG["mySecurityGroup<br/>HTTP (80) + SSH (22) access"]
end
WEB_USER["Web Users"] -->|HTTP requests| IGW
IGW --> PublicSubnet
SG --> EC2

Key advantages and limitations

Intelligent styling: Claude generates aesthetically pleasing diagrams with consistent formatting, colors, and layout that’s much more polished than native Pulumi output.

Multiple perspectives: Creates different diagram types (technical infrastructure, C4 architecture views) suitable for different audiences and stakeholder needs.

Context awareness: Claude understands the purpose and relationships of resources, creating meaningful groupings and flow representations.

Automated maintenance: Diagrams update automatically with infrastructure changes, staying current without manual intervention.

Integration with code review: Diagrams appear directly in pull requests, making infrastructure changes visible during review.

However, this approach also has limitations:

Potential for inaccuracy: Unlike native Pulumi diagrams that are generated directly from infrastructure state, AI-generated diagrams depend on Claude’s interpretation of preview output. While generally reliable, there’s inherent risk of misinterpretation or missed details that could lead to diagram inaccuracies.

AI dependency: Diagram accuracy is only as good as Claude’s understanding of complex infrastructure relationships, which may occasionally miss nuances or make incorrect assumptions.

Setup complexity: Requires more configuration including API keys, GitHub app installation, and workflow permissions.

Cost considerations: Each diagram update consumes Claude API credits, though costs are typically minimal for most projects.

Preview limitations: Diagrams reflect planned changes from pulumi preview rather than actual deployed state, which may differ if deployments fail.

This approach works best for teams that value diagram aesthetics and need multiple architectural views for different stakeholders, while accepting slightly more complexity and potential accuracy trade-offs in exchange for significantly better visual presentation.

Generate diagrams from your code

You can produce accurate architecture diagrams directly from your Pulumi state and preview, then wire the workflow into any coding agent through the Pulumi MCP server. Start a project to keep your diagrams in sync with your infrastructure.

Get started

Pulumi Neo: Enterprise-scale intelligent diagramming

Pulumi Neo brings the next evolution in infrastructure diagramming, with AI-powered intelligence that enables organization-wide diagram generation. Unlike the previous approaches that focus on individual stacks, Pulumi Neo provides enterprise-scale diagramming capabilities with intelligent customization for different stakeholders.

How the workflow works

Pulumi Neo streamlines enterprise diagramming through an intelligent, organization-aware approach that scales across multiple projects and stakeholders:

Repository setup: Create a dedicated repository to host your architecture diagrams and ensure your GitHub App has access. The repository structure helps Neo understand your diagramming patterns:
- overview/ folder for organization-wide infrastructure views
- stacks/ folder for individual stack diagrams
- Template files that Neo can model new diagrams from
- README documentation explaining the repository’s purpose and conventions

Neo prompt engineering: Use structured prompts to guide Neo’s diagram generation with enterprise-grade specificity. You can also select your architecture diagram repository to tell Neo where to store his work:

1. Scope: Create diagrams for all resources in my prod Pulumi stacks
1. Diagram Types:
- Individual stack diagrams showing resources within each stack
- Master overview diagram showing cross-stack dependencies and data flow
1. Visual Standards:
- Use official AWS/Azure/GCP service icons from their architecture icon sets
- Show resource relationships with labeled connections (security groups, subnets, etc.)
- Group related resources visually (VPC boundaries, availability zones)
1. Content Focus:
- Infrastructure resources only (compute, storage, networking, databases)
- Resource dependencies and data flow directions
- Cross-stack references and shared resources
1. Format: Generate diagrams as Mermaid code that can be rendered in documentation

Automated pull request generation: Neo analyzes your entire organization’s infrastructure state, identifies changes, and automatically creates pull requests with updated diagrams for review and approval.

Complete example: You can see my resulting architecture diagrams repository on GitHub.

Key advantages and limitations

Pulumi Neo offers the most sophisticated approach to infrastructure diagramming, particularly for enterprise environments:

Enterprise-scale intelligence: Neo understands your entire organization’s infrastructure landscape, generating diagrams that show cross-project dependencies and organization-wide resource relationships that individual stack-based approaches cannot capture.

Style customization: Customize your prompts to request different styles of diagrams.

Organizational consistency: Maintains consistent diagramming standards across teams and projects, ensuring visual coherence in large organizations with multiple infrastructure teams.

Cross-stack visibility: Unlike single-stack approaches, Neo provides organization-wide infrastructure views showing how different projects and teams’ resources interconnect.

Template-driven generation: Learns from your existing diagram patterns and templates to maintain consistency with your established visual standards and conventions.

AI-powered context understanding: Goes beyond simple resource mapping to understand business context, automatically highlighting critical paths, security boundaries, and architectural patterns.

However, Neo also has limitations:

AI interpretation risks: Like the Claude approach, AI-generated diagrams may miss nuances or make incorrect assumptions about complex enterprise infrastructure relationships.

Repository access requirements: Neo requires permissions to open pull requests against your repository.

Learning investment: Getting maximum value from Neo requires developing sophisticated prompt engineering skills and understanding how to structure repositories for optimal AI comprehension.

Conclusion

Automating diagram generation transforms one of the most tedious aspects of infrastructure management into a seamless part of your development workflow. All three approaches eliminate the manual overhead of keeping architecture diagrams current while solving the core problem of documentation drift.

Choose native Pulumi diagramming when accuracy is paramount and you need diagrams that perfectly reflect your deployed infrastructure. This approach offers the highest reliability with minimal setup complexity.

Choose AI-powered diagramming when you need polished, stakeholder-friendly diagrams and can accept slightly more complexity for significantly better aesthetics and multiple architectural perspectives.

Choose Pulumi Neo when you need enterprise-scale diagramming with organization-wide consistency, multi-level views across projects and stacks, and intelligent customization for different stakeholders with varying technical backgrounds.

Regardless of which approach you choose, you’ll eliminate hours of manual work while ensuring your documentation stays synchronized with your infrastructure changes. With Pulumi Neo’s AI capabilities now available, intelligent, context-aware diagramming has moved from possibility to reality, making infrastructure documentation both effortless and incredibly powerful.

The future of infrastructure documentation is here: automated, intelligent, and always accurate. With these examples as your foundation, you’re ready to transform how your team approaches architecture visualization at any scale.

Your Perfect Infrastructure May Not Be So Perfect

Simen A. W. Olsen — Mon, 16 Dec 2024 10:43:07 +0000

Guest Article: Simen A. W. Olsen from Bjerk, is here to share his lessons learned on why designing the perfect architecture for your future needs might be a mistake

I remember standing in front of our engineering team in 2018, proudly presenting what I believed was the future-proof architectural design for our new distributed system. The diagrams were immaculate, the technology choices were cutting-edge, and the scalability patterns were ready for any possible future scenario.

I was basically the Leonardo da Vinci of system design… if Leonardo had been really into Kubernetes and had a concerning addiction to coffee. But six months later, that “future-proof” architecture had become a constraint rather than an enabler, and my masterpiece was looking more like a finger painting done by a caffeinated raccoon.

This experience taught me something crucial: trying to build the perfect system that anticipates every future need is often worse than creating a system designed to change quickly. It’s like trying to predict what your kid will want to be when they grow up and pre-buying all the necessary equipment. Congrats, you now own a space suit, a stethoscope, and a dragon costume — and they decided to become a software engineer anyway.

The Over-Planning

Many teams fall into a common trap: they try to design systems that anticipate every possible future requirement. This happens even in agile teams, where we convince ourselves we need to “get the architecture right” before we can start iterating. You know, because nothing says “agile” like spending three months in a room drawing boxes and arrows while muttering “microservices” under your breath like it’s a magic spell.

In 2008, Netflix faced a choice: build the perfect data center that could handle all their anticipated future needs, or move to the cloud with a simpler architecture that could evolve. They chose the latter, focusing on making their system easy to change rather than trying to make it perfect. Smart move — unlike those my past self made who probably would’ve insisted on building a data center capable of streaming to Mars, just in case Elon asked nicely.

You might also like:

The Core Principles of Change-Ready Architecture

Through both failures and successes, I’ve identified three principles that define truly adaptable architecture:

Embrace simplicity. I think it makes sense to start with the simplest architecture that could possibly work for your current needs. Complexity should be earned, not presumed. If your architecture diagram looks like a plate of spaghetti that’s been hit by lightning, you might be doing it wrong.
Make change cheap. Instead of trying to avoid change, make it inexpensive. This means investing in automated testing, continuous deployment, and monitoring. When change is cheap, you don’t need to fear it.
Learn through action. Rather than trying to predict the future, build mechanisms that help you learn quickly about real needs. It includes feature toggles (Protip: Try Unleash.), A/B testing, and robust monitoring of how your system is actually being used. You know, actual data, not just what that one loud guy in planning insists will definitely happen.

The rise of AI and machine learning systems has made one thing clear: we can’t predict how our systems will need to evolve. The most successful teams aren’t those that try to build the perfect AI architecture upfront, but those that can rapidly experiment and adapt their systems based on real-world feedback.

The biggest pushback I hear is, “But what if we need to scale?” or “What about future requirements?” These fears often drive teams to over-architect their solutions. But here’s the reality: the cost of changing a simple system is usually lower than the cost of maintaining an over-engineered one. The key is understanding that good architecture isn’t about predicting the future — it’s about making future changes as painless as possible.

Conclusion

That over-engineered system I was so proud of in 2018? Its most significant flaw wasn’t in what it got wrong about the future — it was that it tried too hard to be right about the future in the first place. It’s like bringing a fully packed suitcase to a first date. Today, I know that the best architecture isn’t one that anticipates every need, but one that makes it easy to respond to needs as they emerge.

The next time you’re tempted to design for every possible future scenario, remember: the goal isn’t to build a perfect system, but to build one that’s perfectly easy to change. And if someone tells you they’ve designed the perfect future-proof architecture, they’re either lying, or they’ve discovered time travel — and in that case, they should be sharing lottery numbers, not system designs.

You might also like:

Pulumi Patterns and Practices Platform (P3): Some Assembly Required

Troy Howard — Mon, 11 Nov 2024 00:00:00 +0000

Note: This post discusses Pulumi Copilot, which Pulumi Neo has replaced. Learn about Neo →

Setting up an internal developer platform (IDP) can be a daunting task. There are a lot of tools out there that do some of the work for you, but none of them do all of it. Pulumi P3 is no different. Pulumi Patterns & Practices Platform (P3) is a reference architecture that we will be describing, and providing code for, through this series of articles.

We will never try to sell you on the idea that you can simply download a package, click next a few times, and achieve transformative success. That’s because any effective IDP will require some customization and integration to work within your environment.

Tools that purport to have it all figured out have only figured out how to manipulate you into a false narrative they have constructed in a vacuum, where all your organizational needs fit neatly into a few boxes they’ve decided on for you. And also charge you for. In addition to everything else you’re being charged for. Ultimately you’ll still need to build a lot yourself and these products rarely give guidance on how to do that.

When we first started hearing about our customers using Pulumi as an internal developer platform (IDP), we were frankly surprised, as our goals were primarily for Pulumi to be the best developer experience in infrastructure. But it makes sense. All the parts are there, some assembly required. Our goal with Pulumi Patterns and Practices Platform (P3) is to help with that assembly process.

Starting with our previous blog post on the topic, and continuing here, we are examining this use case, and attempting to formalize that into a collection of reusable components and some guidance on how you can skip the marketing pitches and pricing charts, and get straight to the hard work of building your own highly customized internal developer platform with Pulumi at its core.

Pulumi P3: Bill of Materials

Previously we identified the essential qualities of an effective IDP. Those were consistency, reproducibility, visibility, security and compliance, auditability, developer experience. In the last half of the post we discussed which parts of Pulumi could be used to meet those needs. That looks like:

Consistency: component resources, organization templates, drift detection
Reproducibility: stacks, deployments, versioned data
Visibility: Pulumi Insights, Pulumi Copilot
Security and Compliance: RBAC, GitHub Teams, SAML-SSO, Pulumi ESC, Pulumi Crossguard
Auditability: audit logging
Developer Experience: Python/Go/JavaScript/C#, popular IDE support, command-line tools, deeply hackable

That’s all great, and much of that is already built-into Pulumi without the need for you to do anything at all. So, what parts do you actually need to set up and configure? Here’s the bill of materials (BOM) to set up your own instance of Pulumi P3:

Bill of Materials:

Authentication and Identity Management:
- A GitHub organization that matches your Pulumi Cloud organization
- GitHub Teams users and roles that match your organizational structure and security needs
Secrets, Configuration, and Policy:
- Pulumi ESC environments to manage secrets across clouds
- Pulumi Crossguard policy packs that capture your company policies
Developer Experience:
- A set of reusable multi-language components for cross-cutting concerns/common services
- A set of organization templates that match your common use cases

Let’s go through each of those and briefly discuss what it looks like to set that up.

Authentication and identity management

We highly recommend using GitHub for code management. So much so that we have deeply integrated GitHub into Pulumi Cloud across a number of features. While we support alternatives such as GitLab, this will be the easiest and more feature-rich way to configure your platform.

In Pulumi Cloud, you have the ability to create organizations. A Pulumi Cloud organization can help you manage teams, roles, stacks, settings, and provide a dashboard across the entire organization. Pulumi Cloud also allows you to use a variety of identity providers to log in, including GitHub.

For simplicity’s sake, we suggest that you start with your GitHub organization. Create the GitHub organization, set up teams, and add members to those teams, assigning either admin or user roles to each member.

Next, in Pulumi Cloud, create an organization with exactly the same name as your GitHub organization, and choose GitHub as your identity provider. When a Pulumi organization is backed by a GitHub organization, then only members of that GitHub organization may be added to the Pulumi organization. Similarly, as soon as someone loses access to the GitHub organization, they will no longer have access to the Pulumi organization. You will also be able to import your GitHub teams directly into Pulumi Cloud. Then assign your users to the same roles in Pulumi Cloud teams as they have in the associated GitHub teams.

Figure: Mapping GitHub orgs, teams, and roles to Pulumi

Finally, you can map teams to stacks to grant access at specific permission levels. If you’re not familiar with Pulumi Stacks, a stack is a materialized instance of a specific set of cloud resources, as defined in a Pulumi program.

Pulumi ESC: Managing credentials, configuration, and other secrets

In order to deploy a stack you will need secrets such as cloud credentials and other configuration values that are provided to the deployment engine. Pulumi ESC is a secure system for managing secrets. They are organized by environments.

An example set of environments might look something like this:

Example: AWS login/credentials

# aws-creds ESC environment
values:
 creds:
 fn::open::aws-login:
 oidc:
 roleArn: arn:aws:iam::123456789012:role/pulumi-environments-oidc
 sessionName: pulumi-environments-session
 duration: 1h
 environmentVariables:
 AWS_ACCESS_KEY_ID: ${aws.creds.accessKeyId}
 AWS_SECRET_ACCESS_KEY: ${aws.creds.secretAccessKey}
 AWS_SESSION_TOKEN: ${aws.creds.sessionToken}

Example: Default production environment to use us-east-1 region

# aws-production ESC environment
imports:
 - aws-creds
values:
 aws:
 region: us-east-1
 pulumiConfig:
 aws:region: ${aws.region}

Example: Default staging environment to use us-west-2 region

# aws-staging ESC environment
imports:
 - aws-creds
values:
 aws:
 region: us-west-2
 pulumiConfig:
 aws:region: ${aws.region}

Here we define three environments for AWS:

aws-creds: sets up login via OpenID Connect (OIDC) and provides standard environment variables containing AWS credentials to the Pulumi program
aws-production: imports everything from aws-creds then sets the region to us-east-1
aws-staging: does the same, but sets the region to us-west-2.

Using that in a Pulumi program is as simple as adding the following settings to your stack config:

# Pulumi.staging.yaml
environment:
 - aws-staging

In this manner, you can configure separate environments for staging and production, with a complex set of configuration values and secrets, using different environments for each one. From the developer’s perspective they would only need to change aws-staging to aws-production when they go to deploy their stack.

Another strong benefit of this approach is that all secrets will be encrypted both in-flight and at-rest. Pulumi waits until the last moment to decrypt secrets at runtime. By default, uses automatic, per-stack encryption keys provided by Pulumi Cloud, but you could use a provider of your own choosing instead.

Pulumi Crossguard: Policy-as-Code

Pulumi Crossguard allows you to check and enforce policies on your deployments. Policies are rules, written in code, that run during deployments to check that the resources are conforming to the necessary criteria. You can use off-the-shelf policies like AWSGuard and Pulumi Compliance-Ready Policies or write your own.

Either way you end up with a policy pack that you can apply to your entire Pulumi organization via Pulumi Cloud.

Here’s an example policy that checks for the presence of a tag user:Stack on a S3 bucket:

from pulumi_policy import (
 EnforcementLevel,
 PolicyPack,
 ResourceValidationPolicy,
)

def s3_check_required_tags(args, report_violation):
 if args.resource_type == "aws:s3/bucket:Bucket":
 if ("tags" not in args.props or
 "user:Stack" not in args.props["tags"]):
 report_violation("S3 Bucket is missing required user:Stack tag.")

PolicyPack(
 name="bucket-tags",
 enforcement_level=EnforcementLevel.MANDATORY,
 policies=[
 ResourceValidationPolicy(
 name="s3-tags",
 description="Ensure required tags are present on S3 buckets.",
 validate=s3_check_required_tags,
 ),
 ],
)

If the tag isn’t on the resource, it blocks the deployment with an error message. The error message would look something like this:

Policies:
❌ bucket-tags@v0.0.1
- [mandatory] s3-tags (aws:s3/bucket:Bucket: my-bucket)
Ensure required tags are present on S3 buckets.
S3 Bucket is missing required user:Stack tag.

This allows you to implement company-specific policies that can be as simple or complex as you need them to be.

To apply this across your entire organization, you can publish this policy pack to Pulumi Cloud, with the following commands:

$ pulumi policy publish myorg
$ pulumi policy enable myorg/my-policy-pack latest

Some other great features of Crossguard are the ability to version policies, define multiple policy groups, and create remediation policies that automatically fix policy violations when possible. We will cover these topics in a future post where we go deeper on how to use policies effectively.

Multi-Language Components (MLC)

In Pulumi, a component resource is something that your developers can import in their Pulumi program, instantiate and modify. These are made available via a provider, which is in turn, made available to Pulumi via a provider package. There are many of these already available in the Pulumi Registry. However, in a custom internal developer platform you can define your own components, and bake appropriate settings/configuration directly into the underlying code.

A multi-language component (MLC) is even more useful. You can author your component in your language of choice and then generate a SDK that surfaces that component into all of the languages that Pulumi supports. For example, your platform team might be comfortable writing in Python, but the developers that write your microservices might use Go, and the developers who write the front-end apps might use Node.js. Both teams might need to deploy apps and infrastructure into your Kubernetes cluster. With multi-language components you can write a component in Python that abstracts away all the details of your custom Kubernetes cluster, and make that available to both teams, in both Go, Node.js, and any other language that Pulumi supports.

To build a MLC, you’ll follow these basic steps to create the component, provider, provider package, and generate the multi-language SDK:

Fork one of the component provider boilerplate repos for Python, TypeScript, or Go.
Update the package and code-generator configuration files, which name your component and package, define the inputs and outputs, and declare the dependencies.
Implement the component in your preferred language.
Generate an SDK for the other languages.
Deploy the package.

Here’s a quick example of creating a custom S3 Bucket component in Python, that complies with the tagging policy we built earlier:

from pulumi_aws import s3
import pulumi

class TaggedBucket(pulumi.ComponentResource):

 def __init__(self, name, opts = None):
 super().__init__('mycorp:index:TaggedBucket', name, None, opts)

 # Create a bucket and add a custom tag to it.
 bucket = s3.Bucket(
 f'{name}-bucket',
 tags={
 'user:Stack': pulumi.get_stack()
 },
 opts=ResourceOptions(parent=self))

 self.register_outputs({
 'bucket': bucket,
 'websiteUrl': bucket.website_endpoint,
 'bucketDnsName': bucket.bucketDomainName
 })

This shows the component implementation in isolation from the provider/packaging/SDK boilerplate. In this code sample, we’re creating a component called TaggedBucket that creates a S3 bucket, and adds a tag user:Stack with the current stack name as its value. A developer could now use this in a TypeScript Pulumi program as such, and this resource would automatically have the tags added to it.

import * as mycorp from "mycorp/mycorp-components";

const taggedBucket = new mycorp.TaggedBucket("example");

export const bucket = taggedBucket.bucket;
export const url = taggedBucket.websiteUrl;
export const dnsName = taggedBucket.bucketDnsName;

If you want to see how to create MLCs in more detail, check out this video that walks you through the entire process, and this repo for the code shown in the video. In a follow-up post in this series, we will build some reference MLCs that do things like implement a time-to-live (TTL) for stacks in your staging environment, automate drift detection, and automatically instrument your developer’s deployments with observability tools integrated by default.

Organization templates and the New Project Wizard

The final piece that ties all this together are organization templates. You may have used some of our built-in templates when you learned how to use Pulumi. These are great for basic use cases, but the real magic happens when you bring together your custom components and custom security environments to create personalized templates which represent the internal use cases for your organization.

Pulumi’s New Project Wizard reads these templates and provides an in-browser way to create a new project and deploy it. Running one of these templates will commit and push code to GitHub, and trigger an initial deployment – all in a few clicks and without leaving the browser.

Each template needs the following parts:

A Pulumi.yaml describing the template and its configuration values
A GitHub repo (public or private) containing the code for the templated Pulumi program

Here’s an example of a simple template using the components and environments we described above.

# Pulumi.yaml
name: ${PROJECT}
description: ${DESCRIPTION}
runtime: python
template:
 description: A Python Pulumi program that creates a tagged bucket.

"""__main__.py: A minimal Pulumi program"""

import pulumi
import mycorp

# Create an AWS resource (S3 Bucket)
tagged_bucket = mycorp.TaggedBucket('my-bucket')

# Export the name of the bucket
pulumi.export('bucket_name', tagged_bucket.bucket)

# Pulumi.production.yaml
environment:
 - aws-production

# Pulumi.staging.yaml
environment:
 - aws-staging

The Pulumi.yaml sets up the template and will populate the name and description from the settings provided during the template dialogue. The custom TaggedBucket component will create an S3 bucket, which will be tagged with user:Stack set to the name of the stack. Default stack configurations are provided for the staging and production environments which map to our two ESC environments, aws-production and aws-staging.

How it all works together

With all of that in place, from the developer’s perspective, all they need to do is create a new project from the template, answering three questions: the stack name, the name of the project, and an optional description.

If the developer names the stack staging it will automatically apply the aws-staging ESC environment, which will include the AWS credentials and set the region to us-west-2. However, if the developer names the stack production it will get the aws-production ESC environment setting it to use the us-east-1 region. The name of the stack will be stored in a tag on the resource.

Pulumi Crossguard will apply the bucket-tags policy check to see if the resource has the required user:Stack tag set and will allow the deployment to proceed only if it has that tag. If a developer created a standard S3 Bucket instead of using our internal TaggedBucket component, and failed to add the required tag, they will get an error message from our custom policy when they try to deploy.

Later, we can create additional automation that might do something like delete anything tagged staging after two weeks, or run drift detection on anything tagged production. We will be exploring these concepts in more detail in later posts.

More to Come

While setting up the Pulumi Patterns and Practices Platform (P3) reference architecture is not a simple click-to-deploy, hopefully this high-level tour of the various parts you need to assemble shows that really, it is only a matter of creating a few carefully constructed YAML files and snippets of code, and wiring them together properly. You can start small and build out your platform over time.

The next few posts in this series will go beyond these simple examples, showing much more complicated implementations of all of these pieces, and recommend some best practices for managing your infrastructure with this platform.

And if you are already ready to get your hands on Pulumi after this introduction, feel free to create an account and follow some of our Getting Started guides to see how easy simple use cases are and begin to imagine how that same developer experience will scale up to your entire organization.

To learn more, you can watch the following video which provides a high level overview of how Pulumi works:

*{padding:0;margin:0;overflow:hidden}html,body{height:100%}img{position:absolute;width:100%;top:0;bottom:0;margin:auto}">

Pulumi Cloud

The Pulumi Cloud is a fully managed service that helps you adopt Pulumi’s open source SDK with ease. It provides built-in state and secrets management, integrates with source control and CI/CD, and offers a web console and API that make it easier to visualize and manage infrastructure. It is free for individual use, with features available for teams.

Create an Account

Pulumi Patterns and Practices Platform (P3): A reference architecture for large-scale organizations

Troy Howard — Mon, 05 Aug 2024 00:00:00 +0000

Note: This post discusses Pulumi Copilot, which Pulumi Neo has replaced. Learn about Neo →

Infrastructure management is all fun and games until you find yourself scrolling through 1000+ resources in your AWS console. Worse, when one rogue product team wants to use Azure and your data team wants to be on GCP, you’re ARM wrestling in Azure and watching your economies of scale tip the wrong direction as you’re copy-pasting CloudFormation templates into yet another git repo. This. Needs. To. Be. A. Platform!

And in that moment of overwhelm, you will be sold to, nurture-emailed every week, and told all your problems will be solved by implementing an IDP (internal developer platform, as if you’ve never seen this acronym before). An IDP that costs a lot of money and a lot of time to implement beyond default settings. An IDP that really only solves half of your problems. Your internal team offers to build something that feels more like welding together random pieces of code into an abstract found-art sculpture built from junkyard refuse, already 5 years out of date. How long will this investment be useful before you have to start over?

It’s exhausting. If there was a good solution on the market, you wouldn’t be reading this article. So let’s talk about what you really need, and how Pulumi can help.

An effective internal developer platform

There are quite a few listicles out there professing to authoritatively tell you the 5, or 7, or 11 essential components of an internal developer platform. Personally, I trust our customers to tell us, and here’s what they have said they need:

Consistency: Bring some order to the chaos. As your company and your infrastructure grows, it gets more and more complicated to maintain consistency. You might already have established design patterns that you want to replicate, but don’t have any way to encode those practices in your current tools. There’s a lot of copy/paste of reusable blocks, but no way to apply DRY principles or to modularize/templatize the important parts (hint: all the parts are important!).

Reproducibility: Repeatable behaviors, who dat? If you run your deploy twice do you get the same results each time? What if you replicate your production environment to create a test environment, are they actually identical? How much more work does it take to get them to be? Will you get the same version of the training dataset every time you run your AI workloads? It’s anyone’s guess. A lack of reproducibility slows down development, makes debugging more difficult, and makes that reuse we just talked about harder to achieve.

Visibility: When your node count, and user count starts to go beyond about 50-100 resources (computing or human) you quickly run into a problem of visibility. It can be very difficult to get a handle on what’s happening, how many resources you have, where they are, and how much they cost. Any system that purports to be able to manage 1000 nodes or more must have deeply integrated analytics, dashboards, charts, and be searchable, across all your clouds, all your users, and every kind of resource.

Security and Compliance: Good fences make good neighbors. RBAC, policy-as-code, excellent secrets management, integration with your existing identity providers. These are the things you need to build security and policy guardrails you can rely on. Without them? It’s just a powder keg of liability waiting to catch a spark.

Auditability: What happened and who did it? This is like a high-stakes game of Clue. How quickly can you figure out who ran that bad deployment? Was it Colonel Mustard in the library with the candlestick? Or Blake the new Front-End Developer with overly-broad permissions in AWS? Being able to answer these questions needs to happen quickly. Quickly, like minutes, not hours or days. And it might have happened 6 months ago. Oof.

Developer Experience: In the ideal world, developers drive their own DevOps. The platform team provides self-service tools and streamlined workflows that allow your engineers to provision new resources, so your team doesn’t have to. And you know, if the developers don’t like the user experience, they won’t use it at all, and will invent their own tools. You will have ROGUE SYSTEMS to hunt down and argue against in tedious overly-technical meetings. This is not what you want. We need to keep the developers happy to prevent this.

A holistic view of the Patterns and Practices Platform reference architecture

Pulumi has a broad surface area of products and features that address these needs. Designed with integration in mind from the beginning, our tools orchestrate well, presenting a smooth and streamlined workflow for both operations teams and developer teams.

We have an idea of how you can use all the Pulumi products together to deliver a comprehensive internal platform for security, infrastructure management, and deployments. Call it an internal platform for developer platform engineers (IPfDPE), if you want. We call it the realization of a vision we’ve been working hard to build for many years.

Pulumi Patterns and Practices Platform (P3) is a reference architecture that we will be describing, and providing code for, through this series of articles. We’ll be diving deep into not just what you can do with our tools, but how to do it, and provide code for a reference implementation that you can use to jump start the process.

Here’s a quick overview to give you an idea of how we’ll be addressing those needs in Pulumi Patterns and Practices Platform (P3).

Consistency

Pulumi can help bring consistency to your software catalog by encoding design patterns into reusable component resources and by building custom organization templates that provide a no-code or low-code way to start a new project. Templates help get projects off the ground faster and ensure consistent code structure, policy compliance, and best practices.

Figure: An internal developer portal using custom templates in Pulumi Cloud

Beyond that, because Pulumi is multi-cloud (AWS, Azure, Google Cloud, and more) and multi-language (JavaScript, Python, Go, C#, Java) you can enjoy the same consistency across all your environments and all your developer teams, regardless of the languages they prefer, or cloud tooling they need.

Another core aspect of consistency is drift detection. Pulumi automatically detects and remediates cloud resources that have deviated from the expected state stored in Pulumi Cloud. This tech is better than ibuprofen at getting rid of developer-created headaches.

Reproducibility

Since 2010, scientists have felt that we are in a crisis – a reproducibility crisis – wherein we cannot easily reproduce an experiment in order to verify published results. Similarly, the software industry is entering into a reproducibility crisis of its own, especially around AI training workflows, where it is increasingly difficult to recreate crucial build and prod environments. Pulumi Stacks make it very easy to manage both configuration and state across multiple environments, and make reproducing a deployment within Pulumi a matter of a few basic operations.

You can use Pulumi programs to capture all of the necessary resources for an AI training workload, including things like versioned data using dynamic tables with time-travel functionality in Snowflake. That means you can be sure that not only will your deployment be on the infrastructure you need, it will also have the exact version of data, every time, which is essential to A/B testing and debugging your models.

Visibility

Every resource under management by Pulumi is visible within Pulumi Insights. From this single-pane-of-glass interface, you can search for resources across all cloud environments. Pulumi Copilot provides a state-of-the-art AI chat interface to ask complex questions and get immediate results. Pulumi Insight’s analytics gives you the ability to identify anomalies or trends in resource usage and dig into cost, security, and compliance concerns.

Figure: Search for any resource with Pulumi Insights

Security and Compliance

In the modern parlance, when you say DevOps, you mean DevSecOps. Pulumi is designed to be secure by default. Pulumi Cloud offers full role-based access control (RBAC) functionality including deep integration with GitHub teams and SAML-based SSO, managed secrets and flexibly-defined secure environments with Pulumi ESC, and policy-as-code provided by Pulumi Crossguard. Most importantly all of these features are deeply integrated across the platform, creating an air-tight system with all the guardrails you need for managing security and access.

Auditability

Every action a user takes in Pulumi can be tracked via the audit log which is searchable in two clicks from the Pulumi Cloud homepage dashboard. Audit logs can be filtered by user with one more click. Creating automated backups of your audit logs is a first-class feature. You will never have to worry about responding quickly when someone asks about an event that happened in your system. Also, each deployment and update has logs directly visible from the Pulumi Cloud app, regardless of how it was initiated.

Figure: Viewing the audit log in Pulumi Cloud

Developer Experience

Probably the most compelling aspect of Pulumi is the developer experience. Developers love Pulumi, because they get to use their preferred tools. General purpose programming languages, visual IDEs, command-line tools, and products with an API-driven architecture are what developers want, and it’s what Pulumi delivers in spades.

With Pulumi templates and custom internal component resources in place, developers can drive their own DevOps, provisioning their own infrastructure resources and managing their own deployments directly, reducing bottlenecks in platform teams. Product engineering teams can self-service with a stream-lined workflow that stays compliant with company policy by default. Deep in the code of their favorite programming languages, your developers will never even know they are following the company rules.

Figure: Using C# to write a Pulumi program in VS Code

More to Come

So now that we’ve made a case for how Pulumi can be applied to meet the most pressing needs of a larger organization, hopefully you will realize that the Pulumi Patterns and Practices Platform (P3) reference architecture we are presenting here is more than just infrastructure-as-code. P3 is a Pulumi-powered platform for teams, where your developer portal is not just a catalog of software, but a fully functional control-plane across all your cloud environments.

Stay tuned for the following series of posts where we will use Pulumi to implement the P3 reference architecture for a fully-featured internal developer platform (IDP, or IPfDPE if you prefer). That said, you may already have invested in some popular in cloud-native tools like Backstage or Kubernetes. Pulumi plays well with others, and you will be delighted to see how you can use Pulumi to cover the gaps in the CNCF ecosystem.

To learn more, you can watch the following video which provides a high level overview of how Pulumi works:

*{padding:0;margin:0;overflow:hidden}html,body{height:100%}img{position:absolute;width:100%;top:0;bottom:0;margin:auto}">

Pulumi Cloud

Create an Account

Next-level IaC: Bridging the Declarative Gap

Troy Howard — Fri, 07 Jun 2024 00:00:00 +0000

Pulumi stands out in the world of infrastructure-as-code (IaC) for its flexibility and ease of use. This is due to its unique approach of using general purpose programming languages to describe system configuration. It accomplishes this through a small but brilliant implementation detail that bridges the worlds of declarative and standard programming using asynchronous semantics.

In Pulumi, you describe your infrastructure in code – real code, not a DSL or YAML – using your preferred general purpose programming language. You don’t have to become a specialist in a niche proprietary declarative language, like Terraform’s HCL. Rather, you can reuse your existing programming skills, writing in standard imperative, object-oriented, and even functional language styles, while still gaining all of the benefits of the declarative style that other tools emphasize.

Pulumi provides a unique mix of a declarative model embedded and implemented inside of a standard programming language, allowing all the flexibility of custom imperative code, while still enabling Pulumi’s deployment engine to infer opportunities for parallel asynchronous execution and to converge a partially-realized system.

The secret sauce that lets Pulumi achieve this is the apply function, and the way it handles inputs and outputs via asynchronous programming constructs, similar to futures or promises. We’ll go deeper on that in this article, but first let’s talk a little bit about the flow of operations in Pulumi.

Pulumi’s architecture and flow of operations

Pulumi is a system that is made up of a number of components. At a high level, those are:

Pulumi Programs: The code you write to describe the infrastructure you need.
Deployment Engine: A process that executes requests to create/modify infrastructure.
Resource Providers: Plugins that interface with cloud services like AWS, Azure, and others.

These components interact together to manage your infrastructure across multiple cloud providers using a consistent programming and execution model.

Figure: Pulumi’s Program, Deployment Engine, and Resource Provider architecture

Let’s get into an example of how information flows back and forth between these components. Suppose you want to write a Pulumi program to create an AWS S3 Bucket to host a static website. When that bucket is created, it will be given a unique identifier that you need to use in other parts of your infrastructure. Every time you create the bucket the identifier will change, and it’s generated by the AWS API, so we can’t know it ahead of time. We need to handle this as a variable, not a fixed configuration value.

To do that in a Pulumi program, you can create a bucket and then refer to its id property later, like this:

import * as pulumi from '@pulumi/pulumi';
import * as aws from '@pulumi/aws';

// Create an S3 bucket
const bucket = new aws.s3.Bucket("bucket");

// Export the name of the bucket
export const bucketName = bucket.id;

import pulumi
import pulumi_aws as aws

# Create an S3 bucket
bucket = aws.s3.Bucket('bucket')

# Export the name of the bucket
pulumi.export('bucket_name', bucket.id)

When this program runs, the call to create the bucket object will issue a request to the deployment engine. The deployment engine will load the resource provider for AWS, and ask it to create the S3 bucket. The AWS resource provider then issues the request to the AWS API, which will create the bucket and then return the id of the newly created resource. The provider will return that to the deployment engine, which will then set the realized value on your Pulumi program’s bucket.id property and then move on to creating anything that depends on that property.

This all seems pretty straight-forward, except that Pulumi programs don’t wait and imperatively do each operation, one at a time. Instead the deployment engine will run them in parallel, only waiting in cases where the output of one operation is needed to run the next operation. This can create complex structures with some operations needing to wait for inputs from other operations, and some that don’t, all finishing at different times, depending on how long the cloud service takes to process that request.

Inputs and Outputs as asynchronous futures

Infrastructure automation tasks can be long-running and can result in intermittent errors and may need to be retried before moving on to the next step. A robust IaC solution will need to run concurrently, be able to restart, retry, and resume itself, and understand that a set of tasks could happen in any order, not necessarily in the order you defined them in code.

Back in our Pulumi program code, that means that some of the time the bucket object from our earlier example has its id property set, and sometimes it doesn’t. We wouldn’t want to run any operation that needed that variable before it was set, but we also wouldn’t want to wait to start operations that don’t need that value.

To address this, Pulumi models the input and output values as futures. This allows you to describe a complex set of needs using a familiar value-like syntax. Instead of using a string result directly, which would only exist some of the time, you instead work with an Output<string>, that Pulumi understands as a reference to a value that currently doesn’t exist, but will exist when the operation completes. Similarly, Input<string> describes a dependency on an input string that will at some point be provided as the result of another operation.

This notion of future completion is essential to understanding why apply blocks are necessary within Pulumi programs. The apply function is called by the deployment engine only when the operation has completed and the fully realized value is available. By using Input<T> and Output<T> to build the connections between different parts of your infrastructure, the code is leveraging asynchronous value semantics not just to wrap and provide access to a future value, but also to describe a relationship between two components. This allows Pulumi programs to be very natural to author and as readable as traditional code, while also enabling Pulumi’s deployment engine to execute the entirety of your graph of operations in parallel, only waiting when necessary. This maximizes the efficiency of interacting with potentially slow and unreliable external cloud services.

Realizing values using the `apply` function

An important distinction though, is that Input<T>/Output<T> values are just declarative placeholders for the values that will eventually be present. At a certain point you will need to access the values directly, for example in the context of a transformation. The output of one operation might produce a string, which you need to transform into another data structure before passing to the next operation. Pulumi really shines in this context!

Using the apply function we can pass an Input<T> or Output<T> to a transformation function which will accept the realized value as its input (and only run when that value is available). Within that function you can handle the string as a normal string, then return it back as an Output<string>. This allows you to use the full power of your programming language to perform a custom operation inline with the rest of your infrastructure automation.

Here’s a simple example of using apply to transform an output to something new using your programming language’s libraries. In this case, Base64 encoding the id of our bucket object.

Example: Using `apply` to Base64 encode an Output

import * as pulumi from '@pulumi/pulumi';
import * as aws from '@pulumi/aws';

// Create an S3 bucket
const bucket = new aws.s3.Bucket("bucket");

// Export the name of the bucket
export const bucketName = bucket.id;

// Export the name of the bucket, in Base64 encoding
export const bucketNameBase64 = bucket.id.apply(id=> {
 // Transform the bucket name into a Base64 encoded string
 Buffer.from(id).toString('base64')
})

import base64
import pulumi
import pulumi_aws as aws

# Create an S3 bucket
bucket = aws.s3.Bucket('bucket')

# Export the name of the bucket
pulumi.export('bucket_name', bucket.id)

# A Base64 encoder function to use in the apply function's lambda
def base64_encode(data):
 data_bytes = data.encode("ascii")
 base64_bytes = base64.b64encode(data_bytes)
 base64_string = base64_bytes.decode("ascii")

# Export the name of the bucket, in Base64 encoding
pulumi.export('bucket_name', bucket.id.apply(lambda data: base64_encode))

Our example shows how to do Base64 encoding, but this technique can be used for any kind of transformation function. These can be as elaborate as your use case requires, and leverage the full power of your programming language and its entire ecosystem. Doing custom transformations like this in other popular tools is often not possible. This leaves you stuck using external coordination (e.g. gluing things together with Bash scripts) which breaks their declarative-only model (because you cannot describe everything you need to do in it) and interrupts these tools’ ability to fully understand your infrastructure’s dependency graph.

While Pulumi’s asynchronous semantics may seem somewhat complex for basic use cases, they unlock abilities in more complex use cases, which is when you really need your IaC tooling to show up for you. Because real life is never as simple as demo code.

Next steps

If you haven’t already, install Pulumi today, and follow our self-directed Getting Started guides to learn more about making the most of Pulumi’s next-level infrastructure management features at your organization.

To learn more, you can watch the following video which provides a high level overview of how Pulumi works:

*{padding:0;margin:0;overflow:hidden}html,body{height:100%}img{position:absolute;width:100%;top:0;bottom:0;margin:auto}">

Pulumi Cloud

Create an Account

Introducing Pulumi Architecture Templates

Laura Santamaria — Wed, 19 Oct 2022 10:59:37 -0500

🚀 Deploying cloud infrastructure is hard. Getting the architecture right from the start can be time-consuming. What if you could skip the hassle and start with prebuilt, best-practice templates?

📢 Pulumi Architecture Templates let you scaffold cloud infrastructure instantly with a single command. Whether you’re launching a serverless app on AWS, a container service on GCP, or a Kubernetes cluster on Azure, Pulumi gives you ready-to-use templates to get started faster.

➡️ Let’s dive in and see how these templates simplify cloud deployments.

Best Practices for Common Architectures

While Pulumi allows you to define any architecture for any cloud, we often get asked for opinionated architectures to get started with different cloud-based scenarios. To meet this need, we’ve started building templates around best-practice architectures like a serverless architecture on Google Cloud or a container service architecture on AWS. To give a sense of what these templates are like, let’s explore the serverless template for Google Cloud, which uses Cloud Storage and Cloud Functions to deploy a small application that tells the current time.

Google Cloud Functions Example

There are a lot of additional components to add to any infrastructure on modern clouds, including roles created through access management. The Google Cloud Serverless Application template defines a number of necessary components:

A storage bucket
An Identity Account Management (IAM) binding for the bucket
A Google Cloud Folder custom component to sync a local folder to the bucket (so you don’t have to create individual objects for each file in a directory!)
Another storage bucket
A bucket object to hold the function app code
A Cloud Function
Another IAM member to run the Function
An object in the bucket to hold some configuration values

Deployments Made Simpler

Using this template (or any of the other templates, for that matter), you can create a new Pulumi project with the pulumi new command. The template’s creation steps will now ask for all of the necessary configuration values for this template. No more deployment errors because you forgot to define your Google Cloud project with pulumi config set!

$ pulumi new serverless-gcp-python
This command will walk you through creating a new Pulumi project.

Enter a value or leave blank to accept the (default), and press <ENTER>.
Press ^C at any time to quit.

project name: (serverless-app)
project description: (A serverless web application on Google Cloud Platform)
Created project 'serverless-app'

Please enter your desired stack name.
To create a stack in an organization, use the format <org-name>/<stack-name> (e.g. `acmecorp/dev`).
stack name: (dev)
Created stack 'dev'

gcp:project: The Google Cloud project to deploy into: fake-proj-1
gcp:region: The Google Cloud region to deploy into: (us-central1)
appPath: The path to the folder containing the functions to be deployed: (./app)
errorDocument: The file to use for error pages: (error.html)
indexDocument: The file to use for top-level pages: (index.html)

Pulumi Templates vs Manual Setup

Feature	Pulumi Architecture Templates	Manual Setup
Preconfigured Best Practices	✅ Yes	❌ No
Multi-Cloud Support	✅ AWS, GCP, Azure	❌ Typically single-cloud
Faster Deployments	✅ One command setup	❌ Manual coding required
Scalability	✅ Easily extensible	⚠️ Needs custom scripts
Infrastructure-as-Code (IaC)	✅ Pulumi-native	❌ Requires manual IaC setup

Test Templates Yourself

There are already a number of templates built, and more are coming over the next weeks and months. We’ll be exploring more templates in detail here on the blog and on PulumiTV in the future. Review all the currently available architecture templates at our templates page. We’d love to hear what you think!

Deploy Infrastructure to Multiple Cloud Regions at Once

Joe Duffy — Wed, 03 Aug 2022 08:00:00 -0700

Pulumi makes it easy to flexibly deploy your cloud infrastructure using code. Usually deployments encompass a single slack and a single region in your cloud of choice. If you need to go multi-region, that usually means creating a stack per-region, which Pulumi’s configuration system makes easy. A stack per region isn’t required, though! Sometimes we want a single stack to span regions for performance, scalability, resilience, or just hard requirements. In these cases, Pulumi can seamlessly orchestrate deployments to, or even across, multiple regions, accounts, or clusters. In this article, we’ll see this in action by provisioning an AWS RDS primary database into one region and a read replica in an entirely different region – all from a single Pulumi program, stack, and pulumi up incantation.

Recap of Stack Configuration

Before seeing how to span regions, let’s review how you’d typically configure your region. Every Pulumi project can have any number of stacks. These stacks are often things like dev, test, prod – and sometimes, things like prod-us-east, prod-us-west, prod-euro, and so on, to represent instances of our infrastructure running in different regions. Each stack is isolated from all others and it’s easy to switch between them.

The standard way to vary regions between stacks is to use Pulumi’s configuration system. If you’ve used Pulumi to deploy to AWS, for instance, you’ve probably uttered a CLI command like this:

$ pulumi config set aws:region us-east-1

This isn’t just about regions: it applies to anything that varies between stacks. It might include accounts, secrets like tokens and passwords, sizes or counts of instances, among many other things.

This is normally very convenient and aligns with how we want to configure our projects and stacks. But there are some relatively common circumstances in which it breaks down:

Managing a large number of multi-tenanted resources spanning multiple accounts or clusters.
Cases where a few pieces of infrastructure must run somewhere different than most of it, as is often the case with DNS or SSL/TLS certificate management services.
Situations where we want to provision resources in many places for performance, scalability, or resilience purposes.
Highly programmatic scenarios where some configuration might be fetched dynamically from an external resource.

In all of these cases, thankfully Pulumi has an answer: explicit provider configuration.

How Explicit Provider Configuration Works

Before diving into our example, let’s take a quick look at how explicit provider configuration works. Unlike ordinary configuration, which is set at the CLI, provider configuration is set programmatically inside your Pulumi program. Every Pulumi package exports a Provider resource class which can be instantiated like any other resource, with the sole difference that these resources exist to pass around to configure other resources, and don’t represent infrastructure that is to be provisioned in a cloud of any kind.

For instance, if we wanted to programmatically create an AWS provider that targets a different region than us-east-1, as shown earlier, we can do so as follows:

const awsWest2 = new aws.Provider("aws-west-2", { region: "us-west-2" });

aws_west_2 = aws.Provider('aws-west-2', region='us-west-2')

awsWest2, err := aws.NewProvider(ctx, "aws-west-2", &aws.ProviderArgs{
 Region: pulumi.String("aws-west-2")
})
if err != nil {
 return err
}

var awsWest2 = new Aws.Provider("aws-west-2", new Aws.ProviderArgs
{
 Region = "us-west-2"
});

resources:
 awsWest2:
 type: pulumi:providers:aw
 properties:
 region: us-west-2

This configuration is not used automatically, however. You must pass it to any resources you’d like to use it:

const buck = new aws.s3.Bucket("my-bucket", {
 // ...
}, { provider: awsWest2 });

buck = aws.s3.Bucket('my-bucket',
 # ...
 opts=pulumi.ResourceOptions(provider=aws_west_2)
)

buck, err := s3.NewBucket("my-bucket",
 &s3.BucketArgs{
 // ...
 },
 pulumi.Provider(awsWest2)
)
if err != nil {
 return err
}

var buck = new Aws.S3.Bucket("my-bucket",
 new Aws.S3.BucketArgs
 {
 // ...
 },
 new ResourceArgs
 {
 Provider = awsWest2
 }
);

resources:
 # ...
 buck:
 type: aws:s3:Bucket
 properties:
 # ...
 options:
 provider: ${awsWest2}

This overrides the default of using whatever was set at the CLI, and will instead use the programmatically configured settings. Note also that anything you can set at the CLI is available, not just the region. You can see the full settings available in the package’s registry documentation for its Provider class (for instance, the AWS Provider.

Multi-Region Deployment In Action!

The architecture for our multi-region setup is going to be relatively straightforward so we can focus on the essentials. We will provision a single RDS primary database in one region (us-east-1) and backup to a read replica in an entirely different region – in fact, on an entirely different continent (eu-west-2)! This is relatively straightforward because many scenarios demand that we deploy to a dynamic number of regions, perhaps across dozens or hundreds of resources. By keeping it to just two resources across two regions, we can see the fundamentals in action which can scale easily to more sophisticated use cases.

This is described in AWS’s docs and is depicted in this diagram:

Now let’s dive into some infrastructure as code. There’s a bit of preamble before getting to the meat of the example:

import * as pulumi from "@pulumi/pulumi";
import * as aws from "@pulumi/aws";
import * as random from "@pulumi/random";

// Code from below will goes here.

import pulumi
import pulumi_aws as aws
import pulumi_random as random

# Code from below goes here.

package main

import (
 "github.com/pulumi/pulumi-aws/sdk/v5/go/aws"
 "github.com/pulumi/pulumi-aws/sdk/v5/go/aws/rds"
 "github.com/pulumi/pulumi-random/sdk/v4/go/random"
 "github.com/pulumi/pulumi/sdk/v3/go/pulumi"
 "github.com/pulumi/pulumi/sdk/v3/go/pulumi/config"
)

func main() {
 pulumi.Run(func(ctx *pulumi.Context) error {
 // Code from below goes here.
 })
}

using System.Collections.Generic;
using Pulumi;
using Aws = Pulumi.Aws;
using Random = Pulumi.Random;

return await Deployment.RunAsync(() =>
{
 // Code from below goes here.
});

name: aws-multireg-rds
runtime: yaml
description: A multi-region example creating an RDS primary and read-replica in different regions

# Code from below goes here.

Next, we’ll make the retention period configurable, by default it is 30 days. Note how we can still use standard configuration features as well as explicit providers alongside one another:

// Enable backup retention to be configured, but default to 30 days.
const config = new pulumi.Config();
const retentionPeriod = config.getNumber("retentionPeriod") || 30;

# Enable backup retention to be configured, but default to 30 days.
config = pulumi.Config()
retention_period = config.get_float('retentionPeriod') or 30

// Enable backup retention to be configured, but default to 30 days.
cfg := config.New(ctx, "")
retentionPeriod := 30
if param := cfg.GetFloat("retentionPeriod"); param != 0 {
 retentionPeriod = param
}

// Enable backup retention to be configured, but default to 30 days.
var config = new Config();
var retentionPeriod = config.GetNumber("retentionPeriod") ?? 30;

# Enable backup retention to be configured, but default to 30 days.
configuration:
 retentionPeriod:
 type: Number
 default: 30

Next, we’ll create a random password for our database so we don’t need to hard-code one:

// Create a random password for the database's admin user.
const dbPassword = new random.RandomPassword("dbPassword", { length: 12 });

# Create a random password for the database's admin user.
db_password = random.RandomPassword('dbPassword', length = 12)

// Create a random password for the database's admin user.
dbPassword, err := random.NewRandomPassword(ctx, "dbPassword", &random.RandomPasswordArgs{
 Length: pulumi.Int(12),
})

// Create a random password for the database's admin user.
var dbPassword = new Random.RandomPassword("dbPassword", new()
{
 Length = 12,
});

 # Create a random password for the database's admin user.
 dbPassword:
 type: random:RandomPassword
 properties:
 length: 12

Now we’re ready to create the providers. We’ll create one per region that we will deploy into:

// Create two AWS providers, one for each region we'll deploy into.
const euProvider = new aws.Provider("euProvider", { region: "eu-west-2" });
const usProvider = new aws.Provider("usProvider", { region: "us-east-1" });

# Create two AWS providers, one for each region we'll deploy into.
eu_provider = aws.Provider('euProvider', region = 'eu-west-2')
us_provider = aws.Provider('usProvider', region = 'us-east-1')

// Create two AWS providers, one for each region we'll deploy into.
euProvider, err := aws.NewProvider(ctx, "euProvider", &aws.ProviderArgs{
 Region: pulumi.String("eu-west-2"),
})
if err != nil {
 return err
}
usProvider, err := aws.NewProvider(ctx, "usProvider", &aws.ProviderArgs{
 Region: pulumi.String("us-east-1"),
})
if err != nil {
 return err
}

// Create two AWS providers, one for each region we'll deploy into.
var euProvider = new Aws.Provider("euProvider", new()
{
 Region = "eu-west-2",
});

var usProvider = new Aws.Provider("usProvider", new()
{
 Region = "us-east-1",
});

resources:
 # Create two AWS providers, one for each region we'll deploy into.
 euProvider:
 type: pulumi:providers:aws
 properties:
 region: eu-west-2
 usProvider:
 type: pulumi:providers:aws
 properties:
 region: us-east-1

To keep things straightforward, we’ve hard-coded the regions into the program. There are more sophisticated possibilities, however. For example, we could have made the regions themselves configurable too, much like the retention period. Even more powerfully, we could use our programming language’s expressiveness to create them dynamically. For instance, we could have looped over a list of them so that the number of regions isn’t even known in advance. These advanced capabilities are helpful for many real-world scenarios.

Next up, we’ll create the primary database instance in us-east-1:

// Create the primary RDS database instance.
const primaryDb = new aws.rds.Instance("primary", {
 allocatedStorage: 10,
 engine: "mysql",
 engineVersion: "5.7",
 instanceClass: "db.t3.micro",
 username: "admin",
 password: dbPassword.result,
 backupRetentionPeriod: retentionPeriod,
 skipFinalSnapshot: true,
}, {
 provider: usProvider,
});

# Create the primary RDS database instance.
primary_db = aws.rds.Instance('primary',
 allocated_storage=10,
 engine='mysql',
 engine_version='5.7',
 instance_class='db.t3.micro',
 username='admin',
 password=db_password.result,
 backup_retention_period=retention_period,
 skip_final_snapshot=True,
 opts=pulumi.ResourceOptions(provider=us_provider)
)

// Create the primary RDS database instance.
primaryDb, err := rds.NewInstance(ctx, "primary", &rds.InstanceArgs{
 AllocatedStorage: pulumi.Int(10),
 Engine: pulumi.String("mysql"),
 EngineVersion: pulumi.String("5.7"),
 InstanceClass: pulumi.String("db.t3.micro"),
 Username: pulumi.String("admin"),
 Password: dbPassword.Result,
 BackupRetentionPeriod: pulumi.Float64(retentionPeriod),
 SkipFinalSnapshot: pulumi.Bool(true),
}, pulumi.Provider(usProvider))
if err != nil {
 return err
}

// Create the primary RDS database instance.
var primaryDb = new Aws.Rds.Instance("primary", new()
{
 AllocatedStorage = 10,
 Engine = "mysql",
 EngineVersion = "5.7",
 InstanceClass = "db.t3.micro",
 Username = "admin",
 Password = dbPassword.Result,
 BackupRetentionPeriod = retentionPeriod,
 SkipFinalSnapshot = true,
}, new CustomResourceOptions
{
 Provider = usProvider,
});

 # Create the primary RDS database instance.
 primary:
 type: aws:rds:Instance
 properties:
 allocatedStorage: 10
 engine: mysql
 engineVersion: "5.7"
 instanceClass: db.t3.micro
 username: admin
 password: ${dbPassword.result}
 backupRetentionPeriod: ${retentionPeriod}
 skipFinalSnapshot: true
 options:
 provider: ${usProvider}

The key here is that we explicitly passed the provider that was configured to use us-east-1, instructing Pulumi to use that configuration rather than the implicit default configuration set at the CLI as usual.

Now we will create the secondary database instance in eu-west-2:

// Now set up our secondary read replica database in an entirely different region.
const secondaryDb = new aws.rds.Instance("secondary", {
 instanceClass: "db.t3.micro",
 replicateSourceDb: primaryDb.arn,
 backupRetentionPeriod: retentionPeriod,
 skipFinalSnapshot: true,
}, {
 provider: euProvider,
});

# Now set up our secondary read replica database in an entirely different region.
secondary_db = aws.rds.Instance("secondary",
 instance_class="db.t3.micro",
 replicate_source_db=primary_db.arn,
 backup_retention_period=retention_period,
 skip_final_snapshot=True,
 opts=pulumi.ResourceOptions(provider=eu_provider)
)

// Now set up our secondary read replica database in an entirely different region.
secondaryDb, err := rds.NewInstance(ctx, "secondary", &rds.InstanceArgs{
 InstanceClass: pulumi.String("db.t3.micro"),
 ReplicateSourceDb: primaryDb.Arn,
 BackupRetentionPeriod: pulumi.Float64(retentionPeriod),
 SkipFinalSnapshot: pulumi.Bool(true),
}, pulumi.Provider(euProvider))
if err != nil {
 return err
}

// Now set up our secondary read replica database in an entirely different region.
var secondaryDb = new Aws.Rds.Instance("secondary", new()
{
 InstanceClass = "db.t3.micro",
 ReplicateSourceDb = primaryDb.Arn,
 BackupRetentionPeriod = retentionPeriod,
 SkipFinalSnapshot = true,
}, new CustomResourceOptions
{
 Provider = euProvider,
});

 # Now set up our secondary read replica database in an entirely different region.
 secondary:
 type: aws:rds:Instance
 properties:
 instanceClass: db.t3.micro
 replicateSourceDb: ${primary.arn}
 backupRetentionPeriod: ${retentionPeriod}
 skipFinalSnapshot: true
 options:
 provider: ${euProvider}

As expected, we passed the provider configured to use eu-west-2. Notice also that, although these resources are deployed into entirely different regions, they can reference one another! Thanks to Pulumi’s dependency system, it understands that referencing primary.arn means the secondary database depends on the primary, which Pulumi will use to ensure correct ordering of operations.

Finally, we’ll emit the primary and secondary database endpoints plus auto-generated password:

// Output the primary and secondary database ARNs, and the auto-generated admin password.
export const primary = primaryDb.endpoint;
export const secondary = secondaryDb.endpoint;
export const password = dbPassword.result;

# Output the primary and secondary database ARNs, and the auto-generated admin password.
pulumi.export('primary', primary_db.endpoint)
pulumi.export('secondary', secondary_db.endpoint)
pulumi.export('password', db_password.result)

// Output the primary and secondary database ARNs, and the auto-generated admin password.
ctx.Export("primary", primaryDb.Endpoint)
ctx.Export("secondary", secondaryDb.Endpoint)
ctx.Export("password", dbPassword.Result)
return nil

// Output the primary and secondary database ARNs, and the auto-generated admin password.
return new Dictionary<string, object?>
{
 ["primary"] = primaryDb.Endpoint,
 ["secondary"] = secondaryDb.Endpoint,
 ["password"] = dbPassword.Result,
};

# Output the primary and secondary database ARNs, and the auto-generated admin password.
outputs:
 primary: ${primary.endpoint}
 secondary: ${secondary.endpoint}
 password: ${dbPassword.result}

Using these, we can easily access our new instance. Don’t worry, the password is automatically encrypted!

For good measure, since all of our AWS resources are meant to use the explicit providers, and not the ambient default configuration, we can disable default providers altogether:

$ pulumi config set --path pulumi:disable-default-providers[0] "aws"

If we forget to pass an explicit provider, we now get an error:

error: Default provider for 'aws' disabled. 'urn:pulumi:dev::aws-multireg-rds::aws:rds/instance:Instance::primary' must use an explicit provider.

Now that we’ve got everything set up, we run pulumi up which orchestrates everything end-to-end:

$ pulumi up
Updating (dev)

 Type Name Status
 + pulumi:pulumi:Stack aws-multireg-rds-dev created
 + ├─ pulumi:providers:aws euProvider created
 + ├─ pulumi:providers:aws usProvider created
 + ├─ random:index:RandomPassword dbPassword created
 + ├─ aws:rds:Instance primary created
 + └─ aws:rds:Instance secondary created

Outputs:
 password : [secret]
 primary : "primarybe35b53.c0q7bvujknic.us-east-1.rds.amazonaws.com:3306"
 secondary: "secondaryacb6a3d.c8qninoaapw8.eu-west-2.rds.amazonaws.com:3306"

Resources:
 + 6 created

Duration: 27m0s

Deploy across regions from one stack

Configure explicit providers in your Pulumi program to provision resources across regions, accounts, and clusters from a single stack. Build and ship your multi-region infrastructure with one pulumi up.

Learn more

Winding Down

In this article, you saw some reasons why deploying your infrastructure across multiple regions, accounts, or clusters may be necessary. You saw that Pulumi supports two forms of configuration – implicit configuration set at the CLI with pulumi config as well as explicit provider configuration which is constructed and passed programmatically – and how and when to use them, often in tandem with one another.

The specific example shown to demonstrate multi-region in action deployed an AWS RDS primary database to a US region and a secondary read replica to Europe, which is a common architecture to improve resilience and performance. The power of full programming languages gives you a ton of flexibility in how you orchestrate such complex architectures.

Hopefully this post put a new tool in your infrastructure as code toolbelt! Happy cloud spelunking.

Pulumi Blog: Architecture

Automatic Diagram Generation for Always-Accurate Diagrams

Native Pulumi diagramming with GitHub Actions

How the workflow works

Key advantages and limitations

Accessing your diagrams

AI-powered diagramming with Claude and Mermaid

The automated workflow

How the AI approach works

Example generated diagram

Key advantages and limitations

Pulumi Neo: Enterprise-scale intelligent diagramming

How the workflow works

Key advantages and limitations

Conclusion

Your Perfect Infrastructure May Not Be So Perfect

The Over-Planning

The Core Principles of Change-Ready Architecture

Conclusion

Pulumi Patterns and Practices Platform (P3): Some Assembly Required

Pulumi P3: Bill of Materials

Bill of Materials:

Authentication and identity management

Pulumi ESC: Managing credentials, configuration, and other secrets

Pulumi Crossguard: Policy-as-Code

Multi-Language Components (MLC)

Organization templates and the New Project Wizard

How it all works together

More to Come

Pulumi Cloud

Pulumi Patterns and Practices Platform (P3): A reference architecture for large-scale organizations

An effective internal developer platform

A holistic view of the Patterns and Practices Platform reference architecture

Consistency

Reproducibility

Visibility

Security and Compliance

Auditability

Developer Experience

More to Come

Pulumi Cloud

Next-level IaC: Bridging the Declarative Gap

Pulumi’s architecture and flow of operations

Inputs and Outputs as asynchronous futures

Realizing values using the apply function

Example: Using apply to Base64 encode an Output

Next steps

Pulumi Cloud

Introducing Pulumi Architecture Templates

Best Practices for Common Architectures

Google Cloud Functions Example

Deployments Made Simpler

Pulumi Templates vs Manual Setup

Test Templates Yourself

Deploy Infrastructure to Multiple Cloud Regions at Once

Recap of Stack Configuration

How Explicit Provider Configuration Works

Multi-Region Deployment In Action!

Winding Down

Realizing values using the `apply` function

Example: Using `apply` to Base64 encode an Output