Issue/Introduction

This article describes how to troubleshoot a failure to add a cloud environment, test a cloud account, or reconnect an existing cloud account in ZCenter. The corresponding cloud platform plugin validates the connection. A failure can be caused by parameters, the network, credentials, a license, a cloud platform API, or an incorrect environment for the account.

Symptoms

• Testing the connection while adding a cloud environment fails. The environment is not saved, or the account status is off after it is saved.
• Reconnecting an existing cloud account fails, and the page displays a cloud-platform-specific error.
• The error might indicate an API timeout, Connection refused, invalid credentials, an expired license, a nonexistent environment, or an unsupported cloud type.
• After repeated failures, scheduled connection checks might temporarily stop retrying, and the log might contain a message related to reconnection failed too many times.

Environment

• Product: ZCenter
• Version: 5.1.0
• Component: Portal cloud environments, cloud accounts, and the corresponding cloud platform connection plugins
• Cloud platforms: ZStack, Cube, Cube HCI, ZSphere, VMware, Kubernetes, and other deployed plugins

Possible causes

• The cloud type, cloud environment ID, API address, version, or authentication mode is incorrect.
• The Portal host or container cannot access the cloud platform API because of a DNS, firewall, routing, or proxy issue.
• The principal, credential, username, password, AK/SK, Kubernetes authentication mode, or Base64 encoding is incorrect.
• A private-cloud account is not associated with a valid cloud environment, or the cloud environment has been deleted.
• The cloud platform license has expired, the quota is insufficient, the API is unavailable, or the current version does not support the type.
• 5 consecutive connection failures trigger temporary suppression, which lasts about 7200 seconds by default. During this period, a failure immediately after correcting the configuration does not necessarily mean that the correction was ineffective.

Resolution

1. Record the request and returned cause

• Record the cloud type, cloud environment ID, account UUID, API address, failure time, API path, and complete error message.
• Do not expose passwords, tokens, AK/SK pairs, or a complete Kubeconfig in a ticket, log, or screenshot.
• Distinguish among adding a new environment, adding an account to an existing environment, testing a connection, and reconnecting an existing account.

2. Validate request parameters and permissions

• Test-connection API: POST /api/portal/v4/cloud-account/CheckAccount.
• Add-cloud-environment API: POST /api/portal/v4/cloud-env/AddEnv.
• Reconnect-existing-account API: POST /api/portal/v4/cloud-account/Reconnect?uuid=<ACCOUNT_UUID>.
• Check: Confirm that the operator account has the required permission and that type and credential are not empty. For a private-cloud type, confirm that cloudEnvId exists.
• Expected result: The request parameters pass validation, and an associated cloud environment can be found for the private-cloud account.
• If abnormal: Correct the parameters or permissions first. Do not directly delete and recreate the environment.

3. Check the network from the Portal runtime

• Check: Access the actual cloud platform API address from the host or container where Portal runs, not from the computer that runs the browser.
• Example commands:

  getent hosts <cloud-api-host>
  nc -vz <cloud-api-host> <cloud-api-port>
  curl -v --connect-timeout 10 --max-time 30 <cloud-api-url>

• Expected result: DNS resolves correctly, the TCP port is reachable, and the cloud platform returns an HTTP response.
• If abnormal: Check the Portal container network, route, firewall, proxy, cloud platform allowlist, API listen address, and certificate trust chain. Do not use disabled TLS verification as a long-term workaround.

4. Validate credentials and platform-specific parameters

• ZStack, Cube, Cube HCI, and ZSphere: Confirm the management node API address, account credentials, version, and license status.
• VMware: Confirm the vCenter address, account password, and access to the compute resource APIs.
• Kubernetes: Confirm the API Server address, authMode, and corresponding Kubeconfig, certificate, or Bearer Token. Base64-encode credentials as required by the API.
• Expected result: The parameter format matches the authentication method used by the cloud platform.
• If abnormal: Regenerate or re-encode the credentials. Avoid introducing line breaks, spaces, or incorrect Base64 content during manual copying.

5. Check Portal logs and connection-suppression state

• Log location: Usually logs/zscmp.log under the Portal runtime directory. In a container environment, also check the container logs.
• Recommended search terms: check ZStack account failed, check VMware account failed, kubernetes check account fail, CloudConnectStateHandler, and reconnection failed too many times.
• Expected result: The logs identify whether the failure occurred during network, authentication, license, or plugin validation.
• If abnormal: If the log shows suppression after consecutive failures, first confirm that the configuration has been corrected and wait for the suppression TTL to expire before reconnecting. Do not repeatedly click reconnect and create more failure records.

6. Collect support information

• The cloud type, API domain/IP and port, version, authentication mode, and error message, with sensitive information redacted.
• Portal service logs, cloud platform API logs, and the failure time window.
• Cloud environment and cloud account UUIDs, account status, and the latest number of connection failures.
• DNS, TCP, and HTTP test results from the Portal host or container.

Handling

1. Correct the cloud environment API address, version, cloud type, or account credentials, and run CheckAccount again.
2. If the network is unreachable, correct the route, firewall, proxy, or allowlist between Portal and the cloud platform.
3. If a license, quota, or cloud platform service is abnormal, restore the cloud platform first and then test the connection.
4. Use Reconnect to restore an existing account. Do not use deletion and recreation as the default approach.
5. During consecutive-failure suppression, stop retrying and wait for the suppression period to end, or follow the operations process to handle the exact connection-failure cache entry.

Verification

• Connection: CheckAccount succeeds or returns no error cause.
• Account: Reconnect succeeds, and the account status changes to on in the account details.
• Environment: The cloud environment details can be queried, and the associated account and API configuration are correct.
• Synchronization: Wait for or trigger 1 controlled resource synchronization and confirm that the resource list can be retrieved.
• Logs: Subsequent scheduled connection checks no longer continuously produce failure logs for the plugin.

Risks and rollback

• Preserve a secure record of the old configuration before changing credentials. Do not write plaintext credentials to a ticket or log.
• Do not directly delete the cloud environment. Deletion might also remove associated cloud accounts.
• Do not bypass certificate, allowlist, or license validation as a long-term solution.
• If a connection-parameter change fails, restore the previous configuration and repeat the read-only connectivity and connection tests.

Additional information

• The ICloudAccount.check() plugin for the cloud type validates the connection. Use the logs from the plugin in the target environment to determine the specific error.