Manage GCP Service Directory Namespace IAM Access

The gcp:servicedirectory/namespaceIamMember:NamespaceIamMember resource, part of the Pulumi GCP provider, manages IAM permissions for Service Directory namespaces using three distinct approaches: policy-level (authoritative), role-level (authoritative for one role), and member-level (non-authoritative). This guide focuses on three capabilities: authoritative policy replacement, role-level member binding, and incremental member addition.

All three IAM resource types reference an existing Service Directory namespace. NamespaceIamPolicy replaces the entire policy and cannot be used with the other two types. NamespaceIamBinding and NamespaceIamMember can coexist as long as they don’t manage the same role. The examples are intentionally small. Combine them with your own namespace infrastructure and identity management.

Replace the entire IAM policy for a namespace

When you need complete control over namespace access, you can set the entire IAM policy at once.

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

const admin = gcp.organizations.getIAMPolicy({
    bindings: [{
        role: "roles/viewer",
        members: ["user:jane@example.com"],
    }],
});
const policy = new gcp.servicedirectory.NamespaceIamPolicy("policy", {
    name: example.name,
    policyData: admin.then(admin => admin.policyData),
});

import pulumi
import pulumi_gcp as gcp

admin = gcp.organizations.get_iam_policy(bindings=[{
    "role": "roles/viewer",
    "members": ["user:jane@example.com"],
}])
policy = gcp.servicedirectory.NamespaceIamPolicy("policy",
    name=example["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/servicedirectory"
	"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/viewer",
					Members: []string{
						"user:jane@example.com",
					},
				},
			},
		}, nil)
		if err != nil {
			return err
		}
		_, err = servicedirectory.NewNamespaceIamPolicy(ctx, "policy", &servicedirectory.NamespaceIamPolicyArgs{
			Name:       pulumi.Any(example.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/viewer",
                Members = new[]
                {
                    "user:jane@example.com",
                },
            },
        },
    });

    var policy = new Gcp.ServiceDirectory.NamespaceIamPolicy("policy", new()
    {
        Name = example.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.servicedirectory.NamespaceIamPolicy;
import com.pulumi.gcp.servicedirectory.NamespaceIamPolicyArgs;
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/viewer")
                .members("user:jane@example.com")
                .build())
            .build());

        var policy = new NamespaceIamPolicy("policy", NamespaceIamPolicyArgs.builder()
            .name(example.name())
            .policyData(admin.policyData())
            .build());

    }
}

resources:
  policy:
    type: gcp:servicedirectory:NamespaceIamPolicy
    properties:
      name: ${example.name}
      policyData: ${admin.policyData}
variables:
  admin:
    fn::invoke:
      function: gcp:organizations:getIAMPolicy
      arguments:
        bindings:
          - role: roles/viewer
            members:
              - user:jane@example.com

The NamespaceIamPolicy resource takes a policyData object from getIAMPolicy, which defines all roles and members. This approach replaces any existing policy, giving you full control but requiring you to specify every permission. Use this when you want to ensure no unexpected access remains.

Grant a role to multiple members at once

When multiple users or service accounts need the same access level, bind them all to a role in one resource.

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

const binding = new gcp.servicedirectory.NamespaceIamBinding("binding", {
    name: example.name,
    role: "roles/viewer",
    members: ["user:jane@example.com"],
});

import pulumi
import pulumi_gcp as gcp

binding = gcp.servicedirectory.NamespaceIamBinding("binding",
    name=example["name"],
    role="roles/viewer",
    members=["user:jane@example.com"])

package main

import (
	"github.com/pulumi/pulumi-gcp/sdk/v9/go/gcp/servicedirectory"
	"github.com/pulumi/pulumi/sdk/v3/go/pulumi"
)

