Manage GCP Tag Key IAM Policies

The gcp:tags/tagKeyIamPolicy:TagKeyIamPolicy resource, part of the Pulumi GCP provider, manages IAM policies for tag keys, controlling who can view, edit, or administer tags. This guide focuses on three capabilities: authoritative policy replacement, role-specific member management, and time-based access with IAM Conditions.

GCP provides three IAM resources for tag keys: TagKeyIamPolicy (authoritative, replaces entire policy), TagKeyIamBinding (authoritative for one role), and TagKeyIamMember (non-authoritative, adds single members). These resources reference existing TagKey resources and cannot be mixed without causing conflicts. The examples are intentionally small. Choose the resource that matches your management style and combine it with your own tag key infrastructure.

Replace the entire IAM policy for a tag key

When you need complete control over tag key access, TagKeyIamPolicy replaces the entire IAM policy with your specified 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.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

The policyData property accepts output from getIAMPolicy, which defines roles and members. TagKeyIamPolicy is authoritative: it removes any existing bindings not in your policy. Use this when you want to manage the complete access list in one place, but avoid combining it with TagKeyIamBinding or TagKeyIamMember on the same tag key.

Grant a role to multiple members on a tag key

TagKeyIamBinding manages all members for a single role while preserving other roles in the policy.

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

The members array lists all identities that should have this role. TagKeyIamBinding is authoritative for the specified role: it replaces the member list for that role but leaves other roles untouched. You can use multiple TagKeyIamBinding resources for different roles on the same tag key, or combine them with TagKeyIamMember as long as they don’t target the same role.

Add a single member to a tag key role

When you need to grant access to one person without managing the full member list, TagKeyIamMember adds a single member non-authoritatively.

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

The member property specifies one identity to grant the role. TagKeyIamMember is non-authoritative: it adds this member without affecting other members who already have the role. Use this when different teams manage access independently, or when you want to grant access without knowing who else has it.

Apply time-based access with IAM Conditions

IAM Conditions restrict when permissions are active, such as granting temporary access that expires automatically.

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"],
        condition: {
            title: "expires_after_2019_12_31",
            description: "Expiring at midnight of 2019-12-31",
            expression: "request.time < timestamp(\"2020-01-01T00:00:00Z\")",
        },
    }],
});
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"],
    "condition": {
        "title": "expires_after_2019_12_31",
        "description": "Expiring at midnight of 2019-12-31",
        "expression": "request.time < timestamp(\"2020-01-01T00:00:00Z\")",
    },
}])
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",
					},
					Condition: {
						Title:       "expires_after_2019_12_31",
						Description: pulumi.StringRef("Expiring at midnight of 2019-12-31"),
						Expression:  "request.time < timestamp(\"2020-01-01T00:00:00Z\")",
					},
				},
			},
		}, 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",
                },
                Condition = new Gcp.Organizations.Inputs.GetIAMPolicyBindingConditionInputArgs
                {
                    Title = "expires_after_2019_12_31",
                    Description = "Expiring at midnight of 2019-12-31",
                    Expression = "request.time < timestamp(\"2020-01-01T00:00:00Z\")",
                },
            },
        },
    });

    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")
                .condition(GetIAMPolicyBindingConditionArgs.builder()
                    .title("expires_after_2019_12_31")
                    .description("Expiring at midnight of 2019-12-31")
                    .expression("request.time < timestamp(\"2020-01-01T00:00:00Z\")")
                    .build())
                .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
            condition:
              title: expires_after_2019_12_31
              description: Expiring at midnight of 2019-12-31
              expression: request.time < timestamp("2020-01-01T00:00:00Z")

The condition block adds constraints to role bindings. The expression property uses CEL (Common Expression Language) to define when the binding is active. Here, the timestamp comparison grants access only until 2020-01-01. Conditions work with all three IAM resources (Policy, Binding, Member) but have known limitations documented by Google Cloud.

Beyond these examples

These snippets focus on specific tag key IAM features: authoritative vs non-authoritative IAM management and IAM Conditions for time-based access. They’re intentionally minimal rather than full access control systems.

The examples reference pre-existing infrastructure such as TagKey resources (referenced by key.name). They focus on configuring IAM policies rather than creating the tag keys themselves.

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

  • Combining Policy with Binding/Member resources (causes conflicts)
  • Custom role references (require full path format)
  • IAM Conditions limitations and edge cases
  • Audit logging and policy change tracking

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 individual members while preserving existing members for that role.
Can I use TagKeyIamPolicy together with TagKeyIamBinding or TagKeyIamMember?
No, TagKeyIamPolicy cannot be used with TagKeyIamBinding or TagKeyIamMember because they will conflict over the policy state.
Can I use TagKeyIamBinding and TagKeyIamMember together?
Yes, but only if they don’t grant privileges to the same role. Using both for the same role will cause conflicts.
Configuration & Usage
How do I set up an IAM policy for a tag key?
Use gcp.organizations.getIAMPolicy to generate policy data, then pass it to TagKeyIamPolicy via the policyData property along with the tagKey identifier.
Can I change the tagKey after creating the resource?
No, tagKey is immutable and cannot be changed after resource creation.
IAM Conditions
How do I add time-based or conditional IAM policies?
Add a condition block to your binding with title, description, and expression fields. For example, use request.time < timestamp("2020-01-01T00:00:00Z") for time-based expiration.
Are there any limitations when using IAM Conditions?
Yes, IAM Conditions have known limitations. Review the GCP documentation on IAM Conditions limitations if you encounter issues.
Import & Custom Roles
What identifier formats can I use when importing tag key IAM resources?
You can use either tagKeys/{{name}} or just {{name}} as the resource identifier during import.
How do I import IAM resources that use custom roles?
Use the full custom role name in the format [projects/my-project|organizations/my-org]/roles/my-custom-role instead of just the role name.

Using a different cloud?

Explore security guides for other cloud providers:

AWS Guides Azure Guides