Vultr Marketplace Variables and Provisioning Scripts

<?xml encoding="utf-8" ??>

If you are new to the Vultr Marketplace, please see the documentation overview to get started.

When a customer deploys your application, it's often useful to generate random passwords and provide them to both the application and the customer. The Marketplace provides this function through Application Variables.

Variable Names

Variable names are referenced in multiple places:

• The Edit App Variables screen
• The Metadata API endpoint
• The customer's Application Instructions
• Your cloud-init provisioning scripts

Provisioning Scripts and the Metadata API

The per-instance cloud-init script is a popular place to use these variables because it only runs one time, when the instance is first deployed. For example, create two variables in the Marketplace Portal:

• demo_password : A password for a user named demo.
• web_password : A password for a web server's basic authentication.

You can discover their values in your startup script through the Vultr Metadata API. The API endpoint is formed from the variable name in the format http://169.254.169.254/v1/internal/app-{variable_name}. For example, a variable named demo_password is requested from the endpoint:

http://169.254.169.254/v1/internal/app-demo_password

When making requests, you must pass METADATA-TOKEN: vultr in the request header. Here's a curl example:

curl -H "METADATA-TOKEN: vultr" http://169.254.169.254/v1/internal/app-demo_password

Likewise, to request a variable named web_password:

curl -H "METADATA-TOKEN: vultr" http://169.254.169.254/v1/internal/app-web_password

Here's a simple example that creates a demo user and reports the web password. Create a /var/lib/cloud/scripts/per-instance/provision.sh cloud-init script.

# nano /var/lib/cloud/scripts/per-instance/provision.sh

Paste the following:

#!/bin/bash
## Runs once-and-only-once at first boot per instance.
echo $(date -u) ": System provisioned." >> /var/log/per-instance.log

## Capture Marketplace Password Variables
DEMO_PASSWORD=$(curl -H "METADATA-TOKEN: vultr" http://169.254.169.254/v1/internal/app-demo_password)
WEB_PASSWORD=$(curl -H "METADATA-TOKEN: vultr" http://169.254.169.254/v1/internal/app-web_password)

## Create user
adduser demo --gecos "First Last,RoomNumber,WorkPhone,HomePhone" --disabled-password
## Set Password
echo demo:$DEMO_PASSWORD | chpasswd

## Report the Web Password
echo "The Web password is: $WEB_PASSWORD" > /root/web-password.txt

Make the script executable.

# chmod +x /var/lib/cloud/scripts/per-instance/provision.sh

This example creates a user account named demo with the unique password generated by the Marketplace variable demo_password. It also writes a file to /root/web-password.txt with the value of web_password.

In a real application, you might pass the values to a database or set HTTP Authentication on your web server.

Here's another example. Add the following to your /var/lib/cloud/scripts/per-instance/provision.sh script.

## Capture the Marketplace Password Variable.
DB_PASS=$(curl -H "METADATA-TOKEN: vultr" http://169.254.169.254/v1/internal/app-db_pass)

## Create an example database.
mysql -u root -e "CREATE DATABASE example_db;";

## Create an example user and set the password to Marketplace Password Variable $DB_PASS.
mysql -u root -e "GRANT ALL ON example_db.* TO 'example_user'@'localhost' IDENTIFIED BY '$DB_PASS' WITH GRANT OPTION;";

Assuming you declared a variable named db_pass on the Edit App Variables screen, this script creates an example database user with a random password. The password is available to you in the Metadata API, and it's shown to the customer on the Application instructions.

Blocking SSH During Provisioning

It's a best practice to disable SSH while your provisioning scripts run, then re-enable SSH when finished, particularly if they require a long time to complete. A user who logs in via SSH while your provisioning script is running could cause unexpected side effects. We recommend disabling the SSH service entirely while your script runs. If this is not possible, please consider blocking access with the OS firewall. The final step in the provisioning script should enable SSH if your application allows SSH access for customers.

Next Steps

The next step is to create a snapshot image of your target server.

More Information

This guide is part of the Vultr Marketplace documentation. Please see the documentation overview for more information.