Manage GCP Tag Value IAM Policies

The gcp:tags/tagValueIamPolicy:TagValueIamPolicy resource, part of the Pulumi GCP provider, manages IAM permissions for GCP tag values, controlling who can view, edit, or administer tags. This guide focuses on three approaches: authoritative policy replacement (TagValueIamPolicy), role-level member management (TagValueIamBinding), and incremental member addition (TagValueIamMember).

These three resources reference existing tag values and cannot be mixed. TagValueIamPolicy conflicts with TagValueIamBinding and TagValueIamMember because they use different update strategies. The examples are intentionally small. Choose the resource that matches your permission management style.

Replace the entire IAM policy for a tag value

When you need complete control over permissions, TagValueIamPolicy sets the entire IAM policy at once, replacing any 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.tags.TagValueIamPolicy("policy", {
    tagValue: value.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.TagValueIamPolicy("policy",
    tag_value=value["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.NewTagValueIamPolicy(ctx, "policy", &tags.TagValueIamPolicyArgs{
			TagValue:   pulumi.Any(value.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.TagValueIamPolicy("policy", new()
    {
        TagValue = @value.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.TagValueIamPolicy;
import com.pulumi.gcp.tags.TagValueIamPolicyArgs;
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 TagValueIamPolicy("policy", TagValueIamPolicyArgs.builder()
            .tagValue(value.name())
            .policyData(admin.policyData())
            .build());

    }
}

resources:
  policy:
    type: gcp:tags:TagValueIamPolicy
    properties:
      tagValue: ${value.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 comes from the getIAMPolicy data source, which constructs a complete policy document from role-member bindings. TagValueIamPolicy is authoritative: it replaces all existing permissions on the tag value with the specified policy.

Grant a role to multiple members at once

TagValueIamBinding manages all members for a single role while preserving other roles on the tag value.

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

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

import pulumi
import pulumi_gcp as gcp

binding = gcp.tags.TagValueIamBinding("binding",
    tag_value=value["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.NewTagValueIamBinding(ctx, "binding", &tags.TagValueIamBindingArgs{
			TagValue: pulumi.Any(value.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.TagValueIamBinding("binding", new()
    {
        TagValue = @value.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.TagValueIamBinding;
import com.pulumi.gcp.tags.TagValueIamBindingArgs;
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 TagValueIamBinding("binding", TagValueIamBindingArgs.builder()
            .tagValue(value.name())
            .role("roles/viewer")
            .members("user:jane@example.com")
            .build());

    }
}

resources:
  binding:
    type: gcp:tags:TagValueIamBinding
    properties:
      tagValue: ${value.name}
      role: roles/viewer
      members:
        - user:jane@example.com

The members array lists all identities that should have the specified role. TagValueIamBinding is authoritative for this role only: it replaces all members for roles/viewer but leaves other roles unchanged. You can use multiple TagValueIamBinding resources for different roles.

Add a single member to a role incrementally

When you need to grant access to one user without affecting existing permissions, TagValueIamMember adds a single member non-authoritatively.

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

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

import pulumi
import pulumi_gcp as gcp

member = gcp.tags.TagValueIamMember("member",
    tag_value=value["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.NewTagValueIamMember(ctx, "member", &tags.TagValueIamMemberArgs{
			TagValue: pulumi.Any(value.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.TagValueIamMember("member", new()
    {
        TagValue = @value.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.TagValueIamMember;
import com.pulumi.gcp.tags.TagValueIamMemberArgs;
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 TagValueIamMember("member", TagValueIamMemberArgs.builder()
            .tagValue(value.name())
            .role("roles/viewer")
            .member("user:jane@example.com")
            .build());

    }
}

resources:
  member:
    type: gcp:tags:TagValueIamMember
    properties:
      tagValue: ${value.name}
      role: roles/viewer
      member: user:jane@example.com

The member property specifies one identity to grant the role. TagValueIamMember is non-authoritative: it adds this member without removing other members who already have the same role. This is the most flexible approach for incremental permission changes.

Beyond these examples

These snippets focus on specific IAM management strategies: authoritative vs non-authoritative updates and role-level vs member-level control. They’re intentionally minimal rather than complete access control configurations.

The examples reference pre-existing infrastructure such as tag values created via gcp.tags.TagValue or referenced by name. They focus on permission assignment rather than tag value creation.

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

Conditional IAM bindings (condition property)
Custom role definitions and references
Service account impersonation
IAM policy retrieval (data source usage)

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

Let's manage GCP Tag Value 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 TagValueIamPolicy, TagValueIamBinding, and TagValueIamMember?

TagValueIamPolicy is authoritative and replaces the entire IAM policy. TagValueIamBinding is authoritative for a specific role, preserving other roles. TagValueIamMember is non-authoritative, adding a single member while preserving other members for that role.

Can I use TagValueIamPolicy with TagValueIamBinding or TagValueIamMember?

No, TagValueIamPolicy cannot be used with TagValueIamBinding or TagValueIamMember because they will conflict over policy control.

Can I use TagValueIamBinding and TagValueIamMember together?

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

Configuration & Immutability

Can I change the tagValue after creation?

No, tagValue is immutable and cannot be changed after the resource is created.

Import & Custom Roles

How does import syntax differ between the IAM resources?

TagValueIamMember requires three space-delimited parts (resource, role, member), TagValueIamBinding requires two (resource, role), and TagValueIamPolicy requires only the resource identifier.

How do I import IAM resources with custom roles?

Use the full role name 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