Environment

• Product: ZStack Cloud on a dual-management-node (MN) HA deployment
• Version: ZStack Cloud versions.
• Component: Management-node UI, zsha2, Java keytool, and openssl.
• Trigger/Condition: The platform HTTPS certificate needs to be replaced with a customer-supplied certificate.

Symptoms

• The customer needs to replace the platform HTTPS certificate.
• Browsers and API clients show the original self-signed certificate warning.

Diagnosis

1. Confirm the customer's certificate is provided as a .pfx / .p12 file and that they have the corresponding private key.
2. Confirm the environment is healthy and that no other maintenance task is running.
3. Confirm the new HTTPS listen port (default 5443 for ZStack management UI when SSL is enabled) is reachable from the user's network.

Cause

The ZStack management node embeds its HTTPS certificate in a PKCS12 keystore that is referenced from zstack.properties (consoleProxyCertFile). To replace the certificate, the customer-supplied PFX must be re-encoded into the keystore format expected by ZStack and registered through zstack-ctl config_ui. Both management nodes must be updated so that the VIP failover does not switch to a node with the old certificate.

Resolution

1. Prerequisites

• Confirm that the environment is healthy, disable global VM HA, back up the ZStack MySQL database on both MNs, and stop the management node service.
• Prepare the certificate files: 9-15.p12 (customer-supplied) and the matching private key, for example, xxxx.key.
• Make sure Java keytool is available. For example:

  /usr/lib/jvm/java-1.8.0-openjdk-1.8.0.222.b10-0.el7_6.x86_64/bin/keytool

Adapt the path to the JDK on the target MN.

2. Procedure

1. Import the certificate into the browser (optional sanity step) and re-export as P12.

• Import the .pfx file into the browser certificate store and export it as .p12.

2. Generate a PEM from the customer's P12.

   openssl pkcs12 -in 9-15.p12 -out 9-15.pem -nodes

3. Confirm environment is healthy; disable HA; back up the database; stop MN services.

• On each MN: back up MySQL, then zsha2 stop-node.

4. Repackage the customer's certificate and key into a new PKCS12.

   openssl pkcs12 -export -in 9-15.pem -inkey xxxx.key -out test.p12

Set a password when prompted; remember it for the next steps.

5. Convert the new PKCS12 back to PEM for processing with keytool.

   openssl pkcs12 -in test.p12 -out test.pem -nodes

6. Find the alias of the certificate in the new PKCS12.

   /usr/lib/jvm/java-1.8.0-openjdk-1.8.0.222.b10-0.el7_6.x86_64/bin/keytool \
     -list -v -keystore /root/Keystore_Tomcat/test.p12

7. Register the new certificate with the management node.

   zstack-ctl config_ui \
     --enable-ssl True \
     --ssl-keyalias=1 \
     --ssl-keystore=/xxxx/xxx/test.p12 \
     --ssl-keystore-type=PKCS12 \
     --ssl-keystore-password=<password set in step 4> \
     --server-port=5443

Adjust --ssl-keyalias, --ssl-keystore, and --ssl-keystore-password to the actual values.

8. Copy the new keystore and PEM into the default ZStack UI directory.

   cp test.p* /usr/local/zstack/zstack-ui/

9. Point consoleProxyCertFile at the absolute path of the new PEM.

• Edit /usr/local/zstack/apache-tomcat/webapps/zstack/WEB-INF/classes/zstack.properties:

     consoleProxyCertFile = /usr/local/zstack/zstack-ui/test.pem

10. Repeat steps 1–9 on the second management node.

• Both MNs must hold the new certificate so that VIP failover does not expose the old certificate.

11. Start the management-node service.

    zsha2 start-node

12. Verify console access on both the primary domain and any subdomain.

• Log in through the primary domain, open a VM console, and repeat the verification on the subdomain.

Verification

• The browser shows the new HTTPS certificate, issued by the customer-supplied CA, on both the primary domain and subdomain.
• VM console opens successfully on both domains.
• zsha2 status shows both MNs healthy and HA in normal state.
• Re-enable global VM HA in the UI once validation passes.

Risks and rollback

• Risk: An incorrect keystore password or alias prevents the management UI from starting, making the platform inaccessible until the certificate is corrected.
• Risk: Failing to update both MNs leaves the VIP holder with the new certificate and the standby with the old one; a VIP failover during a maintenance window will expose the old certificate.
• Rollback: Restore the previous .p12 and .pem files, rerun zstack-ctl config_ui with the old values, restore consoleProxyCertFile in zstack.properties to the previous path, and restart the MN service.