All Products
Search

This Product

    Key Management Service:Purchase and enable a KMS instance

    Document Center

    Key Management Service:Purchase and enable a KMS instance

    Last Updated:May 08, 2025

    Key Management Service (KMS) instances enhance data security by providing key and secret management. Keys encrypt and decrypt sensitive data, while secrets help eliminate the security risks associated with hardcoded secrets. This topic details how to purchase and enable a KMS instance.

    Step 1: Purchase a KMS instance

    1. Log on to the KMS console. In the top navigation bar, select a region. In the left-side navigation pane, choose Resource > Instances.

    2. On the Instances page, click Create Instance. In the Create Instance dialog box, select a billing method. On the buy page, configure the parameters.

      Purchase a subscription instance

      Parameter

      Description

      Site

      The site of the KMS instance. Valid values:

      • Regions Outside the Chinese Mainland.

      • Regions in the Chinese Mainland.

      Instance Type

      Select the target instance type:

      • Software Key Management: Provides a custom key repository, key lifecycle management, and data encryption and decryption. Keys are stored in your dedicated database.

      • Hardware Key Management: Uses dedicated HSMs for key generation, storage, encryption, and decryption. These HSMs meet the State Cryptography Administration and FIPS 140-2 Level 3 standards. An HSM purchase is required. See Configure an HSM cluster for a hardware key management instance for details.

      • External Key Management: Secures Alibaba Cloud workloads using encryption keys from external HSMs or key management software.

      When to select Value-added Plan

      When you want to purchase backups for your software key management instances, or enable key rotation for default keys (including the service keys and default CMK), select Value-added Plan. For more information, see Backups and Configure key rotation.

      Region

      The region of the KMS instance. For optimal performance, select the same region as your application.

      Deployment Mode

      KMS instances support dual-zone and multi-zone configurations, offering high availability, disaster recovery, and load balancing.

      Note

      • Multi-zone deployments support up to three zones.

      • KMS instances in the Phillippines (Manila) and Thailand (Bangkok) regions support only single-zone deployment.

        For the number of zones in each region, see Regions and endpoints.

      Computing Performance

      The computing performance (QPS) of the KMS instance. For example, selecting 2,000 provides a maximum of 2,000 QPS for symmetric algorithms and 300 QPS for asymmetric algorithms.

      If you require a software key management instance with 10,000 or 20,000 QPS, contact us.

      Number of Keys

      The quota of keys allowed per KMS instance. Default value: 1,000. The quotas are consumed per key version. For example, a key with five versions consumes five quotas.

      Number of Secrets

      The quota of secrets allowed per KMS instance. Default value: 0. The quotas are per secret. One secret, regardless of the number of secret versions it contains, only consumes one quota.

      Note

      Secrets are optional. Purchase them later as needed via an upgrade for the instance specification.

      Access Management Quantity

      This quota limits the number of Alibaba Cloud accounts and virtual private clouds (VPCs) that can access the KMS instance. For example, if your KMS instance needs to be associated with 3 VPCs and shared with 2 Alibaba Cloud accounts, you'll need at least 5 access management quotas. The default is 1, allowing access from a single VPC.

      Log Analysis

      Specifies whether to enable the log analysis. Note that it is irreversible once enabled.

      Log Storage Capacity

      The storage capacity for logs, with a minimum allocation of 1,000 GB. The capacity increases in increments of 1,000 GB. For details on how to evaluate the storage capacity, see Overview of Simple Log Service for KMS.

      Purchase quantity

      The number of KMS instances that you want to purchase.

      Duration

      The subscription duration of the KMS instance.

      Select Auto-renewal to automatically renew your KMS instance when it expires.

      Purchase a pay-as-you-go instance

      Parameter

      Description

      Billing Method

      Fixed as Pay-as-you-go 3.0.

      Instance Type

      Select the target instance type:

      • Software Key Management: Provides a custom key repository, key lifecycle management, and data encryption and decryption. Keys are stored in your dedicated database.

      • Hardware Key Management: Uses dedicated HSMs for key generation, storage, encryption, and decryption. These HSMs meet the State Cryptography Administration and FIPS 140-2 Level 3 standards. An HSM purchase is required. See Configure an HSM cluster for a hardware key management instance for details.

      Region

      The region of the KMS instance. For optimal performance, select the same region as your application.

    3. Click Buy Now, confirm the configurations, and review Terms of Service. Then, complete the payment following the on-screen instructions.

      The system requires 1 to 5 minutes to create the KMS instance. You can view the created instance on the Instances page.

    Step 2: Enable the KMS instance

    After purchasing a KMS instance, enable the instance by associating it with a VPC and vSwitch. This network configuration provides secure access for managing cryptographic resources within the instance, including key and secret management, encryption, and decryption.

    The supported KMS instance types are software, hardware and external key management instances.

    Software key management instance

    Prerequisites

    • When you purchase a KMS instance under the following conditions, Private DNS (a new form of Alibaba Cloud DNS PrivateZone) must be activated:

      • Using an International site (alibabacloud.com) account within the Chinese mainland.

      • Using a China site (aliyun.com) account outside the Chinese mainland.

    Note

    • Private DNS is automatically activated without additional configuration under other purchase conditions.

    • KMS covers the domain name resolution fees. You do not need to pay for them in Private DNS.

    Procedure

    Console

    1. Log on to the KMS console. In the top navigation bar, select a region. In the left-side navigation pane, choose Resource > Instances.

    2. On the Software Key Management tab, find the KMS instance that you want to enable and click Enable in the Actions column.

    3. In the Enable KMS Instance panel, configure the parameters and click Enable Now.

      Important

      Specify the correct VPC ID when enabling your KMS instance. You cannot modify it after the instance is enabled.

      Parameter description

      Parameter

      Description

      Instance Name

      Specify a name for the KMS instance. It supports letters, digits, and the following special characters: _/+=.@-.

      VPC ID

      Specify the VPC ID associated with your KMS instance. This ID cannot be modified after enabling the instance.

      Zone Configuration

      Set the zone and associated vSwitch for the instance.

      • Zone and vSwitch Configuration: Configure a zone and associated vSwitch. Make sure that the vSwitch has at least one available IP address. KMS requires this IP to access your network.

      • Other Zones: Select Randomly Assign or Manually Specify.

      The number of zones depends on your purchase option:

      Subscription

      Supports dual-zone and multi-zone deployments. If you selected multi-zone during purchase, you can configure up to three zones.

      Pay-as-you-go

      Defaults to a dual-zone setup.

      Dual-zone or multi-zone deployment provides high availability, disaster recovery, and load balancing for KMS. Latency and performance differences are negligible regardless of zone selection. You can choose freely.

      Single-zone regions

      Specific regions provide only a single zone, such as Thailand (Bangkok). In these regions, the KMS instance will be automatically configured for a single zone.

    Wait for approximately 30 minutes and then refresh the page. If the status of the KMS instance changes to Enabled, the KMS instance is enabled.

    API

    Call the ConnectKmsInstance operation.

    Terraform

    For instructions, see Purchase and enable a software key management instance with Terraform.

    Hardware key management instance

    Prerequisites

    • A connected Cloud Hardware Security Module (HSM) cluster is available for the KMS instance. Configure an HSM cluster.

      The region of the cluster and the hardware key management instance must be the same.

      Warning

      To increase the number of HSMs in the HSM cluster in subsequent operations, contact Alibaba Cloud technical support to change the cluster synchronization method to automatic synchronization. This prevents cluster synchronization failures.

    • Network setting: Each zone requires one vSwitch with at least four available IP addresses for the KMS instance.

      For a dual-zone deployment, choose one of the following options:

      • (Recommended) Use the two vSwitches that are bound to your HSM.

        You do not need to create vSwitches. Just ensure each one has at least four available IP addresses.

      • Do not use the two vSwitches that are bound to your HSM.

        Create two vSwitches in different zones for network planning flexibility. Ensure that four available IP addresses are reserved for each vSwitch.

      To view the number of available IP addresses on a vSwitch, log on to the VPC console, and click the vSwitch ID on the vSwitch page.

      Why four available IP addresses: In dual-zone KMS deployments, each HSM in the cluster requires two IP addresses for its highly available Elastic Network Interface (ENI) pair. So, to host two HSMs in a zone, four IP addresses are needed for each vSwitch.

    • When you purchase a KMS instance under the following conditions, Private DNS (a new form of Alibaba Cloud DNS PrivateZone) must be activated:

      • Using an International site (alibabacloud.com) account within the Chinese mainland.

      • Using a China site (aliyun.com) account outside the Chinese mainland.

    Note

    • Private DNS is automatically activated without additional configuration under other purchase conditions.

    • KMS covers the domain name resolution fees. You do not need to pay for them in Private DNS.

    Procedure

    Hardware key management instances can only be enabled through the console.

    1. Log on to the KMS console. In the top navigation bar, select a region. In the left-side navigation pane, choose Resource > Instances.

    2. On the Hardware Key Management tab, find the KMS instance that you want to enable and click Enable in the Actions column.

    3. In the Connect to HSM panel, specify an HSM cluster and click Connect to HSM.

      To specify an HSM cluster, you must configure the following parameters.

      Parameter

      Description

      Instance Name

      Specify a name for the KMS instance. It supports letters, digits, and the following special characters: _/+=.@-.

      Configure HSM Cluster

      Select the HSM cluster that you created.

      Note

      You can connect a hardware key management instance to only one HSM cluster.

      Configure HSM Access Secret.

      • Username: the username of the crypto user. The value is fixed as kmsuser.

      • Password: the password of the crypto user. Enter the password that you specified when you created the crypto user.

      • Security Domain Certificate: a root certification authority (CA) certificate in the PEM format. To obtain the certificate, perform the following operations: Log on to the Cloud Hardware Security Module console. Click one HSM ID in the cluster. On the Details page, find ClusterOwnerCertificate, which is the Security Domain Certificate. Copy the content of the Security Domain Certificate or save it in PEM format, then upload it.

      VPC ID

      By default, the ID of the VPC that is associated with the HSM is used. You cannot modify this default ID.

      Zone and vSwitch Configuration

      Set the zone and associated vSwitch for the instance. The deployment modes are dual-zone and multi-zone. If you selected multi-zone, you can configure up to three zones. Make sure that at least four available IP addresses are reserved for each vSwitch in a zone.

      Dual-zone or multi-zone deployment provides high availability, disaster recovery, and load balancing for KMS. Latency and performance differences are negligible regardless of zone selection. You can choose freely.

      The enablement time for the KMS instance depends on whether you configured the Number of Secrets parameter during purchase. Refresh the page to monitor the status. The KMS instance is enabled when its status displays Enabled.

      • With Number of Secrets: About 30 minutes.

      • Without Number of Secrets: About 10 minutes.

    External key management instance

    Prerequisites

    • A hardware security module outside the cloud is purchased, and an external key instance (XKI) proxy is configured. For instructions, contact your HSM provider.

    • If you want to use a VPC endpoint service to connect to KMS, you must first create a VPC endpoint service. Note the following:

      • The endpoint service zones match your KMS instance zones.

      • The current Alibaba Cloud account must be added to the endpoint service whitelist.

      • Automatically Accept Endpoint Connections is set to Yes.

      Alternatively, if you do not want to use VPC Endpoint Service, KMS supports connections to the XKI proxy by using a public endpoint.

    • When you purchase a KMS instance under the following conditions, Private DNS (a new form of Alibaba Cloud DNS PrivateZone) must be activated:

      • Using an International site (alibabacloud.com) account within the Chinese mainland.

      • Using a China site (aliyun.com) account outside the Chinese mainland.

    Note

    • Private DNS is automatically activated without additional configuration under other purchase conditions.

    • KMS covers the domain name resolution fees. You do not need to pay for them in Private DNS.

    Procedure

    External key management instances can only be enabled through the console.

    1. Log on to the KMS console. In the top navigation bar, select a region. In the left-side navigation pane, choose Resource > Instances.

    2. Click the External Key Management tab, find the instance that you want to enable, and then click Enable in the Actions column.

    3. In the Connect to HSM panel, configure parameters and click Connect to HSM.

      Parameter

      Description

      Instance Name

      Specify a name for the KMS instance. It supports letters, digits, and the following special characters: _/+=.@-.

      VPC ID

      Specify the VPC ID associated with your KMS instance. This ID cannot be modified after enabling the instance.

      Zone Configuration

      Set the zone and associated vSwitch for the instance. The deployment modes are dual-zone and multi-zone. If you select multi-zone, you can configure up to three zones.

      • Zone and vSwitch Configuration: Configure a zone and vSwitch. Make sure that the vSwitch has at least one available IP address. KMS requires this IP to access your network.

      • Other Zones: Select Randomly Assign or Manually Specify.

      Dual-zone or multi-zone deployment provides high availability, disaster recovery, and load balancing for KMS. Latency and performance differences are negligible regardless of zone selection. You can choose freely.

      Single-zone regions

      Specific regions provide only a single zone, such as Thailand (Bangkok). In these regions, the KMS instance is automatically configured for a single zone.

      External Proxy Connectivity

      • Public Endpoint Connectivity: The KMS instance connects to the XKI proxy by using a public endpoint over the Internet.

      • VPC Endpoint Service Connectivity : The KMS instance connects to the XKI proxy by using a VPC endpoint service.

      Domain Name of External Proxy

      If you set External Proxy Connectivity to Public Endpoint Connectivity, enter the domain name of your XKI proxy.

      Endpoint Service

      If you set External Proxy Connectivity to VPC Endpoint Service Connectivity , select an endpoint service.

      The two zones of the endpoint service must be the same as those that you select when you enable the KMS instance.

      External Proxy Configuration

      • Manual Configuration: You must configure External Proxy Path, Certificate Fingerprint, AccessKey ID, and AccessKey Secret. Enter the AccessKey ID and AccessKey secret of the XKI proxy.

      • Configuration File Upload: You can upload a configuration file.

      The enablement time for the KMS instance depends on whether you configured the Number of Secrets parameter during purchase. Refresh the page to monitor the status. The KMS instance is enabled when its status displays Enabled.

      • With Number of Secrets: About 30 minutes.

      • Without Number of Secrets: About 10 minutes.

    FAQs

    References