{"id":22689020,"url":"https://github.com/terraform-ibm-modules/terraform-ibm-hpcs","last_synced_at":"2025-04-12T21:52:27.368Z","repository":{"id":45888993,"uuid":"308575884","full_name":"terraform-ibm-modules/terraform-ibm-hpcs","owner":"terraform-ibm-modules","description":"Create and configure an IBM Cloud Hyper Protect Crypto Services instance.","archived":false,"fork":false,"pushed_at":"2025-04-12T19:10:59.000Z","size":645,"stargazers_count":3,"open_issues_count":1,"forks_count":6,"subscribers_count":14,"default_branch":"main","last_synced_at":"2025-04-12T21:52:24.836Z","etag":null,"topics":["core-team","graduated","hpcs","hyper-protect","ibm-cloud","kms","supported","terraform","terraform-module"],"latest_commit_sha":null,"homepage":"https://cloud.ibm.com/docs/hs-crypto","language":"HCL","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/terraform-ibm-modules.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2020-10-30T08:59:32.000Z","updated_at":"2025-04-12T19:11:01.000Z","dependencies_parsed_at":"2023-10-20T20:25:50.565Z","dependency_job_id":"58417566-1a50-480b-a56e-b900e1849eee","html_url":"https://github.com/terraform-ibm-modules/terraform-ibm-hpcs","commit_stats":null,"previous_names":[],"tags_count":16,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/terraform-ibm-modules%2Fterraform-ibm-hpcs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/terraform-ibm-modules%2Fterraform-ibm-hpcs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/terraform-ibm-modules%2Fterraform-ibm-hpcs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/terraform-ibm-modules%2Fterraform-ibm-hpcs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/terraform-ibm-modules","download_url":"https://codeload.github.com/terraform-ibm-modules/terraform-ibm-hpcs/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248637833,"owners_count":21137538,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["core-team","graduated","hpcs","hyper-protect","ibm-cloud","kms","supported","terraform","terraform-module"],"created_at":"2024-12-10T00:17:15.013Z","updated_at":"2025-04-12T21:52:27.359Z","avatar_url":"https://github.com/terraform-ibm-modules.png","language":"HCL","funding_links":[],"categories":[],"sub_categories":[],"readme":"# IBM Cloud Hyper Protect Crypto Services\n[![Graduated (Supported)](https://img.shields.io/badge/Status-Graduated%20(Supported)-brightgreen)](https://terraform-ibm-modules.github.io/documentation/#/badge-status)\n[![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit\u0026logoColor=white)](https://github.com/pre-commit/pre-commit)\n[![latest release](https://img.shields.io/github/v/release/terraform-ibm-modules/terraform-ibm-hpcs?logo=GitHub\u0026sort=semver)](https://github.com/terraform-ibm-modules/terraform-ibm-hpcs/releases/latest)\n[![Renovate enabled](https://img.shields.io/badge/renovate-enabled-brightgreen.svg)](https://renovatebot.com/)\n[![semantic-release](https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg)](https://github.com/semantic-release/semantic-release)\n\nYou can use this module to provision an IBM Cloud Hyper Protect Crypto Services (HPCS) instance.\n\nThe next step after provisioning an HPCS instance is to [initialize](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-get-started) the service to manage the keys. This module supports the following approaches:\n- Provision and initialize the service by using the [recovery crypto units method](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-initialize-hsm-recovery-crypto-unit).\n- Provision the service and [initialize](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-initialize-instance-mode) it manually. For example, by using smart cards or key part files. This approach requires additional steps to execute after provisioning the service instance.\n- Provision and initialize the service by using your own hardware security module (HSM).\n\n\nFor more information, see [components and concepts](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-understand-concepts) of HPCS and [about service instance initialization](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-introduce-service) in the Cloud Docs.\n\nIf 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.\n\n\u003c!-- Below content is automatically populated via pre-commit hook --\u003e\n\u003c!-- BEGIN OVERVIEW HOOK --\u003e\n## Overview\n* [terraform-ibm-hpcs](#terraform-ibm-hpcs)\n* [Submodules](./modules)\n    * [fscloud](./modules/fscloud)\n* [Examples](./examples)\n    * [Basic example](./examples/basic)\n    * [Complete example that creates and initialize HPCS instance](./examples/complete)\n    * [Financial Services Cloud profile](./examples/fscloud)\n    * [Hybrid-HPCS example](./examples/hybrid-hpcs)\n* [Contributing](#contributing)\n\u003c!-- END OVERVIEW HOOK --\u003e\n\n\n## terraform-ibm-hpcs\n\n### Usage to create the HPCS instance\n\n```hcl\nprovider \"ibm\" {\n  ibmcloud_api_key = \"XXXXXXXXXXXXXX\"\n  region           = \"us-south\"\n}\n\nmodule \"hpcs\" {\n  source                                          = \"terraform-ibm-modules/hpcs/ibm\"\n  version                                         = \"X.X.X\" # Replace \"X.X.X\" with a release version to lock into a specific release\n  resource_group_id                               = \"xxXXxxXXxXxXXXXxxXxxxXXXXxXXXXX\"\n  region                                          = \"us-south\"\n  name                                            = \"my-hpcs-instance\"\n  tags                                            = [\"tag1\",\"tag2\"]\n  plan                                            = \"standard\"\n  auto_initialization_using_recovery_crypto_units = false\n}\n```\n\nThere are multiple ways to initialize the service instance few of them include some manual steps, they are as follows:\n - [Initializing service instances by using smart cards and the Hyper Protect Crypto Services Management Utilities](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-initialize-hsm-management-utilities) : This approach gives you the highest security, which enables you to store and manage master key parts using smart cards.\n - [Initializing service instances by using key part files](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-initialize-hsm) : You can also initialize your service instance using master key parts that are stored in files on your local workstation. You can use this approach regardless of whether or not your service instance includes recovery crypto units.\n - [Initializing service instances using recovery crypto units](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-initialize-hsm-recovery-crypto-unit) : If you create your service instance in **Dallas (us-south) or Washington DC (us-east)** where the recovery crypto units are enabled, you can choose this approach where the master key is randomly generated within a recovery crypto unit and then exported to other crypto units.\n\n### Create and initialize the Hyper Protect Crypto Services instance\n\n#### Before you begin: creating administrator signature keys\n\nTo initialize the instance with a third-party signing service, see [Using a signing service to manage signature keys for instance initialization](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-signing-service-signature-key\u0026interface=ui) in the Cloud Docs.\n\nOtherwise, if you are not using a third-party signing service, run the following commands that use the IBM Cloud TKE CLI plug-in\nto generate admin signature keys.\n\n* Install the [IBM Cloud CLI](https://cloud.ibm.com/docs/cli?topic=cli-install-ibmcloud-cli)\n\n* Make sure you have a recent version the IBM Cloud Trusted Key Entry (TKE) CLI plug-in installed.\n  * Run this command to install the plug-in:\n    ```\n    ibmcloud plugin install tke\n    ```\n\n    Or\n\n  * Run this command to update your plug-in to the latest version with the following command:\n    ```\n    ibmcloud plugin update tke\n    ```\n\n* Set the environment variable `CLOUDTKEFILES` to specify the directory where you want to save signature key files.\n  ```\n  export CLOUDTKEFILES=\u003cabsolute path of directory\u003e\n  ```\n\n* 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.\n  ```\n  ibmcloud login\n  ibmcloud target -r \u003cregion\u003e -g \u003cresource_group\u003e\n  ```\n\n* 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.\n  ```\n  ibmcloud tke sigkey-add\n  ```\n\n:information_source: **Requirement:** Make sure that information about the administrator who is associated with the key is set in the `admins` input variable.\n\n\n### Usage to create and initialize the HPCS instance\n\n```hcl\nprovider \"ibm\" {\n  ibmcloud_api_key = \"XXXXXXXXXXXXXX\"\n  region           = \"us-south\"\n}\n\nmodule \"hpcs\" {\n  source                                          = \"terraform-ibm-modules/hpcs/ibm\"\n  version                                         = \"X.X.X\" # Replace \"X.X.X\" with a release version to lock into a specific release\n  resource_group_id                               = \"xxXXxxXXxXxXXXXxxXxxxXXXXxXXXXX\"\n  region                                          = \"us-south\"\n  name                                            = \"my-hpcs-instance\"\n  tags                                            = [\"tag1\",\"tag2\"]\n  auto_initialization_using_recovery_crypto_units = true\n  number_of_crypto_units                          = 3\n  admins = [\n    {\n      name  = \"admin1\"\n      key   = \"/cloudTKE/1.sigkey\"\n      token = \"sensitive1234\"\n    },\n    {\n      name  = \"admin2\"\n      key   = \"/cloudTKE/2.sigkey\"\n      token = \"sensitive1234\"\n    }\n  ]\n}\n```\n\n### Usage to create and initialize the HPCS instance using Schematics\n\n* Convert the signature keys to Base64 encoding.\n  ```sh\n  cat 1.sigkey | base64\n  cat 2.sigkey | base64\n  ```\n\n```hcl\nprovider \"ibm\" {\n  ibmcloud_api_key = \"XXXXXXXXXXXXXX\"\n  region           = \"us-south\"\n}\n\nmodule \"hpcs\" {\n  source                                          = \"terraform-ibm-modules/hpcs/ibm\"\n  version                                         = \"X.X.X\" # Replace \"X.X.X\" with a release version to lock into a specific release\n  resource_group_id                               = \"xxXXxxXXxXxXXXXxxXxxxXXXXxXXXXX\"\n  region                                          = \"us-south\"\n  name                                            = \"my-hpcs-instance\"\n  tags                                            = [\"tag1\",\"tag2\"]\n  auto_initialization_using_recovery_crypto_units = true\n  number_of_crypto_units                          = 3\n  base64_encoded_admins = [\n    {\n      name  = \"admin1\"\n      key   = \"eyJlbmNrZXkiOiJyYW5kb21fa2V5Iiwia2V5VHlwZSI6InJhbmRvbSIsIm5hbWUiOiJhZG1pbjEiLCJzZWFTYWx0IjoicmFuZG9tIiwic2tpIjoicmFuZG9tIn0=\"\n      token = \"sensitive1234\"\n    },\n    {\n      name  = \"admin2\"\n      key   = \"eyJlbmNrZXkiOiJyYW5kb20yX2tleSIsImtleVR5cGUiOiJyYW5kb20yIiwibmFtZSI6ImFkbWluMiIsInNlYVNhbHQiOiJyYW5kb20yIiwic2tpIjoicmFuZG9tMiJ9\"\n      token = \"sensitive1234\"\n    }\n  ]\n}\n```\n\n### Required IAM access policies\nYou need the following permissions to run this module.\n\n- Account Management\n    - **Resource Group** service\n        - `Viewer` platform access\n- IAM Services\n    - **Hyper Protect Crypto Services** service\n        - `Editor` platform access\n        - `Manager` service access\n\n\u003c!-- BEGINNING OF PRE-COMMIT-TERRAFORM DOCS HOOK --\u003e\n### Requirements\n\n| Name | Version |\n|------|---------|\n| \u003ca name=\"requirement_terraform\"\u003e\u003c/a\u003e [terraform](#requirement\\_terraform) | \u003e= 1.9.0 |\n| \u003ca name=\"requirement_ibm\"\u003e\u003c/a\u003e [ibm](#requirement\\_ibm) | \u003e= 1.49.0, \u003c 2.0.0 |\n| \u003ca name=\"requirement_local\"\u003e\u003c/a\u003e [local](#requirement\\_local) | \u003e= 2.4.0, \u003c 3.0.0 |\n\n### Modules\n\nNo modules.\n\n### Resources\n\n| Name | Type |\n|------|------|\n| [ibm_hpcs.hpcs_instance](https://registry.terraform.io/providers/IBM-Cloud/ibm/latest/docs/resources/hpcs) | resource |\n| [ibm_resource_instance.base_hpcs_instance](https://registry.terraform.io/providers/IBM-Cloud/ibm/latest/docs/resources/resource_instance) | resource |\n| [local_file.admin_files](https://registry.terraform.io/providers/hashicorp/local/latest/docs/resources/file) | resource |\n\n### Inputs\n\n| Name | Description | Type | Default | Required |\n|------|-------------|------|---------|:--------:|\n| \u003ca name=\"input_admins\"\u003e\u003c/a\u003e [admins](#input\\_admins) | A list of administrators for the instance crypto units. See [instructions](https://github.com/terraform-ibm-modules/terraform-ibm-hpcs#before-you-begin) to create administrator signature keys. You can set up to 8 administrators. Required if auto\\_initialization\\_using\\_recovery\\_crypto\\_units set to true. | \u003cpre\u003elist(object({\u003cbr/\u003e    name = string # max length: 30 chars\u003cbr/\u003e    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\u003cbr/\u003e    # if you are using a signing service, the key name is appended to a URI that will be sent to the signing service\u003cbr/\u003e    token = string # sensitive: the administrator password/token to authorize and access the corresponding signature key file\u003cbr/\u003e  }))\u003c/pre\u003e | `[]` | no |\n| \u003ca name=\"input_auto_initialization_using_recovery_crypto_units\"\u003e\u003c/a\u003e [auto\\_initialization\\_using\\_recovery\\_crypto\\_units](#input\\_auto\\_initialization\\_using\\_recovery\\_crypto\\_units) | Set to true if auto initialization using recovery crypto units is required. | `bool` | `true` | no |\n| \u003ca name=\"input_base64_encoded_admins\"\u003e\u003c/a\u003e [base64\\_encoded\\_admins](#input\\_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. | \u003cpre\u003elist(object({\u003cbr/\u003e    name  = string # max length: 30 chars\u003cbr/\u003e    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\u003cbr/\u003e    token = string # sensitive: the administrator password/token to authorize and access the corresponding signature key file\u003cbr/\u003e  }))\u003c/pre\u003e | `[]` | no |\n| \u003ca name=\"input_create_timeout\"\u003e\u003c/a\u003e [create\\_timeout](#input\\_create\\_timeout) | Create timeout value of the HPCS instance. | `string` | `\"180m\"` | no |\n| \u003ca name=\"input_delete_timeout\"\u003e\u003c/a\u003e [delete\\_timeout](#input\\_delete\\_timeout) | Delete timeout value of the HPCS instance. | `string` | `\"180m\"` | no |\n| \u003ca name=\"input_hsm_connector_id\"\u003e\u003c/a\u003e [hsm\\_connector\\_id](#input\\_hsm\\_connector\\_id) | The HSM connector ID provided by IBM required for Hybrid HPCS. Available to selected customers only. | `string` | `null` | no |\n| \u003ca name=\"input_name\"\u003e\u003c/a\u003e [name](#input\\_name) | The name to give the Hyper Protect Crypto Service instance. Max length allowed is 30 chars. | `string` | n/a | yes |\n| \u003ca name=\"input_number_of_crypto_units\"\u003e\u003c/a\u003e [number\\_of\\_crypto\\_units](#input\\_number\\_of\\_crypto\\_units) | The number of operational crypto units for your service instance. | `number` | `2` | no |\n| \u003ca name=\"input_number_of_failover_units\"\u003e\u003c/a\u003e [number\\_of\\_failover\\_units](#input\\_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 |\n| \u003ca name=\"input_plan\"\u003e\u003c/a\u003e [plan](#input\\_plan) | The name of the service plan that you choose for your Hyper Protect Crypto Service instance. | `string` | `\"standard\"` | no |\n| \u003ca name=\"input_region\"\u003e\u003c/a\u003e [region](#input\\_region) | The region where you want to deploy your instance. | `string` | n/a | yes |\n| \u003ca name=\"input_resource_group_id\"\u003e\u003c/a\u003e [resource\\_group\\_id](#input\\_resource\\_group\\_id) | The resource group name where the Hyper Protect Crypto Service instance will be created. | `string` | n/a | yes |\n| \u003ca name=\"input_revocation_threshold\"\u003e\u003c/a\u003e [revocation\\_threshold](#input\\_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 |\n| \u003ca name=\"input_service_endpoints\"\u003e\u003c/a\u003e [service\\_endpoints](#input\\_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 |\n| \u003ca name=\"input_signature_server_url\"\u003e\u003c/a\u003e [signature\\_server\\_url](#input\\_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 |\n| \u003ca name=\"input_signature_threshold\"\u003e\u003c/a\u003e [signature\\_threshold](#input\\_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 |\n| \u003ca name=\"input_tags\"\u003e\u003c/a\u003e [tags](#input\\_tags) | Optional list of resource tags to apply to the HPCS instance. | `list(string)` | `[]` | no |\n| \u003ca name=\"input_update_timeout\"\u003e\u003c/a\u003e [update\\_timeout](#input\\_update\\_timeout) | Update timeout value of the HPCS instance. | `string` | `\"180m\"` | no |\n\n### Outputs\n\n| Name | Description |\n|------|-------------|\n| \u003ca name=\"output_crn\"\u003e\u003c/a\u003e [crn](#output\\_crn) | HPCS instance crn |\n| \u003ca name=\"output_endpoints\"\u003e\u003c/a\u003e [endpoints](#output\\_endpoints) | HPCS instance endpoints |\n| \u003ca name=\"output_guid\"\u003e\u003c/a\u003e [guid](#output\\_guid) | HPCS instance guid |\n| \u003ca name=\"output_hpcs_name\"\u003e\u003c/a\u003e [hpcs\\_name](#output\\_hpcs\\_name) | HPCS instance name |\n| \u003ca name=\"output_id\"\u003e\u003c/a\u003e [id](#output\\_id) | HPCS instance id |\n\u003c!-- END OF PRE-COMMIT-TERRAFORM DOCS HOOK --\u003e\n\u003c!-- BEGIN CONTRIBUTING HOOK --\u003e\n\n\u003c!-- Leave this section as is so that your module has a link to local development environment set up steps for contributors to follow --\u003e\n## Contributing\n\nYou can report issues and request features for this module in GitHub issues in the module repo. See [Report an issue or request a feature](https://github.com/terraform-ibm-modules/.github/blob/main/.github/SUPPORT.md).\n\nTo set up your local development environment, see [Local development setup](https://terraform-ibm-modules.github.io/documentation/#/local-dev-setup) in the project documentation.\n\u003c!-- Source for this readme file: https://github.com/terraform-ibm-modules/common-dev-assets/tree/main/module-assets/ci/module-template-automation --\u003e\n\u003c!-- END CONTRIBUTING HOOK --\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fterraform-ibm-modules%2Fterraform-ibm-hpcs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fterraform-ibm-modules%2Fterraform-ibm-hpcs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fterraform-ibm-modules%2Fterraform-ibm-hpcs/lists"}