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. This guide focuses on three capabilities: non-authoritative member grants, authoritative role bindings, 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, or they will conflict. The examples are intentionally small. Choose the resource that matches your control requirements.

Grant a single user access without affecting other members

When adding individual users to billing accounts, AccountIamMember grants access without modifying other members who already have the same role.

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, using formats like “user:jane@example.com” for Google accounts or “serviceAccount:app@project.iam.gserviceaccount.com” for service accounts. The role property defines the permission level. AccountIamMember is non-authoritative: it adds this member without removing others who have the same role.

Manage all members for a specific role

Teams that need to control the complete membership list for a role use AccountIamBinding to define all members at once.

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 the specified role: any existing members not in this list are removed. Other roles on the billing account remain unchanged.

Replace the entire IAM policy for a billing account

Organizations that need complete control over billing account access use AccountIamPolicy to define the entire IAM policy in one place.

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 policyData property comes from getIAMPolicy, which constructs a complete policy document from bindings. AccountIamPolicy is fully authoritative: it replaces the entire IAM policy, removing any permissions not explicitly defined. This can accidentally remove billing account ownership if not carefully managed.

Beyond these examples

These snippets focus on specific IAM management approaches: complete policy replacement (AccountIamPolicy), role-level member management (AccountIamBinding), and individual member grants (AccountIamMember). They’re intentionally minimal rather than full access control configurations.

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

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

Conditional IAM bindings (condition property)
Service account and group member types
Custom role definitions
Policy conflict resolution between resource types

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 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 given 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 these IAM resources together?

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 privileges to the same role.

Why might I lose access to my billing account when using AccountIamPolicy?

gcp.billing.AccountIamPolicy replaces the entire IAM policy, which can accidentally remove existing ownership or permissions. Carefully review your policy data to ensure all necessary permissions are included.

Configuration & Formats

What member identity formats can I use?

You can use four formats: user:{emailid} for specific Google accounts, serviceAccount:{emailid} for service accounts, group:{emailid} for Google groups, and domain:{domain} for G Suite domains.

Which properties can't be changed after creation?

All key properties are immutable: billingAccountId, member, role, and condition. Changing any of these requires recreating the resource.

Using a different cloud?

Explore security guides for other cloud providers:

AWS Guides Azure Guides