Pulumi.yaml

Overview

The `Pulumi.yaml` file serves as the primary project configuration manifest for a Pulumi infrastructure-as-code (IaC) project. Pulumi uses this YAML file to define key metadata about the project, including its name, runtime environment, and an optional project description.

In this particular file, the project is named **"polygon"**, uses the **Node.js** runtime, and has a brief description labeled **"coin stack"**. This configuration enables Pulumi to understand how to execute the project code and provides essential context when deploying or managing infrastructure.

Detailed Explanation

This file does **not** contain classes, functions, or methods, as it is a declarative configuration file. Instead, it declares project-level settings used by the Pulumi CLI and runtime.

Key Fields

Field	Type	Description	Example
`name`	string	The unique name of the Pulumi project. This identifies the project within the Pulumi ecosystem and local workspace.	`polygon`
`runtime`	string	Specifies the runtime environment for the Pulumi program. It indicates which language Pulumi should use to execute the infrastructure code.	`nodejs`
`description`	string	A brief textual description of the project’s purpose or functionality. This is optional but helps with documentation and project clarity.	`coin stack`

Usage Example

This file is automatically used when running Pulumi commands such as `pulumi up`, `pulumi preview`, or [pulumi destroy](/projects/291/68799) in the project directory. Pulumi reads the configuration to determine:

What the project is called (for stacks and state storage).
Which runtime to invoke (e.g., Node.js).
Optional descriptive metadata.

Example project setup:

name: polygon
runtime: nodejs
description: coin stack

To initialize this project, you would run:

pulumi stack init dev
npm install
pulumi up

Pulumi uses `Pulumi.yaml` to understand that it should run Node.js scripts found in the project for infrastructure deployment.

Important Implementation Details

Runtime Environment: The runtime field controls the execution environment. For nodejs, Pulumi runs the Node.js SDK. Other supported runtimes include python, go, and dotnet.
Project Name: The name is crucial for Pulumi’s stack management and state storage. It must be unique within your organization or workspace.
Description: While optional, this field helps document the project purpose, useful for teams or when publishing projects.

Interaction with Other System Components

Pulumi CLI: The CLI uses this file to configure the project before executing commands.
Pulumi Runtime: Determines the language runtime to load and execute the provisioning scripts.
Pulumi Stacks: The project name defined here is used as a base when creating different environment stacks (e.g., polygon/dev, polygon/prod).
Infrastructure Code: This YAML file complements the infrastructure code files (e.g., index.js or index.ts in a Node.js project) by providing the context for deployment.
State Backends: Pulumi stores state and metadata linked to this project name in configured backends (local, cloud storage, etc.).

Visual Diagram

Since `Pulumi.yaml` is a configuration file without classes or functions, the diagram below represents the **workflow** of how this configuration file integrates with the Pulumi system and project components.

flowchart TD
    A[Pulumi.yaml] --> B[Pulumi CLI]
    B --> C[Runtime Loader]
    C --> D[Node.js Runtime]
    D --> E[Infrastructure Code (JS/TS)]
    E --> F[Cloud Provider APIs]
    B --> G[Stack & State Management]
    G --> H[State Backend (S3, Local, etc.)]

    style A fill:#f9f,stroke:#333,stroke-width:2px
    style B fill:#bbf,stroke:#333,stroke-width:2px
    style C fill:#ccf,stroke:#333,stroke-width:2px
    style D fill:#cfc,stroke:#333,stroke-width:2px
    style E fill:#fcf,stroke:#333,stroke-width:2px
    style F fill:#fcc,stroke:#333,stroke-width:2px
    style G fill:#cff,stroke:#333,stroke-width:2px
    style H fill:#ffc,stroke:#333,stroke-width:2px

Summary

Pulumi.yaml configures the Pulumi project metadata.
It defines the project name, runtime environment, and optional description.
This file is essential for Pulumi CLI to run and manage infrastructure deployments.
The file interacts closely with Pulumi runtime, stacks, state management, and infrastructure code.
It is a simple but critical part of the Pulumi project structure.

This file forms the foundational metadata layer that supports the broader infrastructure-as-code workflows in a Pulumi Node.js project.