The gcp:pubsub/subscriptionIAMBinding:SubscriptionIAMBinding resource, part of the Pulumi GCP provider, grants IAM roles to members for a Pub/Sub subscription, controlling who can pull messages, acknowledge deliveries, or modify subscription settings. This guide focuses on two capabilities: authoritative role bindings for multiple members and non-authoritative member additions.
This resource manages access to existing Pub/Sub subscriptions. The examples are intentionally small. Combine them with your own subscription resources and identity management.
Grant a role to multiple members
Teams managing subscriptions often need to grant the same role to multiple service accounts or users at once, such as giving editor access to a group of application service accounts.
import * as pulumi from "@pulumi/pulumi";
import * as gcp from "@pulumi/gcp";
const editor = new gcp.pubsub.SubscriptionIAMBinding("editor", {
subscription: "your-subscription-name",
role: "roles/editor",
members: ["user:jane@example.com"],
});
import pulumi
import pulumi_gcp as gcp
editor = gcp.pubsub.SubscriptionIAMBinding("editor",
subscription="your-subscription-name",
role="roles/editor",
members=["user:jane@example.com"])
package main
import (
"github.com/pulumi/pulumi-gcp/sdk/v9/go/gcp/pubsub"
"github.com/pulumi/pulumi/sdk/v3/go/pulumi"
)
func main() {
pulumi.Run(func(ctx *pulumi.Context) error {
_, err := pubsub.NewSubscriptionIAMBinding(ctx, "editor", &pubsub.SubscriptionIAMBindingArgs{
Subscription: pulumi.String("your-subscription-name"),
Role: pulumi.String("roles/editor"),
Members: pulumi.StringArray{
pulumi.String("user:jane@example.com"),
},
})
if err != nil {
return err
}
return nil
})
}
using System.Collections.Generic;
using System.Linq;
using Pulumi;
using Gcp = Pulumi.Gcp;
return await Deployment.RunAsync(() =>
{
var editor = new Gcp.PubSub.SubscriptionIAMBinding("editor", new()
{
Subscription = "your-subscription-name",
Role = "roles/editor",
Members = new[]
{
"user:jane@example.com",
},
});
});
package generated_program;
import com.pulumi.Context;
import com.pulumi.Pulumi;
import com.pulumi.core.Output;
import com.pulumi.gcp.pubsub.SubscriptionIAMBinding;
import com.pulumi.gcp.pubsub.SubscriptionIAMBindingArgs;
import java.util.List;
import java.util.ArrayList;
import java.util.Map;
import java.io.File;
import java.nio.file.Files;
import java.nio.file.Paths;
public class App {
public static void main(String[] args) {
Pulumi.run(App::stack);
}
public static void stack(Context ctx) {
var editor = new SubscriptionIAMBinding("editor", SubscriptionIAMBindingArgs.builder()
.subscription("your-subscription-name")
.role("roles/editor")
.members("user:jane@example.com")
.build());
}
}
resources:
editor:
type: gcp:pubsub:SubscriptionIAMBinding
properties:
subscription: your-subscription-name
role: roles/editor
members:
- user:jane@example.com
The SubscriptionIAMBinding resource is authoritative for the specified role: it replaces all members for that role with the list you provide. The members array accepts service accounts, users, groups, and special identifiers like allAuthenticatedUsers. Other roles on the subscription remain unchanged.
Add a single member to a role
When onboarding individual users or service accounts, teams add them one at a time without affecting other members who already have the same role.
import * as pulumi from "@pulumi/pulumi";
import * as gcp from "@pulumi/gcp";
const editor = new gcp.pubsub.SubscriptionIAMMember("editor", {
subscription: "your-subscription-name",
role: "roles/editor",
member: "user:jane@example.com",
});
import pulumi
import pulumi_gcp as gcp
editor = gcp.pubsub.SubscriptionIAMMember("editor",
subscription="your-subscription-name",
role="roles/editor",
member="user:jane@example.com")
package main
import (
"github.com/pulumi/pulumi-gcp/sdk/v9/go/gcp/pubsub"
"github.com/pulumi/pulumi/sdk/v3/go/pulumi"
)
func main() {
pulumi.Run(func(ctx *pulumi.Context) error {
_, err := pubsub.NewSubscriptionIAMMember(ctx, "editor", &pubsub.SubscriptionIAMMemberArgs{
Subscription: pulumi.String("your-subscription-name"),
Role: pulumi.String("roles/editor"),
Member: pulumi.String("user:jane@example.com"),
})
if err != nil {
return err
}
return nil
})
}
using System.Collections.Generic;
using System.Linq;
using Pulumi;
using Gcp = Pulumi.Gcp;
return await Deployment.RunAsync(() =>
{
var editor = new Gcp.PubSub.SubscriptionIAMMember("editor", new()
{
Subscription = "your-subscription-name",
Role = "roles/editor",
Member = "user:jane@example.com",
});
});
package generated_program;
import com.pulumi.Context;
import com.pulumi.Pulumi;
import com.pulumi.core.Output;
import com.pulumi.gcp.pubsub.SubscriptionIAMMember;
import com.pulumi.gcp.pubsub.SubscriptionIAMMemberArgs;
import java.util.List;
import java.util.ArrayList;
import java.util.Map;
import java.io.File;
import java.nio.file.Files;
import java.nio.file.Paths;
public class App {
public static void main(String[] args) {
Pulumi.run(App::stack);
}
public static void stack(Context ctx) {
var editor = new SubscriptionIAMMember("editor", SubscriptionIAMMemberArgs.builder()
.subscription("your-subscription-name")
.role("roles/editor")
.member("user:jane@example.com")
.build());
}
}
resources:
editor:
type: gcp:pubsub:SubscriptionIAMMember
properties:
subscription: your-subscription-name
role: roles/editor
member: user:jane@example.com
The SubscriptionIAMMember resource is non-authoritative: it adds one member to a role without replacing existing members. Use this when you want to grant access incrementally. The member property accepts the same identity formats as members in SubscriptionIAMBinding (service accounts, users, groups, domains).
Beyond these examples
These snippets focus on specific IAM binding features: role-based access control and authoritative vs non-authoritative bindings. They’re intentionally minimal rather than full access management solutions.
The examples reference pre-existing infrastructure such as Pub/Sub subscriptions. They focus on configuring access rather than provisioning subscriptions.
To keep things focused, common IAM patterns are omitted, including:
- Conditional IAM bindings (condition property)
- Cross-project subscription references (project property)
- Policy-level management (SubscriptionIAMPolicy)
These omissions are intentional: the goal is to illustrate how IAM bindings are wired, not provide drop-in access control modules. See the Pub/Sub SubscriptionIAMBinding resource reference for all available configuration options.
Let's manage GCP Pub/Sub Subscription IAM Bindings
Get started with Pulumi Cloud, then follow our quick setup guide to deploy this infrastructure.
Try Pulumi Cloud for FREEFrequently Asked Questions
Resource Selection & Conflicts
SubscriptionIAMPolicy is authoritative and replaces the entire IAM policy. SubscriptionIAMBinding is authoritative for a specific role, preserving other roles. SubscriptionIAMMember is non-authoritative, adding individual members while preserving existing members for that role.SubscriptionIAMPolicy for complete policy control, SubscriptionIAMBinding to manage all members for a specific role, or SubscriptionIAMMember to add individual members without affecting others.SubscriptionIAMPolicy cannot be used with SubscriptionIAMBinding or SubscriptionIAMMember as they’ll conflict. However, SubscriptionIAMBinding and SubscriptionIAMMember can coexist if they don’t grant privileges to the same role.IAM Configuration
[projects|organizations]/{parent-name}/roles/{role-name}.allUsers, allAuthenticatedUsers, user:{email}, serviceAccount:{email}, group:{email}, and domain:{domain}.Immutability & Lifecycle
role, subscription, project, and condition properties are immutable and require resource replacement if changed.