Skip to content

Latest commit

 

History

History
235 lines (208 loc) · 22.9 KB

README.md

File metadata and controls

235 lines (208 loc) · 22.9 KB
Raw

Cloud Object Storage module

Graduated (Supported) semantic-release pre-commit latest release Renovate enabled Catalog release

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:

Overview

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.29.0
instance_cbr_rule terraform-ibm-modules/cbr/ibm//modules/cbr-rule-module 1.29.0

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.