Issue

Use this article to troubleshoot userdata injection and cloud-init issues.

Environment

• Product: ZCF
• Component: Cloud
• Affected object: userdata/cloud-init
• Versions: 4.x, 5.x
• Scenario: Userdata injection/cloud-init

Symptoms

• Userdata or SSH key injection fails, preventing passwordless VM login or execution of initialization scripts.

Possible causes

• The cloud-init service, metadata address, DHCP/userdata network, image packaging, or SSH key configuration is abnormal.

Resolution

1. Confirm cloud-init status and logs in the image.
2. Check metadata address reachability and platform userdata configuration.
3. Verify the VM IP address, default route, and Layer 3 network DHCP/userdata settings.

Key command

systemctl status cloud-init
cloud-init status --long
curl http://169.254.169.254/2009-04-04/meta-data/instance-id
grep -a -nE "userdata|cloud-init|sshkey" /usr/local/zstack/apache-tomcat/logs/management-server.log*

Remediation

• Based on the troubleshooting result, repair the affected component, configuration, data state, or connection path.
• If databases, underlying storage, snapshot chains, VM disks, GPU passthrough, or management-service restarts are involved, first confirm backups, scope of impact, and rollback paths.

Verification

• Confirm that the symptom described in this article no longer occurs.
• UI, API, management-node logs, and underlying command output corroborate one another.
• Observe at least one related task or alarm cycle to confirm that the issue does not recur.

Risks and rollback

• Before remediation in production, confirm customer service impact, the change window, and the rollback plan.
• For data deletion, database modifications, snapshot-chain repairs, underlying file operations, or hardware operations, ZStack recommends contacting technical support for confirmation.

Notes

• Before adjusting management services, databases, certificates, permissions, auditing, or security settings, confirm the HA state, service window, rollback plan, and compliance-retention requirements.
• If database modifications, underlying file operations, lock release, service restarts, driver or firmware upgrades, or bulk resource changes are required, contact ZStack technical support before proceeding.