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
  • buckets
  • fscloud
• Examples
  • Advanced example
  • Basic example
  • Bucket replication example
  • Financial Services compliant example
  • One Rate plan 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"
  existing_kms_instance_guid = "xxxxxxxx-XXXX-XXXX-XXXX-xxxxxxxx"
  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.79.2, < 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.33.0
instance_cbr_rule	terraform-ibm-modules/cbr/ibm//modules/cbr-rule-module	1.33.0

Resources

Name	Type
ibm_cos_bucket.cos_bucket	resource
ibm_cos_bucket.cos_bucket1	resource
ibm_cos_bucket_lifecycle_configuration.cos_bucket_lifecycle	resource
ibm_cos_bucket_object_lock_configuration.lock_configuration	resource
ibm_iam_authorization_policy.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

Inputs

Name	Description	Type	Default	Required
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	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.	number	90	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
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_location	The location for the Object Storage instance. Required if create_cos_instance is set to true.	string	"global"	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
existing_kms_instance_guid	The GUID of the Key Protect or Hyper Protect Crypto Services instance that holds the key specified in kms_key_crn. Required if skip_iam_authorization_policy 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.	number	365	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
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
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	Whether to create an IAM authorization policy that permits the Object Storage instance to read the encryption key from the key management service instance. An authorization policy must exist before an encrypted bucket can be created. Set to true to avoid creating the policy. If set to false, specify a value for the key management service instance in existing_kms_guid.	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.