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
  • 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 GUID of your HPCS instance in the var.existing_kms_instance_guid 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
      force_delete_key_ring = false
      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
      force_delete_key_ring = true
      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

Name	Version
terraform	>= 1.0.0, <1.7.0
ibm	>= 1.64.0, <2.0.0

Modules

Name	Source	Version
existing_key_ring_keys	terraform-ibm-modules/kms-key/ibm	v1.2.1
key_protect	terraform-ibm-modules/key-protect/ibm	2.7.0
kms_key_rings	terraform-ibm-modules/kms-key-ring/ibm	v2.3.1
kms_keys	terraform-ibm-modules/kms-key/ibm	v1.2.1

Resources

No resources.

Inputs

Name	Description	Type	Default	Required
access_tags	A list of access tags to apply to the Key Protect instance created by the module. Only used if 'create_key_protect_instance' is true.	list(string)	[]	no
create_key_protect_instance	A flag to control whether a Key Protect instance is created, defaults to true.	bool	true	no
dual_auth_delete_enabled	If set to true, Key Protect enables a dual authorization policy on the instance. Note: Once the dual authorization policy is set on the instance, it cannot be reverted. An instance with dual authorization policy enabled cannot be destroyed using Terraform. Only used if 'create_key_protect_instance' is true.	bool	false	no
enable_metrics	Set to true to enable metrics on the Key Protect instance. Only used if 'create_key_protect_instance' is true. In order to view metrics, you will need a Monitoring (Sysdig) instance that is located in the same region as the Key Protect instance. Once you provision the Monitoring instance, you will need to enable platform metrics.	bool	true	no
existing_kms_instance_guid	The GUID of an existing Key Protect or Hyper Protect Crypto Services instance. Required if 'create_key_protect_instance' is false.	string	null	no
key_create_import_access_enabled	If set to true, Key Protect enables a key create import access policy on the instance. Only used if 'create_key_protect_instance' is true.	bool	true	no
key_create_import_access_settings	Key create import access policy settings to configure if 'enable_key_create_import_access_policy' is true. Only used if 'create_key_protect_instance' is true. For more info see https://cloud.ibm.com/docs/key-protect?topic=key-protect-manage-keyCreateImportAccess	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) })	{}	no
key_endpoint_type	The type of endpoint to be used for creating keys. Accepts 'public' or 'private'	string	"public"	no
key_protect_allowed_network	The type of the allowed network to be set for the Key Protect instance. Possible values are 'private-only', or 'public-and-private'. Only used if 'create_key_protect_instance' is true.	string	"public-and-private"	no
key_protect_instance_name	The name to give the Key Protect instance that will be provisioned by this module. Only used if 'create_key_protect_instance' is true.	string	"key-protect"	no
key_protect_plan	Plan for the Key Protect instance. Currently only 'tiered-pricing' is supported. Only used if 'create_key_protect_instance' is true.	string	"tiered-pricing"	no
key_ring_endpoint_type	The type of endpoint to be used for creating key rings. Accepts 'public' or 'private'	string	"public"	no
keys	A list of objects which contain the key ring name, a flag indicating if this key ring already exists, and a flag to enable force deletion of the key ring. In addition, this object contains a list of keys with all of the information on the keys to be created in that key ring.	list(object({ key_ring_name = string existing_key_ring = optional(bool, false) force_delete_key_ring = optional(bool, true) 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, true) })) }))	[]	no
region	The IBM Cloud region where all resources will be provisioned.	string	n/a	yes
resource_group_id	The ID of the Resource Group to provision the Key Protect instance in. Not required if 'create_key_protect_instance' is false.	string	null	no
resource_tags	Optional list of tags to be added to the Key Protect instance. Only used if 'create_key_protect_instance' is true.	list(string)	[]	no
rotation_enabled	If set to true, Key Protect enables a rotation policy on the Key Protect instance. Only used if 'create_key_protect_instance' is true.	bool	true	no
rotation_interval_month	Specifies the key rotation time interval in months. Must be between 1 and 12 inclusive. Only used if 'create_key_protect_instance' is true.	number	1	no

Outputs

Name	Description
key_protect_crn	Key Protect service instance CRN when an instance is created, otherwise null
key_protect_id	Key Protect service instance ID when an instance is created, otherwise null
key_protect_instance_policies	Instance Polices of the Key Protect instance
key_protect_name	Key Protect Name
key_rings	IDs of new Key Rings created by the module
keys	IDs of new Keys created by the module
kms_guid	KMS GUID
kp_private_endpoint	Key Protect instance private endpoint URL
kp_public_endpoint	Key Protect instance public endpoint URL

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.