The Pulumi Examples repository serves as a definitive, comprehensive collection of infrastructure-as-code (IaC) implementations, designed to demonstrate complex cloud deployment patterns across a diverse array of cloud providers and programming languages. It functions not merely as a repository of code but as a pedagogical framework and a reference implementation for industry-standard best practices in cloud orchestration. By providing over 150 working examples, the repository allows developers to transition from theoretical concepts to functional deployments, effectively bridging the gap between initial infrastructure design and production-ready environments. This ecosystem ensures that engineers can leverage pre-validated patterns to deploy scalable cloud infrastructure and applications using the Pulumi platform.
Repository Architecture and Navigation
The architectural organization of the Pulumi Examples repository is based on a strict, structured naming convention that facilitates rapid discovery and implementation. This pattern encodes both the target cloud provider and the programming language utilized in the project, ensuring that users can identify the relevant example without manually searching through directory structures.
The naming convention follows a specific <cloud>-<language> format. For instance, an example targeting Amazon Web Services written in TypeScript is identified as aws-ts-static-website, while an example targeting Microsoft Azure written in Python is labeled as azure-py-webserver. This systematic approach reduces the cognitive load on developers when selecting a starting point for their infrastructure project.
The repository encompasses examples for the most prominent cloud providers, including:
- AWS Examples
- Azure Examples
- GCP Examples
Beyond basic cloud provider examples, the repository extends into specialized domains such as testing strategies and frameworks within the Testing Infrastructure section, as well as detailed CI/CD automation blueprints within the CI/CD Workflows documentation.
Sparse Checkout and Targeted Example Acquisition
To avoid the overhead of downloading the entire repository containing hundreds of examples, Pulumi provides a method for performing a sparse checkout. This process allows a user to isolate and download only the specific example they intend to use, which is particularly useful for those with limited bandwidth or those who require a clean environment for a single specific use case.
To obtain a specific example, such as the aws-go-fargate project, the following sequence of terminal commands is required:
bash
mkdir examples && cd examples
git init
git remote add origin -f https://github.com/pulumi/examples/
git config core.sparseCheckout true
echo "aws-go-fargate" >> .git/info/sparse-checkout
git pull origin master
In this workflow, the user first creates a local directory and initializes a git repository. By enabling core.sparseCheckout, the user instructs Git to only populate the working directory with files that match the patterns specified in the .git/info/sparse-checkout file. This precision ensures that only the aws-go-fargate directory (or whichever example is substituted) is pulled from the master branch.
For users who cannot find a pre-existing example that fits their specific architectural requirements, Pulumi AI is available. This tool leverages natural-language prompts to generate bespoke infrastructure-as-code programs in any supported language, acting as a generative extension to the static examples repository.
Quality Assurance and Pull Request Validation
Maintaining the integrity of over 150 examples requires a rigorous validation process. Pulumi implements a series of sanity checks to ensure that examples remain functional as the cloud providers' APIs evolve. The repository includes a make pr_preview target specifically designed to validate changes before they are submitted via a pull request.
These preview checks provide sanity validation without requiring a full deployment of the infrastructure, which would be cost-prohibitive and time-consuming for every commit. The following commands are utilized for these validation tasks:
To run preview checks on all changed examples:
make pr_previewTo generate a list of examples that would be tested without actually executing the previews:
DRY_LIST=1 make pr_previewTo utilize a custom base branch for comparison instead of the default:
BASE_REF=origin/mybranch make pr_preview
The execution of these scripts assumes that the user has already configured the necessary credentials for the various cloud providers involved in the examples.
The GitHub Provider and Resource Management
The GitHub provider is a specialized Pulumi package designed to interact directly with GitHub resources, allowing for the programmatic management of organization members, teams, and other administrative assets. This shifts the management of GitHub settings from manual UI interactions to a version-controlled, reproducible process.
The provider is available across all major Pulumi-supported languages, as detailed in the following table:
| Language | Package Name |
|---|---|
| JavaScript/TypeScript | @pulumi/github |
| Python | pulumi-github |
| Go | github.com/pulumi/pulumi-github/sdk/v6/go/github |
| .NET | Pulumi.Github |
| Java | com.pulumi/github |
Multi-Language Implementation Examples
To demonstrate the versatility of the GitHub provider, the following implementations show how to add a user to an organization using different runtimes.
For Node.js (TypeScript/JavaScript), the implementation is as follows:
typescript
// Pulumi.yaml provider configuration file
name: configuration-example
runtime: nodejs
import * as pulumi from "@pulumi/pulumi";
import * as github from "@pulumi/github";
// Add a user to the organization
const membershipForUserX = new github.Membership("membership_for_user_x", {});
For Python, the implementation utilizes the pulumi_github library:
```python
Pulumi.yaml provider configuration file
name: configuration-example
runtime: python
import pulumi
import pulumi_github as github
Add a user to the organization
membershipforuserx = github.Membership("membershipforuserx")
```
For .NET, the implementation uses an asynchronous deployment run:
csharp
// Pulumi.yaml provider configuration file
name: configuration-example
runtime: dotnet
using System.Collections.Generic;
using System.Linq;
using Pulumi;
using Github = Pulumi.Github;
return await Deployment.RunAsync(() =>
{
// Add a user to the organization
var membershipForUserX = new Github.Index.Membership("membership_for_user_x");
});
For Go, the implementation leverages the github SDK and the pulumi.Run function:
go
// Pulumi.yaml provider configuration file
name: configuration-example
runtime: go
package main
import (
"github.com/pulumi/pulumi-github/sdk/v6/go/github"
"github.com/pulumi/pulumi/sdk/v3/go/pulumi"
)
func main() {
pulumi.Run(func(ctx *pulumi.Context) error {
// Add a user to the organization
_, err := github.NewMembership(ctx, "membership_for_user_x", nil)
if err != nil {
return err
}
return nil
})
}
Authentication and Configuration for GitHub Provider
Proper authentication is critical for the GitHub provider to interact with the GitHub API. There are several mechanisms for establishing this connection, depending on the security requirements and the nature of the integration.
OAuth and Personal Access Tokens
Authentication via OAuth or Personal Access Tokens (PAT) is a common approach. This requires the token argument to be set or the GITHUB_TOKEN environment variable to be configured. In a Pulumi.yaml configuration file, this is represented as:
```yaml
Pulumi.yaml provider configuration file
name: configuration-example
runtime:
config:
github:token:
value: 'TODO: var.token'
```
GitHub App Installation
For more robust, application-level integration, GitHub App installations can be used. This method requires the configuration of the appAuth block or the use of GITHUB_APP_XXX environment variables. A critical requirement for this method is the owner parameter; if this is omitted, the API will return a 403 "Resource not accessible by integration" error.
The configuration for the owner in Pulumi.yaml is as follows:
```yaml
Pulumi.yaml provider configuration file
name: configuration-example
runtime:
config:
github:owner:
value: 'TODO: var.github_organization'
```
It should be noted that some API operations are not supported when using GitHub App installations, and users should refer to the supported endpoints list for limitations.
CLI Path Configuration
In specific environments, such as those using the Cygwin terminal, the Pulumi GitHub provider may fail to automatically determine the path to the GitHub CLI (gh). To resolve this, users can manually specify the path to the executable using the GH_PATH environment variable.
CI/CD Integration with GitHub Actions
GitHub Actions provides a native CI/CD service that allows Pulumi programs to be executed automatically based on repository events such as pushes, pull requests, or tags. These workflows are defined in YAML files located within the .github/workflows/ directory.
The primary mechanism for executing Pulumi within these workflows is the pulumi/actions official action. This tool installs the Pulumi CLI and executes Pulumi commands as a discrete step in the workflow. Because it operates as a wrapper for the CLI, it is agnostic to the language used in the Pulumi program and the target cloud provider.
Pulumi maintains several specific actions on the GitHub Marketplace to handle different stages of the deployment lifecycle:
pulumi/actions: This action installs the Pulumi CLI and runs core commands such aspreview,up, anddestroy.pulumi/setup-pulumi: This is used for workflows that require the Pulumi CLI to be installed but intend to invoke commands directly rather than through the wrapper.pulumi/auth-actions: This allows the exchange of a GitHub OIDC token for a short-lived Pulumi Cloud access token, which enhances security by removing the need to store long-lived secrets in GitHub.pulumi/esc-action: This opens a Pulumi ESC environment and injects essential environment variables, including cloud credentials, secrets, and configuration, directly into the workflow.
Pulumi Kubernetes Operator and Advanced Patterns
The Pulumi Kubernetes Operator allows for the management of application deployments through GitOps workflows. This pattern enables the deployment of cloud resources (such as AWS S3 buckets) directly from within a Kubernetes cluster, facilitating a declarative approach to infrastructure.
Operator Use Cases and Implementations
Several advanced patterns are supported by the operator:
- Cloud Provider Integration: Deploying AWS S3 buckets demonstrates how the operator handles cloud provider authentication and configuration.
- Alternative Backends: The operator can be configured to use S3 as a backend instead of Pulumi Cloud, which is a vital capability for air-gapped or self-hosted deployments where external cloud access is restricted.
- Self-Bootstrapping: Using TypeScript, users can create a pattern where Pulumi manages the operator that is running the Pulumi programs, creating a recursive management loop.
Project Structure and Deployment Optimization
The TypeScript project structure for the operator follows standard Node.js and TypeScript conventions. The @pulumi/kubernetes package is utilized to programmatically create Stack resources.
To optimize startup time and support air-gapped environments, a custom source pattern is used. This involve the creation of pre-built container images that have the Pulumi programs embedded within them. The Dockerfile associated with this process ensures a self-contained image is produced.
Deployment Ordering and Resource Lifecycle
In complex architectures, stacks can declare prerequisites. This establishes a strict deployment ordering, ensuring that foundational infrastructure dependencies are fully deployed before dependent application layers are initiated.
Additionally, the destroyOnFinalize field provides control over the resource lifecycle. When this field is configured, it determines whether the underlying cloud resources are destroyed when the Stack Custom Resource (CR) is deleted from the Kubernetes cluster.
Analysis of Infrastructure-as-Code Patterns
The integration of Pulumi with GitHub and Kubernetes represents a shift toward "Infrastructure as Software." By leveraging the Pulumi Examples repository, developers can move away from static configuration files and toward dynamic, typed programs. The transition from using simple Personal Access Tokens to utilizing OIDC through pulumi/auth-actions highlights a maturation in security practices, moving toward short-lived, identity-based access.
The use of the Pulumi Kubernetes Operator further evolves this by implementing GitOps, where the state of the infrastructure is continuously reconciled with the desired state defined in Git. The capability for self-bootstrapping and the use of alternative backends for air-gapped environments demonstrate that Pulumi is designed for both high-scale public cloud environments and highly restricted corporate or government infrastructures. The systematic naming convention of the examples repository acts as the entry point for this entire ecosystem, providing a scalable way for developers to find and implement these complex architectural patterns.