KMS all inclusive module

This module combines the following key management service (KMS) modules to create a full end-to-end key infrastructure:

• Key Protect module
• KMS Key module
• KMS Key Ring module

Overview

• terraform-ibm-kms-all-inclusive
• Examples
  • Advanced private only instance with CBRs
  • Basic example
  • Existing KMS example
• Contributing

Reference architectures

• KMS standard solution

terraform-ibm-kms-all-inclusive

The module takes a list, called keys, that supports hierarchical "key rings" for a single key management service (KMS) instance. Because access to key rings is managed in the KMS, you can comply with controls around least privilege (for example, NIST AC-6) and can reduce the number of access groups you need to assign. For more information about key rings, see Grouping keys together using key rings. The following example shows a typical topology for a KMS instance:

├── cos-key-ring
│   ├── root-key-cos-bucket-1
│   ├── root-key-cos-bucket-2
│   ├── root-key-cos-bucket-...
├── ocp-key-ring
│   ├── root-key-ocp-cluster-1
│   ├── root-key-ocp-cluster-2
│   ├── root-key-ocp-cluster-...

In this scenario cos and ocp represent different IBM Cloud Services that utilize KMS keys to encrypt data at rest, each of the keys represent a different bucket or cluster in your environment.

Using HPCS instead of Key Protect

This module supports creating key rings and keys for Key Protect or Hyper Protect Crypto Services (HPCS). By default the module creates a Key Protect instance and creates the key rings and keys in that service instance, but this can be modified to use an existing HPCS instance by providing the CRN of your HPCS instance in the var.existing_kms_instance_crn input variable, and then setting the var.create_key_protect_instance input variable to false. For more information on provisioning an HPCS instance, please see: https://github.com/terraform-ibm-modules/terraform-ibm-hpcs

Using Multiple Key Protect instances

The module supports only a single KMS instance and creates the key topology in that instance. The module code doesn't create multiple Key Protect instances, or support key rings and keys across multiple KMS instances.

In a typical production environment, services might need multiple Key Protect or HPCS instances for compliance reasons. For example, you might need isolation between regulatory boundaries (for example, between FedRamp and everything else). Or you might be required to isolate keys that are used by a service's control plane from the data plane (for example, with IBM Cloud Databases (ICD) services).

To achieve compliance, you can write logic to call the module multiple times for multiple KMS instances.

One emerging pattern is to use one KMS instance per VPC. All workloads in the VPC access the KMS instance through a VPE binding. This simple approach ensures network segmentation. A drawback is that this approach creates more KMS instances than necessary, in some case.

Usage

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

module "kms_all_inclusive" {
  source                    = "terraform-ibm-modules/kms-all-inclusive/ibm"
  version                   = "X.X.X" # replace "X.X.X" with a release version to lock into a specific release
  key_protect_instance_name = "my-key-protect-instance"
  resource_group_id         = "xxXXxxXXxXxXXXXxxXxxxXXXXxXXXXX"
  region                    = "us-south"
  keys = [
    # use an existing key ring named "example-key-ring-1"
    {
      key_ring_name = "example-key-ring-1"
      existing_key_ring = true
      keys = [
        {
          key_name = "example-key-1"
          standard_key = true
          rotation_interval_month = 1
          dual_auth_delete_enabled = true
          force_delete = true
        },
        {
          key_name = "example-key-2"
          standard_key = false
          rotation_interval_month = 12
          dual_auth_delete enabled = false
          force_delete = false
        }
      ]
    },
    # create a new key ring named "example-key-ring-2"
    {
      key_ring_name = "example-key-ring-2"
      existing_key_ring = false
      keys = [
        {
          key_name = "example-key-3"
          standard_key = true
          rotation_interval_month = 4
          dual_auth_delete_enabled = true
          force_delete = true
        },
        {
          key_name = "example-key-4"
          standard_key = false
          rotation_interval_month = 8
          dual_auth_delete enabled = false
          force_delete = false
        }
      ]
    }
  ]
}

Required IAM access policies

You need the following permissions to run this module.

• Account Management
  • Resource Group service
    • Viewer platform access
• IAM Services
  • Key Protect service
    • Editor platform access
    • Manager service access

For more info, see Understanding user roles and resources

Requirements

Modules

Resources

Inputs

list(object({
    description = string
    account_id  = string
    rule_contexts = list(object({
      attributes = optional(list(object({
        name  = string
        value = string
    }))) }))
    enforcement_mode = string
    operations = optional(list(object({
      api_types = list(object({
        api_type_id = string
      }))
    })))
  }))

object({
    create_root_key     = optional(bool, true)
    create_standard_key = optional(bool, true)
    import_root_key     = optional(bool, true)
    import_standard_key = optional(bool, true)
    enforce_token       = optional(bool, false)
  })

list(object({
    key_ring_name     = string
    existing_key_ring = optional(bool, false)
    keys = list(object({
      key_name                 = string
      standard_key             = optional(bool, false)
      rotation_interval_month  = optional(number, 1)
      dual_auth_delete_enabled = optional(bool, false)
      force_delete             = optional(bool, false)
    }))
  }))

Outputs

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.