hunfabric/modules/iam-service-account/README.md

Google Service Account Module

This module allows simplified creation and management of one a service account and its IAM bindings.

Note that outputs have no dependencies on IAM bindings to prevent resource cycles.

• Simple Example
• IAM
• Reusing Existing Service Accounts
• Tag Bindings
• Files
• Variables
• Outputs

Simple Example

module "myproject-default-service-accounts" {
  source     = "./fabric/modules/iam-service-account"
  project_id = var.project_id
  name       = "vm-default"
  # authoritative roles granted *on* the service accounts to other identities
  iam = {
    "roles/iam.serviceAccountUser" = ["group:${var.group_email}"]
  }
  # non-authoritative roles granted *to* the service accounts on other resources
  iam_project_roles = {
    "${var.project_id}" = [
      "roles/logging.logWriter",
      "roles/monitoring.metricWriter",
    ]
  }
}
# tftest modules=1 resources=4 inventory=basic.yaml e2e

IAM

IAM is managed via several variables that implement different features and levels of control.

The following variables control IAM bindings where this module's managed service account is the resource, and they conform to the standard interface adopted across all other modules:

• iam and iam_by_principals configure authoritative bindings that manage individual roles exclusively, and are internally merged
• iam_bindings configure authoritative bindings with optional support for conditions, and are not internally merged with the previous two variables
• iam_bindings_additive configure additive bindings via individual role/member pairs with optional support conditions

The authoritative and additive approaches can be used together, provided different roles are managed by each. Some care must also be taken with the iam_by_principals variable to ensure that variable keys are static values, so that Terraform is able to compute the dependency graph. Refer to the project module for examples of the IAM interface.

The following variables control additive IAM bindings on external resources where this module's managed service account is the principal:

• iam_billing_roles
• iam_folder_roles
• iam_organization_roles
• iam_project_roles
• iam_sa_roles
• iam_storage_roles

IAM also supports variable interpolation for both roles and principals and for the foreign resources where the service account is the principal, via the respective attributes in the var.context variable. Basic usage is shown in the example below.

module "service-account-with-tags" {
  source     = "./fabric/modules/iam-service-account"
  project_id = var.project_id
  name       = "test-service-account"
  context = {
    folder_ids = {
      test = "folders/1234567890"
    }
  }
  iam_billing_roles = {
    "ABCDE-12345-ABCDE" = [
      "roles/billing.user"
    ]
  }
  iam_folder_roles = {
    "$folder_ids:test" = [
      "roles/resourcemanager.folderAdmin"
    ]
  }
}
# tftest modules=1 resources=3 inventory=iam.yaml

Reusing Existing Service Accounts

Like other modules in this repository, this module allows reusing existing service accounts where only IAM or tag bindings management is needed, via the service_account_reuse variable.

When reusing service accounts, the name variable can be set to the fully fledged service account email. In such cases the project_id variable can be ignored as the project id is derived from the email.

The service_account_reuse.use_data_source flag also allows to skip the data source used to fetch the service account unique id (numeric), which is only used when setting tag bindings. If those are needed while still skipping the data source, populate the additional attributes service_account_reuse.attributes.

module "service-account" {
  source = "./fabric/modules/iam-service-account"
  name   = "test-0@myproject.iam.gserviceaccount.com"
  context = {
    folder_ids = {
      test = "folders/1234567890"
    }
  }
  iam_billing_roles = {
    "ABCDE-12345-ABCDE" = [
      "roles/billing.user"
    ]
  }
  iam_folder_roles = {
    "$folder_ids:test" = [
      "roles/resourcemanager.folderAdmin"
    ]
  }
  service_account_reuse = {
    use_data_source = false
  }
}
# tftest modules=1 resources=2 inventory=reuse-0.yaml

Tag Bindings

Use the tag_bindings variable to attach tags to the service account. Provide project_number to prevent potential permadiffs with the tag binding resource.

module "service-account-with-tags" {
  source         = "./fabric/modules/iam-service-account"
  project_id     = var.project_id
  name           = "test-service-account"
  project_number = var.project_number
  tag_bindings = {
    foo = "tagValues/123456789"
  }
}
# tftest modules=1 resources=2 inventory=tags.yaml

Files

name	description	resources
iam.tf	IAM bindings.	google_billing_account_iam_member · google_folder_iam_member · google_organization_iam_member · google_project_iam_member · google_service_account_iam_binding · google_service_account_iam_member · google_storage_bucket_iam_member
main.tf	Module-level locals and resources.	google_service_account · google_tags_tag_binding
outputs.tf	Module outputs.
variables-iam.tf	None
variables.tf	Module variables.
versions.tf	Version pins.

Variables

name	description	type	required	default
name	Name of the service account to create.	string	✓
context	External context used in replacements.	object({…})		{}
create_ignore_already_exists	If set to true, skip service account creation if a service account with the same email already exists.	bool		null
description	Optional description.	string		null
display_name	Display name of the service account to create.	string		"Terraform-managed."
iam	IAM bindings in {ROLE => [MEMBERS]} format.	map(list(string))		{}
iam_billing_roles	Billing account roles granted to this service account, by billing account id. Non-authoritative.	map(list(string))		{}
iam_bindings	Authoritative IAM bindings in {KEY => {role = ROLE, members = [], condition = {}}}. Keys are arbitrary.	map(object({…}))		{}
iam_bindings_additive	Individual additive IAM bindings. Keys are arbitrary.	map(object({…}))		{}
iam_by_principals	Authoritative IAM binding in {PRINCIPAL => [ROLES]} format. Principals need to be statically defined to avoid errors. Merged internally with the iam variable.	map(list(string))		{}
iam_by_principals_additive	Additive IAM binding in {PRINCIPAL => [ROLES]} format. Principals need to be statically defined to avoid errors. Merged internally with the iam_bindings_additive variable.	map(list(string))		{}
iam_folder_roles	Folder roles granted to this service account, by folder id. Non-authoritative.	map(list(string))		{}
iam_organization_roles	Organization roles granted to this service account, by organization id. Non-authoritative.	map(list(string))		{}
iam_project_roles	Project roles granted to this service account, by project id.	map(list(string))		{}
iam_sa_roles	Service account roles granted to this service account, by service account name.	map(list(string))		{}
iam_storage_roles	Storage roles granted to this service account, by bucket name.	map(list(string))		{}
prefix	Prefix applied to service account names.	string		null
project_id	Project id where service account will be created. This can be left null when reusing service accounts.	string		null
project_number	Project number of var.project_id. Set this to avoid permadiffs when creating tag bindings. This can be left null when reusing service accounts and tags are not used.	string		null
service_account_reuse	Reuse existing service account if not null. Data source can be forced disabled if tag bindings are not used, or unique id is set.	object({…})		null
tag_bindings	Tag bindings for this service accounts, in key => tag value id format.	map(string)		{}

Outputs

name	description	sensitive
email	Service account email.
iam_email	IAM-format service account email.
id	Fully qualified service account id.
name	Service account name.
service_account	Service account resource.
unique_id	Fully qualified service account id.