Pulumi Blog: Davide Massarenti

Pulumi IAM Expands: Manage Access at Scale with Tags, Roles, and Teams

Devon Grove — Thu, 19 Mar 2026 10:30:00 -0700

Since the launch of Pulumi IAM with custom roles and scoped access tokens, organizations have been using fine-grained permissions to secure their automation and CI/CD pipelines. As teams scale to hundreds or thousands of stacks, environments, and accounts, the next challenge is applying those permissions efficiently.

Today, we’re introducing three new capabilities to help you manage permissions more dynamically at scale: tag-based access control, team role assignments, and user role assignments.

Why tag-based access control?

With custom roles, you can define granular permissions using fine-grained scopes. However, applying those roles still requires selecting individual stacks, environments, or accounts one by one. For organizations managing a large number of Pulumi entities, this means either granting overly broad access or spending significant time on manual configuration. Tag-based access control solves this problem.

What’s new?

Tag-based access control

You can now create rules within a custom role that dynamically grant permissions based on entity tags. This works across IaC stacks, ESC environments, and Insights accounts. For example, when a new stack is created and tagged env:prod, anyone with a role containing a matching tag-based rule automatically gets the right permissions. No manual assignment required.

A single role can include multiple tag-based rules, and they are evaluated with OR logic. If an entity matches any of the rules, the permissions are granted. Within a single rule, you can combine multiple key-value conditions with implicit AND logic for precise targeting. For example, a rule with conditions env:prod and team:payments ensures access is granted only to production resources owned by the payments team.

Team role assignments

Custom roles can now be assigned directly to teams within your Pulumi organization. When an engineer joins a team, whether manually or via SCIM provisioning, they automatically inherit the permissions defined in the team’s assigned roles.

Teams support both inline permissions (ad-hoc access to specific stacks, environments, or accounts) and role-based permissions simultaneously. You can assign multiple roles to a single team, giving you full flexibility to compose access from reusable building blocks while retaining the ability to grant one-off access where needed. If you have existing workflows built around ad-hoc assignments to teams, those continue to work exactly as before. You can adopt roles incrementally or mix both approaches on the same team.

Team admins (or users with the team:update scope) can continue to manage their team’s inline permissions as they do today. However, assigning organization-level custom roles to a team requires additional permissions: role:read and role:update.

User role assignments

Custom roles can also be assigned directly to individual organization members. This is useful for users whose responsibilities span multiple teams or require permissions beyond the existing org-level Admin, Member, and Billing Manager roles.

How permissions work together

Permissions in Pulumi IAM are additive. A user receives the union of all permissions granted to them, including permissions from roles assigned directly to them as a user and permissions from roles assigned to any team they belong to. A user on both the “SRE” and “Security” teams inherits permissions from both team roles, plus any role assigned to them individually.

How to get started

Configuring tag-based access control and role assignments is done through the Pulumi Cloud console and REST API.

1. Create a custom role with tag-based rules

In Pulumi Cloud, navigate to Settings > Access Management > Roles and create a new custom role. In the role configuration, add tag-based rules that define which entities the role should apply to.

For example, to create a role that grants write access to all production stacks:

Click Create custom role and give it a descriptive name (e.g., “Production Deployer”)
Add a permission set (e.g., Stack Write) to the role
Under entity selection, choose Tag-based rule
Set the condition: tag key env equals prod
Save the role

2. Assign the role to a team

Go to Settings > Access Management > Teams, select a team, and assign your custom role. All team members immediately inherit the defined permissions.

3. Assign a role to an individual user

For users with unique access requirements, go to Settings > Access Management > Members, select a user, and assign a custom role directly.

Enforce tagging standards with Pulumi Policy

Tag-based access control relies on consistent tagging. If a stack is missing a tag or has an incorrect value, permissions won’t be applied as expected. Pulumi Policy closes this gap by letting you enforce tagging standards as a preventative policy group, so any pulumi up on a stack with missing or invalid tags is blocked before deployment. This ensures your tag-based RBAC rules always grant the correct permissions. Policy enforces the standard, RBAC enforces the access.

To learn how to write policies that validate stack tags, see Using stack tags in policies.

