What is cloud-init?

canonical/cloud-init — explained in plain English

Analysis updated 2026-07-03

★ 3,687PythonAudience · ops devopsComplexity · 3/5LicenseSetup · moderate

Mindmap

mindmap
  root((cloud-init))
    What it does
      First-boot config
      User account setup
      Package installation
      SSH key placement
    Inputs
      Cloud metadata
      User-supplied script
      Config file
    Platforms
      AWS Azure GCP
      Most Linux distros
      Private clouds
    Use cases
      Automated provisioning
      Repeatable server setup
      Multi-cloud config

mindmap root((cloud-init)) What it does First-boot config User account setup Package installation SSH key placement Inputs Cloud metadata User-supplied script Config file Platforms AWS Azure GCP Most Linux distros Private clouds Use cases Automated provisioning Repeatable server setup Multi-cloud config

Click or tap to explore — scroll the page freely

What do people build with it?

USE CASE 1

Write a user-data config file that installs Nginx and creates a deploy user with your SSH key every time you launch a new AWS EC2 instance.

USE CASE 2

Create a portable server configuration that works identically across AWS, Azure, and GCP without changing any settings.

USE CASE 3

Automate setting up a development environment on a fresh VM by writing a cloud-init script that installs packages and clones your repo.

USE CASE 4

Contribute a new feature or fix a bug in the industry-standard first-boot configuration tool used by most major Linux distributions.

What is it built with?

PythonYAMLBash

How does it compare?

	canonical/cloud-init	williamleif/graphsage	boris-code/feapder
Stars	3,687	3,687	3,686
Language	Python	Python	Python
Setup difficulty	moderate	moderate	moderate
Complexity	3/5	4/5	3/5
Audience	ops devops	researcher	developer

Figures from each repo's GitHub metadata at analysis time.

How do you get it running?

Difficulty · moderate Time to first run · 30min

Most useful in a cloud environment, testing locally requires a VM or cloud instance, though the project provides test tooling.

Apache 2.0 and GPL v3, free to use and modify, check the license file for the exact terms per component.

So what is it?

Cloud-init is a tool that runs automatically the first time a virtual machine or cloud server starts up. Its job is to configure the new machine based on instructions provided at launch, so the system arrives in a usable state without a human logging in and doing it manually. When a server boots on a cloud platform like AWS, Azure, or Google Cloud, cloud-init reads setup instructions from two sources. The first is metadata provided by the cloud platform itself, such as the hostname or network configuration. The second is optional user data, which is a script or configuration file you supply when launching the instance. Cloud-init processes these instructions and carries out tasks like setting up network interfaces, configuring storage, installing packages, creating user accounts, and placing SSH keys so you can log in securely. The tool is described as the industry-standard approach for this kind of first-boot setup. It ships by default in most major Linux distributions and is supported by virtually all public cloud providers as well as private cloud systems. Because it speaks a common format, the same user-data configuration file can work across different cloud platforms and Linux distributions without modification. The project is maintained by Canonical, the company behind Ubuntu, but it is not Ubuntu-specific. The README links to documentation covering supported clouds, supported distributions, and a contributing guide for developers who want to help with the code. The README itself is brief, as most of the detail lives in the external documentation site at docs.cloud-init.io.

Copy-paste prompts

Prompt 1

Write a cloud-init user-data YAML file that creates a user called 'deploy', adds my public SSH key, installs Docker, and enables the Docker service on Ubuntu 24.04.

Prompt 2

I want the same cloud-init config to work on both AWS and Google Cloud. What parts need to be cloud-specific and what is portable?

Prompt 3

Show me how to test a cloud-init user-data script locally without spinning up a real VM, what tools or approaches does the cloud-init project itself use?

Prompt 4

My cloud-init config runs but the package installation step fails silently. How do I read the cloud-init logs on a running Ubuntu server to debug what went wrong?

Prompt 5

Convert this Bash setup script into a proper cloud-init YAML configuration with the correct module order for network setup, user creation, and package install.

Frequently asked questions