Manage GCP Tag Key IAM Policies

The gcp:tags/tagKeyIamPolicy:TagKeyIamPolicy resource, part of the Pulumi GCP provider, manages IAM policies for GCP tag keys, controlling who can view, edit, or delete tags. This guide focuses on three capabilities: authoritative policy replacement, role-based member binding, and incremental member addition.

Tag key IAM resources reference existing TagKey resources. The three resource types (Policy, Binding, Member) serve different use cases and have compatibility constraints: TagKeyIamPolicy cannot be used with TagKeyIamBinding or TagKeyIamMember, as they conflict over policy ownership. The examples are intentionally small. Choose the resource type that matches your access management pattern.

Replace the entire IAM policy for a tag key

When you need complete control over permissions, you can set the entire IAM policy at once, replacing any existing policy.

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.tags.TagKeyIamPolicy("policy", {
    tagKey: key.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.tags.TagKeyIamPolicy("policy",
    tag_key=key["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/tags"
	"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 = tags.NewTagKeyIamPolicy(ctx, "policy", &tags.TagKeyIamPolicyArgs{
			TagKey:     pulumi.Any(key.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.Tags.TagKeyIamPolicy("policy", new()
    {
        TagKey = key.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.tags.TagKeyIamPolicy;
import com.pulumi.gcp.tags.TagKeyIamPolicyArgs;
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 TagKeyIamPolicy("policy", TagKeyIamPolicyArgs.builder()
            .tagKey(key.name())
            .policyData(admin.policyData())
            .build());

    }
}

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

TagKeyIamPolicy is authoritative: it replaces the entire policy attached to the tag key. The policyData property comes from the getIAMPolicy data source, which constructs a policy document from role-member bindings. This approach ensures no unexpected permissions remain, but requires managing all roles and members together.

Grant a role to multiple members at once

Teams often need to grant the same role to several users or service accounts without affecting other roles.

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

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

import pulumi
import pulumi_gcp as gcp

binding = gcp.tags.TagKeyIamBinding("binding",
    tag_key=key["name"],
    role="roles/viewer",
    members=["user:jane@example.com"])

package main

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

func main() {
	pulumi.Run(func(ctx *pulumi.Context) error {
		_, err := tags.NewTagKeyIamBinding(ctx, "binding", &tags.TagKeyIamBindingArgs{
			TagKey: pulumi.Any(key.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.Tags.TagKeyIamBinding("binding", new()
    {
        TagKey = key.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.tags.TagKeyIamBinding;
import com.pulumi.gcp.tags.TagKeyIamBindingArgs;
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 TagKeyIamBinding("binding", TagKeyIamBindingArgs.builder()
            .tagKey(key.name())
            .role("roles/viewer")
            .members("user:jane@example.com")
            .build());

    }
}

resources:
  binding:
    type: gcp:tags:TagKeyIamBinding
    properties:
      tagKey: ${key.name}
      role: roles/viewer
      members:
        - user:jane@example.com

TagKeyIamBinding manages all members for a single role. The members property lists user accounts, service accounts, or groups. Other roles on the tag key remain unchanged. You can use multiple Binding resources for different roles, but each role can only have one Binding resource.

Add a single member to a role incrementally

When you need to grant access to one user without managing the full member list, non-authoritative member resources let you add individuals incrementally.

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

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

import pulumi
import pulumi_gcp as gcp

member = gcp.tags.TagKeyIamMember("member",
    tag_key=key["name"],
    role="roles/viewer",
    member="user:jane@example.com")

package main

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

func main() {
	pulumi.Run(func(ctx *pulumi.Context) error {
		_, err := tags.NewTagKeyIamMember(ctx, "member", &tags.TagKeyIamMemberArgs{
			TagKey: pulumi.Any(key.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.Tags.TagKeyIamMember("member", new()
    {
        TagKey = key.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.tags.TagKeyIamMember;
import com.pulumi.gcp.tags.TagKeyIamMemberArgs;
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 TagKeyIamMember("member", TagKeyIamMemberArgs.builder()
            .tagKey(key.name())
            .role("roles/viewer")
            .member("user:jane@example.com")
            .build());

    }
}

resources:
  member:
    type: gcp:tags:TagKeyIamMember
    properties:
      tagKey: ${key.name}
      role: roles/viewer
      member: user:jane@example.com

TagKeyIamMember is non-authoritative: it adds one member to a role without affecting other members. The member property specifies a single identity (user, service account, or group). You can create multiple Member resources for the same role, and they coexist with Binding resources as long as they target different roles.

Beyond these examples

These snippets focus on specific IAM management patterns: authoritative vs non-authoritative updates, and policy, binding, and member resource types. They’re intentionally minimal rather than full access control configurations.

The examples reference pre-existing infrastructure such as TagKey resources (referenced by key.name). They focus on IAM policy configuration rather than tag key creation.

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

IAM conditions for time-based or attribute-based access
Custom roles (require full role path)
Service account impersonation
Audit logging configuration

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

Let's manage GCP Tag Key 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 TagKeyIamPolicy, TagKeyIamBinding, and TagKeyIamMember?

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

Can I use TagKeyIamPolicy with TagKeyIamBinding or TagKeyIamMember?

No. TagKeyIamPolicy cannot be used alongside TagKeyIamBinding or TagKeyIamMember because they will conflict over the policy state.

Can I use TagKeyIamBinding and TagKeyIamMember together?

Yes, but only if they grant different roles. Using both for the same role causes conflicts.

Configuration & Setup

How do I generate the policyData for TagKeyIamPolicy?

Use the gcp.organizations.getIAMPolicy data source to generate policyData, as shown in the example.

Can I change the tagKey after creating the resource?

No. The tagKey property is immutable and cannot be changed after creation.

What format should I use for the tagKey property?

Use either tagKeys/{{name}} or just {{name}}. Both formats are accepted.

Import & Custom Roles

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

Use the full role name format: [projects/my-project|organizations/my-org]/roles/my-custom-role. Standard roles like roles/viewer don’t require this format.

Using a different cloud?

Explore security guides for other cloud providers:

AWS Guides Azure Guides