Pulumi Policy currently supports tag enforcement for IaC stacks. For ESC environments and Insights accounts, tags are managed through the Pulumi Cloud console or REST API.

Availability

Tag-based access control, team role assignments, and user role assignments are available today for customers on the Pulumi Enterprise and Pulumi Business Critical plans. Check out our pricing page for more details on editions and what’s included.

Conclusion

With custom roles providing fine-grained permissions, tag-based rules enabling dynamic access policies, and the ability to assign roles directly to teams and users, Pulumi IAM now provides everything you need to implement automated, least-privilege access control at scale. We’re excited to see how you leverage these new capabilities to secure and streamline your cloud operations.

Explore the IAM documentation to get started, and share your feedback in our GitHub repository.

Learn more

How We Built a Distributed Work Scheduling System for Pulumi Cloud

Levi Blackstone — Thu, 26 Feb 2026 00:00:00 +0000

Pulumi Cloud orchestrates a growing number of workflow types: Deployments, Insights discovery scans, and policy evaluations. Some of that work runs on Pulumi’s infrastructure, and some of it runs on yours via customer-managed workflow runners. We needed a scheduling system that could handle all of these workflow types reliably across both environments. In this post, we’ll take a look at the system we built.

Where we started

For our first workflow integration, Deployments, scheduling wasn’t too complicated. A deployment was queued, a worker picked it up, and it ran. The queue was purpose-built for deployments, and it worked well for that single use case. Over time, we added more sophisticated logic to handle retries, ordering, rate limiting, observability, and more.

With the launch of Insights, the number of workflow types grew. Now Pulumi Cloud manages discovery scans to catalog cloud resources and runs audit policy evaluations to continuously verify compliance. While these workflows share similarities, each type needed its own scheduling, retry logic, and failure handling.

Later we added the option for customers to run workflows on their own infrastructure using customer-managed workflow runners. As the complexity of these requirements grew, we knew that our initial approach for Deployments wasn’t going to scale. We needed a single system that could schedule any type of work, route it to the right place, and handle the messy reality of distributed execution: crashes, network failures, rate limits, and retries.

We call this the background activity system.

Why not use an off-the-shelf queue?

Why build this instead of using Amazon SQS, RabbitMQ, or one of the many existing queue libraries? We considered these options but chose to build our own for a few reasons.

Pulumi Cloud supports self-hosted installations, including air-gapped environments. We intentionally minimize external dependencies so that self-hosted customers don’t have to stand up additional infrastructure. A system built on an external queue works fine for our hosted service, but it means self-hosted customers would need to provide a compatible backend. By building on top of the database we already require, we avoid adding another system to maintain.

More importantly, queueing is only part of the problem. What we actually need is scheduling with durability. This means ensuring that remote workers don’t lose activities on restart, priority so that urgent work gets compute resources first, constraints like “only so many scans per org at a time,” structured logging for observability, and checkpointing so that long-running operations can resume after a failure.

These features can be layered onto a generic queue library but can require more code than implementing them directly. For example, priority queues are often implemented with multiple ranked queues, but this breaks single-activity-at-a-time constraints. A second queue wouldn’t see a job already running in the first one. There’s no way for producers in a distributed system to coordinate across the queues without support in the queuing system itself.

Capacity management is another area where generic queues fall short. Distributed systems need to respond dynamically to slowdowns, network interruptions, and rate limits from downstream services. These are common low-level details that every workflow type needs, and building them into the scheduling layer means individual handlers don’t have to solve them independently.

We also need structured logging that works everywhere, including on customer-managed runners behind firewalls where centralized logging services aren’t accessible.

Building this ourselves gave us a system that works with existing infrastructure and handles these requirements natively.

Design constraints

With that context, here are some of the constraints that shaped the design:

Pull-only agents. Customer-managed workflow runners live behind NATs, corporate proxies, and air-gapped networks. They can’t accept inbound connections, so all communication has to be agent-initiated.
Mixed execution environments. The same system needs to work for Pulumi-hosted workers (with direct access to internal systems) and customer-managed runners (communicating entirely over REST). We didn’t want to maintain two separate code paths.
Different workflow types. Deployments, Insights scans, and audit policy evaluations have different payloads and execution semantics, but they all need the same scheduling guarantees: exactly-once execution, automatic retries, failure recovery, and observability.
Automatic fault tolerance. Agents crash, networks drop, and machines get recycled by autoscalers. The system needs to detect these failures and recover without needing a person to step in.
Extensibility. We knew we’d keep adding workflow types. Adding a new one should mean writing a handler and registering it, not building new infrastructure.

