Manage GCP Pub/Sub Subscription IAM Policies

The gcp:pubsub/subscriptionIAMPolicy:SubscriptionIAMPolicy resource, part of the Pulumi GCP provider, controls IAM permissions for Pub/Sub subscriptions. This guide focuses on two approaches: authoritative policy replacement and incremental member grants.

IAM resources reference existing Pub/Sub subscriptions. The examples are intentionally small. Combine them with your own subscription resources and identity management.

Replace the entire IAM policy for a subscription

When you need complete control over subscription access, you can define the entire IAM policy and replace any existing permissions.

import * as pulumi from "@pulumi/pulumi";
import * as gcp from "@pulumi/gcp";

const admin = gcp.organizations.getIAMPolicy({
    bindings: [{
        role: "roles/editor",
        members: ["user:jane@example.com"],
    }],
});
const editor = new gcp.pubsub.SubscriptionIAMPolicy("editor", {
    subscription: "your-subscription-name",
    policyData: admin.then(admin => admin.policyData),
});

import pulumi
import pulumi_gcp as gcp

admin = gcp.organizations.get_iam_policy(bindings=[{
    "role": "roles/editor",
    "members": ["user:jane@example.com"],
}])
editor = gcp.pubsub.SubscriptionIAMPolicy("editor",
    subscription="your-subscription-name",
    policy_data=admin.policy_data)

package main

import (
	"github.com/pulumi/pulumi-gcp/sdk/v9/go/gcp/organizations"
	"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 {
		admin, err := organizations.LookupIAMPolicy(ctx, &organizations.LookupIAMPolicyArgs{
			Bindings: []organizations.GetIAMPolicyBinding{
				{
					Role: "roles/editor",
					Members: []string{
						"user:jane@example.com",
					},
				},
			},
		}, nil)
		if err != nil {
			return err
		}
		_, err = pubsub.NewSubscriptionIAMPolicy(ctx, "editor", &pubsub.SubscriptionIAMPolicyArgs{
			Subscription: pulumi.String("your-subscription-name"),
			PolicyData:   pulumi.String(admin.PolicyData),
		})
		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 admin = Gcp.Organizations.GetIAMPolicy.Invoke(new()
    {
        Bindings = new[]
        {
            new Gcp.Organizations.Inputs.GetIAMPolicyBindingInputArgs
            {
                Role = "roles/editor",
                Members = new[]
                {
                    "user:jane@example.com",
                },
            },
        },
    });

    var editor = new Gcp.PubSub.SubscriptionIAMPolicy("editor", new()
    {
        Subscription = "your-subscription-name",
        PolicyData = admin.Apply(getIAMPolicyResult => getIAMPolicyResult.PolicyData),
    });

});

package generated_program;

import com.pulumi.Context;
import com.pulumi.Pulumi;
import com.pulumi.core.Output;
import com.pulumi.gcp.organizations.OrganizationsFunctions;
import com.pulumi.gcp.organizations.inputs.GetIAMPolicyArgs;
import com.pulumi.gcp.pubsub.SubscriptionIAMPolicy;
import com.pulumi.gcp.pubsub.SubscriptionIAMPolicyArgs;
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) {
        final var admin = OrganizationsFunctions.getIAMPolicy(GetIAMPolicyArgs.builder()
            .bindings(GetIAMPolicyBindingArgs.builder()
                .role("roles/editor")
                .members("user:jane@example.com")
                .build())
            .build());

        var editor = new SubscriptionIAMPolicy("editor", SubscriptionIAMPolicyArgs.builder()
            .subscription("your-subscription-name")
            .policyData(admin.policyData())
            .build());

    }
}

resources:
  editor:
    type: gcp:pubsub:SubscriptionIAMPolicy
    properties:
      subscription: your-subscription-name
      policyData: ${admin.policyData}
variables:
  admin:
    fn::invoke:
      function: gcp:organizations:getIAMPolicy
      arguments:
        bindings:
          - role: roles/editor
            members:
              - user:jane@example.com

The SubscriptionIAMPolicy resource sets the complete IAM policy for the subscription, replacing any existing policy. The policyData property accepts output from getIAMPolicy, which defines bindings between roles and members. This approach is authoritative: it removes any permissions not explicitly listed.

Grant a role to a single member

Most access grants add one identity to one role without affecting other permissions.

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 adds a single member to a role without changing other role assignments. The member property specifies one identity (user, service account, or group), and the role property defines what permissions they receive. This approach is non-authoritative: existing members and roles remain unchanged.

Beyond these examples

These snippets focus on specific IAM management features: authoritative policy replacement and incremental member grants. They’re intentionally minimal rather than full access control configurations.

The examples reference pre-existing infrastructure such as Pub/Sub subscriptions. They focus on IAM bindings rather than subscription creation or message handling.

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

Conditional IAM bindings (condition blocks)
Project-level scoping (project property)
Service account and group member types
Custom role definitions

These omissions are intentional: the goal is to illustrate how each IAM resource type works, not provide drop-in access control modules. See the Pub/Sub Subscription IAM Policy resource reference for all available configuration options.

Let's manage GCP Pub/Sub Subscription IAM Policies

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 will conflict over the policy. Use SubscriptionIAMPolicy alone, or use SubscriptionIAMBinding/SubscriptionIAMMember without SubscriptionIAMPolicy.

Can I use SubscriptionIAMBinding and SubscriptionIAMMember together?

Yes, but only if they don’t grant privileges to the same role. Each role must be managed by only one resource type to avoid conflicts.

Configuration & Usage

How do I set a complete IAM policy for a subscription?

Use SubscriptionIAMPolicy with policyData from the gcp.organizations.getIAMPolicy data source, as shown in the example.

How do I grant a role to multiple members?

Use SubscriptionIAMBinding with the role property and a members array containing all members who should have that role.

How do I add a single member to a role without affecting other members?

Use SubscriptionIAMMember with the role and member properties. This preserves existing members for that role.

Properties & Immutability

What properties can't I change after creating the resource?

Both subscription and project are immutable and cannot be changed after creation.

Using a different cloud?

Explore security guides for other cloud providers:

AWS Guides Azure Guides