☁️ Google Cloud Storage Bucket IAM Bindings Terraform Module

Grants additive, bucket-scoped IAM role bindings via google_storage_bucket_iam_member, targeting hashicorp/google ~> 7.0.

• 🔑 Grants one IAM role to one principal per map entry, via google_storage_bucket_iam_member.member — additive and non-authoritative.
• 🚫 Never creates google_storage_bucket_iam_binding (authoritative for a role) or google_storage_bucket_iam_policy (authoritative for the entire bucket policy).
• 🗺️ No keystone this — this is an aggregation module. Every resource is named by role: member.
• 🪣 Attaches to an already-existing Cloud Storage bucket, referenced by bare name — this module never creates, modifies, or destroys the bucket itself.
• ⏱️ Supports an optional per-binding IAM Condition for time-bound or context-scoped access.
• 📤 Emits member_ids and member_etags, keyed identically to var.bindings, for composition convenience.

💡 Why it matters: google_storage_bucket_iam_binding and google_storage_bucket_iam_policy are authoritative — an apply that uses either one removes any grant it does not explicitly declare, including ones a teammate added out-of-band. This module only ever adds a member to a role on a specific bucket, so two teams can safely grant different roles (or even the same role to different principals) on the same bucket without a shared-state apply silently deleting the other's access.

If these Terraform modules have been helpful to you or your organization, I'd appreciate your support in any of the following ways:

• ⭐ Star this repository to help others discover this Terraform module.
• 🤝 Connect with me on LinkedIn: linkedin.com/in/microsoftexpert
• ☕ Buy me a coffee: buymeacoffee.com/microsoftexpert

Whether it's a star, a professional connection, or a coffee, every gesture helps keep these modules actively maintained and continually improving. Thank you for being part of the community!

flowchart LR
 SB["terraform-google-storage-bucket"]
 SA["terraform-google-service-account"]
 THIS["terraform-google-storage-bucket-iam-bindings"]
 BUCKET["Target Cloud Storage Bucket<br/>(IAM Policy)"]

 SB -->|"name output, bare bucket name"| THIS
 SA -.->|"email output, formatted 'serviceAccount:&lt;email&gt;' (optional)"| THIS
 THIS -->|"google_storage_bucket_iam_member grants"| BUCKET

 style THIS fill:#4285F4,color:#ffffff
 style SB fill:#174EA6,color:#ffffff
 style BUCKET fill:#174EA6,color:#ffffff
 style SA fill:#E8EAED,color:#202124

terraform-google-storage-bucket is the upstream keystone whose bucket this module attaches IAM grants to — its name output feeds var.bucket directly (see 🧠 Architecture Notes for why the bare name, not self_link, is the expected form). terraform-google-service-account is an optional upstream source of member principal values: its email output, formatted "serviceAccount:<email>" by the caller, becomes a member value here — not every entry requires this dependency, since member may equally be a caller-supplied user:/group:/domain: principal. The "Target Cloud Storage Bucket" node represents the actual GCP bucket whose IAM policy is modified, not a module in this catalog.

flowchart LR
 VB["var.bucket"]
 VBI["var.bindings (map, for_each)"]
 VT["var.timeouts (optional)"]
 RES["google_storage_bucket_iam_member.member[each.key]"]
 OID["output: member_ids"]
 OET["output: member_etags"]

 VB -->|"bucket"| RES
 VBI -->|"role, member, condition"| RES
 VT -.->|"timeouts.create"| RES
 RES -->|"id"| OID
 RES -->|"etag"| OET

 style RES fill:#4285F4,color:#ffffff
 style VB fill:#E8EAED,color:#202124
 style VBI fill:#E8EAED,color:#202124
 style VT fill:#E8EAED,color:#202124
 style OID fill:#E8EAED,color:#202124
 style OET fill:#E8EAED,color:#202124

Resource inventory:

Schema notes that bite:

• bucket is required and wants the bare bucket name — confirmed against the live schema (terraform providers schema -json) and the terraform-registry MCP's live google_storage_bucket_iam docs, whose own Example Usage passes bucket = google_storage_bucket.default.name. Passing a self_link or a projects/.../buckets/...-qualified id is not the expected form.
• condition is part of a binding's identity, not just metadata — changing title/description/expression out-of-band destroys the old binding and creates a new one (the provider's own documented behavior).
• No self_link — this resource family's only identity form is the resource id ("b/{{bucket}} {{role}} {{member}}").
• No labels argument exists on this resource's schema at all (confirmed — this resource's only attributes are bucket, etag, id, member, role). A timeouts block does exist but supports only create (default 20 minutes) — no update/delete. See 🧠 Architecture Notes.
• This resource carries the provider's general IAM Conditions limitations warning — review it before relying on conditional bucket grants (see 🔗 Related Docs).

