Add user data when deploying Compute Instances

The Metadata service is always active, so there's no need to enable it. User data can be provided to the Metadata service, which is then consumed by cloud-init when your Compute Instance boots up for the first time.

  • Cloud Manager:

    1. Navigate to the Linodes page in Cloud Manager and click the Create Linode button. This opens the Create Linode form.

    2. Fill out the form with your desired settings. Be sure to select one of the supported distribution images and data centers.

    3. Expand the Add User Data section and enter your user data into the User Data field.

      Screenshot of the Add User Data section in <<CLOUD_PORTAL>>

      If you are unfamiliar with cloud-init, see Using cloud-config files to configure a server for help creating a cloud-config file.

    4. Once you are ready, click the Create Linode button to deploy the Compute Instance.

  • Linode CLI:

    linode-cli linodes create \
      --label new-instance-with-metadata \
      --region us-iad \
      --type g6-standard-2 \
      --image linode/ubuntu22.04 \
      --root_pass [your-root-password] \
      --metadata.user_data [your-user-data]
    

    Replace [your-root-password] with a strong root password and [your-user-data] with the cloud-config data or script you wish to use. When using the CLI, user data must be a Base64-encoded string. Review the Base64 Encoded section below to generate the string.

  • Linode API:

    Run the API curl request below, making sure to properly paste in or reference your API token.

    curl -H "Content-Type: application/json" \
        -H "Authorization: Bearer $TOKEN" \
        -X POST -d '{
          "label": "new-instance-with-metadata",
          "region": "us-iad",
          "type": "g6-standard-2",
          "image": "linode/ubuntu22.04",
          "root_pass": "[your-root-password]",
          "metadata": {
              "user_data": "[your-user-data]"
          }
        }' \
        https://api.linode.com/v4/linode/instances
    

    Replace [your-root-password] with a strong root password and [your-user-data] with the cloud-config data or script you wish to use. When using the API, user data must be a Base64-encoded string. Review the Base64 Encoded section below to generate the string.

When your Compute Instance boots up using a compatible distribution, cloud-init runs. If it detects that this is the first time running on this Compute Instance, it connects to the Metadata API and captures the instance data for that Compute Instance, including any user data that you added. It then uses that metadata to provision the software on the Compute Instance, including setting the hostname to the Compute Instance's label and executing the user data script.

📘

User data can be added when creating a new Compute Instance, rebuilding a Compute Instance, cloning a Compute Instance, and restoring from a backup.

User data formats

User data can be provided in many different formats, with the most common being cloud-config.

  • Cloud-config script: cloud-config is the default syntax for cloud-init and can be used on any Linux distribution. It contains a list of directives formatted using YAML. Review the Using cloud-config files to configure a server guide for more details.

    #cloud-config
    package_update: true
    package_upgrade: true
    packages:
    - nginx
    - mysql-server
    
  • Executable script: Cloud-init also accepts other scripts that can be executed by the target distribution. This includes bash and python. Since many commands (including those to create users and install packages) differ between distributions, providing these scripts may limit which distributions you can target.

    #!/bin/bash
    apt-get update -y && apt-get upgrade -y
    apt-get install nginx mysql-server -y
    
  • Other formats: Review the User data formats guide within the official documentation to learn more about other types of formats supported by cloud-init.

Base64 encoded

When submitting user data through the Linode CLI or API, you first need to encode it into Base64 (without any line breaks/wraps). To do that, run the command below that corresponds with your local operating system. Replace [file] with the name (and path, if needed) of your cloud-config or script file.

  • macOS:

    base64 --break=0 --input=[file]
    
  • Linux: