README.md

Description

This module creates a Google Cloud Storage (GCS) bucket.

For more information on this and other network storage options in the Cluster Toolkit, see the extended Network Storage documentation.

Example

The following example will create a bucket named simulation-results-xxxxxxxx, where xxxxxxxx is a randomly generated id.

  - id: bucket
    source: modules/file-system/cloud-storage-bucket
    settings:
      name_prefix: simulation-results
      random_suffix: true

NOTE: Use of random_suffix may cause the following error when used with other modules: value depends on resource attributes that cannot be determined until apply. To resolve this set random_suffix to false (default).

NOTE: Bucket namespace is shared by all users of Google Cloud so it is possible to have a bucket name clash with an existing bucket that is not in your project. To resolve this try to use a more unique name, or set the random_suffix variable to true.

Naming of Bucket

There are potentially three parts to the bucket name. Each of these parts are configurable in the blueprint.

1. A custom prefix, provided by the user in the blueprint
   Provide the custom prefix using the name_prefix setting.

2. The deployment name, included by default
   The deployment name can be excluded by setting use_deployment_name_in_bucket_name: false.

3. A random id suffix, excluded by default
   The random id can be included by setting random_suffix: true.

If none of these are provided (no name_prefix, use_deployment_name_in_bucket_name: false, & random_suffix: false), then the bucket name will default to no-bucket-name-provided.

Since bucket namespace is shared by all users of Google Cloud, it is more likely to experience naming clashes than with other resources. In many cases, adding the random_suffix will resolve the naming clash issue.

Warning: If a bucket is created with a random_suffix and then used as the bucket for a startup script in the same deployment group this will cause a not known at apply time error in terraform. The solution is to either create the bucket in a separate deployment group or to remove the random suffix.

Mounting

To mount the Cloud Storage bucket you must first ensure that the GCS Fuse client has been installed and then call the proper mount command.

Both of these steps are automatically handled with the use of the use command in a selection of Cluster Toolkit modules. See the compatibility matrix in the network storage doc for a complete list of supported modules.

If mounting is not automatically handled as described above, the cloud-storage-bucket module outputs runners that can be used with the startup-script module to install the client and mount the file system. See the following example:

  - id: bucket
    source: modules/file-system/cloud-storage-bucket
    settings: {local_mount: /data}

  - id: mount-at-startup
    source: modules/scripts/startup-script
    settings:
      runners:
      - $(bucket.client_install_runner)
      - $(bucket.mount_runner)

License

Copyright 2026 Google LLC

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

 http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Requirements

Providers

Modules

No modules.

Resources

Inputs

object({
    zones            = list(string)
    ttl              = optional(string, "86400s")
    admission_policy = optional(string, "admit-on-first-miss")
  })

object({
    enabled                = optional(bool, false)
    terminal_storage_class = optional(string, null)
  })

{
  "enabled": false
}

list(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 = object({
      type          = string
      storage_class = optional(string)
    })

    # Object with keys:
    # - age - (Optional) Minimum age of an object in days to satisfy this condition.
    # - send_age_if_zero - (Optional) While set true, num_newer_versions value will be sent in the request even for zero value of the field.
    # - 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, ARCHIVE, 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 = object({
      age                        = optional(number)
      send_age_if_zero           = optional(bool)
      created_before             = optional(string)
      with_state                 = optional(string)
      matches_storage_class      = optional(string)
      matches_prefix             = optional(string)
      matches_suffix             = optional(string)
      num_newer_versions         = optional(number)
      custom_time_before         = optional(string)
      days_since_custom_time     = optional(number)
      days_since_noncurrent_time = optional(number)
      noncurrent_time_before     = optional(string)
    })
  }))

Outputs