Skip to content
Tutorials Center
My learning

Topics

Lesson 16 of 36 ยท Config and Secrets

Pulumi Secrets in Config and Outputs: Encryption Explained

Store passwords and tokens safely with pulumi config set --secret, learn how secrets are encrypted in state, how they propagate through Outputs, and how to change the secrets provider.

Infrastructure needs credentials: database passwords, API tokens, private keys. Hard-coding them in source is a security incident waiting to happen. Pulumi treats secrets as a first-class kind of value: encrypted in config, encrypted in state, masked in output, and tracked as they flow through your program.

Pulumi's encryption runs in the CLI and backend, not on this site. Real commands and code are read-only; the stand-ins use a toy cipher purely to show the flow (never use it for real secrets).

Setting a secret

Terminal
pulumi config set --secret dbPassword 'S3cr3t!pass'

The stack file now contains ciphertext, not the password:

YAML
config:
  web-platform:dbPassword:
    secure: AAABADx3...long-base64...

You can commit this file. Anyone with access to the stack's secrets provider (a key or passphrase) can decrypt it; everyone else sees only the blob. Show the plain text with pulumi config get dbPassword (secrets are printed on get) or pulumi config --show-secrets; the plain pulumi config list shows [secret].

Typing a password on the command line leaves it in your shell history. Pipe it instead, or enter it interactively:

Terminal
pulumi config set --secret dbPassword          # prompts, input hidden
echo -n "$DB_PASS" | pulumi config set --secret dbPassword

Reading secrets in a program

TypeScript
const config = new pulumi.Config();
const dbPassword = config.requireSecret("dbPassword");   // Output<string>, marked secret

const db = new aws.rds.Instance("db", {
  engine: "postgres",
  instanceClass: "db.t4g.micro",
  allocatedStorage: 20,
  username: "app",
  password: dbPassword,          // stays secret in state and in the console
});

require("dbPassword") on a secret key returns the plain string, but Pulumi marks values derived from require calls on secret keys as secret too in recent SDKs, so prefer requireSecret, which makes the intent clear.

Secret outputs and propagation

A secret value stays secret as it flows:

TypeScript
const url = pulumi.interpolate`postgres://app:${dbPassword}@${db.endpoint}/app`;   // secret
const upper = dbPassword.apply(p => p.toUpperCase());                               // secret
export const connectionString = url;      // shown as [secret] in the CLI and Pulumi Cloud

Rules:

  • If any input to apply, all or interpolate is secret, the result is secret.
  • Resource properties marked sensitive by the provider (such as an RDS password) are stored encrypted in state.
  • You can mark a value yourself with pulumi.secret(value); additionalSecretOutputs: ["password"] as a resource option marks outputs of a resource as secret.
TypeScript
const key = new tls.PrivateKey("key", { algorithm: "RSA", rsaBits: 4096 });
export const privateKey = pulumi.secret(key.privateKeyPem);

To read a secret output from the CLI use pulumi stack output privateKey --show-secrets.

How encryption works: secrets providers

Each stack has a secrets provider that encrypts and decrypts:

Provider Where the key is Typical use
Pulumi Cloud (default for the service) managed by Pulumi Cloud teams using the hosted backend
passphrase a passphrase you supply via PULUMI_CONFIG_PASSPHRASE or a file default for local/self-managed backends
awskms://, azurekeyvault://, gcpkms:// a cloud KMS key self-managed state with cloud IAM access control
hashivault:// HashiCorp Vault transit key Vault shops

Choose it when creating a stack, or change it later:

Terminal
pulumi stack init prod --secrets-provider="awskms://alias/pulumi-prod?region=eu-west-1"
pulumi stack change-secrets-provider "awskms://alias/pulumi-prod?region=eu-west-1"

Changing the provider re-encrypts config and state. Back up the old key until you have verified the new one works. Lose the passphrase and the secrets are gone.

What is and is not protected

Protected: config values set with --secret, secret-marked outputs in state, display in the CLI and console.

Not protected:

  • Anything you print with console.log or log from apply.
  • Plain config values (config set without --secret): readable by everyone with repo access.
  • The resource itself: if the password is also visible in the cloud console or logs, Pulumi cannot hide it.
  • A decrypted state export (pulumi stack export --show-secrets).

Treat state access like secret access: restrict who can read the backend and who can run --show-secrets.

Rotating a secret

Terminal
pulumi config set --secret dbPassword 'N3w!pass'
pulumi up

The preview shows the dependent resources changing, with the password diff masked as [secret].

Stand-in: secrets are tracked, then masked

This stand-in marks values as secret, propagates the flag through a derived string, and masks it when "printing" a stack's outputs. The cipher is a toy and only simulates the flow.

JS Stand-in: secret propagation and masking

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

No output.

Stand-in: what a stack file would contain

JS Stand-in: toy encryption for the stack file

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. How do you store a database password in stack config safely?

    --secret stores ciphertext (secure:) in the stack file.
  2. 2. If one input to pulumi.interpolate is secret, the result is...

    Secretness propagates through apply, all and interpolate.
  3. 3. What happens if you lose the passphrase of a passphrase-based stack?

    Back up the passphrase or use a KMS-based provider.
  4. 4. Which is NOT protected by Pulumi's secret handling?

    Output you print yourself is not masked.

Summary

  • pulumi config set --secret stores encrypted values; read them with requireSecret.
  • Secrets propagate through Outputs and are encrypted in state and masked in the CLI.
  • The secrets provider (Pulumi Cloud, passphrase, cloud KMS, Vault) holds the key; protect and back it up.
  • Do not log secrets and restrict who can read state or use --show-secrets.
  • Rotate by setting a new value and running pulumi up.

Next: Config per Environment