Skip to content
Tutorials Center
My learning

Topics

Lesson 15 of 36 ยท Config and Secrets

Pulumi Config Basics: pulumi config and the Config Object

Learn Pulumi configuration: set and read values with pulumi config, key namespaces, typed getters in TypeScript, Python and Go, defaults, structured values and validation.

Configuration is how one program behaves differently in dev and prod: instance sizes, domain names, feature flags, regions. Pulumi stores configuration per stack, in Pulumi.<stack>.yaml, and gives your program typed accessors. This lesson covers the CLI, the key format, reading values and checking them.

Setting values with the CLI

Terminal
pulumi config set instanceCount 3
pulumi config set domain app.example.com
pulumi config set enableBackups true
pulumi config set aws:region eu-west-1

These write into the current stack's file:

YAML
config:
  aws:region: eu-west-1
  web-platform:domain: app.example.com
  web-platform:enableBackups: "true"
  web-platform:instanceCount: "3"

Notice two things. Keys are namespaced: a bare domain becomes <project name>:domain, while aws:region stays in the aws namespace and configures the AWS provider (Providers). And values are stored as strings; typing happens when you read them.

More commands:

Terminal
pulumi config                       # list all values of the current stack
pulumi config get domain            # one value
pulumi config rm instanceCount      # remove
pulumi config set -s prod domain app.example.com   # another stack
pulumi config set --path 'tags.team' web           # nested path
pulumi config set-all --path -p a.b=1 -p a.c=2     # several at once
pulumi config refresh               # restore a deleted file from the backend

Reading config in a program

Create a Config object for your project's namespace and read typed values:

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

const config = new pulumi.Config();

const domain   = config.require("domain");               // string, fails if missing
const count    = config.getNumber("instanceCount") ?? 1; // number or undefined
const backups  = config.getBoolean("enableBackups");     // boolean or undefined
const size     = config.get("size") ?? "small";          // string or undefined

Python:

Python
config = pulumi.Config()
domain = config.require("domain")
count = config.get_int("instanceCount") or 1
backups = config.get_bool("enableBackups")

Go:

Go
cfg := config.New(ctx, "")
domain := cfg.Require("domain")
count := cfg.GetInt("instanceCount")
Method Behaviour
require(key) Error if missing: use for mandatory settings
get(key) Returns undefined / None when missing
requireNumber, getNumber (require_int, get_int) Parses numbers, error if not numeric
requireBoolean, getBoolean Parses true / false
requireObject, getObject Parses structured (JSON) values
requireSecret, getSecret Marks the value secret (Secrets in Config)

To read another namespace pass its name: new pulumi.Config("aws") then .require("region").

Structured values

Set JSON with --path or write YAML by hand:

YAML
config:
  web-platform:subnets:
    - 10.0.1.0/24
    - 10.0.2.0/24
  web-platform:limits:
    cpu: 2
    memory: 4096
TypeScript
const subnets = config.requireObject<string[]>("subnets");
const limits = config.requireObject<{ cpu: number; memory: number }>("limits");

Declaring config in Pulumi.yaml

The project file can declare a schema: type, default and description. Pulumi then validates types and supplies defaults before your program runs.

YAML
name: web-platform
runtime: nodejs
config:
  instanceCount:
    type: integer
    default: 1
    description: Number of web servers
  domain:
    type: string
  enableBackups:
    type: boolean
    default: false

Declared types are string, integer, boolean and array (with items). Declared keys without a default must be set, so a missing value fails early with a clear message.

Validating inside the program

Fail fast with clear errors:

TypeScript
const count = config.requireNumber("instanceCount");
if (count < 1 || count > 10) {
  throw new Error(`instanceCount must be between 1 and 10, got ${count}`);
}

Environment variables and files

Config is not read from environment variables by default. Some providers read their own variables (AWS_REGION), and you can read process.env in your program, but config keys are the clean way because they are recorded per stack and reviewable. A CI job can set values with pulumi config set before pulumi up, or use ESC (ESC Environments).

Stand-in: typed getters

This stand-in reproduces how require, get, getNumber and getBoolean behave on string values.

JS Stand-in: a Config object

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

No output.

Stand-in: schema defaults and validation

JS Stand-in: config schema from Pulumi.yaml

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. In which file does pulumi config set store values for the prod stack?

    Each stack has its own Pulumi.<stack>.yaml.
  2. 2. What type does Pulumi use to store config values in the file?

    Typed getters such as getNumber parse the string.
  3. 3. Which method fails if the key is not set?

    require throws a clear error for missing mandatory settings.
  4. 4. How do you read the AWS region key inside a program?

    Use a Config object for the aws namespace.

Summary

  • pulumi config set key value writes to the current stack's file; keys are namespaced by project or provider.
  • Values are stored as strings; use require, get, getNumber, getBoolean, getObject to read them typed.
  • Declare config in Pulumi.yaml for types, defaults and required keys.
  • Validate early and fail with clear errors.

Next: Secrets in Config and Outputs