Virtual Machines

It's what's on the inside that matters.

Configuring the operating system of your newly minted virtual machines(s) can be achieved in a variety of ways. We provide two generic solutions that allow you to leverage whatever tools you want to perform inner configuration, and we'll continue to improve the experience based on your feedback.

On AWS the mechanism that delivers customization to the instance is called user data. It typically consists of a script that gets executed on first boot. On Linux instances this is usually handled by a package called cloud-init. On Windows instances this is handled by a package called EC2Launch.

On Azure most customization is delivered to virtual machines through Azure VM Extensions. This allows the script execution to be monitored for success. When using cloud-init configuration on Azure Linux instances, it is processed through Azure VM custom data. Both concepts are functionally the same. Most stock images have both methods enabled.

Never deliver secrets - passwords, private keys, etc. - to instances through these configuration mechanisms.

In some cases the content persists and can be retrieved through the venue management console.

To use secrets in userdata go here.

configure.admin

This method configures a single administrative user you can use for remote administration through SSH (Linux) or RDP (Windows). An administrative user has unfettered access to the entire virtual machine. See the schema reference for additional details.

Syntax

Best practices for admin configuration leverage variables:

variables:
  admin_username:
    description: The administrative account username.
    type: string
    default: adminuser
  admin_password:
    description: The administrative account password.
    type: string
    # secret: true (future)
  admin_public_key:
    description: The OpenSSH Public Key used to protect access.
    type: string

compute:
  vm:
    example:
      # ... other properties ...
      configure:
        admin:
          username: (( admin_username ))
          password: (( admin_password ))
          public_key: (( admin_public_key ))

Linux Behavior

On Linux, the administrative user has sudo permissions without the need to enter a password. Linux administrators are able to connect through SSH using the public_key that you specify. The behavior for Linux administrative access is the same on AWS and Azure: we inject a small cloud-init script to perform this configuration. Therefore the image you choose must have cloud-init installed and enabled. Many standard images come with these features enabled.

If the image does not have cloud-init, the configuration will not be applied and there will be no failure indication.

Requirements

• Image must have cloud-init enabled.

• [Azure] The Azure Agent must have CustomData processing enabled. Most stock images do.

If your image does not have cloud-init, try userdata configuration with a shell script instead.

Applying the configure.admin properties to your Linux virtual machine will:

1. Allow you to set the administrative username.

2. Allow you to set the administrative public key for SSH access.

Windows Behavior

On Windows, the administrative user is a member of the (Local) Administrators group.

Requirements

• Image must have the Azure Agent installed. Almost all images in the marketplace have this.

On AWS, the username and password are currently ignored. The administrative username will always be Administrator and the password can only be acquired by going to the AWS management console and retrieving the instance password using the private key.

On Azure, applying the configure.admin properties to your virtual machine will allow you to set the username and password. The public_key property is ignored.

configure.userdata

This configuration mechanism allows you to inject a script that is executed when the virtual machine first boots. Depending on the operating system, this supports cloud-init, shell script, powershell script, and batch script injection. See the schema reference for additional details.

On AWS when configure.userdata is used, configure.admin is ignored. On Azure however, configure.admin is always required to create a virtual machine.

Examples

Our documented examples for Linux and Windows include examples of userdata configuration.

Troubleshooting

If your script does not seem to be working, try following the procedures documented by the venues.

AWS

AWS provides specific instructions for Windows (EC2Launch). Note the troubleshooting for EC2Launch is for the 2nd version of the service, which is not widely distributed at this time. There is no troubleshooting guide for the v1 service.

Azure

Azure provides specific instructions for their Azure Agent (waagent) solution for Linux and Windows.