Setting up Terraform for Hyper Protect Crypto Services with Unified Key Orchestrator

Example: Provisioning and initializing service instances by using Terraform

Complete the following steps to create and initialize a Hyper Protect Crypto Services instance by using Terraform:

1. Install the Terraform CLI and configure the IBM Cloud Provider plug-in for Terraform by following the Terraform on IBM Cloud getting started tutorial.

   The plug-in abstracts the IBM Cloud APIs that are used to provision, update, or delete Hyper Protect Crypto Services service instances and resources. The preferred Terraform versions are 0.13.x, 0.14.x, and 0.15.x. In the versions.tf file, you need to specify the version parameter to 1.29.0.

2. Set up crypto unit administrator signature keys. You can select one of the following ways to create administrator signature keys:

   • Using the IBM Cloud Trusted Key Entry (TKE) CLI plug-in

     After you install and configure the TKE CLI plug-in by following these instructions, you can use the command ibmcloud tke sigkey-add to create administrator signature keys. The signature keys are stored in files that are protected by passwords on your local workstation. The file path is specified by the environment variable CLOUDTKEFILES.

   • Using a third-party signing service

     A third-party signing service can be used to create, store, and access the signature keys that are used by both the TKE CLI plug-in and Terraform. To enable the signing service in the TKE CLI plug-in, you need to set the TKE_SIGNSERV_URL environment variable on the local workstation to the URL and port number where the signing service is running. To enable the signing service in Terraform, you need to set the signature_server_url parameter in the resource block to the same value.

3. Create a Terraform configuration file main.tf in the same folder as versions.tf. In this file, you add the configurations to perform the corresponding actions.

   The following template is an example configuration file to provision a Hyper Protect Crypto Services instance with 2 operational crypto units in the us-south region. This instance is charged according to the Unified Key Orchestrator pricing plan and is initialized with 2 administrators. The master key is automatically generated in recovery crypto units that are assigned to the instance. The signature keys are created by using the TKE CLI plug-in and stored in local protected files.

   As recovery crypto units are currently available in supported regions other than Madrid (eu-es), using Terraform to initialize Hyper Protect Crypto Services instances is not supported in this region. For more information about manual initialization, see Introducing service instance initialization approaches.

   resource ibm_hpcs hpcs {
      location             = "us-south"
      name                 = "test-hpcs"
      plan                 = "hpcs-hourly-uko"
      units                = 2
      signature_threshold  = 1
      revocation_threshold = 1
      admins {
        name  = "admin1"
        key   = "/cloudTKE/1.sigkey"
        token = "sensitive1234"
      }
      admins {
        name  = "admin2"
        key   = "/cloudTKE/2.sigkey"
        token = "sensitive1234"
      }
   }
   
   resource "ibm_iam_user_policy" "policy" {
      ibm_id = "user@ibm.com"
      roles  = ["Manager"]
   
      resources {
        service              = "test-hpcs"
        resource_instance_id = element(split(":", ibm_resource_instance.hpcs.id), 7)
      }
   }
   

   In production environments, it is suggested to provide the passwords for the signature key files or the tokens for the signing service during the process of applying Terraform instead of writing it in plain text in the configuration file. In that case, you are prompted to enter the authentication passwords or tokens when you run Terraform commands. After the instance initialization, the values that you enter for the passwords or tokens are stored in a .tfstate file. For more information about securing sensitive data in Terraform, see Sensitive Data in State.

   The following table lists supported parameters when you create and initialize a service instance with Terraform:

   Table 1. Supported parameters for provisioning a service instance with Terraform

   Parameter	Description
   name	Required. The name of your Hyper Protect Crypto Services instance.
   location	Required. The region abbreviation, such as us-south, that represents the geographic area where the operational crypto units of your service instance are located. For more information, see Regions and locations. As recovery crypto units are not available in Madrid (eu-es), you cannot use Terraform for instance initialization in the eu-es region.
   plan	Required. The pricing plan for your service instance.
   units	Required. The number of operational crypto units for your service instance. Valid values are 2 or 3.
   failover_units	Not applicable. Cross-region high availability is not currently supported for Unified Key Orchestrator.
   service_endpoints	Not applicable. The default setting is public-and-private.
   tags	Optional. Tags that are associated with your instance are used to organize your resources. For more information about tags, see Working with tags.
   resource_group_id	Optional. The resource group where you want to organize and manage your service instance. If you do not specify the value, the default resource group is Default.
   signature_threshold	Required. The number of administrator signatures that is required to execute administrative commands. The valid value is in the range 1 - 8. You need to set it to at least 2 to enable quorum authentication.
   revocation_threshold	Required. The number of administrator signatures that is required to remove an administrator after you leave imprint mode. The valid value is in the range 1 - 8.
   admins	Required. The list of administrators for the instance crypto units. You can set up to eight administrators and the number needs to be equal to or greater than the thresholds that you specify. The following values need to be set for each administrator: name: The name of the administrator. It needs to be no more than 30 characters in length. key: If you are using signature key files on the local workstation that are created by the TKE CLI plug-in and are not using a third-party signing service, specify the absolute path and file name of the signature key file that is to be used. If you are using a signing service to provide signature keys, specify the name of the signature key depending on the signing service definition. The character string for the key name is appended to a URI that is sent to the signing service and must contain only unreserved characters as defined by section 2.3 of RFC3986. token: If you are using signature key files on the local workstation that are created by the TKE CLI plug-in and are not using a third-party signing service, specify the administrator password to access the corresponding signature key file. If you are using a signing service to provide signature keys, specify the token that authorizes use of the signature key depending on the signing service definition. Note: The token parameter is optional. If you don't specify the token, you are prompted to enter the token value when you run Terraform commands. After the instance initialization, the value that you enter for the token parameter is stored in a .tfstate file. For more information about securing sensitive data in Terraform, see Sensitive Data in State.
   signature_server_url	Optional. The URL and port number where the signing service is running. If you are using a third-party signing service to provide administrator signature keys, you need to specify this parameter.

   If you manage multiple service instances in the main.tf file, make sure to set the same signature_server_url parameter for each instance. Otherwise, you will not be able to perform the actions successfully.

4. Initialize the Terraform CLI with the following command.

   terraform init
   

5. Create a Terraform execution plan with the following command. The Terraform execution plan summarizes all the actions that need to be run to create the Hyper Protect Crypto Services instance in your account.

   terraform plan
   

6. Create and initialize the Hyper Protect Crypto Services instance by applying Terraform.

   terraform apply
   

7. Check whether the Hyper Protect Crypto Services instance is created and initialized from the IBM Cloud resource list.

8. Verify that the access policy is successfully assigned. For more information, see Reviewing assigned access in the UI.

What's next?

For more information about using Terraform to manage Hyper Protect Crypto Services instances with Unified Key Orchestrator, see the following Terraform documentation:

• Managing keys
• Managing keystores
• Managing key templates
• Managing vaults