• roles/storage.admin — needed on the target project/bucket to read and write bucket-level IAM policy bindings (the applying principal must be able to manage IAM on the specific bucket this module targets).

• storage.googleapis.com API enabled on the target project (via terraform-google-project-services).
• The target bucket must already exist (created by terraform-google-storage-bucket) before this module is applied — this module does not create the bucket and will fail at apply time against a bucket name that does not yet exist.
• No quota consideration specific to IAM member bindings identified; standard project IAM API rate limits apply as with any google_*_iam_member resource.

terraform-google-storage-bucket-iam-bindings/
├── providers.tf # required_providers (hashicorp/google ~> 7.0) + required_version — no provider {} block
├── variables.tf # var.bucket (bare name, resolved) + var.bindings (map(object({role, member, condition}))) + var.timeouts (create only)
├── main.tf # google_storage_bucket_iam_member.member, for_each over var.bindings, dynamic condition + timeouts blocks
├── outputs.tf # member_ids, member_etags — no self_link (resource exports none)
├── README.md # this file
├── SCOPE.md # cross-module contract
└── examples/ # runnable example matching the Quick Start below

The caller configures the google provider (project, region/zone, authentication) in the root module — this module never declares its own provider block.

module "storage_bucket_iam_bindings" {
  source = "git::https://github.com/microsoftexpert/terraform-google-storage-bucket-iam-bindings.git?ref=v1.0.0"

  bucket = "casey-prod-app-data"

  bindings = {
    "app-sa-object-viewer" = {
      role   = "roles/storage.objectViewer"
      member = "serviceAccount:app-sa@casey-prod-app-data.iam.gserviceaccount.com"
    }
  }
}

Consumes

Emits

module "storage_bucket_iam_bindings" {
  source = "git::https://github.com/microsoftexpert/terraform-google-storage-bucket-iam-bindings.git?ref=v1.0.0"

  bucket = "casey-dev-sandbox-bucket"

  bindings = {
    "jane-viewer" = {
      role   = "roles/storage.objectViewer"
      member = "user:jane@financialpartners.com"
    }
  }
}

module "storage_bucket_iam_bindings" {
  source = "git::https://github.com/microsoftexpert/terraform-google-storage-bucket-iam-bindings.git?ref=v1.0.0"

  bucket = "casey-prod-app-data"

  bindings = {
    "eng-group-admin" = {
      role   = "roles/storage.admin"
      member = "group:engineering@financialpartners.com"
    }
  }
}

module "storage_bucket_iam_bindings" {
  source = "git::https://github.com/microsoftexpert/terraform-google-storage-bucket-iam-bindings.git?ref=v1.0.0"

  bucket = "casey-prod-app-data"

  bindings = {
    "app-sa-object-viewer" = {
      role   = "roles/storage.objectViewer"
      member = "serviceAccount:app-sa@casey-prod-app-data.iam.gserviceaccount.com"
    }
  }
}

module "storage_bucket_iam_bindings" {
  source = "git::https://github.com/microsoftexpert/terraform-google-storage-bucket-iam-bindings.git?ref=v1.0.0"

  bucket = "casey-prod-app-data"

  bindings = {
    "eng-group-viewer"      = { role = "roles/storage.objectViewer", member = "group:engineering@financialpartners.com" }
    "sre-group-admin"       = { role = "roles/storage.admin", member = "group:sre@financialpartners.com" }
    "app-sa-object-creator" = { role = "roles/storage.objectCreator", member = "serviceAccount:app-sa@casey-prod-app-data.iam.gserviceaccount.com" }
  }
}

module "storage_bucket_iam_bindings" {
  source = "git::https://github.com/microsoftexpert/terraform-google-storage-bucket-iam-bindings.git?ref=v1.0.0"

  bucket = "casey-prod-app-data"

  bindings = {
    "temp-writer-2026" = {
      role   = "roles/storage.objectCreator"
      member = "user:jane@financialpartners.com"
      condition = {
        title       = "expires_after_2026_12_31"
        description = "Temporary write access, expires end of 2026"
        expression  = "request.time < timestamp(\"2027-01-01T00:00:00Z\")"
      }
    }
  }
}

module "storage_bucket_iam_bindings" {
  source = "git::https://github.com/microsoftexpert/terraform-google-storage-bucket-iam-bindings.git?ref=v1.0.0"

  bucket = "casey-prod-app-data"

  bindings = {
    "domain-viewer" = {
      role   = "roles/storage.objectViewer"
      member = "domain:financialpartners.com"
    }
  }
}

