Skip to content

Create and configure an IBM Cloud Hyper Protect Crypto Services instance.

License

Notifications You must be signed in to change notification settings

terraform-ibm-modules/terraform-ibm-hpcs

Repository files navigation

IBM Cloud Hyper Protect Crypto Services

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

You can use this module to provision an IBM Cloud Hyper Protect Crypto Services (HPCS) instance.

The next step after provisioning an HPCS instance is to initialize the service to manage the keys. This module supports the following approaches:

  • Provision and initialize the service by using the recovery crypto units method.
  • Provision the service and initialize it manually. For example, by using smart cards or key part files. This approach requires additional steps to execute after provisioning the service instance.
  • Provision and initialize the service by using your own hardware security module (HSM).

For more information, see components and concepts of HPCS and about service instance initialization in the Cloud Docs.

If you provision an HPCS instance with a private-only endpoint, both public and private endpoints URLs are included in the output. You can ignore the public endpoint. It is included for convenience in case you need to switch to it temporarily. However, make sure that you switch back to the private endpoint as soon as possible.

Overview

terraform-ibm-hpcs

Usage to create the HPCS instance

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

module "hpcs" {
  source                                          = "terraform-ibm-modules/hpcs/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"
  name                                            = "my-hpcs-instance"
  tags                                            = ["tag1","tag2"]
  plan                                            = "standard"
  auto_initialization_using_recovery_crypto_units = false
}

There are multiple ways to initialize the service instance few of them include some manual steps, they are as follows:

Create and initialize the Hyper Protect Crypto Services instance

Before you begin: creating administrator signature keys

To initialize the instance with a third-party signing service, see Using a signing service to manage signature keys for instance initialization in the Cloud Docs.

Otherwise, if you are not using a third-party signing service, run the following commands that use the IBM Cloud TKE CLI plug-in to generate admin signature keys.

  • Install the IBM Cloud CLI

  • Make sure you have a recent version the IBM Cloud Trusted Key Entry (TKE) CLI plug-in installed.

    • Run this command to install the plug-in:

      ibmcloud plugin install tke
      

      Or

    • Run this command to update your plug-in to the latest version with the following command:

      ibmcloud plugin update tke
      
  • Set the environment variable CLOUDTKEFILES to specify the directory where you want to save signature key files.

    export CLOUDTKEFILES=<absolute path of directory>
    
  • Login in to IBM CLoud CLI and make sure that you're logged in to the correct region and resource group where the service instance locates.

    ibmcloud login
    ibmcloud target -r <region> -g <resource_group>
    
  • Run the following command to create administrator signature keys. The signature keys are created in the path specified in CLOUDTKEFILES and stored in files that are protected by passwords. Repeat this step to generate more keys.

    ibmcloud tke sigkey-add
    

ℹ️ Requirement: Make sure that information about the administrator who is associated with the key is set in the admins input variable.

Usage to create and initialize the HPCS instance

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

module "hpcs" {
  source                                          = "terraform-ibm-modules/hpcs/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"
  name                                            = "my-hpcs-instance"
  tags                                            = ["tag1","tag2"]
  auto_initialization_using_recovery_crypto_units = true
  number_of_crypto_units                          = 3
  admins = [
    {
      name  = "admin1"
      key   = "/cloudTKE/1.sigkey"
      token = "sensitive1234"
    },
    {
      name  = "admin2"
      key   = "/cloudTKE/2.sigkey"
      token = "sensitive1234"
    }
  ]
}

Usage to create and initialize the HPCS instance using Schematics

  • Convert the signature keys to Base64 encoding.
    cat 1.sigkey | base64
    cat 2.sigkey | base64
provider "ibm" {
  ibmcloud_api_key = "XXXXXXXXXXXXXX"
  region           = "us-south"
}

