Manage GCP Spanner Instance IAM Policies

The gcp:spanner/instanceIAMPolicy:InstanceIAMPolicy resource, part of the Pulumi GCP provider, controls IAM permissions for Spanner instances using three distinct approaches: authoritative policy replacement (InstanceIAMPolicy), role-based binding (InstanceIAMBinding), and incremental member addition (InstanceIAMMember). This guide focuses on three capabilities: replacing the entire policy, binding multiple members to a role, and adding individual members.

These resources reference existing Spanner instances by name. InstanceIAMPolicy cannot be used with InstanceIAMBinding or InstanceIAMMember because they manage permissions differently. The examples are intentionally small. Choose the approach that matches your access control requirements.

Replace the entire IAM policy with a new definition

Some teams define the complete IAM policy from scratch, ensuring it matches exactly what’s declared in code.

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

const admin = gcp.organizations.getIAMPolicy({
    bindings: [{
        role: "roles/editor",
        members: ["user:jane@example.com"],
    }],
});
const instance = new gcp.spanner.InstanceIAMPolicy("instance", {
    instance: "your-instance-name",
    policyData: admin.then(admin => admin.policyData),
});

import pulumi
import pulumi_gcp as gcp

admin = gcp.organizations.get_iam_policy(bindings=[{
    "role": "roles/editor",
    "members": ["user:jane@example.com"],
}])
instance = gcp.spanner.InstanceIAMPolicy("instance",
    instance="your-instance-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/spanner"
	"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/editor",
					Members: []string{
						"user:jane@example.com",
					},
				},
			},
		}, nil)
		if err != nil {
			return err
		}
		_, err = spanner.NewInstanceIAMPolicy(ctx, "instance", &spanner.InstanceIAMPolicyArgs{
			Instance:   pulumi.String("your-instance-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/editor",
                Members = new[]
                {
                    "user:jane@example.com",
                },
            },
        },
    });

    var instance = new Gcp.Spanner.InstanceIAMPolicy("instance", new()
    {
        Instance = "your-instance-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.spanner.InstanceIAMPolicy;
import com.pulumi.gcp.spanner.InstanceIAMPolicyArgs;
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/editor")
                .members("user:jane@example.com")
                .build())
            .build());

        var instance = new InstanceIAMPolicy("instance", InstanceIAMPolicyArgs.builder()
            .instance("your-instance-name")
            .policyData(admin.policyData())
            .build());

    }
}

resources:
  instance:
    type: gcp:spanner:InstanceIAMPolicy
    properties:
      instance: your-instance-name
      policyData: ${admin.policyData}
variables:
  admin:
    fn::invoke:
      function: gcp:organizations:getIAMPolicy
      arguments:
        bindings:
          - role: roles/editor
            members:
              - user:jane@example.com

InstanceIAMPolicy replaces the entire policy, removing any permissions not explicitly declared. The policyData property accepts output from getIAMPolicy, which defines bindings (role and member pairs). This approach can lock you out if you omit your own access, so include all necessary permissions in the policy definition.

Grant a role to multiple members at once

When multiple users or service accounts need the same role, binding them together manages them as a group.

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

const instance = new gcp.spanner.InstanceIAMBinding("instance", {
    instance: "your-instance-name",
    role: "roles/spanner.databaseAdmin",
    members: ["user:jane@example.com"],
});

import pulumi
import pulumi_gcp as gcp

instance = gcp.spanner.InstanceIAMBinding("instance",
    instance="your-instance-name",
    role="roles/spanner.databaseAdmin",
    members=["user:jane@example.com"])

package main

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