func main() {
	pulumi.Run(func(ctx *pulumi.Context) error {
		_, err := servicedirectory.NewNamespaceIamBinding(ctx, "binding", &servicedirectory.NamespaceIamBindingArgs{
			Name: pulumi.Any(example.Name),
			Role: pulumi.String("roles/viewer"),
			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 binding = new Gcp.ServiceDirectory.NamespaceIamBinding("binding", new()
    {
        Name = example.Name,
        Role = "roles/viewer",
        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.servicedirectory.NamespaceIamBinding;
import com.pulumi.gcp.servicedirectory.NamespaceIamBindingArgs;
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 binding = new NamespaceIamBinding("binding", NamespaceIamBindingArgs.builder()
            .name(example.name())
            .role("roles/viewer")
            .members("user:jane@example.com")
            .build());

    }
}

resources:
  binding:
    type: gcp:servicedirectory:NamespaceIamBinding
    properties:
      name: ${example.name}
      role: roles/viewer
      members:
        - user:jane@example.com

The NamespaceIamBinding resource is authoritative for the specified role: it controls the complete list of members for that role while preserving other roles on the namespace. The members array can include users, service accounts, groups, or special identifiers like allAuthenticatedUsers.

Add a single member to a role incrementally

To grant access to one identity without affecting other members of the same role, use a non-authoritative member resource.

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

const member = new gcp.servicedirectory.NamespaceIamMember("member", {
    name: example.name,
    role: "roles/viewer",
    member: "user:jane@example.com",
});

import pulumi
import pulumi_gcp as gcp

member = gcp.servicedirectory.NamespaceIamMember("member",
    name=example["name"],
    role="roles/viewer",
    member="user:jane@example.com")

package main

import (
	"github.com/pulumi/pulumi-gcp/sdk/v9/go/gcp/servicedirectory"
	"github.com/pulumi/pulumi/sdk/v3/go/pulumi"
)

func main() {
	pulumi.Run(func(ctx *pulumi.Context) error {
		_, err := servicedirectory.NewNamespaceIamMember(ctx, "member", &servicedirectory.NamespaceIamMemberArgs{
			Name:   pulumi.Any(example.Name),
			Role:   pulumi.String("roles/viewer"),
			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 member = new Gcp.ServiceDirectory.NamespaceIamMember("member", new()
    {
        Name = example.Name,
        Role = "roles/viewer",
        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.servicedirectory.NamespaceIamMember;
import com.pulumi.gcp.servicedirectory.NamespaceIamMemberArgs;
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 member = new NamespaceIamMember("member", NamespaceIamMemberArgs.builder()
            .name(example.name())
            .role("roles/viewer")
            .member("user:jane@example.com")
            .build());

    }
}

resources:
  member:
    type: gcp:servicedirectory:NamespaceIamMember
    properties:
      name: ${example.name}
      role: roles/viewer
      member: user:jane@example.com

The NamespaceIamMember resource adds one member to a role without removing existing members. This is the safest approach when multiple teams manage access independently. The member property accepts the same identity formats as NamespaceIamBinding, but you specify only one at a time.

Beyond these examples

These snippets focus on specific IAM management features: authoritative vs non-authoritative IAM management, and policy-level, role-level, and member-level grants. They’re intentionally minimal rather than full access control systems.

The examples reference pre-existing infrastructure such as a Service Directory namespace (referenced by the name property). They focus on configuring IAM permissions rather than provisioning the namespace itself.

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

Conditional IAM bindings (condition property)
Custom role definitions
Federated identity configuration
Service account creation

These omissions are intentional: the goal is to illustrate how each IAM resource type is wired, not provide drop-in access control modules. See the Service Directory Namespace IAM Member resource reference for all available configuration options.

Let's manage GCP Service Directory Namespace IAM Access

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 NamespaceIamPolicy, NamespaceIamBinding, and NamespaceIamMember?

NamespaceIamPolicy is authoritative and replaces the entire IAM policy. NamespaceIamBinding is authoritative for a specific role, preserving other roles. NamespaceIamMember is non-authoritative and adds a single member to a role without affecting other members.

Can I use NamespaceIamPolicy with NamespaceIamBinding or NamespaceIamMember?

No, NamespaceIamPolicy cannot be used with NamespaceIamBinding or NamespaceIamMember as they will conflict over the policy configuration.

Can I use NamespaceIamBinding and NamespaceIamMember together?

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

IAM Configuration

What member identity formats can I use?

You can use: allUsers, allAuthenticatedUsers, user:{email}, serviceAccount:{email}, group:{email}, domain:{domain}, projectOwner/Editor/Viewer:{projectid}, or federated identities like principal://iam.googleapis.com/....

How do I specify a custom role?

Custom roles must use the full format: [projects|organizations]/{parent-name}/roles/{role-name}. For example, projects/my-project/roles/my-custom-role.

Resource Management

What properties can't I change after creation?

The member, role, and name properties are all immutable and cannot be changed after the resource is created.

How do I import a namespace IAM resource with a custom role?

Use the full custom role name in the import command: [projects/my-project|organizations/my-org]/roles/my-custom-role. For example:

pulumi import gcp:servicedirectory/namespaceIamMember:NamespaceIamMember editor "projects/my-project/locations/us-central1/namespaces/my-ns roles/myCustomRole user:jane@example.com"

What identifier formats can I use for the name property?

You can use: projects/{{project}}/locations/{{location}}/namespaces/{{namespace_id}}, {{project}}/{{location}}/{{namespace_id}}, or {{location}}/{{namespace_id}}. Missing variables are taken from the provider configuration.

Using a different cloud?

Explore security guides for other cloud providers:

AWS Guides Azure Guides