Terraform Google Cloud Storage Module

This module makes it easy to create one or more GCS buckets, and assign basic permissions on them to arbitrary users.

The resources/services/activations/deletions that this module will create/trigger are:

• One or more GCS buckets
• Zero or more IAM bindings for those buckets

If you only wish to create a single bucket, consider using the simple bucket submodule instead.

Compatibility

This module is meant for use with Terraform 0.13+ and tested using Terraform 1.0+. If you find incompatibilities using Terraform >=0.13, please open an issue. If you haven't upgraded and need a Terraform 0.12.x-compatible version of this module, the last released version intended for Terraform 0.12.x is v1.7.1.

Usage

Basic usage of this module is as follows:

module "gcs_buckets" {
  source  = "terraform-google-modules/cloud-storage/google"
  version = "~> 9.0"
  project_id  = "<PROJECT ID>"
  names = ["first", "second"]
  prefix = "my-unique-prefix"
  set_admin_roles = true
  admins = ["group:[email protected]"]
  versioning = {
    first = true
  }
  bucket_admins = {
    second = "user:[email protected],user:[email protected]"
  }
}

Functional examples are included in the examples directory.

Inputs

Name	Description	Type	Default	Required
admins	IAM-style members who will be granted roles/storage.objectAdmin on all buckets.	list(string)	[]	no
autoclass	Optional map of lowercase unprefixed bucket name => boolean, defaults to false.	map(bool)	{}	no
bucket_admins	Map of lowercase unprefixed name => comma-delimited IAM-style per-bucket admins.	map(string)	{}	no
bucket_creators	Map of lowercase unprefixed name => comma-delimited IAM-style per-bucket creators.	map(string)	{}	no
bucket_hmac_key_admins	Map of lowercase unprefixed name => comma-delimited IAM-style per-bucket HMAC Key admins.	map(string)	{}	no
bucket_lifecycle_rules	Additional lifecycle_rules for specific buckets. Map of lowercase unprefixed name => list of lifecycle rules to configure.	map(set(object({ # Object with keys: # - type - The type of the action of this Lifecycle Rule. Supported values: Delete and SetStorageClass. # - storage_class - (Required if action type is SetStorageClass) The target Storage Class of objects affected by this Lifecycle Rule. action = map(string) # Object with keys: # - age - (Optional) Minimum age of an object in days to satisfy this condition. # - created_before - (Optional) Creation date of an object in RFC 3339 (e.g. 2017-06-13) to satisfy this condition. # - with_state - (Optional) Match to live and/or archived objects. Supported values include: "LIVE", "ARCHIVED", "ANY". # - matches_storage_class - (Optional) Comma delimited string for storage class of objects to satisfy this condition. Supported values include: MULTI_REGIONAL, REGIONAL, NEARLINE, COLDLINE, STANDARD, DURABLE_REDUCED_AVAILABILITY. # - num_newer_versions - (Optional) Relevant only for versioned objects. The number of newer versions of an object to satisfy this condition. # - custom_time_before - (Optional) A date in the RFC 3339 format YYYY-MM-DD. This condition is satisfied when the customTime metadata for the object is set to an earlier date than the date used in this lifecycle condition. # - days_since_custom_time - (Optional) The number of days from the Custom-Time metadata attribute after which this condition becomes true. # - days_since_noncurrent_time - (Optional) Relevant only for versioned objects. Number of days elapsed since the noncurrent timestamp of an object. # - noncurrent_time_before - (Optional) Relevant only for versioned objects. The date in RFC 3339 (e.g. 2017-06-13) when the object became nonconcurrent. condition = map(string) })))	{}	no
bucket_policy_only	Disable ad-hoc ACLs on specified buckets. Defaults to true. Map of lowercase unprefixed name => boolean	map(bool)	{}	no
bucket_storage_admins	Map of lowercase unprefixed name => comma-delimited IAM-style per-bucket storage admins.	map(string)	{}	no
bucket_viewers	Map of lowercase unprefixed name => comma-delimited IAM-style per-bucket viewers.	map(string)	{}	no
cors	Set of maps of mixed type attributes for CORS values. See appropriate attribute types here: https://www.terraform.io/docs/providers/google/r/storage_bucket.html#cors	set(any)	[]	no
creators	IAM-style members who will be granted roles/storage.objectCreators on all buckets.	list(string)	[]	no
custom_placement_config	Map of lowercase unprefixed name => custom placement config object. Format is the same as described in provider documentation https://www.terraform.io/docs/providers/google/r/storage_bucket#custom_placement_config	any	{}	no
default_event_based_hold	Enable event based hold to new objects added to specific bucket. Defaults to false. Map of lowercase unprefixed name => boolean	map(bool)	{}	no
encryption_key_names	Optional map of lowercase unprefixed name => string, empty strings are ignored.	map(string)	{}	no
folders	Map of lowercase unprefixed name => list of top level folder objects.	map(list(string))	{}	no
force_destroy	Optional map of lowercase unprefixed name => boolean, defaults to false.	map(bool)	{}	no
hmac_key_admins	IAM-style members who will be granted roles/storage.hmacKeyAdmin on all buckets.	list(string)	[]	no
hmac_service_accounts	List of HMAC service accounts to grant access to GCS.	map(string)	{}	no
labels	Labels to be attached to the buckets	map(string)	{}	no
lifecycle_rules	List of lifecycle rules to configure. Format is the same as described in provider documentation https://www.terraform.io/docs/providers/google/r/storage_bucket.html#lifecycle_rule except condition.matches_storage_class should be a comma delimited string.	set(object({ # Object with keys: # - type - The type of the action of this Lifecycle Rule. Supported values: Delete and SetStorageClass. # - storage_class - (Required if action type is SetStorageClass) The target Storage Class of objects affected by this Lifecycle Rule. action = map(string) # Object with keys: # - age - (Optional) Minimum age of an object in days to satisfy this condition. # - created_before - (Optional) Creation date of an object in RFC 3339 (e.g. 2017-06-13) to satisfy this condition. # - with_state - (Optional) Match to live and/or archived objects. Supported values include: "LIVE", "ARCHIVED", "ANY". # - matches_storage_class - (Optional) Comma delimited string for storage class of objects to satisfy this condition. Supported values include: MULTI_REGIONAL, REGIONAL, NEARLINE, COLDLINE, STANDARD, DURABLE_REDUCED_AVAILABILITY. # - matches_prefix - (Optional) One or more matching name prefixes to satisfy this condition. # - matches_suffix - (Optional) One or more matching name suffixes to satisfy this condition. # - num_newer_versions - (Optional) Relevant only for versioned objects. The number of newer versions of an object to satisfy this condition. # - custom_time_before - (Optional) A date in the RFC 3339 format YYYY-MM-DD. This condition is satisfied when the customTime metadata for the object is set to an earlier date than the date used in this lifecycle condition. # - days_since_custom_time - (Optional) The number of days from the Custom-Time metadata attribute after which this condition becomes true. # - days_since_noncurrent_time - (Optional) Relevant only for versioned objects. Number of days elapsed since the noncurrent timestamp of an object. # - noncurrent_time_before - (Optional) Relevant only for versioned objects. The date in RFC 3339 (e.g. 2017-06-13) when the object became nonconcurrent. condition = map(string) }))	[]	no
location	Bucket location.	string	"EU"	no
logging	Map of lowercase unprefixed name => bucket logging config object. Format is the same as described in provider documentation https://www.terraform.io/docs/providers/google/r/storage_bucket.html#logging	any	{}	no
names	Bucket name suffixes.	list(string)	n/a	yes
prefix	Prefix used to generate the bucket name.	string	""	no
project_id	Bucket project id.	string	n/a	yes
public_access_prevention	Prevents public access to a bucket. Acceptable values are inherited or enforced. If inherited, the bucket uses public access prevention, only if the bucket is subject to the public access prevention organization policy constraint.	string	"inherited"	no
randomize_suffix	Adds an identical, but randomized 4-character suffix to all bucket names	bool	false	no
retention_policy	Map of retention policy values. Format is the same as described in provider documentation https://www.terraform.io/docs/providers/google/r/storage_bucket#retention_policy	any	{}	no
set_admin_roles	Grant roles/storage.objectAdmin role to admins and bucket_admins.	bool	false	no
set_creator_roles	Grant roles/storage.objectCreator role to creators and bucket_creators.	bool	false	no
set_hmac_access	Set S3 compatible access to GCS.	bool	false	no
set_hmac_key_admin_roles	Grant roles/storage.hmacKeyAdmin role to hmac_key_admins and bucket_hmac_key_admins.	bool	false	no
set_storage_admin_roles	Grant roles/storage.admin role to storage_admins and bucket_storage_admins.	bool	false	no
set_viewer_roles	Grant roles/storage.objectViewer role to viewers and bucket_viewers.	bool	false	no
soft_delete_policy	Soft delete policies to apply. Map of lowercase unprefixed name => soft delete policy. Format is the same as described in provider documentation https://www.terraform.io/docs/providers/google/r/storage_bucket.html#nested_soft_delete_policy	map(any)	{}	no
storage_admins	IAM-style members who will be granted roles/storage.admin on all buckets.	list(string)	[]	no
storage_class	Bucket storage class.	string	"STANDARD"	no
versioning	Optional map of lowercase unprefixed name => boolean, defaults to false.	map(bool)	{}	no
viewers	IAM-style members who will be granted roles/storage.objectViewer on all buckets.	list(string)	[]	no
website	Map of website values. Supported attributes: main_page_suffix, not_found_page	map(any)	{}	no

Outputs

Name	Description
apphub_service_uri	URI in CAIS style to be used by Apphub.
bucket	Bucket resource (for single use).
buckets	Bucket resources as list.
buckets_map	Bucket resources by name.
hmac_keys	List of HMAC keys.
name	Bucket name (for single use).
names	Bucket names.
names_list	List of bucket names.
url	Bucket URL (for single use).
urls	Bucket URLs.
urls_list	List of bucket URLs.

Requirements

These sections describe requirements for using this module.

Software

The following dependencies must be available:

• Terraform >= 0.13.0
  • For Terraform v0.11 see the Compatibility section above
• Terraform Provider for GCP plugin >= v4.42

Service Account

User or service account credentials with the following roles must be used to provision the resources of this module:

• Storage Admin: roles/storage.admin

The Project Factory module and the IAM module may be used in combination to provision a service account with the necessary roles applied.

APIs

A project with the following APIs enabled must be used to host the resources of this module:

• Google Cloud Storage JSON API: storage-api.googleapis.com

The Project Factory module can be used to provision a project with the necessary APIs enabled.

Contributing

Refer to the contribution guidelines for information on contributing to this module.