Pulumi Security: Protect State, Secrets Providers and ESC Environments

Pulumi state records every resource your programs manage, and the secrets inside it are only as safe as the encryption provider, the backend and the people who can read the stack. Pulumi lets teams write infrastructure in general purpose languages, store state in Pulumi Cloud or a self-managed backend, and centralise secrets and short-lived cloud credentials in Pulumi ESC (Environments, Secrets, and Configuration). Each of those layers has customer-side settings that decide who can decrypt what. This guide covers how to choose and configure a secrets provider, how to secure Pulumi Cloud and DIY state backends, how to design ESC environments and their permissions, how to replace static cloud keys with OIDC login, and how to enforce guardrails with Pulumi Policies. It is written for platform engineers and cloud security teams. This page focuses on building the controls before anything goes wrong.

This is an independent guide from NHI Mgmt Group, based on Pulumi's public documentation as of November 2026. It is not sponsored or reviewed by Pulumi. Product features change, so confirm settings against Pulumi's current documentation.

Key takeaways

• Stack Read includes decrypt. Pulumi's Stack Read permission set carries the stack:decrypt scope, and for Pulumi Cloud stacks decryption keys are supplied automatically to readers, so treat read access to a production stack as secret access.
• Pick the secrets provider at stack creation. Pulumi Cloud encrypts with a per-stack key by default; awskms, azurekeyvault, gcpkms and hashivault let you hold the key yourself, and passphrase suits local or DIY use with a strong, managed passphrase.
• A DIY backend makes you the platform. With S3, Azure Blob, Google Cloud Storage, PostgreSQL or file backends you own access control, encryption at rest, auditing and backups for the .pulumi folder.
• Environment Open is the privileged ESC right. Environment Read shows definitions, but Environment Open resolves secrets and mints cloud credentials, so grant it per environment, per consumer.
• Prefer OIDC login over stored keys. The aws-login, azure-login and gcp-login providers exchange Pulumi's OIDC token for short-lived cloud credentials, so ESC environments need not hold long-lived access keys.

How identity and access work in Pulumi

Three separate trust relationships sit behind every pulumi up: the identity that talks to the state backend, the cloud credentials the providers use, and the key that encrypts secrets in state. Pulumi documents that state does not include your cloud credentials; they stay on the machine where the CLI runs, even with Pulumi Cloud.

How secrets are marked and encrypted

A value is encrypted in state when it is marked secret. Use pulumi config set --secret for configuration (pulumi config then displays [secret]), getSecret or requireSecret when reading configuration in code, pulumi.secret() or the language equivalent to wrap a computed value, and the additionalSecretOutputs resource option to keep a resource's outputs encrypted wherever they flow. Combining a secret with apply or Output.all produces a secret output. Three behaviours from Pulumi's documentation shape your design:

• Resource IDs are plain text: adding id to additionalSecretOutputs has no effect. Pulumi recommends random.RandomPassword with additionalSecretOutputs: ["result"] instead of random.RandomString, whose value is its ID.
• apply callbacks receive plain text: Pulumi cannot stop code inside a callback from printing or saving the value, so review apply blocks in code review.
• Stack config files are safe to commit: Pulumi.<stack>.yaml holds ciphertext under secure keys, plus encryptionsalt for passphrase stacks or encryptedkey for KMS providers. The risk is values that were never marked secret.

Admin roles and privileged access

Pulumi Cloud RBAC combines permission sets with entity access over stacks and ESC environments. Pulumi's RBAC documentation lists the built-in organisation roles (Reader, Builder, Maintainer, Admin and Billing Manager) in all editions, with custom roles and teams on the Pro and Enterprise editions; the permission sets below are what decide secret exposure.

• Separate read from decrypt by design: publish values other teams need as stack outputs that are not secret, or through StackReference to outputs, rather than giving them Stack Read on a stack full of secrets.
• Treat environment edits as production changes: Pulumi ESC lists Versioning, Approvals and Webhooks among its concepts; use version tags for promoted environments and require approval for production edits where your edition provides it.
• DIY backends: privileged access is whoever can write to the bucket or database and use the KMS key. Keep those groups as small as the Pulumi Cloud Stack Admin group would be.

