Manage GCP Pub/Sub Subscription IAM Bindings

The gcp:pubsub/subscriptionIAMBinding:SubscriptionIAMBinding resource, part of the Pulumi GCP provider, grants a specific IAM role to a list of members on a Pub/Sub subscription while preserving other roles in the subscription’s IAM policy. This guide focuses on two capabilities: granting roles to multiple members and adding individual members to roles.

This resource is one of three IAM management options for Pub/Sub subscriptions. SubscriptionIAMBinding is authoritative for a single role, meaning it controls the complete member list for that role but leaves other roles untouched. It references existing subscriptions and requires valid member identifiers. The examples are intentionally small. Combine them with your own subscription references and member lists.

Grant a role to multiple members

Teams managing subscriptions often need to grant the same role to multiple users or service accounts at once, such as giving editor access to a team.

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 members property accepts a list of identities that will receive the specified role. This binding is authoritative for the editor role: it replaces any existing members of that role but preserves members of other roles on the subscription. The subscription property references an existing Pub/Sub subscription by name.

Add a single member to a role

When onboarding individual users or service accounts, teams add them one at a time without affecting existing members.

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 member property (singular) adds one identity to the role without replacing existing members. This is non-authoritative: multiple SubscriptionIAMMember resources can grant the same role to different members. Use this when you need incremental access changes rather than managing the complete member list.

Beyond these examples

These snippets focus on specific subscription IAM features: role-based access control and member vs members properties. They’re intentionally minimal rather than full access control configurations.

The examples reference pre-existing infrastructure such as Pub/Sub subscriptions. They focus on granting access rather than creating subscriptions or managing full IAM policies.

To keep things focused, common IAM patterns are omitted, including:

Conditional IAM bindings (condition property)
Custom role formats ([projects|organizations]/{parent-name}/roles/{role-name})
Full IAM policy replacement (SubscriptionIAMPolicy)
Special identifiers (allUsers, allAuthenticatedUsers, domain:{domain})

These omissions are intentional: the goal is to illustrate how role-based access is 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 FREE

Frequently Asked Questions

Resource Selection & Conflicts

What's the difference between SubscriptionIAMPolicy, SubscriptionIAMBinding, and SubscriptionIAMMember?

SubscriptionIAMPolicy is authoritative and replaces the entire IAM policy. SubscriptionIAMBinding is authoritative for a specific role but preserves other roles. SubscriptionIAMMember is non-authoritative and adds a single member while preserving other members for that role.

Can I use SubscriptionIAMPolicy with SubscriptionIAMBinding or SubscriptionIAMMember?

No, SubscriptionIAMPolicy cannot be used with SubscriptionIAMBinding or SubscriptionIAMMember because they’ll conflict over the policy configuration.

Can I use SubscriptionIAMBinding and SubscriptionIAMMember together?

Yes, but only if they don’t grant privileges to the same role. Using both for the same role will cause conflicts.

Can I create multiple SubscriptionIAMBinding resources for the same role?

No, only one SubscriptionIAMBinding can be used per role. List all members in a single resource’s members array.

Configuration & Member Formats

What member identity formats are supported?

Supported formats include allUsers, allAuthenticatedUsers, user:{email}, serviceAccount:{email}, group:{email}, and domain:{domain}.

What's the format for custom roles?

Custom roles must follow the format [projects|organizations]/{parent-name}/roles/{role-name}.

Immutability & Limitations

What properties can't I change after creating a SubscriptionIAMBinding?

The role, subscription, project, and condition properties are immutable and require resource replacement if changed.

Using a different cloud?

Explore security guides for other cloud providers:

AWS Guides Azure Guides