Manage GCP Billing Account IAM Members

The gcp:billing/accountIamMember:AccountIamMember resource, part of the Pulumi GCP provider, grants IAM permissions on GCP billing accounts by adding individual members to roles without affecting other members or roles. This guide focuses on three capabilities: non-authoritative member grants, role-level binding management, and complete policy replacement.

GCP provides three resources for billing account IAM: AccountIamPolicy (replaces entire policy), AccountIamBinding (manages all members for one role), and AccountIamMember (adds individual members). AccountIamPolicy cannot be used with the other two; they conflict over policy ownership. The examples are intentionally small. Choose the resource that matches your authority level and combine it with your own billing account IDs.

Add a single member to a role incrementally

Most teams grant billing permissions as new users join or service accounts are created. AccountIamMember adds one member without affecting others.

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

const editor = new gcp.billing.AccountIamMember("editor", {
    billingAccountId: "00AA00-000AAA-00AA0A",
    role: "roles/billing.viewer",
    member: "user:jane@example.com",
});

import pulumi
import pulumi_gcp as gcp

editor = gcp.billing.AccountIamMember("editor",
    billing_account_id="00AA00-000AAA-00AA0A",
    role="roles/billing.viewer",
    member="user:jane@example.com")

package main

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

func main() {
	pulumi.Run(func(ctx *pulumi.Context) error {
		_, err := billing.NewAccountIamMember(ctx, "editor", &billing.AccountIamMemberArgs{
			BillingAccountId: pulumi.String("00AA00-000AAA-00AA0A"),
			Role:             pulumi.String("roles/billing.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 editor = new Gcp.Billing.AccountIamMember("editor", new()
    {
        BillingAccountId = "00AA00-000AAA-00AA0A",
        Role = "roles/billing.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.billing.AccountIamMember;
import com.pulumi.gcp.billing.AccountIamMemberArgs;
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 editor = new AccountIamMember("editor", AccountIamMemberArgs.builder()
            .billingAccountId("00AA00-000AAA-00AA0A")
            .role("roles/billing.viewer")
            .member("user:jane@example.com")
            .build());

    }
}

resources:
  editor:
    type: gcp:billing:AccountIamMember
    properties:
      billingAccountId: 00AA00-000AAA-00AA0A
      role: roles/billing.viewer
      member: user:jane@example.com

The member property specifies the identity to grant access: user:{email}, serviceAccount:{email}, group:{email}, or domain:{domain}. The role property names the permission set to grant. This is non-authoritative: other members with the same role and other roles in the policy remain unchanged.

Grant a role to multiple members at once

When several users or service accounts need the same role, AccountIamBinding manages them together.

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

const editor = new gcp.billing.AccountIamBinding("editor", {
    billingAccountId: "00AA00-000AAA-00AA0A",
    role: "roles/billing.viewer",
    members: ["user:jane@example.com"],
});

import pulumi
import pulumi_gcp as gcp

editor = gcp.billing.AccountIamBinding("editor",
    billing_account_id="00AA00-000AAA-00AA0A",
    role="roles/billing.viewer",
    members=["user:jane@example.com"])

package main

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

func main() {
	pulumi.Run(func(ctx *pulumi.Context) error {
		_, err := billing.NewAccountIamBinding(ctx, "editor", &billing.AccountIamBindingArgs{
			BillingAccountId: pulumi.String("00AA00-000AAA-00AA0A"),
			Role:             pulumi.String("roles/billing.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 editor = new Gcp.Billing.AccountIamBinding("editor", new()
    {
        BillingAccountId = "00AA00-000AAA-00AA0A",
        Role = "roles/billing.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.billing.AccountIamBinding;
import com.pulumi.gcp.billing.AccountIamBindingArgs;
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 editor = new AccountIamBinding("editor", AccountIamBindingArgs.builder()
            .billingAccountId("00AA00-000AAA-00AA0A")
            .role("roles/billing.viewer")
            .members("user:jane@example.com")
            .build());

    }
}

resources:
  editor:
    type: gcp:billing:AccountIamBinding
    properties:
      billingAccountId: 00AA00-000AAA-00AA0A
      role: roles/billing.viewer
      members:
        - user:jane@example.com

The members property lists all identities that should have this role. AccountIamBinding is authoritative for this specific role: it replaces the member list for roles/billing.viewer but preserves other roles in the policy. Use this when you want to define all members for a role in one place.

Replace the entire IAM policy for a billing account

Some teams define the complete IAM policy in one place, replacing any existing bindings.

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

const admin = gcp.organizations.getIAMPolicy({
    bindings: [{
        role: "roles/billing.viewer",
        members: ["user:jane@example.com"],
    }],
});
const editor = new gcp.billing.AccountIamPolicy("editor", {
    billingAccountId: "00AA00-000AAA-00AA0A",
    policyData: admin.then(admin => admin.policyData),
});

import pulumi
import pulumi_gcp as gcp

admin = gcp.organizations.get_iam_policy(bindings=[{
    "role": "roles/billing.viewer",
    "members": ["user:jane@example.com"],
}])
editor = gcp.billing.AccountIamPolicy("editor",
    billing_account_id="00AA00-000AAA-00AA0A",
    policy_data=admin.policy_data)

package main

import (
	"github.com/pulumi/pulumi-gcp/sdk/v9/go/gcp/billing"
	"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/billing.viewer",
					Members: []string{
						"user:jane@example.com",
					},
				},
			},
		}, nil)
		if err != nil {
			return err
		}
		_, err = billing.NewAccountIamPolicy(ctx, "editor", &billing.AccountIamPolicyArgs{
			BillingAccountId: pulumi.String("00AA00-000AAA-00AA0A"),
			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/billing.viewer",
                Members = new[]
                {
                    "user:jane@example.com",
                },
            },
        },
    });

    var editor = new Gcp.Billing.AccountIamPolicy("editor", new()
    {
        BillingAccountId = "00AA00-000AAA-00AA0A",
        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.billing.AccountIamPolicy;
import com.pulumi.gcp.billing.AccountIamPolicyArgs;
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/billing.viewer")
                .members("user:jane@example.com")
                .build())
            .build());

        var editor = new AccountIamPolicy("editor", AccountIamPolicyArgs.builder()
            .billingAccountId("00AA00-000AAA-00AA0A")
            .policyData(admin.policyData())
            .build());

    }
}

resources:
  editor:
    type: gcp:billing:AccountIamPolicy
    properties:
      billingAccountId: 00AA00-000AAA-00AA0A
      policyData: ${admin.policyData}
variables:
  admin:
    fn::invoke:
      function: gcp:organizations:getIAMPolicy
      arguments:
        bindings:
          - role: roles/billing.viewer
            members:
              - user:jane@example.com

AccountIamPolicy takes a policyData object from getIAMPolicy, which defines all role bindings. This resource is fully authoritative: it replaces the entire policy, removing any bindings not specified. Use this only when you need complete control and can safely manage all permissions in your Pulumi stack.

Beyond these examples

These snippets focus on specific IAM management features: authoritative vs non-authoritative IAM management, and single-member and multi-member role grants. They’re intentionally minimal rather than full access control systems.

The examples reference pre-existing infrastructure such as GCP billing accounts with known IDs. They focus on granting permissions rather than creating billing accounts or service accounts.

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

Conditional IAM bindings (condition property)
Custom role definitions and formats
Service account creation and management
IAM policy auditing and drift detection

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

Let's manage GCP Billing Account IAM Members

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 AccountIamPolicy, AccountIamBinding, and AccountIamMember?

gcp.billing.AccountIamPolicy is authoritative and replaces the entire IAM policy. gcp.billing.AccountIamBinding is authoritative for a specific role, preserving other roles. gcp.billing.AccountIamMember is non-authoritative and adds a single member to a role without affecting other members.

Can I use multiple IAM resources together on the same billing account?

gcp.billing.AccountIamPolicy cannot be used with gcp.billing.AccountIamBinding or gcp.billing.AccountIamMember, as they will conflict. However, gcp.billing.AccountIamBinding and gcp.billing.AccountIamMember can be used together only if they don’t grant privilege to the same role.

What should I watch out for when using AccountIamPolicy?

gcp.billing.AccountIamPolicy replaces the entire IAM policy, which can accidentally remove billing account ownership. Ensure all necessary bindings, including ownership, are included in your policy.

Configuration & Formats

What member identity formats are supported?

Four formats are supported:

user:{email} for specific Google accounts (e.g., alice@gmail.com)
serviceAccount:{email} for service accounts (e.g., my-app@appspot.gserviceaccount.com)
group:{email} for Google groups (e.g., admins@example.com)
domain:{domain} for G Suite domains (e.g., example.com)

How do I specify custom roles?

Custom roles must follow the format [projects|organizations]/{parent-name}/roles/{role-name}.

Immutability & Limitations

What properties can't I change after creating the resource?

The billingAccountId, member, role, and condition properties are all immutable and require resource replacement if changed.

Using a different cloud?

Explore security guides for other cloud providers:

AWS Guides Azure Guides