Cloud Object Storage module

Use this module to provision and configure an IBM Cloud Object Storage instance and bucket.

In addition, a buckets submodule supports creating multiple buckets in an existing instance.

You can configure the following aspects of your instances:

• Key management service (KMS) encryption
• Activity tracking and auditing
• Monitoring
• Data retention, lifecycle and archiving options

Overview

• terraform-ibm-cos
• Submodules
  • backup_vault
  • buckets
  • fscloud
  • lifecycle_rules
• Examples ℹ️ Ctrl/Cmd+Click or right-click on the Schematics deploy button to open in a new tab
  • Advanced example
  • Basic example
  • Financial Services compliant example
  • Bucket replication example
• Contributing

terraform-ibm-cos

Usage

provider "ibm" {
  ibmcloud_api_key = "XXXXXXXXXX"
  region           = "us-south"
}

# Creates:
# - COS instance
# - COS buckets with retention, encryption, monitoring and activity tracking
module "cos_module" {
  source                     = "terraform-ibm-modules/cos/ibm"
  version                    = "X.X.X" # Replace "X.X.X" with a release version to lock into a specific release
  resource_group_id          = "xxXXxxXXxXxXXXXxxXxxxXXXXxXXXXX"
  region                     = "us-south"
  cos_instance_name          = "my-cos-instance"
  bucket_name                = "my-cos-bucket"
  kms_key_crn                = "crn:v1:bluemix:public:kms:us-south:a/xxXXxxXXxXxXXXXxxXxxxXXXXxXXXXX:xxxxxx-XXXX-XXXX-XXXX-xxxxxx:key:xxxxxx-XXXX-XXXX-XXXX-xxxxxx"
}

# Creates additional buckets in existing instance:
module "additional_cos_bucket" {
  source                   = "terraform-ibm-modules/cos/ibm"
  version                  = "X.X.X" # Replace "X.X.X" with a release version to lock into a specific release
  region                   = "us-south"
  create_cos_instance      = false
  existing_cos_instance_id = module.cos_module.cos_instance_id
  kms_key_crn              = "crn:v1:bluemix:public:kms:us-south:a/xxXXxxXXxXxXXXXxxXxxxXXXXxXXXXX:xxxxxx-XXXX-XXXX-XXXX-xxxxxx:key:xxxxxx-XXXX-XXXX-XXXX-xxxxxx"
}

# Creates additional Cloud Object Storage buckets using the buckets sub module
module "cos_buckets" {
  source  = "terraform-ibm-modules/cos/ibm//modules/buckets"
  version = "X.X.X" # Replace "X.X.X" with a release version to lock into a specific release
  bucket_configs = [
    {
      bucket_name          = "my-encrypted-bucket"
      kms_key_crn          = "crn:v1:bluemix:public:kms:us-south:a/xxXXxxXXxXxXXXXxxXxxxXXXXxXXXXX:xxxxxx-XXXX-XXXX-XXXX-xxxxxx:key:xxxxxx-XXXX-XXXX-XXXX-xxxxxx"
      region_location      = "us-south"
      resource_instance_id = module.cos_module.cos_instance_id
    },
    {
      bucket_name            = "my-versioned-bucket"
      kms_encryption_enabled = false
      region_location        = "us-south"
      resource_instance_id   = module.cos_module.cos_instance_id
      object_versioning = {
        enable = true
      }
    },
    {
      bucket_name            = "my-archive-bucket"
      kms_encryption_enabled = false
      region_location        = "us-south"
      resource_instance_id   = module.cos_module.cos_instance_id
      archive_rule = {
        days   = 90
        enable = true
        type   = "Accelerated"
      }
      expire_rule = {
        days   = 90
        enable = true
      }
    }
  ]
}

Required IAM access policies

You need the following permissions to run this module.

• Service
  • Resource group only
    • Viewer access on the specific resource group
  • Cloud Object Storage service
    • Editor platform access
    • Manager service access

Requirements

Name	Version
terraform	>= 1.9.0
ibm	>= 1.80.0, < 2.0.0
random	>= 3.5.1, < 4.0.0
time	>= 0.9.1, < 1.0.0

Modules

Name	Source	Version
bucket_cbr_rule	terraform-ibm-modules/cbr/ibm//modules/cbr-rule-module	1.35.13
cos_crn_parser	terraform-ibm-modules/common-utilities/ibm//modules/crn-parser	1.4.1
instance_cbr_rule	terraform-ibm-modules/cbr/ibm//modules/cbr-rule-module	1.35.13
kms_crn_parser	terraform-ibm-modules/common-utilities/ibm//modules/crn-parser	1.4.1

Resources

