Skip to main content

Cloud-Init Initialization Configuration

Cloud configuration (Cloud-config) commands provide users with the capability to manage the configuration of a virtual machine at the time of launch. User data can be passed to a virtual machine by using the user_data field within the payload of the create virtual machine endpoints request. Custom user data instructs a virtual machine to perform automated configuration tasks at the time of launch, including software installation, user account configuration, user initialization, automation of repetitive tasks, and provisioning of specific VM configurations.

For official Cloud-init documentation, click here.

Tasks for which virtual machines can be configured using user data scripts include:

  • Change the root user’s password
  • Create a new user
  • Create the new user’s password
  • Grant permissions to a user
  • Install applications from package managers (i.e. Docker)
  • Modify the port that the SSH daemon is set to listen on
  • Restrict root SSH login
  • Run arbitrary commands
  • Start-stop services
  • Update repository sources

User data​

Configure your virtual machine by providing initialization data in the user_data field of the create virtual machine endpoints payload. This data will be executed when the virtual machine first boots up.

Cloud-config​

Cloud-config files are written in the YAML programming language. These YAML-based cloud-config files understand certain directives allowing for the custom configuration of a virtual machine. YAML is a data serialization format that is designed to be easily readable for humans, making it simple to understand and edit. It is an indentation-reliant text format where precise indentation rules must be followed to avoid malformed cloud-config data that will be invalid.

The first line of a cloud-config file must contain the special identifier: #cloud-config so that the cloud-init program knows that the file is a cloud-config file. This special identifier must be placed on the very first line and the other contents will start after the identifier line as seen in the example below. The cloud-config file must be provided when the server is created.


The cloud-config script in this example performs the following virtual machine configurations:

  • Creates a new user called demo.
  • Adds the user to a sudo group.
  • Assigns the user sudo permissions without a password.
  • Sets the default shell to /bin/bash.
  • Writes some configurations on the /etc/ssh/sshd_config file.
Example cloud-config script
#cloud-config

# Define user configurations 
users:
  # Create a new user named "demo"
  - name: demo
    # Add the user's authorized SSH public key
    ssh-authorized-keys:
      - ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQCv60WjxoM39LgPDbiW7ne3gu...
    # Grant "sudo" privileges without a password
    sudo: ['ALL=(ALL) NOPASSWD:ALL']
    # Adds the new user to group "sudo"
    groups: sudo
    # Set the user's default shell
    shell: /bin/bash

# Define files to be written to the system
write_files:
  # The path for the SSH server configuration file.
  - path: /etc/ssh/sshd_config
    # SSH server configuration
    content: |
         Port 4444    
         Protocol 2
         HostKey /etc/ssh/ssh_host_rsa_key
         HostKey /etc/ssh/ssh_host_dsa_key

Shell-script​

Bash scripts are another common way to inject user data into a virtual machine. The file must begin with a #!/bin/bash line to be a valid Bash script.


The Bash script in this example performs the following virtual machine configurations:

  • A virtual machine configuration input file run on boot that installs two APT packages.
  • Enables the Apache HTTP service
  • Creates the index.html file in the server's root directory.
Example Bash script
#!/bin/bash
# install additional packages
sudo apt install -y HTTPd vim
# enable and start the HTTPd service
sudo systemctl enable HTTPd
sudo systemctl start HTTPd
# create a file in HTTP document root
sudo echo "<p>hello world</p>" > /var/www/html/index.html

Initializing a virtual machine using cloud-config​

POST https://infrahub-api.nexgencloud.com/v1/core/virtual-machines

The cloud-config script specifying the desired configuration of your virtual machine can be inserted into the user_data field of the request body of the create virtual machine endpoint. At the time of launch, a virtual machine with the configurations specified in the cloud-config script will be created.


Request body parameter​

user_data optional string​

Custom data or scripts to be executed on virtual machine deployment.

In this example the following cloud-config data is sent:

  • #cloud-config\nusers:\n - name: demo\n ssh-authorized-keys:\n - ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQCv60WjxoM39LgPDbiW7ne3gu...\n sudo: ['ALL=(ALL) NOPASSWD:ALL']\n groups: sudo\n shell: /bin/bash\nwrite_files:\n - path: /etc/ssh/sshd_config\n content: |\n Port 4444"
Example request
{
  "name": "vm1",
  "environment_name": "env1",
  "image_name": "image1",
  "volume_name": "volume1",
  "create_bootable_volume": false,
  "flavor_name": "flavor1",
  "key_name": "key1",
  "user_data": "#cloud-config\nusers:\n  - name: demo\n    ssh-authorized-keys:\n      - ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQCv60WjxoM39LgPDbiW7ne3gu...\n    sudo: ['ALL=(ALL) NOPASSWD:ALL']\n    groups: sudo\n    shell: /bin/bash\nwrite_files:\n  - path: /etc/ssh/sshd_config\n    content: |\n         Port 4444",
  "callback_url": "",
  "assign_floating_ip": false,
  "count": 1
}

At the time of virtual machine launch, this cloud-config script within the user_data field, will instruct the virtual machine being launched to create a new user named demo, add this user to a sudo group, assign the user sudo permissions without a password, set the default shell to /bin/bash and write some configurations on the /etc/ssh/sshd_config file.

See more information about creating a virtual machine.


info

Precise indentation of the cloud-config YAML must be maintained in the user_data field to avoid error.


Back to top​