Integrations, API tokens and service accounts

Choosing a secrets provider

Set the provider when you create the stack with pulumi stack init <name> --secrets-provider="<provider>://<settings>", and change it later with pulumi stack change-secrets-provider. Pulumi implements providers through the Go Cloud Development Kit.

With a KMS provider, decrypting a stack needs both access to state and permission on the key, which gives you a second, independently audited gate. NHI Mgmt Group recommends a KMS or Vault provider for any production stack on a DIY backend, with the encryption context parameters on awskms set to the project and environment so key policy can tell stacks apart.

Securing a DIY state backend

• Least privilege on S3: Pulumi documents exactly four actions for the full stack lifecycle: s3:ListBucket on the bucket ARN, and s3:GetObject, s3:PutObject and s3:DeleteObject on the objects. Scope them to the prefix for each project where you share a bucket.
• Azure Blob: the backend authenticates through the Azure SDK for Go; prefer identity-based sign-in (for example az login or a managed identity) with the Storage Blob Data Contributor role over a shared AZURE_STORAGE_KEY or AZURE_STORAGE_SAS_TOKEN.
• Google Cloud Storage: authenticate with Application Default Credentials from a workload identity rather than a key file.
• PostgreSQL: Pulumi advises against putting credentials in the postgres:// login command; supply them from the environment or a secrets manager.
• Protect history: the .pulumi folder holds stacks/, locks/, history/ and backups/. Old checkpoints contain old ciphertext, so retention, versioning and access rules apply to all of it, not just the current state file.
• Keep the backend current: backends that still use the pre-3.61.0 global namespace are deprecated; plan pulumi state upgrade, which is one-way.

Pulumi ESC environments

An ESC environment is a YAML document that can import other environments, hold values marked with fn::secret, pull secrets from external stores and issue short-lived credentials. Consumers use it from a stack's configuration or with pulumi env run.

• Login providers: aws-login, azure-login, gcp-login and gh-login issue short-lived credentials; an oidc provider mints a token other services can trust.
• Secrets providers: aws-secrets, aws-parameter-store, azure-secrets, gcp-secrets, vault-secrets and others read from the store of record at open time, so the secret is not copied into ESC.
• Rotators: aws-iam, azure-app-secret, mysql, postgres, password, snowflake-user and external rotate credentials on a schedule through fn::rotate.
• Imports: split environments into a base layer per account and thin per-application layers, so Environment Open on an application layer does not expose unrelated secrets.

OIDC instead of stored cloud keys

The aws-login provider supports an oidc block with roleArn, sessionName and an optional duration, and a static block with accessKeyId and secretAccessKey. Pulumi recommends OIDC. The IAM role trusts the federated principal api.pulumi.com/oidc with sts:AssumeRoleWithWebIdentity, an audience condition of aws:<your Pulumi org> and a subject condition that matches the environment. Optional policyArns narrow the session further. For the CI side, OIDC token exchange can give pipelines a short-lived Pulumi token instead of a stored PULUMI_ACCESS_TOKEN; see the CI/CD Pipeline Identity Security Guide and the GitHub Actions OIDC Federation Hardening Guide.

Logging and detection

• Pulumi Cloud audit logs: available on the Pro and Enterprise editions according to Pulumi's audit logs guide, with automated export (for example to Amazon S3 or Microsoft Sentinel) on Enterprise. Confirm the event types you need, such as decryption and stack export, in the audit log format reference and send them to your SIEM.
• KMS and Vault audit: with awskms, azurekeyvault, gcpkms or hashivault, every decrypt appears in CloudTrail, Azure Monitor, Cloud Audit Logs or the Vault audit device, which works for DIY backends too.
• Object storage logs: enable data access logging on the state bucket and alert on reads of stacks/ or history/ by identities other than the deployment roles.
• Cloud sign-ins from OIDC roles: AssumeRoleWithWebIdentity events for Pulumi roles, with session names that identify the environment.
• Policy findings: Pulumi Policies violations from preventative and audit policy groups.

