Manage IAM Permissions for GCP AI Notebooks

The gcp:notebooks/instanceIamMember:InstanceIamMember resource, part of the Pulumi GCP provider, manages IAM permissions for Cloud AI Notebooks instances by adding individual members to roles without replacing existing bindings. This resource is maintained for backwards compatibility; for new projects, consider using gcp.workbench.Instance and its corresponding IAM resources. This guide focuses on three IAM management approaches: single-member grants, role-level bindings, and full policy replacement.

IAM resources for notebook instances reference existing instances and have compatibility constraints. InstanceIamPolicy cannot be used with InstanceIamBinding or InstanceIamMember (they conflict). InstanceIamBinding and InstanceIamMember can coexist if they manage different roles. The examples are intentionally small. Combine them with your own notebook instances and identity management strategy.

Grant a single user access to a notebook instance

When you need to add one user to an instance without affecting other permissions, use InstanceIamMember.

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

const member = new gcp.notebooks.InstanceIamMember("member", {
    project: instance.project,
    location: instance.location,
    instanceName: instance.name,
    role: "roles/viewer",
    member: "user:jane@example.com",
});

import pulumi
import pulumi_gcp as gcp

member = gcp.notebooks.InstanceIamMember("member",
    project=instance["project"],
    location=instance["location"],
    instance_name=instance["name"],
    role="roles/viewer",
    member="user:jane@example.com")

package main

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

