Manage GCP Billing Account IAM Bindings

The gcp:billing/accountIamBinding:AccountIamBinding resource, part of the Pulumi GCP provider, manages IAM role bindings for GCP billing accounts, controlling who can view costs, manage budgets, and link projects. This guide focuses on two capabilities: authoritative role binding management and choosing between Policy, Binding, and Member resources.

These resources reference existing billing accounts by ID and assume users, groups, and service accounts already exist in your organization. The examples are intentionally small. Combine them with your own billing account IDs and identity management.

Replace the entire IAM policy for a billing account

Organizations that need complete control over billing access use AccountIamPolicy to define all role bindings in one place, replacing any existing policy.

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

The getIAMPolicy function constructs a policy document with role bindings. AccountIamPolicy applies this policy to the billing account, replacing whatever policy existed before. This approach is authoritative: any roles not listed in the policy are removed. Be careful not to accidentally remove billing administrators.

Grant a role to multiple members authoritatively

Teams managing specific roles use AccountIamBinding to define the complete member list for that role while preserving other roles.

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

AccountIamBinding is authoritative for the specified role only. The members array lists everyone who should have roles/billing.viewer; anyone not in this list loses that role. Other roles in the billing account’s policy remain unchanged. This is safer than AccountIamPolicy when you only need to manage one role.

Add a single member to a role non-authoritatively

When multiple teams manage billing access independently, AccountIamMember allows adding individual members without coordinating the full member list.

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

AccountIamMember is non-authoritative: it adds one member to one role without affecting other members of that role. Multiple AccountIamMember resources can grant the same role to different members. This is the safest approach when access is managed by multiple teams or automation systems.

Beyond these examples

These snippets focus on specific billing account IAM features: authoritative vs non-authoritative management and role-level and member-level access control. They’re intentionally minimal rather than full identity management solutions.

The examples reference pre-existing infrastructure such as billing accounts with known IDs. They focus on configuring IAM bindings rather than provisioning billing accounts or identities.

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

Conditional IAM bindings (condition property)
Custom role definitions and formatting
Service account creation and management
Group membership and domain-wide delegation

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 Billing Account IAM Binding resource reference for all available configuration options.

Let's manage GCP Billing Account IAM Bindings

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 & Compatibility

What's the difference between AccountIamPolicy, AccountIamBinding, and AccountIamMember?

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

Which IAM resources can I use together?

You cannot use AccountIamPolicy with AccountIamBinding or AccountIamMember (they’ll conflict). You can use AccountIamBinding with AccountIamMember, but only if they manage different roles.

Why should I be careful when using AccountIamPolicy?

AccountIamPolicy replaces the entire IAM policy, which can accidentally remove existing permissions, including billing account ownership. Ensure all necessary bindings are included when using this resource.

Configuration & Syntax

What format should I use for custom roles?

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

What member identity formats are supported?

Four formats are supported:

user:{emailid} for specific Google accounts
serviceAccount:{emailid} for service accounts
group:{emailid} for Google groups
domain:{domain} for G Suite domains

Immutability & Limitations

What properties can't I change after creating an AccountIamBinding?

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

Using a different cloud?

Explore security guides for other cloud providers:

AWS Guides Azure Guides