Skip to content
Tutorials Center
My learning

Topics

Lesson 3 of 36 ยท Getting Started

Project Layout: Pulumi.yaml, Stack Files and Entry Points

Understand the Pulumi project layout: Pulumi.yaml fields, runtime options, stack configuration files, entry points in each language, .gitignore and how to organise a repository.

A Pulumi project is a folder with a Pulumi.yaml file. Everything the CLI needs to know about how to run your program lives there, plus one small settings file per stack. This lesson explains each file and shows common layouts, including repositories with many projects.

Pulumi.yaml in detail

The minimal file has a name and a runtime:

YAML
name: web-platform
runtime: nodejs

A fuller example:

YAML
name: web-platform
description: Static site, CDN and DNS for the marketing website
runtime:
  name: python
  options:
    toolchain: pip
    virtualenv: venv
main: infra/
config:
  aws:region:
    value: eu-central-1
  siteName:
    type: string
    default: demo
backend:
  url: s3://acme-pulumi-state

The fields you will meet most often:

Field Meaning
name Project name; part of every resource's identity (the URN), so rename carefully
runtime nodejs, python, go, dotnet, java or yaml, optionally with options
description Free text shown in Pulumi Cloud
main Folder or file where the program starts, relative to the project folder
config Declares configuration keys with a type and default (read in later chapters)
backend Pins the state backend URL for this project
stackConfigDir Folder for Pulumi.<stack>.yaml files instead of the project root

Stack files

Each stack gets its own Pulumi.<stack>.yaml:

YAML
# Pulumi.prod.yaml
encryptionsalt: v1:...        # present on non-Cloud backends
config:
  aws:region: eu-central-1
  web-platform:siteName: acme
  web-platform:dbPassword:
    secure: AAABAB...          # encrypted value

A key that starts with the provider or project namespace, such as aws:region or web-platform:siteName, belongs to that namespace. Secrets appear as secure: blobs and are safe to commit. You rarely edit this file by hand; pulumi config set does it for you (Config Basics).

Entry points by language

The engine starts your program from a conventional place:

Runtime Default entry Notes
nodejs index.ts or index.js (from package.json main) TypeScript compiled by ts-node or tsc
python __main__.py A virtualenv is created and used
go main.go func main() { pulumi.Run(...) }
dotnet Program.cs await Deployment.RunAsync(...)
java App.java Pulumi.run(...)
yaml Pulumi.yaml itself resources are declared under resources:

A Go program is wrapped like this:

Go
package main

import (
  "github.com/pulumi/pulumi-aws/sdk/v6/go/aws/s3"
  "github.com/pulumi/pulumi/sdk/v3/go/pulumi"
)

func main() {
  pulumi.Run(func(ctx *pulumi.Context) error {
    bucket, err := s3.NewBucketV2(ctx, "assets", nil)
    if err != nil {
      return err
    }
    ctx.Export("bucketName", bucket.ID())
    return nil
  })
}

And the YAML runtime needs no other file at all:

YAML
name: tiny
runtime: yaml
resources:
  assets:
    type: aws:s3:BucketV2
outputs:
  bucketName: ${assets.id}

What to commit and what to ignore

Commit: Pulumi.yaml, every Pulumi.<stack>.yaml, your program, the lock file (package-lock.json, requirements.txt with pins, go.sum).

Ignore: node_modules/, venv/, bin/, obj/, compiled output. The generated .gitignore already covers this. Never commit passphrases or access tokens.

One project or many?

Pulumi has no rule, but patterns emerge:

  • Monolithic: one project, one program, several stacks (dev, prod). Good for a single application.
  • Micro-stacks: separate projects such as network, database, app. Each deploys on its own and shares data through stack outputs (Stack Outputs and References). Good when teams or change rates differ.
flowchart TD
  R["repo/"] --> N["network/<br/>Pulumi.yaml"]
  R --> D["database/<br/>Pulumi.yaml"]
  R --> A["app/<br/>Pulumi.yaml"]
  N --> N1["stack: dev"]
  N --> N2["stack: prod"]
  A --> A1["stack: dev"]
  A --> A2["stack: prod"]

Each folder is a project; each project has its own stacks and state.

Stand-in: validating project names

The CLI rejects project names with unsupported characters. This stand-in applies the same idea.

JS Stand-in: validate a project name

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Stand-in: choose the entry file

JS Stand-in: pick the entry point

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which two fields are the minimum in Pulumi.yaml?

    name and runtime are required; everything else is optional.
  2. 2. Where does the configuration of the prod stack live?

    Every stack has its own Pulumi.<stack>.yaml file.
  3. 3. Why is it safe to commit secure: values in a stack file?

    Secrets are stored as ciphertext, so the file can be reviewed and versioned.
  4. 4. What is a good reason to split infrastructure into several projects?

    Separate projects give separate state and release cadence, connected by outputs.

Summary

  • Pulumi.yaml defines the project: name, runtime, optional main, config schema and backend.
  • Each stack has Pulumi.<stack>.yaml with its configuration; secrets are encrypted there.
  • Each language has a conventional entry point; YAML programs live inside Pulumi.yaml.
  • Commit project and stack files, ignore dependencies and build output.
  • Choose one project with several stacks, or several smaller projects linked by outputs.

Next: pulumi up, preview, refresh and destroy