Core Concepts
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 developers to build, deploy, and manage cloud infrastructure using familiar programming languages. This document outlines the fundamental concepts that form the basis of the Pulumi ecosystem, as derived from its source code. These concepts include the structure of projects and packages, the schema-driven approach to defining cloud resources, and the programming model centered around inputs and outputs.
The system is designed around a schema-driven code generation process, where a schema.json file defines the resources, functions, and types for a given cloud provider. This schema is then used by language-specific code generators to create SDKs for languages like Go, Python, .NET, and Node.js. This ensures a consistent and typed experience across all supported languages.
Projects and Stacks
A Pulumi project is the primary unit of organization for infrastructure code. It is defined by a Pulumi.yaml file, which specifies the project's name, a description, and the language runtime.
Sources: sdk/go/common/workspace/project.json, pkg/cmd/pulumi/newcmd/new.go:300-313
Project Structure
The Pulumi.yaml file is the manifest for a project. Its structure is defined by a JSON schema. The name and runtime are the only required properties.
The following diagram illustrates the conceptual hierarchy of a Pulumi deployment.
This diagram shows that a Pulumi Project contains one or more Stacks, and each Stack manages a collection of cloud Resources.
Pulumi.yaml Properties
The table below summarizes the key properties of the Pulumi.yaml file.
| Property | Type | Description |
|---|---|---|
name | string | Required. The name of the project, containing alphanumeric characters, hyphens, underscores, and periods. |
runtime | string or object | Required. The language runtime for the project (e.g., "nodejs", "python", "go", "dotnet"). Can be an object with a name and options. |
description | string | An optional description of the project. |
stackConfigDir | string | An optional path to a directory for stack-specific configuration files, relative to Pulumi.yaml. |
template | object | Contains metadata if the project was created from a template, including displayName and description. |
packages | object | A map of package dependencies for the project. |
plugins | object | An override for plugin selection, intended for development purposes. |
Sources: sdk/go/common/workspace/project.json:6-180
The pulumi new command orchestrates the creation of a new project, prompting the user for a name and description, copying template files, and initializing a new stack if one is not specified.
Sources: pkg/cmd/pulumi/newcmd/new.go:171-205
Packages and Schemas
Pulumi's multi-language support is enabled by a schema-centric approach. Each Pulumi package, which corresponds to a cloud provider (e.g., AWS, Azure, GCP), is defined by a schema file, typically named schema.json. This schema is the single source of truth for the resources and functions the package provides.
Sources: pkg/codegen/schema/pulumi.json, pkg/cmd/pulumi/packagecmd/package_info.go:50-58
Schema Structure
The package schema defines all the components of a provider. The pulumi package info command reads and displays information from this schema.
This diagram shows the main components defined within a Pulumi package schema.
Key components of a package schema include:
| Component | Description |
|---|---|
name | The unqualified name of the package (e.g., "aws"). |
version | The semantic version of the package. |
description | A Markdown-formatted description of the package. |
provider | A resourceSpec that defines the provider resource itself. |
resources | A map of resource tokens to resourceSpec objects, defining the manageable cloud resources. |
functions | A map of function tokens to functionSpec objects, defining data source functions. |
types | A map of type tokens to complexTypeSpec objects, defining shared object and enum types. |
config | A map of configuration variables for the package. |
language | Language-specific overrides and metadata for code generation (e.g., C#, Go, Node.js, Python). |
Sources: pkg/codegen/schema/pulumi.json:6-185
Code Generation
The language-specific code generators (pkg/codegen/{dotnet,go,nodejs,python}/gen.go) consume this schema to produce idiomatic SDKs. This process ensures that resources and their properties are consistently represented across all supported languages. For example, the Go generator creates Input and Output types for every resource and object type, while the .NET generator creates corresponding *Args and result classes.
Sources: pkg/codegen/go/gen.go:1934-1941, pkg/codegen/dotnet/gen.go:1218-1226, pkg/codegen/nodejs/gen.go:1172-1180, pkg/codegen/python/gen.go:1982-1988
Resources
A resource is the fundamental building block in Pulumi, representing a single component of cloud infrastructure, such as a virtual machine, a storage bucket, or a Kubernetes deployment.
Resource Definition and Lifecycle
Resources are defined in the package schema under the resources key. Each resource has a set of inputProperties (arguments for creation) and properties (attributes available after creation).
The lifecycle of a resource within the Pulumi engine involves a RegisterResource call to the resource monitor. This call is orchestrated by the language-specific SDKs.
This sequence diagram illustrates the process of a resource being registered with the Pulumi engine.
Sources: sdk/nodejs/tests/runtime/langhost/run.spec.ts:1020-1082, pkg/codegen/go/gen.go:2119-2123
Resource Types
Pulumi distinguishes between two main kinds of resources:
- Custom Resources: These map directly to a single physical resource in a cloud provider (e.g., an AWS S3 bucket). The SDKs generate a base class like
pulumi.CustomResourcefor these. - Component Resources: These are logical groupings of other resources. A component resource does not create a physical resource itself but orchestrates the creation of one or more other custom or component resources. The SDKs generate a base class like
pulumi.ComponentResourcefor these.
The distinction is handled during code generation, where the isComponent flag in the resource's schema definition determines the base class.
Sources: pkg/codegen/dotnet/gen.go:1022-1031, pkg/codegen/schema/pulumi.json:674-678
Functions (Invokes)
Functions, also known as "invokes," are used to read data from a cloud provider without creating or managing a resource. They are purely data sources, such as fetching an existing AMI ID or a list of availability zones.
Like resources, functions are defined in the package schema. The invoke call is handled by the language runtime, which communicates with the engine.
Sources: pkg/codegen/schema/pulumi.json:500-504, sdk/nodejs/tests/runtime/langhost/run.spec.ts:983-1002
Inputs and Outputs
The concepts of Input and Output are central to Pulumi's programming model. They are used to manage values that are not known until infrastructure is actually provisioned.
- Inputs: These are used for the arguments of a resource. An
Input<T>can be a value of typeTor anOutput<T>. This allows you to chain resources together, using an output from one resource as an input to another. - Outputs: These represent values that will be available after a resource has been created. For example, the public IP address of a virtual machine is an
Output<string>.Outputtypes have methods likeapply(in Node.js) orApplyT(in Go) to transform their eventual values.
The code generators for each language have extensive logic for creating these Input and Output types for every resource and data type in the schema. This includes simple types (StringInput, StringOutput), collection types (ArrayInput, MapOutput), and complex object types (VpcArgs, VpcOutput).
This diagram shows how the Output of one resource can be used as the Input for another, creating a dependency.
During a preview (pulumi preview), the values of Output properties are unknown, as no resources have been created. The runtime represents these as a special unknownValue. During an update (pulumi up), these outputs are resolved to their concrete values.
Sources: pkg/codegen/go/gen.go:379-502, pkg/codegen/dotnet/gen.go:328-449, pkg/codegen/nodejs/gen.go:273-350, sdk/nodejs/tests/runtime/langhost/run.spec.ts:460-474
Summary
The core concepts of Pulumi revolve around a declarative, schema-driven approach to Infrastructure as Code. Projects and Stacks provide organizational structure. Packages define available functionality through a formal Schema, which is used to generate language-specific SDKs. The programming model is built on Resources and Functions, with the flow of data between them managed by the asynchronous Input and Output types. This architecture enables developers to use familiar programming languages to create, deploy, and manage any cloud infrastructure.