module "storage_bucket_iam_bindings" {
  source = "git::https://github.com/microsoftexpert/terraform-google-storage-bucket-iam-bindings.git?ref=v1.0.0"

  bucket = "casey-prod-app-data"

  bindings = {
    "project-editors-writer" = {
      role   = "roles/storage.objectCreator"
      member = "projectEditor:casey-prod-app-data-project"
    }
  }
}

module "storage_bucket_iam_bindings" {
  source = "git::https://github.com/microsoftexpert/terraform-google-storage-bucket-iam-bindings.git?ref=v1.0.0"

  bucket = "casey-public-demo-assets"

  bindings = {
    "public-viewer" = {
      role   = "roles/storage.objectViewer"
      member = "allUsers"
    }
  }
}

module "storage_bucket_iam_bindings" {
  source = "git::https://github.com/microsoftexpert/terraform-google-storage-bucket-iam-bindings.git?ref=v1.0.0"

  bucket = "casey-prod-app-data"

  bindings = {
    "custom-role-grant" = {
      role   = "projects/casey-prod-networking/roles/customBucketAuditor"
      member = "group:storage-audit@financialpartners.com"
    }
  }
}

module "storage_bucket_iam_bindings" {
  source = "git::https://github.com/microsoftexpert/terraform-google-storage-bucket-iam-bindings.git?ref=v1.0.0"

  bucket = "casey-prod-app-data"

  bindings = {
    "viewer-alice" = { role = "roles/storage.objectViewer", member = "user:alice@financialpartners.com" }
    "viewer-bob"   = { role = "roles/storage.objectViewer", member = "user:bob@financialpartners.com" }
    "viewer-carla" = { role = "roles/storage.objectViewer", member = "user:carla@financialpartners.com" }
  }
}

module "storage_bucket_iam_bindings" {
  source = "git::https://github.com/microsoftexpert/terraform-google-storage-bucket-iam-bindings.git?ref=v1.0.0"

  bucket = "casey-prod-app-data"

  bindings = {
    "viewer-alice" = { role = "roles/storage.objectViewer", member = "user:alice@financialpartners.com" }
    # "viewer-bob" removed — only this entry's grant is revoked on the next apply
    "viewer-carla" = { role = "roles/storage.objectViewer", member = "user:carla@financialpartners.com" }
  }
}

module "storage_bucket_iam_bindings" {
  source = "git::https://github.com/microsoftexpert/terraform-google-storage-bucket-iam-bindings.git?ref=v1.0.0"

  bucket = "casey-prod-app-data"

  bindings = {
    "app-sa-object-viewer" = {
      role   = "roles/storage.objectViewer"
      member = "serviceAccount:app-sa@casey-prod-app-data.iam.gserviceaccount.com"
    }
  }

  timeouts = {
    create = "10m"
  }
}

module "storage_bucket_iam_bindings" {
  source = "git::https://github.com/microsoftexpert/terraform-google-storage-bucket-iam-bindings.git?ref=v1.0.0"

  bucket = "casey-prod-app-data"

  bindings = {
    "app-sa-object-viewer" = {
      role   = "roles/storage.objectViewer"
      member = "serviceAccount:app-sa@casey-prod-app-data.iam.gserviceaccount.com"
    }
  }
}

output "app_sa_binding_id" {
  value = module.storage_bucket_iam_bindings.member_ids["app-sa-object-viewer"]
}

# This will pass `terraform plan` but be REJECTED by the API at apply time —
# GCP does not allow IAM Conditions on Basic Roles (owner/editor/viewer).
module "storage_bucket_iam_bindings" {
  source = "git::https://github.com/microsoftexpert/terraform-google-storage-bucket-iam-bindings.git?ref=v1.0.0"

  bucket = "casey-prod-app-data"

  bindings = {
    "bad-conditional-owner" = {
      role   = "roles/owner" # Basic Role — incompatible with `condition`
      member = "user:jane@financialpartners.com"
      condition = {
        title      = "temp"
        expression = "request.time < timestamp(\"2027-01-01T00:00:00Z\")"
      }
    }
  }
}

module "app_data_bucket" {
  source = "git::https://github.com/microsoftexpert/terraform-google-storage-bucket.git?ref=v1.0.0"

  name     = "casey-prod-app-data"
  location = "US"
}

module "app_service_account" {
  source = "git::https://github.com/microsoftexpert/terraform-google-service-account.git?ref=v1.0.0"

  account_id   = "app-workload"
  display_name = "Application workload service account"
}

module "storage_bucket_iam_bindings" {
  source = "git::https://github.com/microsoftexpert/terraform-google-storage-bucket-iam-bindings.git?ref=v1.0.0"

