Stop fighting cloud-init logs when your bootc image fails to initialize

Technical Briefing | 7/16/2026

You built your perfect bootc image, baked in all your configurations, and pushed it to the registry. Then you deploy it to a fresh VM, and it hangs during the first boot. Cloud-init is running, but it’s not doing what you expected, and because the system is immutable, you can’t just ssh in and hotfix the config. It’s a classic catch-22 that usually ends in an agonizing loop of rebuild-and-redeploy.

Stop guessing why your metadata isn’t applying

The issue is usually that bootc images often expect specific user-data providers that might be getting shadowed by the default cloud-init datasource priority. When you shift to immutable workflows, the cloud-init state directory becomes your primary source of truth. If you need to debug what actually happened during the transition from the base image to your custom state, check the artifacts before they rotate.

journalctl -u cloud-init -o short-precise --no-pager

• Verify if the datasource is actually discovering your platform metadata
• Check for conflicting cloud-config files in /etc/cloud/cloud.cfg.d that might override your image defaults
• Inspect /var/lib/cloud/instance/boot-finished to see if the process actually completed or died mid-execution

If you keep getting stuck, try injecting a custom cloud-init module that dumps the environment to a persistent serial console. You don’t have the luxury of traditional debugging tools here, so leverage the early boot hooks to catch the error before the system hits a restart loop. Keep the configuration as minimal as possible in the image, and pull the heavy lifting from external sources that you can actually modify without needing to trigger a full image rebuild.