The background activity

At the center of the system is the background activity, a persistent, typed work unit. Each activity includes:

A type discriminator that identifies what kind of work it represents (e.g., “insights-discovery” or “policy-evaluation”)
A payload specific to that type, containing whatever data the handler needs
A routing context that determines which runner pool should execute it
Scheduling metadata like priority, activation time, and retry configuration
A status tracking where the activity is in its lifecycle

The type discriminator makes this system polymorphic. The scheduling engine doesn’t need to know what’s inside the payload. It moves activities through their lifecycle and delegates the actual work to a type-specific handler.

The state machine

Every activity follows the same lifecycle regardless of type:

---
config:
flowchart:
curve: linear
---
graph LR
Start(( )) -->|Created| Ready
Ready -->|Leased| Pending
Pending -->|Started| Executing
Executing -->|Success| Completed
Completed --> End(( ))
Executing -->|Error| Failed
Failed --> End
Executing -->|Canceled| Canceled
Canceled --> End
Executing -->|Dependencies| Waiting
Waiting -->|Unblocked| Ready
Pending -->|Lease expired| Restarting
Executing -->|Lease expired| Restarting
Restarting -->|Re-lease| Ready
style Start fill:#000,stroke:#000,color:#000
style End fill:#000,stroke:#000,color:#000

The states fall into two groups:

Running states (work is in flight or can be resumed):

Ready: queued and eligible to be claimed by a worker
Pending: claimed by a worker, execution about to start
Executing: actively running on a worker
Waiting: parked, blocked on one or more dependency activities
Restarting: recovered after a worker failure, ready to be re-claimed

Terminal states (work is done):

Completed, Failed, Canceled

New workflow types get these features automatically: scheduling, retries, dependency management, and observability.

Leases: distributed execution without coordination

A central challenge of any distributed work queue is preventing double-execution. If two agents try to execute the same activity simultaneously, you get duplicate work and data corruption. A central coordinator can solve this, but it becomes a single point of failure.

We use lease-based optimistic concurrency instead. This is a well-known pattern, adapted here for long-running, stateful workflows.

How it works

When an agent is ready for new work, it asks the service to lease an activity. The service atomically selects the highest-priority ready activity, assigns a lease token with an expiration time, and transitions the activity to Pending. No other agent can claim the same activity.

sequenceDiagram
participant Agent
participant Service
Agent->>Service: Poll for work
Note right of Service: Select highest-priority<br/>Ready activity
Note right of Service: Atomically set lease<br/>token + expiration
Service->>Agent: Lease (token, expiration)
Agent->>Service: Begin execution
Note right of Service: Transition to Executing
Note over Agent: Work in progress...
Agent->>Service: Renew lease
Service->>Agent: New expiration
Note over Agent: Work continues...
Agent->>Service: Complete (token, result)
Note right of Service: Transition to Completed<br/>Archive activity
Service->>Agent: Acknowledged

While executing, the agent periodically renews its lease to signal that it’s still working. If the agent crashes, loses network connectivity, or is terminated, it stops renewing. Once the lease expires, the service transitions the activity to Restarting, making it available for another agent to claim.

sequenceDiagram
participant A as Agent A
participant S as Service
participant B as Agent B
A->>S: Lease activity
S->>A: Token + expiration
Note over A: Executing...
A--xS: Agent A crashes
Note right of S: Lease expires
Note right of S: Transition → Restarting
B->>S: Poll for work
Note right of S: Lease to Agent B<br/>Transition → Pending
S->>B: Token + expiration
Note over B: Agent B continues execution

The service doesn’t need to explicitly coordinate between workers because leases are acquired using atomic database operations. The lease expiration is the failure detector; if a lease expires, then the work needs to be rescheduled.

Routing work to the right runner pool