module "hpcs" {
  source                                          = "terraform-ibm-modules/hpcs/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"
  name                                            = "my-hpcs-instance"
  tags                                            = ["tag1","tag2"]
  auto_initialization_using_recovery_crypto_units = true
  number_of_crypto_units                          = 3
  base64_encoded_admins = [
    {
      name  = "admin1"
      key   = "eyJlbmNrZXkiOiJyYW5kb21fa2V5Iiwia2V5VHlwZSI6InJhbmRvbSIsIm5hbWUiOiJhZG1pbjEiLCJzZWFTYWx0IjoicmFuZG9tIiwic2tpIjoicmFuZG9tIn0="
      token = "sensitive1234"
    },
    {
      name  = "admin2"
      key   = "eyJlbmNrZXkiOiJyYW5kb20yX2tleSIsImtleVR5cGUiOiJyYW5kb20yIiwibmFtZSI6ImFkbWluMiIsInNlYVNhbHQiOiJyYW5kb20yIiwic2tpIjoicmFuZG9tMiJ9"
      token = "sensitive1234"
    }
  ]
}

Required IAM access policies

You need the following permissions to run this module.

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

Requirements

Name Version
terraform >= 1.3.0
ibm >= 1.49.0, < 2.0.0
local >= 2.4.0, < 3.0.0

Modules

No modules.

Resources

Name Type
ibm_hpcs.hpcs_instance resource
ibm_resource_instance.base_hpcs_instance resource
local_file.admin_files resource

Inputs

Name Description Type Default Required
admins A list of administrators for the instance crypto units. See instructions to create administrator signature keys. You can set up to 8 administrators. Required if auto_initialization_using_recovery_crypto_units set to true.
list(object({
name = string # max length: 30 chars
key = string # the absolute path and the file name of the signature key file if key files are created using TKE CLI and are not using a third-party signing service
# if you are using a signing service, the key name is appended to a URI that will be sent to the signing service
token = string # sensitive: the administrator password/token to authorize and access the corresponding signature key file
}))
[] no
auto_initialization_using_recovery_crypto_units Set to true if auto initialization using recovery crypto units is required. bool true no
base64_encoded_admins A list of up to 8 administrators for the instance crypto units. Required if auto_initialization_using_recovery_crypto_units is set to true. Pass the signature keys as base64 encoded values. For information about administrator signature keys, see the readme file.
list(object({
name = string # max length: 30 chars
key = string # base64 encoded value of signature key files if key files are created using TKE CLI and are not using a third-party signing service
token = string # sensitive: the administrator password/token to authorize and access the corresponding signature key file
}))
[] no
create_timeout Create timeout value of the HPCS instance. string "180m" no
delete_timeout Delete timeout value of the HPCS instance. string "180m" no
hsm_connector_id The HSM connector ID provided by IBM required for Hybrid HPCS. Available to selected customers only. string null no
name The name to give the Hyper Protect Crypto Service instance. Max length allowed is 30 chars. string n/a yes
number_of_crypto_units The number of operational crypto units for your service instance. number 2 no
number_of_failover_units The number of failover crypto units for your service instance. Default is 0 and cross-region high availability will not be enabled. number 0 no
plan The name of the service plan that you choose for your Hyper Protect Crypto Service instance. string "standard" no
region The region where you want to deploy your instance. string n/a yes
resource_group_id The resource group name where the Hyper Protect Crypto Service instance will be created. string n/a yes
revocation_threshold The number of administrator signatures required to remove an administrator after you leave imprint mode. Required if auto_initialization_using_recovery_crypto_units set to true. number 1 no
service_endpoints The service_endpoints to access your service instance. Used only if auto_initialization_using_recovery_crypto_units is set to true. Can be set to private-only if Terraform has access to the private endpoints. Default value is public-and-private. string "public-and-private" no
signature_server_url The URL and port number of the signing service. Required if auto_initialization_using_recovery_crypto_units set to true and using a third-party signing service to provide administrator signature keys. Used only if auto_initialization_using_recovery_crypto_units is set to true. string null no
signature_threshold The number of administrator signatures required to execute administrative commands. Required if auto_initialization_using_recovery_crypto_units set to true. number 1 no
tags Optional list of resource tags to apply to the HPCS instance. list(string) [] no
update_timeout Update timeout value of the HPCS instance. string "180m" no

Outputs

Name Description
crn HPCS instance crn
endpoints HPCS instance endpoints
guid HPCS instance guid
hpcs_name HPCS instance name
id HPCS instance id

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.