Projects

A Pulumi project is any folder that contains a Pulumi.yaml project file. At runtime, the nearest parent folder containing a Pulumi.yaml file determines the current project. Projects are created with the pulumi new command.

The project file (Pulumi.yaml)

The project file specifies which runtime to use and determines where to look for the program that should be executed during deployments. Supported runtimes are nodejs, python, dotnet, go, java, and yaml.

Project files also contain metadata about your project. The project file must begin with a capital P, although either .yml or .yaml extension will work.

A typical Pulumi.yaml file looks like the following:

name: webserver
runtime: nodejs
description: A minimal JavaScript Pulumi program.

In addition, when using JavaScript or TypeScript, the working directory for the project should contain a package.json file that points to an entrypoint such as index.js. In Python, the presence of a __main__.py or setup.py file defines the entrypoint.

The following are other examples of Pulumi.yaml files that define project configurations for other use cases:

• A Pulumi.yaml file for a Node.js program that uses JavaScript rather than TypeScript:

  name: my-project
  runtime:
    name: nodejs
    options:
      typescript: false
  

• A Pulumi.yaml file for a Go program that uses a pre-built executable named mybinary:

  name: my-project
  description: A precompiled Go Pulumi program.
  runtime:
    name: go
    options:
      binary: mybinary
  

• A Pulumi.yaml file for a .NET program that uses a pre-built assembly named MyInfra.dll in the bin directory:

  name: my-project
  description: A precompiled .NET Pulumi program.
  runtime:
    name: dotnet
    options:
      binary: bin/MyInfra.dll
  

• A Pulumi.yaml file for a Java program that uses a pre-built JAR file:

  name: my-project
  description: A precompiled Java Pulumi program.
  runtime:
      name: java
      options:
          binary: target/my-project-1.0-SNAPSHOT-jar-with-dependencies.jar
  

• A Pulumi.yaml file for a YAML program that includes its resources inline:

  name: my-project
  runtime: yaml
  resources:
    bucket:
      type: aws:s3:Bucket
  

For more information on valid Pulumi project metadata, see the Pulumi.yaml reference.

Project-relative paths

When your Pulumi program refers to resources in the local filesystem, paths are always relative to the working directory. In the following example, the aws.ecr.Image resource refers to a subfolder of the working directory named app that contains a Dockerfile:

"use strict";
const pulumi = require("@pulumi/pulumi");
const awsx = require("@pulumi/awsx");

const repository = new awsx.ecr.Repository("repository", {
    forceDelete: true,
});

const image = new awsx.ecr.Image("image", {
    repositoryUrl: repository.url,
    context: "./app",
    platform: "linux/amd64",
});

exports.url = repository.url;

import * as pulumi from "@pulumi/pulumi";
import * as awsx from "@pulumi/awsx";

const repository = new awsx.ecr.Repository("repository", {
    forceDelete: true,
});

const image = new awsx.ecr.Image("image", {
    repositoryUrl: repository.url,
    context: "./app",
    platform: "linux/amd64",
});

export const url = repository.url;

import pulumi
import pulumi_awsx as awsx

repository = awsx.ecr.Repository("repository", force_delete=True)

image = awsx.ecr.Image(
    "image",
    repository_url=repository.url,
    context="./app",
    platform="linux/amd64",
)

pulumi.export("url", repository.url)

package main

import (
	"github.com/pulumi/pulumi-awsx/sdk/v2/go/awsx/ecr"
	"github.com/pulumi/pulumi/sdk/v3/go/pulumi"
)

func main() {
	pulumi.Run(func(ctx *pulumi.Context) error {
		repository, err := ecr.NewRepository(ctx, "repository", &ecr.RepositoryArgs{
			ForceDelete: pulumi.Bool(true),
		})
		if err != nil {
			return err
		}

		_, err = ecr.NewImage(ctx, "image", &ecr.ImageArgs{
			RepositoryUrl: repository.Url,
			Context:       pulumi.String("./app"),
			Platform:      pulumi.String("linux/amd64"),
		})
		if err != nil {
			return err
		}

		ctx.Export("url", repository.Url)
		return nil
	})
}

using System.Collections.Generic;
using Pulumi;
using Awsx = Pulumi.Awsx;

return await Deployment.RunAsync(() =>
{
    var repository = new Awsx.Ecr.Repository("repository", new()
    {
        ForceDelete = true,
    });

    var image = new Awsx.Ecr.Image("image", new()
    {
        RepositoryUrl = repository.Url,
        Context = "./app",
        Platform = "linux/amd64",
    });

    return new Dictionary<string, object?>
    {
        ["url"] = repository.Url,
    };
});

package myproject;

import com.pulumi.Context;
import com.pulumi.Pulumi;
import com.pulumi.awsx.ecr.Repository;
import com.pulumi.awsx.ecr.RepositoryArgs;
import com.pulumi.awsx.ecr.Image;
import com.pulumi.awsx.ecr.ImageArgs;

public class App {
    public static void main(String[] args) {
        Pulumi.run(App::stack);
    }

    public static void stack(Context ctx) {
        var repository = new Repository("repository", RepositoryArgs.builder()
            .forceDelete(true)
            .build());

        var image = new Image("image", ImageArgs.builder()
            .repositoryUrl(repository.url())
            .context("./app")
            .platform("linux/amd64")
            .build());

        ctx.export("url", repository.url());
    }
}

name: awsx-ecr-image-yaml
runtime: yaml

resources:
  repository:
    type: awsx:ecr:Repository
    properties:
      forceDelete: true

image:
  type: awsx:ecr:Image
  properties:
    repositoryUrl: ${repository.url}
    context: "./app"
    platform: "linux/amd64"

outputs:
  url: ${repository.url}

Getting the current project programmatically

The getProject getProject get_project context.Project Deployment.Instance.ProjectName context.projectName() pulumi.project function returns the name of the currently deploying project. This can be useful for naming or tagging resources.

const project = pulumi.getProject();

const project = pulumi.getProject();

project = pulumi.get_project()

project := ctx.Project()

var project = Deployment.Instance.ProjectName;

var project = ctx.projectName();

variables:
  project: ${pulumi.project}

Stack settings files

Each stack that is created in a project will have a file named Pulumi.<stackname>.yaml that contains the configuration specific to this stack. This file typically resides in the root of the project directory.

For stacks that are actively developed by multiple members of a team, the recommended practice is to check them into source control as a means of collaboration. Since secret values are encrypted, it is safe to check in these stack settings. When using ephemeral stacks, the stack settings are typically not checked into source control.

For more information about configuration and how to manage these files on the command line and programmatically, refer to the Configuration and Secrets documentation.