Example stack README in Pulumi Cloud

This example lives in the pulumi/examples repository. Check out just this directory to use it:

$ git clone --filter=blob:none --sparse https://github.com/pulumi/examples pulumi-examples
$ git -C pulumi-examples sparse-checkout set stack-readme-py
$ cd pulumi-examples/stack-readme-py

This example shows how to set up a Stack README in Python.

Stack READMEs in Pulumi Cloud dynamically update based on Stack Outputs. Stack READMEs interpolate output variables on the stack (${outputs.instances[0].ARN}) so that each stack can construct links to dashboards, shell commands, and other pieces of documentation. All of this content stays up to date as you stand up new stacks, rename resources, and refactor your infrastructure.

To set a Stack README, simply set a Stack Output named readme to the value of your templated Stack README file. In this example, we’ve called the file Pulumi.README.md.

Example project structure#

./__main__.py

import pulumi

pulumi.export('strVar', 'foo')
pulumi.export('arrVar', ['fizz', 'buzz'])

# open template readme and read contents into stack output
with open('./Pulumi.README.md') as f:
    pulumi.export('readme', f.read())

./Pulumi.README.md

# Stack README

Full markdown support! Substitute stack outputs dynamically so that links can depend on your infrastructure! Link to dashboards, logs, metrics, and more.

1. Reference a string stack output: ${outputs.strVar}
2. Reference an array stack output: ${outputs.arrVar[1]}

Prerequisites#

1. Install Pulumi
2. Install Python

Deploying the example#

1. Create a new stack:

   pulumi stack init dev

2. Install dependencies:

   python3 -m venv venv
   source venv/bin/activate
   pip install -r requirements.txt

3. Deploy the stack:

   pulumi up

Viewing the rendered stack README#

Open the stack in the Pulumi Cloud console:

pulumi console

Then click the README tab to see the rendered Stack README with your stack outputs interpolated.

Cleaning up#

Once you’re finished experimenting, you can destroy your stack and remove it:

pulumi destroy
pulumi stack rm