Pulumi.yaml

Overview

The `Pulumi.yaml` file serves as the primary project configuration descriptor for a Pulumi infrastructure-as-code (IaC) project. It defines essential metadata and settings that Pulumi uses to manage the deployment and lifecycle of cloud resources.

Specifically, this file:

Defines the project name, runtime environment, and entry point.
Provides a brief description of the project.
Acts as a manifest that Pulumi CLI commands reference to determine how to build and deploy the infrastructure stack.

This configuration file is critical for orchestrating the deployment workflow and ensuring the Pulumi CLI interacts correctly with the project’s source code and runtime.

File Content Breakdown

name: common
runtime: nodejs
description: common project resources
main: ./index.ts

Fields Explanation

Field	Type	Description
`name`	string	The identifier of the Pulumi project. It is used internally by Pulumi and can be referenced in stacks.
`runtime`	string	Specifies the programming language runtime used for this project. Here it is set to `nodejs`, meaning the infrastructure code is written in JavaScript or TypeScript.
`description`	string	A short human-readable description of the project. Useful for documentation and clarity when managing multiple projects.
`main`	string	The relative path to the main entry point file of the Pulumi program that contains the infrastructure definitions. In this case, it points to `./index.ts`, a TypeScript file.

Usage

This file is automatically consumed by the Pulumi CLI when running commands such as `pulumi up`, `pulumi preview`, or `pulumi stack init`. It guides Pulumi in:

Loading the correct runtime environment (nodejs).
Locating the main program entrypoint to execute the infrastructure code.
Understanding the project context (via name and description).

Example Workflow

Initialize the stack:
```
pulumi stack init dev
```
Pulumi reads Pulumi.yaml to associate the stack with the common project.
Deploy infrastructure:
```
pulumi up
```
Pulumi uses the runtime and main fields to run index.ts under Node.js, which contains the resource definitions.
Preview changes:
```
pulumi preview
```
Pulumi simulates the deployment based on the program loaded from main.

Important Implementation Details

The runtime must match the language and environment of the infrastructure code. For instance, if the code were in Python, runtime would be python.
The main entry point should export or define the Pulumi resources and their relationships.
Pulumi uses this file to establish project boundaries and configurations, so incorrect entries can cause deployment failures or misconfigurations.
The file is YAML-formatted, so indentation and syntax must be strictly adhered to for correct parsing.

Interaction with Other Parts of the System

Pulumi CLI: This file is a key input for the CLI to understand how to execute the infrastructure code.
Source Code (e.g., index.ts): The main entry points to the source code that actually defines the cloud infrastructure resources.
Stacks: Together with stack configuration files (e.g., Pulumi.<stack-name>.yaml), this file helps define different deployment environments (development, production, etc.) within the same project.
Package Manager / Build System: Since the runtime is nodejs and the main file is TypeScript (.ts), this implies the need for a build step (e.g., using tsc or esbuild) or a runtime like ts-node to run the TypeScript code.

Visual Diagram

Since this file is a configuration descriptor rather than containing classes or functions, a **flowchart** illustrating how Pulumi uses this file in the deployment workflow is most appropriate.

flowchart TD
    A[Pulumi CLI Command (e.g. pulumi up)] --> B[Read Pulumi.yaml]
    B --> C{Parse Project Config}
    C -->|runtime=nodejs| D[Load Node.js Environment]
    C -->|main=./index.ts| E[Load Entry Point: index.ts]
    E --> F[Execute Infrastructure Code]
    F --> G[Create/Update Cloud Resources]
    G --> H[Deployment Complete]

Summary

The `Pulumi.yaml` file is a concise yet crucial configuration file that defines the project metadata, runtime environment, and entry point for a Pulumi infrastructure project. It enables the Pulumi CLI to correctly initialize, build, and deploy cloud resources using the specified Node.js/TypeScript program. Proper configuration of this file ensures smooth operation of Pulumi workflows and seamless integration with the broader project architecture.