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

---

Cloud-init in Hyperstack

Cloud-init configuration scripts can be passed during virtual machine deployment as YAML or Bash, enabling automated configuration tasks at launch. These tasks include software installation, user account setup, initialization settings, automation of repetitive tasks, and specific VM configurations.

Cloud-init scripts

Configure your virtual machine by providing initialization data in the Cloud-init scripts field during VM deployment in Hyperstack, or using the user_data field within the payload of the create virtual machine API. 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

Bash scripts

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 via API

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, we first create the cloud-init file called user-data.txt:

cat << EOF > user_data.txt
#cloud-config

users:
  - name: demo
    ssh-authorized-keys:
      - ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQCv60WjxoM39LgPDbiW7ne3gu...
    sudo: ['ALL=(ALL) NOPASSWD:ALL']
    groups: sudo
    shell: /bin/bash

write_files:
  - path: /etc/ssh/sshd_config
    content: |
      Port 4444
EOF

Example curl request

# First convert the user data to a single line JSON string
user_data_content=$(jq -Rs '.' < user_data.txt)

# Then use the API to create a VM with the user data
curl --location 'https://infrahub-api.nexgencloud.com/v1/core/virtual-machines' \
--header 'Content-Type: application/json' \
--header "api_key: $HYPERSTACK_API_KEY" \
--data '{
    "name": "cloud-init-example",
    "environment_name": "default-CANADA-1",
    "image_name": "Ubuntu Server 22.04 LTS R550 CUDA 12.4 with Docker",
    "flavor_name": "n3-A100x1",
    "key_name": "default-CANADA-1-key",
    "count": 1,
    "assign_floating_ip": true,
    "user_data": '"$user_data_content"'
}'

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 via API.

info

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

Back to top