Pulumi Cloud supports multiple workflow runner pools. An organization might have one pool for production in us-east-1, another for staging in eu-west-1, and use Pulumi-hosted runners for development. Work needs to reach the right pool.

Each activity carries a routing context that identifies which runner pool should execute it. When a runner polls for work, it filters by its own pool identifier so that it only sees activities meant for it.

We use prefix matching for this filtering. A runner matches activities whose context starts with its pool’s identifier. This means the service can use hierarchical contexts (e.g., pool-abc/insights/scan-123) and runners will still match on the pool prefix. Cleanup is also straightforward; when a runner pool is deleted, all activities with that context prefix are bulk-canceled.

This routing mechanism works the same way regardless of workflow type, and adding a new workflow type doesn’t require changes to the routing layer.

Dependencies and multi-step workflows

Some workflows are naturally multi-step. An Insights discovery scan might discover resources that then need policy evaluation. Rather than building a separate orchestration engine, we built dependency management into the activity system.

An activity can declare a dependency set: a list of other activities that must complete before it can run. A dependent activity enters the Waiting state when created. As its dependencies complete, the system checks whether all prerequisites are satisfied. When the last one finishes, the waiting activity transitions to Ready and enters the scheduling queue.

graph TD
A["Insights Discovery<br/><b>Executing</b>"] -->|depends on| B["Policy Evaluation<br/><b>Waiting</b>"]
A -->|completes| C["Insights Discovery<br/><b>Completed</b>"]
C -->|triggers| D["Policy Evaluation<br/><b>Ready</b><br/>(auto-scheduled)"]

This gives us a lightweight DAG of work without requiring a separate workflow engine. Dependent activities get the same guarantees as any other activity: lease-based execution, automatic recovery, and observability.

Two execution modes, one interface

This is where the design really pays off for customer-managed runners. The system supports two execution modes:

Direct mode runs in-process alongside the Pulumi Cloud service. Workers have low-latency access to internal systems and can process activities with minimal overhead. This is what Pulumi-hosted runners use.
Remote mode communicates over REST APIs. The runner polls for activities, leases them, executes work locally, and reports results back over HTTP. This is what customer-managed runners use. No database access, no internal network access, no inbound connectivity required.

Both modes share the same handler interface so that a workflow handler doesn’t need to know where it’s running. Whether it’s running on Pulumi’s hosted infrastructure or on a customer’s Kubernetes cluster, the handler simply processes the payload and reports a result.

Putting it all together

Let’s walk through a concrete example. A user wants to run an Insights discovery scan on an AWS account using a customer-managed workflow runner.

sequenceDiagram
participant User
participant PC as Pulumi Cloud
participant Runner as Workflow Runner<br/>(Customer Infrastructure)
User->>PC: 1. Configure Insights scan<br/>for runner pool
Note right of PC: 2. Create background activity<br/>type: insights-discovery<br/>context: runner-pool-xyz<br/>status: Ready
Runner->>PC: 3. Poll for work (filtered by pool)
PC->>Runner: 4. Lease activity (token + expiration)
Runner->>PC: 5. Initialize workflow
PC->>Runner: Return cloud credentials + job token
Note over Runner: 6. Execute scan locally<br/>(talks directly to cloud APIs —<br/>credentials are used only on<br/>the runner)
Runner->>PC: 7. Renew lease
Note right of PC: Extend expiration
Runner->>PC: 8. Report completion
Note right of PC: 9. Mark completed<br/>Archive activity
Note right of PC: 10. Unblock dependent activities<br/>(e.g., policy evaluation)

A user configures an AWS account for Insights scanning in Pulumi Cloud and assigns it to a workflow runner pool.
Pulumi Cloud creates a background activity with the type set to insights discovery, the routing context set to the runner pool, and the payload containing the account configuration.
A customer-managed workflow runner polling that pool detects new work.
The runner leases the activity, acquiring an exclusive lock via the lease token.
The runner initializes the workflow, receiving any required cloud provider credentials (e.g., resolved from Pulumi ESC (Environments, Secrets, and Configuration)) and a job token from Pulumi Cloud.
The runner executes the scan locally on the customer’s infrastructure, talking directly to the cloud provider APIs.
During execution, the runner periodically renews its lease to signal liveness.
The scan completes, and the runner reports the result back to Pulumi Cloud.
The service marks the activity as completed and archives it.
If a dependent policy evaluation activity was waiting on this scan, it automatically transitions to Ready and enters the scheduling queue, where another runner in the pool can pick it up.

