Manage GCP GKE Hub Membership IAM Policies

The gcp:gkehub/membershipIamPolicy:MembershipIamPolicy resource, part of the Pulumi GCP provider, manages IAM policies for GKE Hub memberships, controlling who can access and manage registered clusters. This guide focuses on three capabilities: authoritative policy replacement, role-based member binding, and incremental member grants.

GCP provides three related resources for membership IAM: MembershipIamPolicy (authoritative for all roles), MembershipIamBinding (authoritative per role), and MembershipIamMember (non-authoritative per member). MembershipIamPolicy cannot be used with the other two resources, as they will conflict over policy state. The examples are intentionally small. Combine them with your own membership references and IAM principals.

Set the complete IAM policy for a membership

When you need full control over all IAM bindings, you can replace the entire policy in one operation. This approach removes any existing bindings not defined in your configuration.

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.gkehub.MembershipIamPolicy("policy", {
    project: membership.project,
    location: membership.location,
    membershipId: membership.membershipId,
    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.gkehub.MembershipIamPolicy("policy",
    project=membership["project"],
    location=membership["location"],
    membership_id=membership["membershipId"],
    policy_data=admin.policy_data)

package main

import (
	"github.com/pulumi/pulumi-gcp/sdk/v9/go/gcp/gkehub"
	"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 = gkehub.NewMembershipIamPolicy(ctx, "policy", &gkehub.MembershipIamPolicyArgs{
			Project:      pulumi.Any(membership.Project),
			Location:     pulumi.Any(membership.Location),
			MembershipId: pulumi.Any(membership.MembershipId),
			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.GkeHub.MembershipIamPolicy("policy", new()
    {
        Project = membership.Project,
        Location = membership.Location,
        MembershipId = membership.MembershipId,
        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.gkehub.MembershipIamPolicy;
import com.pulumi.gcp.gkehub.MembershipIamPolicyArgs;
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 MembershipIamPolicy("policy", MembershipIamPolicyArgs.builder()
            .project(membership.project())
            .location(membership.location())
            .membershipId(membership.membershipId())
            .policyData(admin.policyData())
            .build());

    }
}

resources:
  policy:
    type: gcp:gkehub:MembershipIamPolicy
    properties:
      project: ${membership.project}
      location: ${membership.location}
      membershipId: ${membership.membershipId}
      policyData: ${admin.policyData}
variables:
  admin:
    fn::invoke:
      function: gcp:organizations:getIAMPolicy
      arguments:
        bindings:
          - role: roles/viewer
            members:
              - user:jane@example.com

The policyData property accepts output from the getIAMPolicy data source, which defines bindings as role-member pairs. MembershipIamPolicy is authoritative: it replaces the entire policy, removing any bindings you don’t explicitly define. The membershipId, location, and project properties identify which membership to manage.

Grant a role to multiple members at once

When multiple users or service accounts need the same role, you can bind them all in a single resource while preserving other roles in the policy.

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

const binding = new gcp.gkehub.MembershipIamBinding("binding", {
    project: membership.project,
    location: membership.location,
    membershipId: membership.membershipId,
    role: "roles/viewer",
    members: ["user:jane@example.com"],
});

import pulumi
import pulumi_gcp as gcp

binding = gcp.gkehub.MembershipIamBinding("binding",
    project=membership["project"],
    location=membership["location"],
    membership_id=membership["membershipId"],
    role="roles/viewer",
    members=["user:jane@example.com"])

package main

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

func main() {
	pulumi.Run(func(ctx *pulumi.Context) error {
		_, err := gkehub.NewMembershipIamBinding(ctx, "binding", &gkehub.MembershipIamBindingArgs{
			Project:      pulumi.Any(membership.Project),
			Location:     pulumi.Any(membership.Location),
			MembershipId: pulumi.Any(membership.MembershipId),
			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.GkeHub.MembershipIamBinding("binding", new()
    {
        Project = membership.Project,
        Location = membership.Location,
        MembershipId = membership.MembershipId,
        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.gkehub.MembershipIamBinding;
import com.pulumi.gcp.gkehub.MembershipIamBindingArgs;
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 MembershipIamBinding("binding", MembershipIamBindingArgs.builder()
            .project(membership.project())
            .location(membership.location())
            .membershipId(membership.membershipId())
            .role("roles/viewer")
            .members("user:jane@example.com")
            .build());

    }
}

resources:
  binding:
    type: gcp:gkehub:MembershipIamBinding
    properties:
      project: ${membership.project}
      location: ${membership.location}
      membershipId: ${membership.membershipId}
      role: roles/viewer
      members:
        - user:jane@example.com

MembershipIamBinding is authoritative for the specified role but preserves other roles. The members property accepts a list of principals (users, service accounts, groups). If you later remove a member from the list, they lose access; if you add one, they gain it.

Add a single member to a role incrementally

When you need to grant access to one principal without affecting existing bindings, you can add them individually.

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

const member = new gcp.gkehub.MembershipIamMember("member", {
    project: membership.project,
    location: membership.location,
    membershipId: membership.membershipId,
    role: "roles/viewer",
    member: "user:jane@example.com",
});

import pulumi
import pulumi_gcp as gcp

member = gcp.gkehub.MembershipIamMember("member",
    project=membership["project"],
    location=membership["location"],
    membership_id=membership["membershipId"],
    role="roles/viewer",
    member="user:jane@example.com")

package main

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

func main() {
	pulumi.Run(func(ctx *pulumi.Context) error {
		_, err := gkehub.NewMembershipIamMember(ctx, "member", &gkehub.MembershipIamMemberArgs{
			Project:      pulumi.Any(membership.Project),
			Location:     pulumi.Any(membership.Location),
			MembershipId: pulumi.Any(membership.MembershipId),
			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.GkeHub.MembershipIamMember("member", new()
    {
        Project = membership.Project,
        Location = membership.Location,
        MembershipId = membership.MembershipId,
        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.gkehub.MembershipIamMember;
import com.pulumi.gcp.gkehub.MembershipIamMemberArgs;
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 MembershipIamMember("member", MembershipIamMemberArgs.builder()
            .project(membership.project())
            .location(membership.location())
            .membershipId(membership.membershipId())
            .role("roles/viewer")
            .member("user:jane@example.com")
            .build());

    }
}

resources:
  member:
    type: gcp:gkehub:MembershipIamMember
    properties:
      project: ${membership.project}
      location: ${membership.location}
      membershipId: ${membership.membershipId}
      role: roles/viewer
      member: user:jane@example.com

MembershipIamMember is non-authoritative: it adds one member to a role without removing others. The member property accepts a single principal. You can combine multiple MembershipIamMember resources for the same role, or mix them with MembershipIamBinding resources for different roles.

Beyond these examples

These snippets focus on specific IAM management approaches: authoritative vs non-authoritative IAM management, and role-based and member-based bindings. They’re intentionally minimal rather than full access control configurations.

The examples reference pre-existing infrastructure such as GKE Hub memberships (project, location, membershipId). They focus on IAM policy configuration rather than provisioning the membership itself.

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

Conditional IAM bindings (condition blocks)
Multiple roles in a single resource
Custom role definitions
Service account creation and management

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 GKE Hub MembershipIamPolicy resource reference for all available configuration options.

Let's manage GCP GKE Hub Membership 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 MembershipIamPolicy, MembershipIamBinding, and MembershipIamMember?

MembershipIamPolicy is authoritative and replaces the entire IAM policy. MembershipIamBinding is authoritative for a specific role but preserves other roles in the policy. MembershipIamMember is non-authoritative and preserves other members for the same role.

Can I use MembershipIamPolicy with MembershipIamBinding or MembershipIamMember?

No, MembershipIamPolicy cannot be used with MembershipIamBinding or MembershipIamMember because they will conflict over the policy. However, MembershipIamBinding and MembershipIamMember can be used together if they don’t grant privileges to the same role.

Configuration & Setup

How do I generate the policyData for MembershipIamPolicy?

Use the gcp.organizations.getIAMPolicy data source to generate the policy data, then pass it to the policyData property as shown in the examples.

What's the default location for a membership?

The default location is global. If not specified, the value is parsed from the parent resource identifier or taken from the provider configuration.

Which properties are immutable after creation?

The location, membershipId, and project properties are all immutable and cannot be changed after the resource is created.

Import & Migration

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

Use the full name of the custom role in the format [projects/my-project|organizations/my-org]/roles/my-custom-role when importing.

Using a different cloud?

Explore security guides for other cloud providers:

AWS Guides Azure Guides