Home
Relevant source files
The following files were used as context for generating this wiki page:Pulumi is an Infrastructure as Code platform that allows developers to build, deploy, and manage cloud infrastructure using general-purpose programming languages. Instead of using domain-specific languages or YAML, you can use languages like TypeScript, Python, Go, and C# to provision and manage resources across various cloud providers, including AWS, Azure, Google Cloud Platform, and Kubernetes. This approach enables the use of standard language features such as loops, functions, classes, and package management for infrastructure definition.
The core of the Pulumi ecosystem is the pulumi CLI and its associated language SDKs and engine, which are contained within this repository. Pulumi is open source under the Apache 2.0 license and is designed to be extensible, supporting over 120 providers through its registry. Key features include a powerful Automation API for embedding IaC into applications and robust secrets management capabilities.
Sources: README.md:13-23, 31-33
Getting Started
The primary entry point for a new user is the pulumi new command, which creates a new Pulumi project from a template. The process is designed to be straightforward, guiding the user from project creation to cloud deployment in a few steps.
Sources: README.md:120-127, pkg/cmd/pulumi/newcmd/new.go:30-33
New Project Workflow
The typical workflow for a new Pulumi project involves initializing a project, deploying it, and managing its lifecycle.
This diagram illustrates the user flow when creating and managing a new Pulumi project.
The pulumi new command can create a project from a built-in template, a URL pointing to a Git repository, or even from a natural language prompt using Pulumi AI. It handles setting up the project structure, including the Pulumi.yaml file, and prepares the environment for the first deployment.
Sources: pkg/cmd/pulumi/newcmd/new.go:422-445
Core Concepts
Pulumi's platform is built on a few fundamental concepts: Projects, Stacks, and Packages. These concepts provide the structure for organizing, configuring, and managing infrastructure as code.
Projects and Stacks
A Pulumi project is a directory containing a program that defines infrastructure resources. Every project has a Pulumi.yaml file that specifies the project's name, a description, and the language runtime.
Sources: sdk/go/common/workspace/project.json:4-12, pkg/cmd/pulumi/newcmd/new.go:300-305
Pulumi.yaml Structure
The Pulumi.yaml file defines the metadata for a project. The structure is defined by a JSON schema.
The following diagram shows the entity relationships for key properties within a Pulumi.yaml file.
Sources: sdk/go/common/workspace/project.json
Key properties of the Pulumi.yaml file are detailed below:
| Property | Type | Description |
|---|---|---|
name | string | The name of the project. Must contain only alphanumeric characters, hyphens, underscores, and periods. |
runtime | string or object | The language runtime for the project (e.g., nodejs, python, go, dotnet). Can be an object with name and options. |
description | string | An optional description of the project. |
main | string | An optional path to the Pulumi program's entry point. Defaults to the working directory. |
template | object | If the project was created from a template, this section contains template metadata like displayName and description. |
backend | object | Specifies the backend for the project, with an optional url. |
packages | object | Defines package dependencies for the Pulumi project. |
Sources: sdk/go/common/workspace/project.json:7-108
Packages and Providers
Pulumi uses packages to define and manage resources from different cloud and infrastructure providers. Each package corresponds to a provider (e.g., aws, azure-native) and is defined by a schema file, typically pulumi.json or schema.json. This schema describes the provider's resources, functions, and configuration.
Sources: pkg/codegen/schema/pulumi.json:4-7, pkg/cmd/pulumi/packagecmd/package_info.go:42-47
Package Schema Structure
The package schema is the blueprint for a provider, detailing all its components.
This class diagram illustrates the main components of a Pulumi package schema.
You can inspect the contents of a package, including its modules, resources, and functions, using the pulumi package info command. This command parses the package schema to provide detailed information.
Sources: pkg/cmd/pulumi/packagecmd/package_info.go:33-39
Supported Languages
Pulumi supports several popular programming languages, allowing developers to use familiar tools and ecosystems.
| Language | Status | Runtime | Supported Versions |
|---|---|---|---|
| JavaScript | Stable | Node.js | Current, Active and Maintenance LTS versions |
| TypeScript | Stable | Node.js | Current, Active and Maintenance LTS versions |
| Python | Stable | Python | Supported versions |
| Go | Stable | Go | Supported versions |
| .NET (C#/F#/VB.NET) | Stable | .NET | Supported versions |
| Java | Stable | JDK | 11+ |
| YAML | Stable | n/a | n/a |
Sources: README.md:162-172
Development and Contribution
The Pulumi project welcomes contributions. The standard workflow is fork-based: fork the repository, create a topic branch, and submit a pull request.
Key development commands include:
make lint: Runs all lint checks.make changelog: Generates a new changelog entry for a pull request.
For more detailed information on the system architecture, building, and testing, refer to the Pulumi Developer Documentation. The developer documentation is built using Sphinx and MyST.
Sources: CONTRIBUTING.md:31-52, developer-docs/index.md:3-10, developer-docs/build.md:3-5
CLI Documentation Generation
The CLI reference documentation is generated in Markdown format using the pulumi gen-markdown command. This command processes the Cobra command tree and creates one file per command, adding front matter for titles, aliases, and meta descriptions to each file for integration with the documentation website.
Sources: pkg/cmd/pulumi/markdown/gen.go:55-61, 80-97
Conclusion
Pulumi provides a robust platform for Infrastructure as Code, empowering developers to manage cloud resources with the expressiveness and power of general-purpose programming languages. Its architecture is built around a CLI, a core engine, and an extensible system of language SDKs and provider packages. The project is open-source and encourages community contributions, with comprehensive developer documentation to guide contributors.
Sources: README.md:13-23, CONTRIBUTING.md:3-5