Metrics that show it is working

1. Share of production stacks using a customer KMS or Vault provider, or Pulumi Cloud with Stack Read limited to named consumers.
2. Number of ESC environments holding static cloud keys (target: zero, replaced by login providers).
3. Number of principals with Environment Open on each production environment, reviewed quarterly.
4. Share of pipelines using OIDC token exchange rather than stored Pulumi tokens.
5. Mandatory policy violations blocked per month, and the time to fix advisory findings.

Hardening baseline

Rollout plan

1. Inventory: list stacks, their backend, their secrets provider (visible in stack config), and every principal with Stack Read and Environment Open.
2. Find plain-text secrets: search stack config files and exported state for credentials that were never marked secret, and fix them with config set --secret or additionalSecretOutputs.
3. Move providers: run pulumi stack change-secrets-provider to a KMS or Vault key on one non-production stack, confirm preview and up still work, then repeat for production. Roll back by changing the provider again; the old key must stay available until then.
4. Restructure ESC: replace static blocks with oidc login, split environments by import layer, and narrow Environment Open grants.
5. Enforce policy: start packs at advisory, review findings for two weeks, then move critical rules to mandatory.
6. Rotate: after any provider change or access clean-up, rotate the underlying secrets, because old ciphertext remains in history and backups.

Decision guidance

• Pulumi Cloud or DIY: Pulumi Cloud brings RBAC, audit logs, transactional checkpoints and ESC integration; a DIY backend suits teams that must keep state in their own accounts and are ready to run access, encryption, backup and audit themselves.
• Small teams: Pulumi Cloud with the default provider, tight Stack Read grants and OIDC for CI covers most needs.
• Regulated estates: a customer KMS provider gives key-level control and an independent decrypt log; Pulumi lists CIS, ISO 27001, NIST, PCI DSS and other framework policy packs on its Enterprise edition.

Common misconfigurations

• Organisation-wide Stack Read: a default role that lets every member read every stack also lets them decrypt every stack secret.
• Passphrase in the repository or CI log: the passphrase is committed next to the encryptionsalt, or echoed in a pipeline, which makes the encryption decorative.
• Secrets surfaced as IDs or unmarked outputs: a generated password exported as a plain output or produced by a resource whose ID is the secret.
• Public or broadly readable state bucket: a DIY bucket shared with many roles, including history and backups that hold earlier ciphertext and plain-text resource data.
• Static keys in ESC: environments using aws-login static blocks or long-lived keys under fn::secret where an OIDC role would work.
• One giant environment: every secret in a single ESC environment, so any consumer with Environment Open receives everything.

Framework mapping

Practitioner checklist

• Every production stack has a recorded backend, secrets provider and owner.
• Production stacks on DIY backends use awskms, azurekeyvault, gcpkms or hashivault.
• Stack Read on production stacks is limited to named people and pipelines that need the secrets.
• DIY state buckets grant only the documented actions, with encryption, versioning, access logging and no public access.
• Generated secrets use RandomPassword with additionalSecretOutputs, and apply callbacks never log values.
• ESC environments use oidc login blocks, external secrets providers and rotators instead of static keys.
• Environment Open is granted per environment and consumer, and reviewed quarterly.
• CI uses OIDC token exchange instead of stored Pulumi access tokens.
• Critical Pulumi Policies rules run at mandatory enforcement.
• Audit, KMS and storage logs reach the SIEM, with alerts on unexpected decrypts and exports.

Standards and references

• Pulumi: Secrets handling and encryption providers
• Pulumi: State and backends
• Pulumi: Using a DIY backend
• Pulumi: RBAC permission sets
• Pulumi: ESC documentation
• Pulumi: ESC aws-login provider
• Pulumi: Policies as code

Related NHI Mgmt Group resources: Infrastructure as Code Security Guide · IaC identity policy checks · Secrets Management Guide · Cloud Workload Identity Guide