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

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"
  key_protect_plan          = "tiered-pricing" # or "cross-region-resiliency"
  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

Name	Version
terraform	>= 1.9.0
ibm	>= 1.79.1, <2.0.0

Modules

Name	Source	Version
existing_key_ring_keys	terraform-ibm-modules/kms-key/ibm	v1.4.2
key_protect	terraform-ibm-modules/key-protect/ibm	2.10.17
kms_key_rings	terraform-ibm-modules/kms-key-ring/ibm	v2.6.1
kms_keys	terraform-ibm-modules/kms-key/ibm	v1.4.2

Resources

Name	Type
ibm_resource_instance.existing_kms_instance	data source

Inputs

Name	Description	Type	Default	Required
access_tags	A list of access tags to apply to the Key Protect instance. Only used if 'create_key_protect_instance' is set to true.	list(string)	[]	no
cbr_rules	(Optional, list) List of context-based restriction rules to create	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 })) }))) }))	[]	no
create_key_protect_instance	A flag to control whether a Key Protect instance is created. The default is true.	bool	true	no
dual_auth_delete_enabled	If set to true, a dual authorization policy is enabled on the Key Protect instance. After the dual authorization policy is set on the instance, it cannot be reverted. An instance with dual authorization policy enabled cannot be destroyed by using Terraform. Only used if 'create_key_protect_instance' is set to 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 set to true. In order to view metrics, you need an IBM Cloud Monitoring (Sysdig) instance that is located in the same region as the Key Protect instance. After you provision a Monitoring instance, enable platform metrics to monitor your Key Protect instance.	bool	true	no
existing_kms_instance_crn	The CRN of an existing Key Protect or Hyper Protect Crypto Services instance. Required if 'create_key_protect_instance' is set to false.	string	null	no
key_create_import_access_enabled	If set to true, a key create and import access policy is enabled on the instance of Key Protect. Only used if 'create_key_protect_instance' is set to true.	bool	true	no
key_create_import_access_settings	Key create and import access policy settings to configure if 'enable_key_create_import_access_policy' is set to true. Only used if 'create_key_protect_instance' is set to 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. Possible values are 'public' or 'private'	string	"public"	no
key_protect_allowed_network	Allowed network types for the Key Protect instance. Possible values are 'private-only', or 'public-and-private'. Only used if 'create_key_protect_instance' is set to true.	string	"public-and-private"	no
key_protect_instance_name	The name to give the Key Protect instance that that is created by this module. Only used if 'create_key_protect_instance' is set to true.	string	"key-protect"	no
key_protect_plan	Plan for the Key Protect instance. Supported values are 'tiered-pricing' and 'cross-region-resiliency'. Only used if 'create_key_protect_instance' is set to true.	string	"tiered-pricing"	no
key_ring_endpoint_type	The type of endpoint to be used for creating key rings. Possible values are 'public' or 'private'.	string	"public"	no
keys	A list of objects that 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. This object also contains a list of keys to be created in that key ring.	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) kmip = optional(list(object({ name = string description = optional(string) certificates = optional(list(object({ name = optional(string) certificate = string })), []) })), []) })) }))	[]	no
region	The IBM Cloud region where all resources are provisioned.	string	n/a	yes
resource_group_id	The ID of the resource group where the Key Protect instance is created. Not required if 'create_key_protect_instance' is set to false.	string	null	no
resource_tags	Optional list of tags to add to the Key Protect instance. Only used if 'create_key_protect_instance' is set to true.	list(string)	[]	no
rotation_enabled	If set to true, a rotation policy is enabled on the Key Protect instance. Only used if 'create_key_protect_instance' is set to true.	bool	true	no
rotation_interval_month	Specifies how often keys are rotated in months. Value must be between 1 and 12 inclusive. Only used if 'create_key_protect_instance' is set to true.	number	1	no

Outputs

Name	Description
cbr_rule_ids	Context-based restriction rule IDs to restrict access to the Key Protect instance
key_protect_crn	Key Protect service instance CRN when an instance is created, otherwise the value is null.
key_protect_id	Key Protect service instance ID when an instance is created, otherwise the value is null.
key_protect_instance_policies	Instance polices for the Key Protect instance
key_protect_name	Key Protect name
key_rings	Key rings that are created
keys	Keys that are created
kms_account_id	The account ID of the Key Protect instance.
kms_guid	Key Protect GUID
kms_private_endpoint	Key Protect instance private endpoint URL
kms_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.