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"
  sysdig_crn                 = "crn:v1:bluemix:public:sysdig-monitor:us-south:a/xxXXxxXXxXxXXXXxxXxxxXXXXxXXXXX:xxXXxxXXxXxXXXXxxXxxxXXXXxXXXXX::"
  activity_tracker_crn       = "crn:v1:bluemix:public:logdnaat:us-south:a/xxXXxxXXxXxXXXXxxXxxxXXXXxXXXXX:xxXXxxXXxXxXXXXxxXxxxXXXXxXXXXX::"
}

# 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
  sysdig_crn               = "crn:v1:bluemix:public:sysdig-monitor:us-south:a/xxXXxxXXxXxXXXXxxXxxxXXXXxXXXXX:xxXXxxXXxXxXXXXxxXxxxXXXXxXXXXX::"
  activity_tracker_crn     = "crn:v1:bluemix:public:logdnaat:us-south:a/xxXXxxXXxXxXXXXxxXxxxXXXXxXXXXX:xxXXxxXXxXxXXXXxxXxxxXXXXxXXXXX::"
  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, <1.6.0
ibm	>= 1.56.1, < 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.18.0
instance_cbr_rule	terraform-ibm-modules/cbr/ibm//modules/cbr-rule-module	1.18.0

Resources

Name	Type
ibm_cos_bucket.cos_bucket	resource
ibm_cos_bucket.cos_bucket1	resource
ibm_iam_authorization_policy.policy	resource
ibm_resource_instance.cos_instance	resource
ibm_resource_key.resource_key	resource
ibm_resource_tag.cos_access_tag	resource
random_string.bucket_name_suffix	resource
terraform_data.generate_hmac_credentials	resource
terraform_data.resource_key_existing_serviceid_crn	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 cos instance created by the module, see https://cloud.ibm.com/docs/account?topic=account-access-tags-tutorial for more details	list(string)	[]	no
activity_tracker_crn	Activity tracker crn for COS bucket (Optional)	string	null	no
add_bucket_name_suffix	Add random generated suffix (4 characters long) to the newly provisioned COS bucket name (Optional).	bool	false	no
archive_days	Specifies the number of days when the archive rule action takes effect. Only used if 'create_cos_bucket' is true. This must be set to null when when using var.cross_region_location as archive data is not supported with this feature.	number	90	no
archive_type	Specifies the storage class or archive type to which you want the object to transition. Only used if 'create_cos_bucket' is true.	string	"Glacier"	no
bucket_cbr_rules	(Optional, list) List of CBR 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 to give the newly provisioned COS bucket. Only required if 'create_cos_bucket' is true.	string	null	no
bucket_storage_class	the storage class of the newly provisioned COS bucket. Only required if 'create_cos_bucket' is true. Supported values are 'standard', 'vault', 'cold', 'smart' and onerate_active.	string	"standard"	no
cos_instance_name	The name to give the cloud object storage instance that will be provisioned by this module. Only required if 'create_cos_instance' is true.	string	null	no
cos_location	Location to provision the cloud object storage instance. Only used if 'create_cos_instance' is true.	string	"global"	no
cos_plan	Plan to be used for creating cloud object storage instance. Only used if 'create_cos_instance' it true.	string	"standard"	no
cos_tags	Optional list of tags to be added to cloud object storage instance. Only used if 'create_cos_instance' it true.	list(string)	[]	no
create_cos_bucket	Set as true to create a new Cloud Object Storage bucket	bool	true	no
create_cos_instance	Set as true to create a new Cloud Object Storage instance.	bool	true	no
create_resource_key	Set as true to create a new resource key for the Cloud Object Storage instance.	bool	true	no
cross_region_location	Specify the cross-regional bucket location. Supported values are 'us', 'eu', and 'ap'. If you pass a value for this, ensure to set the value of var.region to null.	string	null	no
existing_cos_instance_id	The ID of an existing cloud object storage instance. Required if 'var.create_cos_instance' is false.	string	null	no
existing_kms_instance_guid	The GUID of the Key Protect or Hyper Protect instance in which the key specified in var.kms_key_crn is coming from. Required if var.skip_iam_authorization_policy is false in order to create an IAM Access Policy to allow Key Protect or Hyper Protect to access the newly created COS instance.	string	null	no
expire_days	Specifies the number of days when the expire rule action takes effect. Only used if 'create_cos_bucket' is true.	number	365	no
generate_hmac_credentials	Set as true to generate an HMAC key in the resource key. Only used when create_resource_key is true.	bool	false	no
instance_cbr_rules	(Optional, list) List of CBR 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	Set as true to use KMS key encryption to encrypt data in COS bucket (only applicable when var.create_cos_bucket is true).	bool	true	no
kms_key_crn	CRN of the KMS key to use to encrypt the data in the COS bucket. Required if var.encryption_enabled and var.create_cos_bucket are true.	string	null	no
management_endpoint_type_for_bucket	The type of endpoint for the IBM terraform provider to use to manage the bucket. (public, private or direct)	string	"public"	no
object_versioning_enabled	Enable object versioning to keep multiple versions of an object in a bucket. Cannot be used with retention rule. Only used if 'create_cos_bucket' is true.	bool	false	no
region	The region to provision the bucket. If you pass a value for this, do not pass one for var.cross_region_location.	string	"us-south"	no
resource_group_id	The resource group ID where The COS instance will be provisioned. It is required if setting input variable create_cos_instance to true.	string	null	no
resource_key_existing_serviceid_crn	CRN of existing serviceID to bind with resource key to be created. If null a new ServiceID is created for the resource key.	string	null	no
resource_key_name	The name of the resource key to be created.	string	"cos-resource-key"	no
resource_key_role	The role you want to be associated with your new resource key. Valid roles are 'Writer', 'Reader', 'Manager', 'Content Reader', 'Object Reader', 'Object Writer'.	string	"Manager"	no
retention_default	Specifies default duration of time an object that can be kept unmodified for COS bucket. Only used if 'create_cos_bucket' is true.	number	90	no
retention_enabled	Retention enabled for COS bucket. Only used if 'create_cos_bucket' is true.	bool	false	no
retention_maximum	Specifies maximum duration of time an object that can be kept unmodified for COS bucket. Only used if 'create_cos_bucket' is true.	number	350	no
retention_minimum	Specifies minimum duration of time an object must be kept unmodified for COS bucket. Only used if 'create_cos_bucket' is true.	number	90	no
retention_permanent	Specifies a permanent retention status either enable or disable for COS bucket. Only used if 'create_cos_bucket' is true.	bool	false	no
skip_iam_authorization_policy	Set to true to skip the creation of an IAM authorization policy that permits the COS instance created to read the encryption key from the KMS instance in existing_kms_instance_guid. WARNING: An authorization policy must exist before an encrypted bucket can be created	bool	false	no
sysdig_crn	Sysdig Monitoring crn for COS bucket (Optional)	string	null	no

Outputs

Name	Description
bucket_cbr_rules	COS bucket rules
bucket_crn	Bucket CRN
bucket_id	Bucket id
bucket_name	Bucket name
bucket_storage_class	Bucket Storage Class
cbr_rule_ids	List of all rule ids
cos_instance_guid	The GUID of the Cloud Object Storage Instance where the buckets are created
cos_instance_id	The ID of the Cloud Object Storage Instance where the buckets are created
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
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.