func main() {
	pulumi.Run(func(ctx *pulumi.Context) error {
		_, err := notebooks.NewInstanceIamMember(ctx, "member", &notebooks.InstanceIamMemberArgs{
			Project:      pulumi.Any(instance.Project),
			Location:     pulumi.Any(instance.Location),
			InstanceName: pulumi.Any(instance.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.Notebooks.InstanceIamMember("member", new()
    {
        Project = instance.Project,
        Location = instance.Location,
        InstanceName = instance.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.notebooks.InstanceIamMember;
import com.pulumi.gcp.notebooks.InstanceIamMemberArgs;
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 InstanceIamMember("member", InstanceIamMemberArgs.builder()
            .project(instance.project())
            .location(instance.location())
            .instanceName(instance.name())
            .role("roles/viewer")
            .member("user:jane@example.com")
            .build());

    }
}

resources:
  member:
    type: gcp:notebooks:InstanceIamMember
    properties:
      project: ${instance.project}
      location: ${instance.location}
      instanceName: ${instance.name}
      role: roles/viewer
      member: user:jane@example.com

The member property specifies the identity in the format “user:email@example.com”. The role property defines what permissions they receive. This resource is non-authoritative: it adds the member to the role without removing other members who already have that role. The instanceName, location, and project properties identify which notebook instance to modify.

Grant multiple users the same role

When several users need identical permissions, bind them all to a single role.

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

const binding = new gcp.notebooks.InstanceIamBinding("binding", {
    project: instance.project,
    location: instance.location,
    instanceName: instance.name,
    role: "roles/viewer",
    members: ["user:jane@example.com"],
});

import pulumi
import pulumi_gcp as gcp

binding = gcp.notebooks.InstanceIamBinding("binding",
    project=instance["project"],
    location=instance["location"],
    instance_name=instance["name"],
    role="roles/viewer",
    members=["user:jane@example.com"])

package main

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

func main() {
	pulumi.Run(func(ctx *pulumi.Context) error {
		_, err := notebooks.NewInstanceIamBinding(ctx, "binding", &notebooks.InstanceIamBindingArgs{
			Project:      pulumi.Any(instance.Project),
			Location:     pulumi.Any(instance.Location),
			InstanceName: pulumi.Any(instance.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.Notebooks.InstanceIamBinding("binding", new()
    {
        Project = instance.Project,
        Location = instance.Location,
        InstanceName = instance.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.notebooks.InstanceIamBinding;
import com.pulumi.gcp.notebooks.InstanceIamBindingArgs;
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 InstanceIamBinding("binding", InstanceIamBindingArgs.builder()
            .project(instance.project())
            .location(instance.location())
            .instanceName(instance.name())
            .role("roles/viewer")
            .members("user:jane@example.com")
            .build());

    }
}

resources:
  binding:
    type: gcp:notebooks:InstanceIamBinding
    properties:
      project: ${instance.project}
      location: ${instance.location}
      instanceName: ${instance.name}
      role: roles/viewer
      members:
        - user:jane@example.com

The members property accepts a list of identities. InstanceIamBinding is authoritative for the specified role: it replaces any existing members for that role while preserving other roles on the instance. If you later add another InstanceIamBinding for the same role, they will conflict.

Replace the entire IAM policy with a new configuration

Organizations with centralized IAM management can set the complete policy, replacing all existing bindings.

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.notebooks.InstanceIamPolicy("policy", {
    project: instance.project,
    location: instance.location,
    instanceName: instance.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.notebooks.InstanceIamPolicy("policy",
    project=instance["project"],
    location=instance["location"],
    instance_name=instance["name"],
    policy_data=admin.policy_data)

package main

import (
	"github.com/pulumi/pulumi-gcp/sdk/v9/go/gcp/notebooks"
	"github.com/pulumi/pulumi-gcp/sdk/v9/go/gcp/organizations"
	"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 = notebooks.NewInstanceIamPolicy(ctx, "policy", &notebooks.InstanceIamPolicyArgs{
			Project:      pulumi.Any(instance.Project),
			Location:     pulumi.Any(instance.Location),
			InstanceName: pulumi.Any(instance.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.Notebooks.InstanceIamPolicy("policy", new()
    {
        Project = instance.Project,
        Location = instance.Location,
        InstanceName = instance.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.notebooks.InstanceIamPolicy;
import com.pulumi.gcp.notebooks.InstanceIamPolicyArgs;
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 InstanceIamPolicy("policy", InstanceIamPolicyArgs.builder()
            .project(instance.project())
            .location(instance.location())
            .instanceName(instance.name())
            .policyData(admin.policyData())
            .build());

    }
}

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

InstanceIamPolicy uses policyData from getIAMPolicy to define the full set of role bindings. This resource is authoritative: it replaces the entire IAM policy on the instance. The bindings array in getIAMPolicy specifies roles and their members. Use this approach when you need complete control over all permissions, but avoid mixing it with InstanceIamBinding or InstanceIamMember.

Beyond these examples

These snippets focus on specific IAM management features: single-member grants, role-level bindings, and full policy replacement. They’re intentionally minimal rather than complete access control configurations.

The examples reference pre-existing infrastructure such as Cloud AI Notebooks instances (gcp.notebooks.Instance). They focus on configuring IAM permissions rather than provisioning the instances themselves.

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

Conditional IAM bindings (condition property)
Custom role definitions
Service account impersonation
Workload identity federation

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 Notebooks InstanceIamMember resource reference for all available configuration options.

Let's manage IAM Permissions for GCP AI Notebooks

Get started with Pulumi Cloud, then follow our quick setup guide to deploy this infrastructure.

Try Pulumi Cloud for FREE

Frequently Asked Questions

Migration & Deprecation

Should I migrate from gcp.notebooks.Instance to gcp.workbench.Instance?

Yes, gcp.notebooks.Instance is deprecated and will be removed in a future major release. Migrate to gcp.workbench.Instance instead.

Resource Selection & Conflicts

What's the difference between InstanceIamPolicy, InstanceIamBinding, and InstanceIamMember?

Each serves a different use case:

InstanceIamPolicy: Authoritative, replaces the entire IAM policy
InstanceIamBinding: Authoritative for a specific role, preserves other roles
InstanceIamMember: Non-authoritative, adds a single member to a role while preserving other members

Can I use InstanceIamPolicy with InstanceIamBinding or InstanceIamMember?

No, InstanceIamPolicy cannot be used with InstanceIamBinding or InstanceIamMember because they will conflict over the policy.

Can I use InstanceIamBinding and InstanceIamMember together?

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

Configuration & Identity Management

What identity formats are supported for the member property?

The member property supports multiple formats:

allUsers: Anyone on the internet
allAuthenticatedUsers: Anyone with a Google account
user:{email}: Specific Google account (e.g., user:alice@gmail.com)
serviceAccount:{email}: Service account (e.g., serviceAccount:my-app@appspot.gserviceaccount.com)
group:{email}: Google group (e.g., group:admins@example.com)
domain:{domain}: G Suite domain (e.g., domain:example.com)
projectOwner:projectid, projectEditor:projectid, projectViewer:projectid: Project-level roles
Federated identities (see Principal identifiers documentation)

How do I specify a custom IAM role?

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

Do I need to specify location and project?

Not necessarily. If not specified, location and project will be parsed from the parent resource identifier. If not available there, they’re taken from the provider configuration.

Resource Management

What properties can I change after creating an InstanceIamMember?

None. All properties (instanceName, location, member, project, role, and condition) are immutable and require resource replacement if changed.

How do I import an existing IAM member?

Use space-delimited identifiers with the resource path, role, and member identity. For example:

pulumi import gcp:notebooks/instanceIamMember:InstanceIamMember editor "projects/{{project}}/locations/{{location}}/instances/{{instance_name}} roles/viewer user:jane@example.com"

Using a different cloud?

Explore iam guides for other cloud providers:

AWS Guides Azure Guides