This flow works the same way whether the runner is hosted by Pulumi or by the customer. The only difference is whether the execution mode is direct or remote.

Retries and scheduling

Failures are expected in distributed systems. The background activity system handles them at several levels:

Lease expiration covers hard failures like agent crashes, network partitions, and machine terminations. If a lease expires, the activity moves to Restarting, and is available for another agent to pick up.
Handler-controlled retries cover soft failures like transient API errors and rate limits. A handler can request a reschedule with a delay, putting the activity back in Ready with a future activation time.
Automatic retries provide a configurable retry budget per activity. Each activity can specify how many times it should be retried and the delay between attempts, preventing runaway retry loops.
Priority scheduling ensures urgent work gets processed first. Higher-priority activities are leased before lower-priority ones, even if the lower-priority activity has been waiting longer.
Lease renewal during slowdowns keeps the activity alive without blocking other work, even if a downstream service is slow. The agent continues renewing its lease while it waits, and the scheduler remains free to assign other activities to other agents.

Observability

Every activity generates a structured log of its execution, including timestamps, severity levels, and code context. Logs are stored with the activity record and are accessible via an API and admin tooling.

This is especially useful for customer-managed runners, where the service can’t directly observe the execution environment. The structured log gives operators visibility into the execution context, even when the runner is behind a firewall. Handlers can also use these logs as a progress journal, encoding checkpoints that allow a restarted activity to pick up where it left off rather than starting from scratch.

Retention policies are configurable per organization and per workflow type. Completed activities can be retained for auditing or purged to manage storage, and failed activities are typically retained longer for debugging.

What we learned

A generic system pays off quickly. Our initial instinct was to build targeted solutions for each workflow type. Investing in a generic activity system required more upfront design work, but now adding a new workflow type requires a fraction of the effort it would take otherwise. New workflows ship with full scheduling, retry, and observability support from day one.

Leases handle many failure modes. We evaluated several approaches for distributed work coordination, including message queues with explicit acknowledgment and coordinator-based assignment. The lease model works well because all failure modes are handled through timeouts. If an agent is running as expected, it renews. If it isn’t, the lease expires.

Keeping the execution paths symmetric requires discipline. Making the hosted and self-hosted paths share the same handler interface was a deliberate choice. It would be easy to add shortcuts for the hosted path that bypass the remote API, but resisting that temptation means that features work for both cases automatically.

The hard part isn’t running the work. Running a scan or a deployment is straightforward once you have the right credentials. The real complexity is in everything around the execution: scheduling, routing, leasing, retrying, resolving dependencies, and cleaning up. These operational concerns aren’t visible to users, but they are essential to providing a reliable experience.

Wrapping it up

Today this system powers deployments, Insights discovery scans, and policy evaluations across both Pulumi Cloud and customer-managed infrastructure. The architecture is general enough that every new workflow type we add inherits the full scheduling, routing, retry, and observability stack without additional plumbing.

If you’re interested in running workflows on your own infrastructure, check out customer-managed workflow runners. To see how Insights can help you understand and manage your cloud infrastructure, get started with Pulumi Insights.

Announcing OpenAPI support for the Pulumi Cloud REST API

Davide Massarenti — Thu, 05 Feb 2026 00:00:00 +0000

We’re thrilled to announce that the Pulumi Cloud REST API is now described by an OpenAPI 3.0 specification, and we’re just getting started.

This is a feature that has been a long time coming. We have heard your requests for OpenAPI support loud and clear, and we’re excited to share that not only do we have a published specification for consumption, but our API code is now built from this specification as well. Moving forward, this single source of truth unlocks better tooling, tighter integration, and a more predictable API experience for everyone.

You can fetch the spec directly from the API at runtime or use it for client generation, validation, and documentation, all from one machine-readable contract.

A single contract for the Pulumi Cloud REST API

The Pulumi Cloud API powers the Pulumi CLI, the Pulumi Console, and third-party integrations. Until now, there was no single, published machine-readable description of that API. We’ve changed that. The API is now defined and served as a standard OpenAPI 3.0.3 document.