Name	Type
ibm_cos_backup_policy.policy	resource
ibm_cos_bucket.cos_bucket	resource
ibm_cos_bucket_lifecycle_configuration.cos_bucket_lifecycle	resource
ibm_cos_bucket_object_lock_configuration.lock_configuration	resource
ibm_iam_access_group_policy.access_policy	resource
ibm_iam_authorization_policy.policy	resource
ibm_iam_authorization_policy.vault_policy	resource
ibm_resource_instance.cos_instance	resource
ibm_resource_key.resource_keys	resource
ibm_resource_tag.cos_access_tag	resource
random_string.bucket_name_suffix	resource
time_sleep.wait_for_authorization_policy	resource
time_sleep.wait_for_vault_authorization_policy	resource
ibm_iam_access_group.public_access_group	data source
ibm_resource_instance.cos_instance	data source

Inputs

Name	Description	Type	Default	Required
abort_multipart_days	The number of days after which incomplete multipart uploads will be aborted. If null is passed, no lifecycle configuration will be added for aborting multipart uploads.	number	null	no
abort_multipart_filter_prefix	Apply abort incomplete multipart upload rule to only objects with the following prefix. Defaults to apply to all objects.	string	null	no
access_tags	A list of access tags to apply to the Object Storage instance created by the module. Learn more.	list(string)	[]	no
activity_tracker_management_events	If set to true, all Object Storage management events are sent to Activity Tracker Event Routing.	bool	true	no
activity_tracker_read_data_events	If set to true, all Object Storage bucket read events (i.e. downloads) are sent to Activity Tracker Event Routing.	bool	true	no
activity_tracker_write_data_events	If set to true, all Object Storage bucket write events (i.e. uploads) are sent to Activity Tracker Event Routing.	bool	true	no
add_bucket_name_suffix	Whether to add a randomly generated 4-character suffix to the bucket name.	bool	true	no
allow_public_access_to_bucket	Set it to true to grant public access to the Object Storage bucket by attaching an IAM access group policy to the IBM Cloud Public Access access group. This is only applicable when create_cos_bucket is set set to true. Learn More	bool	false	no
archive_days	The number of days before the archive_type rule action takes effect. Applies only if create_cos_bucket is set to true. Set to null if you specify a bucket location in cross_region_location because archive data is not supported with cross-region buckets. If null is passed, no lifecycle configuration will be added for bucket archival.	number	null	no
archive_filter_prefix	Apply archive lifecycle rule to only objects with the following prefix. Applies to all objects by default.	string	null	no
archive_type	The storage class or archive type to which you want the object to transition. Possible values are Glacier or Accelerated. Applies only if create_cos_bucket is set to true.	string	"Glacier"	no
backup_policies	List of backup policies to create for the bucket. Each policy requires a unique policy_name, target_backup_vault_crn, and initial_delete_after_days. Maximum of 3 policies allowed per bucket. Note: The source bucket must have object versioning enabled.	list(object({ policy_name = string target_backup_vault_crn = string initial_delete_after_days = number }))	[]	no
bucket_cbr_rules	The list of context-based restriction rules to create for the bucket.	list(object({ description = string account_id = string rule_contexts = list(object({ attributes = optional(list(object({ name = string value = string }))) })) enforcement_mode = string tags = optional(list(object({ name = string value = string })), []) operations = optional(list(object({ api_types = list(object({ api_type_id = string })) }))) }))	[]	no
bucket_name	The name for the Object Storage bucket. Applies only if create_cos_bucket is set to true.	string	null	no
bucket_storage_class	The storage class of the bucket. Applies only if create_cos_bucket is set to true. Possible values are standard, vault, cold, smart, or onerate_active.	string	"standard"	no
cos_instance_name	The name for the IBM Cloud Object Storage instance provisioned by this module. Required if create_cos_instance is set to true.	string	null	no
cos_plan	The plan to use when Object Storage instances are created. Possible values are standard or cos-one-rate-plan. Required if create_cos_instance is set to true. Learn more.	string	"standard"	no
cos_tags	A list of tags to apply to the Object Storage instance.	list(string)	[]	no
create_cos_bucket	Whether to create an Object Storage bucket.	bool	true	no
create_cos_instance	Whether to create an IBM Cloud Object Storage instance.	bool	true	no
cross_region_location	Specify the cross-region bucket location. Possible values are us, eu, or ap. If specified, set region and single_site_location to null.	string	null	no
existing_cos_instance_id	The ID of an existing Object Storage instance. Required if create_cos_instance is set to false.	string	null	no
expire_days	The number of days before the expire rule action takes effect. Applies only if create_cos_bucket is set to true. If null is passed, no lifecycle configuration will be added for bucket expiration.	number	null	no
expire_filter_prefix	Apply expire lifecycle rule to only objects with the following prefix. Applies to all objects by default.	string	null	no
force_delete	Whether to delete all the objects in the Object Storage bucket before the bucket is deleted.	bool	true	no
hard_quota	The maximum amount of available storage in bytes for a bucket. If set to null, the quota is disabled.	number	null	no
instance_cbr_rules	The list of context-based restriction rules to create for the instance.	list(object({ description = string account_id = string rule_contexts = list(object({ attributes = optional(list(object({ name = string value = string }))) })) enforcement_mode = string tags = optional(list(object({ name = string value = string })), []) operations = optional(list(object({ api_types = list(object({ api_type_id = string })) }))) }))	[]	no
kms_encryption_enabled	Whether to use key management service key encryption to encrypt data in Object Storage buckets. Applies only if create_cos_bucket is set to true.	bool	true	no
kms_key_crn	The CRN of the key management service key to encrypt the data in the Object Storage bucket. Required if kms_encryption_enabled and create_cos_bucket are set to true.	string	null	no
management_endpoint_type_for_bucket	The type of endpoint for the IBM terraform provider to manage the bucket. Possible values are public, private, or direct.	string	"public"	no
monitoring_crn	The CRN of an IBM Cloud Monitoring instance to send Object Storage bucket metrics to. If no value is set, metrics are sent to the instance associated with the container's location unless otherwise specified in the Metrics Router service configuration.	string	null	no
noncurrent_version_expiration_days	The number of days after which non-current versions will be deleted. If null is passed, no lifecycle configuration will be added for bucket non-current version expiration.	number	null	no
noncurrent_version_expiration_filter_prefix	Apply noncurrent version expiration lifecycle rule to only objects with the following prefix. Applies to all objects by default.	string	null	no
object_lock_duration_days	The number of days for the object lock duration. If you specify a number of days, do not specify a value for object_lock_duration_years. Applies only if create_cos_bucket is set to true.	number	0	no
object_lock_duration_years	The number of years for the object lock duration. If you specify a number of years, do not specify a value for object_lock_duration_days. Applies only if create_cos_bucket is set to true.	number	0	no
object_locking_enabled	Whether to create an object lock configuration. If set to true, object_versioning_enabled and create_cos_bucket must also be set to true.	bool	false	no
object_versioning_enabled	Whether to enable object versioning to keep multiple versions of an object in a bucket. Can't be used with retention rule. Applies only if create_cos_bucket is set to true.	bool	false	no
public_access_role	IAM role to include in the access policy assigned to the Public Access access group for the Object Storage bucket. Only applicable when allow_public_access_to_bucket is true and create_cos_bucket is true.	list(string)	[ "Object Reader" ]	no
region	The region to provision the bucket. If specified, set cross_region_location and single_site_location to null.	string	"us-south"	no
request_metrics_enabled	If set to true, all Object Storage bucket request metrics are sent to Cloud Monitoring.	bool	true	no
resource_group_id	The resource group ID for the Object Storage instance. Required if create_cos_instance is set to true.	string	null	no
resource_keys	The definition of the resource keys to generate. Learn more.	list(object({ name = string key_name = optional(string, null) generate_hmac_credentials = optional(bool, false) role = optional(string, "Reader") service_id_crn = optional(string, null) }))	[]	no
retention_default	The number of days that an object can remain unmodified in an Object Storage bucket. Applies only if create_cos_bucket is set to true.	number	90	no
retention_enabled	Whether retention for the Object Storage bucket is enabled. Applies only if create_cos_bucket is set to true.	bool	false	no
retention_maximum	The maximum number of days that an object can be kept unmodified in the bucket. Applies only if create_cos_bucket is set to true.	number	350	no
retention_minimum	The minimum number of days that an object must be kept unmodified in the bucket. Applies only if create_cos_bucket is set to true.	number	90	no
retention_permanent	Whether permanent retention status is enabled for the Object Storage bucket. Learn more. Applies only if create_cos_bucket is set to true.	bool	false	no
single_site_location	The single site bucket location. If specified, set the value of region and cross_region_location to null.	string	null	no
skip_iam_authorization_policy	Set to true the skip the creation of an IAM authorization policy that grants the Object Storage instance 'Reader' access to the specified KMS key. This policies must exist in your account for encryption to work. Ignored if 'kms_encryption_enabled' is false.	bool	false	no
usage_metrics_enabled	If set to true, all Object Storage bucket usage metrics are sent to Cloud Monitoring.	bool	true	no

Outputs

Name	Description
bucket_cbr_rules	Object Storage bucket context-based restriction rules
bucket_crn	Bucket CRN
bucket_id	Bucket ID
bucket_name	Bucket name
bucket_region	Bucket region if a regional bucket is created
bucket_storage_class	Bucket storage class
cbr_rule_ids	List of all rule IDs
cos_account_id	The account ID in which the Object Storage instance is created.
cos_instance_crn	The CRN of the Object Storage instance
cos_instance_guid	The GUID of the Object Storage instance
cos_instance_id	The ID of the Object Storage instance
cos_instance_name	The name of the Object Storage instance
instance_cbr_rules	Object Storage instance context-based restriction rules
kms_key_crn	The CRN of the KMS key used to encrypt the bucket
resource_group_id	Resource group ID
resource_keys	List of resource keys
s3_endpoint_direct	S3 direct endpoint
s3_endpoint_private	S3 private endpoint
s3_endpoint_public	S3 public endpoint

Contributing

You can report issues and request features for this module in GitHub issues in the module repo. See Report an issue or request a feature.

To set up your local development environment, see Local development setup in the project documentation.