Getting Started
Relevant source files
The following files were used as context for generating this wiki page:Pulumi is an Infrastructure as Code (IaC) platform that allows you to build, deploy, and manage cloud infrastructure using familiar programming languages like TypeScript, Python, Go, C#, and Java. Instead of using domain-specific languages or YAML, you can leverage standard language features such as loops, functions, and classes to provision and manage resources across various cloud providers. This guide provides an overview of how to get started with the Pulumi CLI, from installation to deploying your first project.
This document covers the initial setup and basic workflow. For those interested in contributing to the Pulumi project itself, refer to the Contributing and Development section. For more advanced programmatic control, see the section on the Automation API.
Sources: README.md:12-21, CONTRIBUTING.md:29-31, sdk/go/auto/README.md:10-14
Installation
The primary way to install the Pulumi CLI is by using a shell script. The command downloads and runs the installer script, which places the pulumi binary in your user's .pulumi/bin directory.
$ curl -fsSL https://get.pulumi.com/ | sh
For contributors or those wishing to test a specific pull request, Pulumi artifacts can be downloaded directly from a PR build. This is done by specifying the PR number in the installation script. Note that these artifacts expire 7 days after the CI run.
curl -fsSL https://get.pulumi.com | sh -s -- --version pr#<number>
Sources: README.md:124-128, CONTRIBUTING.md:73-75
Creating a New Project with pulumi new
The pulumi new command is the entry point for creating a new Pulumi project. It initializes a new project from a template, which can be an official Pulumi template, a Git repository, a local file path, or even a prompt to Pulumi AI.
Sources: pkg/cmd/pulumi/newcmd/new.go:596-600, README.md:132-138
Command-Line Arguments and Flags
The pulumi new command can be customized with several flags to control its behavior, such as skipping prompts, specifying project details, and managing configuration.
| Flag | Shorthand | Description |
|---|---|---|
--ai | Prompt to use for Pulumi AI. | |
--config | -c | Configuration key-value pairs to save. |
--config-path | Indicates that config keys contain a path to a property. | |
--description | -d | The project description. |
--dir | The directory to place the generated project in. | |
--force | -f | Force content generation even if it overwrites existing files. |
--generate-only | -g | Generate the project only; do not create a stack or install dependencies. |
--language | Language to use for Pulumi AI. | |
--list-templates | -l | List locally installed templates. |
--name | -n | The project name. |
--offline | -o | Use locally cached templates without network requests. |
--secrets-provider | The secrets provider to use (e.g., default, passphrase, awskms). | |
--stack | -s | The stack name to create or select. |
--yes | -y | Skip all prompts and proceed with default values. |
Sources: pkg/cmd/pulumi/newcmd/new.go:683-739
Project Initialization Flow
The runNew function orchestrates the project creation process. The following diagram illustrates the high-level logic flow.
This diagram shows the control flow for the pulumi new command, from initial argument parsing to final project generation.
Sources: pkg/cmd/pulumi/newcmd/new.go:101-441
Template Sources
pulumi new can create projects from various sources:
- Official Templates: Use a shorthand name like
aws-typescript. If no template is provided, an interactive list is shown. - Git URL: A URL to a Git repository (GitHub, GitLab, Bitbucket) can be used. You can also specify a branch.
- Local Path: A path to a template on the local filesystem.
- Pulumi AI: By providing the
--aiflag with a prompt, or selectingaiin the interactive menu, Pulumi's AI can generate a project.
Sources: pkg/cmd/pulumi/newcmd/new.go:601-641
Pulumi AI Project Generation
When using Pulumi AI, the new command interacts with the Pulumi backend to generate a template URL based on a natural language prompt.
The following sequence diagram illustrates this process.
Sources: pkg/cmd/pulumi/newcmd/new.go:900-940
Basic Workflow
After creating a project, the typical development lifecycle involves a few core commands.
pulumi up: This command creates or updates your infrastructure to match the state defined in your code. It shows a preview of changes before performing them.pulumi stack output <key>: Use this to view stack outputs, such as a created URL or resource ID.pulumi logs -f: If your stack includes functions or containers, this command tails their logs.pulumi destroy: This command tears down all resources managed by the stack.
The following diagram shows the basic Pulumi workflow.
Sources: README.md:140-169
Supported Languages
Pulumi supports a variety of popular programming languages. The support status and required runtimes are listed below.
| Language | Status | Runtime | Versions |
|---|---|---|---|
| JavaScript | Stable | Node.js | Current, Active & Maintenance LTS |
| TypeScript | Stable | Node.js | Current, Active & Maintenance LTS |
| 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:180-196
Automation API
For more advanced use cases, such as CI/CD integration, building custom tooling, or orchestrating multiple stacks, Pulumi offers an Automation API. This API allows you to embed and drive the Pulumi engine programmatically from your own applications.
The Automation API provides three primary ways to define a stack's source:
NewStackLocalSource: For projects on the local filesystem.NewStackRemoteSource: For projects in a Git repository.NewStackInlineSource: For programs defined as a function within the automation code itself.
All stacks are managed within a Workspace, which is the execution context for a Pulumi project.
This diagram illustrates how the Automation API client interacts with a Workspace to manage multiple stacks programmatically.
Sources: sdk/go/auto/README.md:16-43
Contributing and Development
For those looking to contribute to the Pulumi project, the repository provides guidance and tooling.
Development Environment
The official developer documentation contains instructions for setting up a development environment. Before submitting a pull request, all lint checks must pass by running make lint.
Sources: CONTRIBUTING.md:29-41
Building the Docs
The developer documentation is generated using Sphinx and MyST from Markdown sources. Building the documentation requires Python, pip, and PlantUML.
The process is:
- Install
plantuml. - Install Python requirements:
pip install requirements.txt. - Build the HTML docs:
make.
Sources: developer-docs/build.md:7-20
Generating SDKs
Pulumi providers and SDKs are generated from a schema. The pkg/codegen directory contains the logic for generating code for different languages. For example, pkg/codegen/python/gen.go and pkg/codegen/dotnet/gen.go contain the core logic for generating Python and .NET SDKs, respectively. This process involves creating module contexts, generating resource and function definitions, and packaging the final SDK with necessary metadata like setup.py for Python or a .csproj file for .NET.
Sources: pkg/codegen/python/gen.go, pkg/codegen/dotnet/gen.go