Runtime discovery: You can retrieve the spec from the API itself, so your tooling always sees the same surface the service implements.
Client generation: Use your favorite OpenAPI tooling (e.g. OpenAPI Generator, Swagger Codegen) to generate API clients in the language of your choice.
Validation and testing: Validate requests and responses, or build mocks and tests, from the same spec the service uses.
Documentation: The spec is the source of truth, not a separate, hand-maintained API doc that can drift from reality. Load the spec into Swagger UI, Redoc, or another viewer to browse the Pulumi Cloud API interactively.

How to get the spec

Send a GET request to:

https://api.pulumi.com/api/openapi/pulumi-spec.json

No authentication is required. The response is the OpenAPI 3.0 document for the Pulumi Cloud API, describing the supported, documented API surface.

Source of truth and stability

We do not hand-write the OpenAPI spec. We generate it from the same API definition that drives our backend and console code. When we add or change API routes or models, we regenerate the spec so the published document stays in sync with what the service actually implements. That gives you a clear, stable contract for the Pulumi Cloud API.

What we are building next

We are using this spec as the foundation for our own tooling, and have plans to continue leveraging the spec in our toolchain long-term.

CLI: We plan to drive the Pulumi CLI’s API client from the OpenAPI spec so that CLI and API stay in lockstep.
Pulumi Service Provider: We are also building towards day 1 updates to the Pulumi Service Provider so that new and changed API resources are generated from the spec and ship in sync with the service.
Docs Enhancements: Although you can load the spec using Swagger UI for your own browsing, we are intent on shipping enhancements to our public REST API docs that will keep them up-to-date according to the OpenAPI spec.

As we ship those updates, you will get a single source of truth from API to CLI to provider.

If you have questions or feedback about the OpenAPI spec or the Pulumi Cloud API, reach out in our Community Slack or open an issue in the Pulumi repository. We’re excited to see what you build with it.

Pulumi IAM Now Available for Self-Hosted Pulumi Cloud

Davide Massarenti — Wed, 14 Jan 2026 11:18:00 +0000

We’re excited to announce that Pulumi Identity and Access Management (IAM) is now available for self-hosted instances of Pulumi Cloud. This foundational security capability brings the same enterprise-grade access management we launched for Pulumi Cloud SaaS to organizations running Pulumi on their own infrastructure.

Enterprise Security for Self-Hosted Deployments

Self-hosted Pulumi Cloud customers can now leverage the full power of Custom Roles and Granular Access Tokens to implement Zero Trust security principles and least privilege access controls within their own environments. This means you can:

Define Custom Permissions with fine-grained scopes (e.g., stack:delete, environment:read) tailored to your organization’s security requirements.
Create Custom Roles by combining these permissions with specific Pulumi entities (Stacks, Environments, etc.).
Generate Scoped Organization Access Tokens that are precisely limited to the permissions defined in their associated roles, dramatically reducing the blast radius if credentials are compromised.

Secure Automation for On-Premises Infrastructure

This release is powerful for self-hosted Pulumi Cloud deployments where security and compliance requirements are often even more stringent. You can now:

Implement Least Privilege CI/CD: Scope pipeline tokens to only the actions and resources they absolutely need, ensuring your automation follows the same security standards as your infrastructure.
Enhance Compliance Posture: Demonstrate precise, auditable control over programmatic access to auditors and security teams.
Reduce Operational Risk: Limit the potential impact of compromised tokens by restricting them to specific roles and permissions.

Getting Started

Self-hosted customers can access IAM features through the same intuitive interface available in Pulumi Cloud SaaS. Navigate to Settings -> Access Management -> Roles to begin creating Custom Permissions and Custom Roles, then generate scoped Organization Access Tokens from Settings -> Access Management -> Access Tokens.

For detailed information about Pulumi IAM capabilities, including step-by-step guides and best practices, see our comprehensive announcement blog post.

Learn More

Explore the IAM & RBAC documentation to get started:

We’re committed to bringing enterprise-grade security features to all Pulumi deployments, whether in the cloud or on-premises. If you have questions or feedback, please reach out through your account representative or our GitHub repository.