Pulumi Blog: Patterns and practices platform

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