  # Sibling module output -> this module's bucket input, per SCOPE.md's Consumes contract —
  # bare bucket name, never self_link.
  bucket = module.app_data_bucket.name

  bindings = {
    # Sibling module output -> this module's member input, formatted per SCOPE.md's Consumes contract.
    "app-sa-object-viewer" = {
      role   = "roles/storage.objectViewer"
      member = "serviceAccount:${module.app_service_account.email}"
    }

    # A literal group principal — not every entry requires a sibling-module reference.
    "eng-group-admin" = {
      role   = "roles/storage.admin"
      member = "group:engineering@financialpartners.com"
    }
  }
}

variable "bucket" {
  type = string
  # Validated: 3-222 chars, lowercase letters/digits/dashes/underscores/dots, must not
  # start or end with a dot or dash.
}

variable "bindings" {
  type = map(object({
    role   = string
    member = string
    condition = optional(object({
      expression  = string
      title       = string
      description = optional(string)
    }))
  }))
  default = {}
}

variable "timeouts" {
  type = object({
    create = optional(string)
  })
  default = null
}

This resource family exports no self_link — the resource id above is its only identity form.

• bucket argument form — resolved fact, not an open item. SCOPE.md's Prompt-1 open question ("bare name vs. full id") is settled: confirmed against the live schema and the terraform-registry MCP's google_storage_bucket_iam docs, bucket wants the bare bucket name (every provider Example Usage passes google_storage_bucket.default.name), never a self_link or a fully-qualified id. google_storage_bucket's own id and name resolve to the same string, so either output works identically — variables.tf documents name as the canonical source for clarity.
• labels/timeouts — schema-confirmed partial exception. google_storage_bucket_iam_member's attributes are only bucket, etag, id, member, role, with condition and timeouts as its only block types. There is no labels argument at all — omitted from this module entirely, consistent with terraform-google-project-iam-bindings's identical omission (IAM grant resources are policy records, not taggable infrastructure). The timeouts block does exist but supports only create (default 20 minutes) — no update/delete override — so variables.tf's timeouts variable declares only create, applied uniformly to every for_each instance via a dynamic "timeouts" block in main.tf.
• IAM propagation delay. google_storage_bucket_iam_member changes can take up to ~60 seconds to become effective at the API level. A composition that applies this module and then immediately creates a resource depending on the freshly-granted role in the same apply can hit a transient permission-denied error even though Terraform's graph ordering was correct. This is an operational characteristic of GCP IAM, not a bug to work around in code.
• condition is part of a binding's identity. Changing title/description/expression out-of-band causes Terraform to destroy the old binding and create a new one, not update in place.
• No self_link. The resource id ("b/{{bucket}} {{role}} {{member}}") is this resource family's only identity form.
• for_each key stability. var.bindings is keyed by a caller-chosen stable string, never derived from role/member. Removing a middle entry destroys only that resource instance — no other binding is re-keyed or forced to replace.
• No members (plural) list. One google_storage_bucket_iam_member per (role, member) pair, matching the resource's own one-member-at-a-time design.

cd C:\GitHubCode\newgooglecloudmodules\terraform-google-storage-bucket-iam-bindings
terraform init -backend=false
terraform validate
terraform fmt -check

Pin ?ref=v1.0.0 in every consuming composition — never a branch. This library is plan-only; a human applies from CI with valid credentials (ADC or Workload Identity Federation).

terraform init -backend=false && terraform validate && terraform fmt -check is the entire offline proof gate for this module: validate confirms internal type/reference consistency (e.g. that var.bindings' object shape is well-formed and every reference resolves), and fmt -check confirms canonical formatting. Neither can catch GCP API-level rejections — quota, org policy (domain restriction, public access prevention, IAM Condition-on-Basic-Role), or IAM propagation delay are all invisible to this proof gate and surface only at apply time in a real project, per this suite's plan-only posture convention. The examples/ directory exists so a consuming GitHub Actions workflow can run a real terraform plan against a real project as part of that pipeline's own review gate.

$ terraform output

member_ids = {
 "app-sa-object-viewer" = "b/casey-prod-app-data roles/storage.objectViewer serviceAccount:app-sa@casey-prod-app-data.iam.gserviceaccount.com"
 "eng-group-admin" = "b/casey-prod-app-data roles/storage.admin group:engineering@financialpartners.com"
}
member_etags = {
 "app-sa-object-viewer" = "CAI="
 "eng-group-admin" = "CAI="
}

• google_storage_bucket_iam resource docs (covers _member, _binding, _policy)
• IAM Conditions overview and its limitations
• Cloud Storage bucket naming rules
• Sibling modules: terraform-google-storage-bucket, terraform-google-service-account, terraform-google-project-iam-bindings
• This module's SCOPE.md