func main() {
	pulumi.Run(func(ctx *pulumi.Context) error {
		_, err := spanner.NewInstanceIAMBinding(ctx, "instance", &spanner.InstanceIAMBindingArgs{
			Instance: pulumi.String("your-instance-name"),
			Role:     pulumi.String("roles/spanner.databaseAdmin"),
			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 instance = new Gcp.Spanner.InstanceIAMBinding("instance", new()
    {
        Instance = "your-instance-name",
        Role = "roles/spanner.databaseAdmin",
        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.spanner.InstanceIAMBinding;
import com.pulumi.gcp.spanner.InstanceIAMBindingArgs;
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 instance = new InstanceIAMBinding("instance", InstanceIAMBindingArgs.builder()
            .instance("your-instance-name")
            .role("roles/spanner.databaseAdmin")
            .members("user:jane@example.com")
            .build());

    }
}

resources:
  instance:
    type: gcp:spanner:InstanceIAMBinding
    properties:
      instance: your-instance-name
      role: roles/spanner.databaseAdmin
      members:
        - user:jane@example.com

InstanceIAMBinding assigns a role to a list of members in a single operation. The members array can include users, service accounts, and groups. This resource is authoritative for the specified role but preserves other roles on the instance. You can combine multiple InstanceIAMBinding resources as long as they manage different roles.

Add a single member to a role incrementally

Applications often grant access to individual service accounts without affecting existing role assignments.

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

const instance = new gcp.spanner.InstanceIAMMember("instance", {
    instance: "your-instance-name",
    role: "roles/spanner.databaseAdmin",
    member: "user:jane@example.com",
});

import pulumi
import pulumi_gcp as gcp

instance = gcp.spanner.InstanceIAMMember("instance",
    instance="your-instance-name",
    role="roles/spanner.databaseAdmin",
    member="user:jane@example.com")

package main

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

func main() {
	pulumi.Run(func(ctx *pulumi.Context) error {
		_, err := spanner.NewInstanceIAMMember(ctx, "instance", &spanner.InstanceIAMMemberArgs{
			Instance: pulumi.String("your-instance-name"),
			Role:     pulumi.String("roles/spanner.databaseAdmin"),
			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 instance = new Gcp.Spanner.InstanceIAMMember("instance", new()
    {
        Instance = "your-instance-name",
        Role = "roles/spanner.databaseAdmin",
        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.spanner.InstanceIAMMember;
import com.pulumi.gcp.spanner.InstanceIAMMemberArgs;
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 instance = new InstanceIAMMember("instance", InstanceIAMMemberArgs.builder()
            .instance("your-instance-name")
            .role("roles/spanner.databaseAdmin")
            .member("user:jane@example.com")
            .build());

    }
}

resources:
  instance:
    type: gcp:spanner:InstanceIAMMember
    properties:
      instance: your-instance-name
      role: roles/spanner.databaseAdmin
      member: user:jane@example.com

InstanceIAMMember adds one member to a role while preserving other members who already have that role. The member property accepts a single identity (user, service account, or group). This non-authoritative approach lets you grant permissions incrementally without coordinating with other IAM configurations.

Beyond these examples

These snippets focus on specific IAM management approaches: authoritative policy replacement, role-based binding, and incremental member addition. They’re intentionally minimal rather than full access control configurations.

The examples reference pre-existing infrastructure such as Spanner instances (by name). They focus on IAM permission assignment rather than instance provisioning.

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

Project specification (defaults to provider project)
Conditional IAM bindings
Service account creation
Custom role definitions

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 Spanner Instance IAM Policy resource reference for all available configuration options.

Let's manage GCP Spanner Instance 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

Common Pitfalls & Conflicts

Can I lock myself out of my Spanner instance using InstanceIAMPolicy?

Yes, gcp.spanner.InstanceIAMPolicy is authoritative and replaces the entire IAM policy. Any default permissions will be removed unless you explicitly include them in your configuration.

Which IAM resources can I use together?

You cannot use gcp.spanner.InstanceIAMPolicy with gcp.spanner.InstanceIAMBinding or gcp.spanner.InstanceIAMMember, as they will conflict. However, you can use gcp.spanner.InstanceIAMBinding with gcp.spanner.InstanceIAMMember as long as they don’t grant privileges to the same role.

Resource Selection & Use Cases

What's the difference between the three Spanner IAM resources?

gcp.spanner.InstanceIAMPolicy is authoritative and replaces the entire policy. gcp.spanner.InstanceIAMBinding is authoritative for a specific role but preserves other roles. gcp.spanner.InstanceIAMMember is non-authoritative and adds individual members without affecting existing ones.

Which Spanner IAM resource should I use?

Use gcp.spanner.InstanceIAMPolicy for complete policy control, gcp.spanner.InstanceIAMBinding to manage all members for a specific role, or gcp.spanner.InstanceIAMMember to add individual members without affecting others.

Configuration & Setup

How do I generate the policy data for InstanceIAMPolicy?

Use the gcp.organizations.getIAMPolicy data source to generate the policyData value, as shown in the examples.

Using a different cloud?

Explore security guides for other cloud providers:

AWS Guides Azure Guides