Virtual Machines

Running LEAP platform on remote virtual machines

Introduction

You can use the leap command line to easily manage remote virtual machines.

Note: there are two types of virtual machines that leap can handle:

This guide is for “remote virtual machines”. For “local virtual machines” see Vagrant.

Currently, only Amazon AWS is supported as a cloud provider.

Configuration

To get started with virtual machines, you must configure a cloud.json file with your API credentials for the virtual machine vendor. This file lives in the root of your provider directory.

For example:

{
  "my_aws": {
    "api": "aws",
    "vendor": "aws",
    "auth": {
      "region": "us-west-2",
      "aws_access_key_id": "xxxx my key id xxxx",
      "aws_secret_access_key": "xxxx my access key xxxx"
    }
  }
}

This will configure a cloud “authentication profile” called “my_aws”. This profile will be used by default if there is only one. See below for managing multiple authentication profiles.

Required cloud.json properties

Additional cloud.json properties

In addition to required configuration properties, these are optional:

A more complete example cloud.json:

{
  "my_aws": {
    "api": "aws",
    "vendor": "aws",
    "auth": {
      "region": "us-west-2",
      "aws_access_key_id": "xxxx my key id xxxx",
      "aws_secret_access_key": "xxxx my access key xxxx"
    },
    "default_image": "ami-98e114f8",
    "default_options": {
      "InstanceType": "t2.nano"
    }
  }
}

See also:

Usage

See leap help vm for a description of all the possible commands.

In order to be able to create new virtual machine instances, you need to register your SSH key with the VM vendor.

leap vm key-register

You only have to do this once, and only people who will be creating new VM instances need to do this.

Once you have done that, you just leap vm add to create the virtual machine and then leap vm start to actually boot it.

leap vm add mynode
leap vm start mynode

You can specify seed values to leap vm add. For example:

leap vm add mynode services:webapp tags:seattle vm.options.InstanceType:t2.small

For an email provider installation, you should specify the following seeds:

leap vm add mynode services:webapp,couchdb,soledad,mx

Check to see what the status is of all VMs:

leap vm status

If it looks good, you can now deploy to the new server:

leap node init mynode
leap deploy mynode

To stop the VM:

leap vm stop mynode

To destroy the VM and clean up its storage space:

leap vm rm mynode

In general, you should remove VMs instead of stopping them, unless you plan on stopping the VM for a short amount of time. A stopped VM will still use disk space and still incur charges.

Keeping State Synchronized

The LEAP platform stores all its state information in flat static files. The virtual machine vendor, however, also has its own state.

On the provider side, VM state is stored in node configuration files in nodes/*.json. Of particular importance are the properties ip_address and vm.id.

Most of the time, you should not have any trouble: the leap vm commands will keep things in sync. However, if the state of your configuration files gets out of sync with the state of the virtual machines, it can cause problems.

The command leap vm status will warn you whenever it detects a problem and it will usually propose a fix.

Typically, the fix is to manually update the binding between a local node configuration and the running remote virtual machine, like so:

leap vm bind NODE_NAME VM_ID

Multiple authentication profiles

If you have multiple profiles configured in cloud.json, you can specify which one you want to use: