All Products
Search

This Product

    Key Management Service:Manage KMS instances

    Document Center

    Key Management Service:Manage KMS instances

    Last Updated:Aug 28, 2026

    This topic describes how to enable, view, upgrade, and renew KMS instances, and how to enable security audit for KMS instances.

    Enable KMS instance

    After you purchase a KMS instance, you must enable it before you can use key management and secret management features.

    Important

    Check the remaining subscription period of your KMS instance regularly. Renew the instance before it expires to prevent business disruptions. For more information, see Expiration.

    Enable a software key management instance

    Prerequisites

    • Network configuration: Ensure that you have one VPC and one vSwitch. To create a VPC and a vSwitch, see Create a VPC and a vSwitch or Create a vSwitch.

      Note

      You can log on to the VPC console to view existing VPCs, vSwitches, and the availability zones of the vSwitches.

    • PrivateZone configuration: If you use an Alibaba Cloud account for the Chinese mainland site (aliyun.com) to purchase a KMS instance in a region outside the Chinese mainland, or if you use an Alibaba Cloud account for the international site (alibabacloud.com) to purchase a KMS instance in a region within the Chinese mainland, you must manually activate PrivateZone. Activate PrivateZone.

      Note

      • If you use an Alibaba Cloud account for the Chinese mainland site (aliyun.com) to purchase a KMS instance in a region within the Chinese mainland, or if you use an Alibaba Cloud account for the international site (alibabacloud.com) to purchase a KMS instance in a region outside the Chinese mainland, PrivateZone is activated automatically.

      • KMS covers the DNS resolution fees. You are not charged by PrivateZone.

    Procedure

    Enable a software key management instance in the console

    1. Log on to the Key Management Service console. In the top navigation bar, select a region. In the left-side navigation pane, choose Resources > Instances.

    2. On the Software Key Management tab, find the target software key management instance and click Enable in the Actions column.

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

      Parameter

      Description

      Instance Name

      Custom name for the KMS instance. Supported characters: letters, digits, and the following special characters: _/+=.@-.

      VPC ID

      Select the VPC to bind to the KMS instance.

      Configure Zone and vSwitch

      Depends on the deployment mode selected at purchase. Up to three availability zones can be configured for multi-zone mode.

      • Zone and vSwitch: Configure a single availability zone and a vSwitch. Ensure the vSwitch has at least one available IP address.

      • Other Zones: Supports random assignment or manual specification.

      Note

      • Some regions offer only one availability zone, so the KMS instance can only be deployed in a single zone.

      • Dual-zone and multi-zone deployments support high availability, disaster recovery, and load balancing. Performance and latency differences between business zones and non-business zones are negligible.

    4. Wait about 30 minutes, then refresh the page. When the status changes to Enabled, the software key management instance is enabled.

    Enable a software key management instance by calling KMS API operations

    Call the ConnectKmsInstance operation.

    Enable a software key management instance by using Terraform

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

    Enable a hardware key management instance

    Prerequisites

    • Network configuration requirements: Ensure a vSwitch is available in each availability zone of the KMS instance. The following assumes a dual-zone deployment.

      Note

      You can log on to the VPC console, click the target vSwitch on the vSwitch page, and view the number of available IP addresses on the details page.

      • Use the two vSwitches that are bound to the HSM instance: No new vSwitches needed. Ensure each vSwitch has at least four available IP addresses.

      • Do not use the two vSwitches that are bound to the HSM instance: Create two vSwitches in different availability zones, each with at least four available IP addresses. .

    • PrivateZone configuration requirements: If you use an Alibaba Cloud account for the Chinese mainland site (aliyun.com) to purchase a KMS instance in a region outside the Chinese mainland, or if you use an Alibaba Cloud account for the international site (alibabacloud.com) to purchase a KMS instance in a region within the Chinese mainland, you must manually activate PrivateZone. Activate PrivateZone.

      Note

      • If you use an Alibaba Cloud account for the Chinese mainland site (aliyun.com) to purchase a KMS instance in a region within the Chinese mainland, or if you use an Alibaba Cloud account for the international site (alibabacloud.com) to purchase a KMS instance in a region outside the Chinese mainland, PrivateZone is activated automatically.

      • KMS covers DNS resolution fees, so PrivateZone does not charge you.

    Procedure

    Note

    You can enable hardware key management instances only in the console. You cannot enable them using KMS API operations or Terraform.

    Purchased without HSM configured

    1. Go to the CloudHSM console to configure an HSM cluster for the KMS instance. Configure an HSM cluster.

      Warning

      To add HSMs to the cluster later, contact Alibaba Cloud technical support to switch the synchronization method to automatic to prevent failures.

    2. Log on to the Key Management Service console. In the top navigation bar, select a region. In the left-side navigation pane, choose Resources > Instances.

    3. Click the Hardware Key Management tab, find the target hardware key management instance, and click Enable in the Actions column.

    4. In the Connect to HSM panel, configure the settings and then click Connect to HSM to specify the HSM cluster.

      • Instance Name: A custom name for the KMS instance. The name can contain letters, digits, and the following special characters: _/+=.@-.

      • Select Cluster: Select the HSM cluster that you configured in CloudHSM.

        Note

        A hardware key management instance can be bound to only one HSM cluster.

      • Configure HSM Access Secret.:

        Chinese mainland HSM

        • Automatically generate certificates: If you select Automatically generate certificates when purchasing an HSM in the Chinese mainland, HSM generates the required certificates automatically.

        • Manually generate certificates: If automatic certificate generation was not configured, you must configure a client certificate (PKCS#12 with protection password) and a security domain certificate (PEM-formatted CA certificate for the HSM cluster's TLS server certificate). Generate certificates and configure mutual TLS authentication.

          • Client Protection Password: The protection password that you set when you generate the client.p12 client certificate. If you use the certificate generation tool (hsm_certificate_generate), the default password is 12345678.

          • Client Certificate: A PKCS#12 certificate. Click Select File and select the generated client.p12 file to upload.

          • Security Domain Certificate: A PEM-formatted CA certificate. Click Select File and select the generated rootca.pem file to upload.

        International HSM

        • Automatically generate certificates: If you select Automatically generate certificates when purchasing an HSM outside the Chinese mainland, HSM generates and deploys the certificates to the server-side HSM. You only need to configure the corresponding certificates on the client SDK.

        • Manually generate certificates: If automatic certificate generation was not configured, manually configure the client certificate. Import a GVSM (NIST FIPS) cluster certificate.

          • Username: The username of the HSM operator. This is fixed to kmsuser.

          • Password: The password for the HSM operator. This is the password that you set when you create an HSM operator (CU user).

          • Security Domain Certificate: A PEM-formatted certificate. Log on to the CloudHSM console, click the ID of any HSM instance in the cluster, go to the Instance Details tab, and find the HSM Certificate section. Click ClusterOwnerCertificate and copy the content, or save it as a PEM file and then upload the file.

      • VPC: This defaults to the VPC ID that is bound to the HSM and cannot be changed.

      • Configure Zone and vSwitch: Depends on the deployment mode. Dual-zone and multi-zone deployments are supported. Each vSwitch must have at least four available IP addresses.

        Multi-zone deployments support up to three availability zones.

        Note

        Multi-zone deployments provide high availability, disaster recovery, and load balancing. Latency and performance differences between zones are negligible.

    5. After configuration, wait for the system to process. The instance is enabled when its status changes to Enabled.

      Note

      Enablement takes about 30 minutes with a secret quota, or about 10 minutes without. Refresh the page to see the updated status.

    Enable an external key management instance

    Prerequisites

    • HSM configuration requirements:

      • You have purchased an off-cloud HSM.

      • You have configured an XKI Proxy external proxy. The following connection methods are supported. For specific instructions, contact your HSM provider.

        • Public network connection: A direct connection is established over the public internet.

        • VPC endpoint connection: Create an endpoint service first by following Create and manage endpoint services.

          • Service Resource Type：CLB or NLB。

          • Service Resource: The availability zones configured for the endpoint service must match the availability zones selected when launching the KMS instance.

          • Whitelist Configuration: Add your current Alibaba Cloud Account ID to the whitelist of the endpoint service.

          • Automatically Accept Endpoint Connections: Set to Yes.

    • PrivateZone configuration requirements: If you use an Alibaba Cloud account for the Chinese mainland site (aliyun.com) to purchase a KMS instance in a region outside the Chinese mainland, or if you use an Alibaba Cloud account for the international site (alibabacloud.com) to purchase a KMS instance in a region within the Chinese mainland, you must manually activate PrivateZone. Activate PrivateZone.

      Note

      • If you use an Alibaba Cloud account for the Chinese mainland site (aliyun.com) to purchase a KMS instance in a region within the Chinese mainland, or if you use an Alibaba Cloud account for the international site (alibabacloud.com) to purchase a KMS instance in a region outside the Chinese mainland, PrivateZone is activated automatically.

      • KMS covers DNS resolution fees, so PrivateZone does not charge you.

    Procedure

    Note

    You can enable external key management instances only in the console. You cannot enable them using KMS API operations or Terraform.

    1. Log on to the Key Management Service console. In the top navigation bar, select a region. In the left-side navigation pane, choose Resources > Instances.

    2. Click the External Key Management tab, find the target instance, and click Enable in the Actions column.

    3. In the Connect to HSM panel, configure the settings and then click Connect to HSM to specify the HSM cluster.

      Parameter

      Description

      Instance Name

      A custom name for the KMS instance. The name can contain letters, digits, and the following special characters: _/+=.@-.

      VPC

      Select a VPC to bind to the KMS instance.

      Zone Configuration

      Depends on your deployment mode. Dual-zone and multi-zone (up to three) deployments are supported.

      • Zone and vSwitch: Configure an availability zone and a vSwitch. Make sure that the vSwitch has at least one available IP address.

      • Other Zones: Assign availability zones randomly or specify them manually.

      Note

      • Some regions have only one availability zone, limiting deployment to a single zone.

      • Multi-zone deployments provide high availability, disaster recovery, and load balancing. Latency and performance differences between zones are negligible.

      External Proxy Connectivity

      • Public Endpoint Connectivity: The KMS instance connects to the XKI Proxy external proxy over the public internet.

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

      Domain Name of External Proxy

      This parameter is required only if you set External Proxy Connectivity to Public Endpoint Connectivity. Enter the domain name of the XKI Proxy external proxy.

      Endpoint Service

      This parameter is required only if you set External Proxy Connectivity to VPC Endpoint Service Connectivity . Select an endpoint service.

      Note

      The availability zones selected for the KMS instance must be the same as the availability zones of the endpoint service. For more configuration details, see VPC Endpoint Connection Configuration Guide.

      External Proxy Configuration

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

      • Configuration File Upload: Configure the parameters by uploading a configuration file.

      Enablement takes about 30 minutes with a secret quota, or about 10 minutes without. Refresh the page. The instance is enabled when its status changes to Enabled.

    Set an alias for a KMS instance

    An instance alias must be 1 to 128 characters in length and can contain letters, digits, and the special characters /_+=.@-.

    1. Log on to the Key Management Service console. In the top navigation bar, select a region. In the left-side navigation pane, choose Resources > Instances.

    2. Click the tab for the target instance type. Below the instance ID, click the image icon to set the alias.

    View KMS instance details

    After you enable a KMS instance, you can query the instance ID, VPC endpoint, and VPC information.

    1. Log on to the Key Management Service console. In the top navigation bar, select a region. In the left-side navigation pane, choose Resources > Instances.

    2. On the Instances page, click the tab for the instance.

    3. Find the target KMS instance and click Details in the Actions column to view information on the instance details page.

    Upgrade KMS instance

    If the specifications of the current KMS instance no longer meet your business requirements, you can upgrade the instance specifications, such as computing performance, secret quota, and key quota. The upgrade does not affect your business.

    1. Log on to the Key Management Service console. In the top navigation bar, select a region. In the left-side navigation pane, choose Resources > Instances.

    2. On the Instances page, click the tab for the instance.

    3. Find the target KMS instance and click Upgrade in the Actions column. On the upgrade page, select the specifications after the upgrade.

    4. Read the Terms of Service, click Buy Now, and complete the payment.

    Release KMS instance

    Only pay-as-you-go KMS instances can be manually released. Subscription instances cannot be manually released. To cancel a subscription instance, see Unsubscription and refunds.

    Warning

    • When an instance is released, all its resources are also released. Resources encrypted by keys from the instance cannot be decrypted, and secrets from the instance cannot be retrieved. Before releasing an instance, confirm that no data is encrypted by its keys and no services depend on its secrets.

    • If your instance is a software key management instance, back up resources before releasing. For more information, see KMS backup management.

    • Pay-as-you-go instances are billed daily. After release, the bill for the previous day is generated by 12:00 the following day.

    1. Log on to the Key Management Service console. In the top navigation bar, select a region. In the left-side navigation pane, choose Resources > Instances.

    2. On the Instances page, click the tab for the instance.

    3. Find the target KMS instance and click Release in the Actions column. Then, confirm the details and click Release.

      Note

      If the Release button is unavailable, deletion protection might be enabled for the KMS instance. Disable deletion protection before you release the instance.

    Enable deletion protection for a KMS instance

    Deletion protection prevents a KMS instance from being accidentally released or unsubscribed. After this feature is enabled, the instance cannot be released or unsubscribed through the console, API, or CLI.

    1. Log on to the Key Management Service console. In the top navigation bar, select a region. In the left-side navigation pane, choose Resources > Instances.

    2. On the Instances page, click the tab for the instance.

    3. Find the target KMS instance and click Enable Deletion Protection in the Actions column. Then, confirm the details and click Enable.

    Enable security audit for a KMS instance

    When you access a KMS instance, audit logs are generated. These logs record access data for the instance, such as request information, user information, accessed resource information, and access results. The following code block shows a sample log file:

    2021-10-19T212021-10-19T21:40:01     [INFO]  - - 3dd60a7a-4587-4c57-8197-d749c3578974 CreateKey - TMP.3KfAHseF5DVULM2s8YUhdB8YvwM4nZA1wXr8AcAAhR7YhdyosXG2eSpsRFPMjYbvUArPRtsCWKzxEo88bC5w5LBfyp**** 111760096384**** 111760096384**** - kst-phzz6108e50c15333w**** - 37 - -40:01     [INFO]  - - 3dd60a7a-4587-4c57-8197-d749c3578974 CreateKey - TMP.3KfAHseF5DVULM2s8YUhdB8YvwM4nZA1wXr8AcAAhR7YhdyosXG2eSpsRFPMjYbvUArPRtsCWKzxEo88bC5w5LBfyp**** 111760096384**** 111760096384**** - kst-phzz6108e50c15333w**** - 37 - -

    After you enable security audit, KMS delivers audit logs to your specified OSS bucket every hour to meet regulatory and business requirements. Before you enable security audit, make sure that you have created an OSS bucket. For more information, see Create a bucket.

    1. Log on to the Key Management Service console. In the top navigation bar, select a region. In the left-side navigation pane, choose Resources > Instances.

    2. On the Instances page, click the tab for the instance.

    3. Find the target KMS instance and click Manage in the Actions column. On the instance details page, enable Security Audit.

    4. In the Configure Security Audit dialog box, select Log Storage Bucket and click OK.

      After you enable security audit, audit logs are generated and delivered within one hour.

    Renew a KMS instance

    1. Log on to the Key Management Service console. In the top navigation bar, select a region. In the left-side navigation pane, choose Resources > Instances.

    2. Click the Software Key Management or Hardware Key Management tab. Find the instance you want to renew and click Renew in the Actions column.

    3. On the Renew page, set the Duration. Read and select the Terms of Service check box.

    4. Click Buy Now and complete the payment.

    You can also renew the instance on the Expenses and Costs page. For more information, see Renewal guide.

    Set the sharing model

    The owner of a KMS instance can share it with other Alibaba Cloud accounts. For more information, see Share KMS instances across multiple accounts. KMS supports two sharing models:

    Important

    • New instances default to the Joint Ownership model.

    • In both models, instance users cannot use or manage the keys and secrets of the instance owner.

    Feature

    Independent ownership

    Joint ownership

    Use case

    Cross-account secrets with the same name, or permission isolation between accounts.

    Internal collaboration where a central team (such as IT or security) manages and audits all keys and secrets.

    Core feature

    Independent data sovereignty: The instance owner cannot manage or use the keys and secrets created by instance users.

    Shared data sovereignty: The instance owner can manage and use the keys and secrets created by instance users.

    Same-name secrets across accounts

    Allowed. Instance users and the instance owner can create secrets with the same name.

    Not allowed. All key and secret names within the instance must be unique.

    Model change

    Cannot be changed to Joint Ownership.

    Can be changed to Independent Ownership.

    Change the bound VPC

    1. On the Instances page, click the tab for the instance.

    2. Find the target KMS instance and click Details in the Actions column. At the bottom of the page, click the Multi-VPC tab.

    3. Click Configure VPCs. In the Configure VPCs panel, click Edit next to the VPC ID configuration item.

    4. Select the target VPC from the drop-down list and click OK in the lower-left corner of the configuration panel.

    Set the default instance

    This feature is for users migrating from KMS 1.0 to KMS 3.0. If you are not migrating, skip this section.

    For more information about migration, see Migrate resources from KMS 1.0 to a KMS 3.0 instance.

    FAQ

    What does it mean when the KMS instance status shows "Modifying"?

    Modifying indicates that the KMS instance is undergoing a configuration change, such as adding a virtual private cloud (VPC) or upgrading the instance specifications. This is a normal transitional state and requires no manual intervention. After the change is complete, the instance status automatically returns to Enabled. The instance remains active in this state and can be used as usual. However, you cannot rename a hardware key management instance while it is in this state.

    Note

    The full list of configuration changes that trigger this state is determined by the backend and cannot be exhaustively enumerated. In addition to adding a VPC and upgrading instance specifications, other configuration changes may also trigger this state.

    If the instance does not return to Enabled for a long time after you add a VPC, or if the Add button in the Configure VPCs panel is unavailable, perform the following troubleshooting steps:

    1. Go to the Multi-VPC tab on the details page of the instance and check whether the Add button is available:

      • If the Add button is dimmed and a message indicates that the number of VPCs you selected exceeds the association resource limit, the Access Management Quota of the instance is exhausted. Upgrade the instance specifications first to increase the quota (see the Upgrade KMS instance section in this topic), and then add the VPC again (see the Change the bound VPC section in this topic).

      • If the Add button is available, the quota is sufficient. In this case, Modifying simply indicates that the configuration change is still in progress. No action is required. The status automatically returns to normal after the change is complete.

    2. Notes about the Access Management Quota:

      • This quota item is displayed only on the details page of subscription instances. It is not displayed for pay-as-you-go instances, which are not subject to this limit.

      • Number of VPCs that can be associated = Access Management Quota − number of bound VPCs (including the one VPC that is enabled by default for the instance) − number of accounts in use for multi-account sharing. This means the quota is consumed by both bound VPCs and multi-account sharing, not by VPC bindings alone.

      • To increase the Access Management Quota, perform the Upgrade operation described in the Upgrade KMS instance section to increase the instance specifications. Do not confuse this operation with upgrading the instance image version. They are different features.

    3. We recommend that you change no more than three VPCs at a time. Changing more VPCs in a single operation may cause a timeout error. If no result is returned after a long time, refresh the page later to check whether the change is complete.