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.

• Account Management
  • Resource Group service
    • Viewer platform access
• IAM Services
  • IBM Cloud Activity Tracker service
    • Editor platform access
    • Manager service access
  • IBM Cloud Monitoring service
    • Editor platform access
    • Manager service access
  • IBM Cloud Object Storage service
    • Editor platform access
    • Manager service access

Requirements

Name	Version
terraform	>= 1.4.0
ibm	>= 1.70.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.28.1
instance_cbr_rule	terraform-ibm-modules/cbr/ibm//modules/cbr-rule-module	1.28.1

Resources

Name	Type
ibm_cos_bucket.cos_bucket	resource
ibm_cos_bucket.cos_bucket1	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 will be sent to Activity Tracker.	bool	true	no
activity_tracker_read_data_events	If set to true, all Object Storage bucket read events (i.e. downloads) will be sent to Activity Tracker.	bool	true	no
activity_tracker_write_data_events	If set to true, all Object Storage bucket write events (i.e. uploads) will be sent to Activity Tracker.	bool	true	no
add_bucket_name_suffix	Whether to add a randomly generated 4-character suffix to the new 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 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_type	The storage class or archive type to which you want the object to transition. Possible values: Glacier, Accelerated. Applies only if create_cos_bucket is 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 new Object Storage bucket. Applies only if create_cos_bucket is true.	string	null	no
bucket_storage_class	The storage class of the new bucket. Required only if create_cos_bucket is true. Possible values: standard, vault, cold, smart, onerate_active.	string	"standard"	no
cos_instance_name	The name for the IBM Cloud Object Storage instance provisioned by this module. Applies only if create_cos_instance is true.	string	null	no
cos_location	The location for the Object Storage instance. Applies only if create_cos_instance is true.	string	"global"	no
cos_plan	The plan to use when Object Storage instances are created. Possible values: standard, cos-one-rate-plan. Applies only if create_cos_instance is true. For more details refer https://cloud.ibm.com/docs/cloud-object-storage?topic=cloud-object-storage-provision.	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 a IBM Cloud Object Storage instance.	bool	true	no
cross_region_location	Specify the cross-region bucket location. Possible values: us, eu ap. If specified, set region and single_site_location to null.	string	null	no
existing_cos_instance_id	The ID of an existing cloud object storage instance. Required if create_cos_instance is 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 false.	string	null	no
expire_days	The number of days before the expire rule action takes effect. Applies only if create_cos_bucket is true.	number	365	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 KMS key encryption to encrypt data in Object Storage buckets. Applies only if create_cos_bucket is true.	bool	true	no
kms_key_crn	The CRN of the KMS key to encrypt the data in the Object Storage bucket. Required if kms_encryption_enabled and create_cos_bucket are true.	string	null	no
management_endpoint_type_for_bucket	The type of endpoint for the IBM terraform provider to manage the bucket. Possible values: public, private, direct.	string	"public"	no
monitoring_crn	The CRN of an IBM Cloud Monitoring instance to to send Object Storage bucket metrics to. If no value passed, metrics are sent to the instance associated to 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 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 true.	number	0	no
object_locking_enabled	Whether to create an object lock configuration. Applies only if object_versioning_enabled and create_cos_bucket are true.	bool	false	no
object_versioning_enabled	Whether to enable object versioning to keep multiple versions of an object in a bucket. Cannot be used with retention rule. Applies only if create_cos_bucket is 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 will be sent to the monitoring service.	bool	true	no
resource_group_id	The resource group ID for the new Object Storage instance. Required only if create_cos_instance is 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 true.	number	90	no
retention_enabled	Whether retention for the Object Storage bucket is enabled. Applies only if create_cos_bucket is 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 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 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 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 KMS 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 KMS instance in existing_kms_guid.	bool	false	no
usage_metrics_enabled	If set to true, all Object Storage bucket usage metrics will be sent to the monitoring service.	bool	true	no

Outputs

Name	Description
bucket_cbr_rules	COS bucket rules
bucket_crn	Bucket CRN
bucket_id	Bucket id
bucket_name	Bucket name
bucket_region	Bucket region if you create a regional bucket
bucket_storage_class	Bucket Storage Class
cbr_rule_ids	List of all rule ids
cos_account_id	The account ID in which the Cloud Object Storage instance is created.
cos_instance_crn	The CRN of the Cloud Object Storage instance
cos_instance_guid	The GUID of the Cloud Object Storage instance
cos_instance_id	The ID of the Cloud Object Storage instance
cos_instance_name	The name of the Cloud Object Storage instance
instance_cbr_rules	COS instance rules
kms_key_crn	The CRN of the KMS key used to encrypt the COS 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.