From 0a09a6e6f247729457d15480f8d2b9bb0b89ae5e Mon Sep 17 00:00:00 2001 From: elijah Date: Mon, 29 Aug 2016 22:55:41 -0700 Subject: Updated (very out of date) docs and README.md --- docs/en/guide/virtual-machines.html | 299 ++++++++++++++++++++++++++++++++++++ 1 file changed, 299 insertions(+) create mode 100644 docs/en/guide/virtual-machines.html (limited to 'docs/en/guide/virtual-machines.html') diff --git a/docs/en/guide/virtual-machines.html b/docs/en/guide/virtual-machines.html new file mode 100644 index 00000000..5cee9a40 --- /dev/null +++ b/docs/en/guide/virtual-machines.html @@ -0,0 +1,299 @@ + + + + +Virtual Machines - LEAP Platform Documentation + + + + + + + + +
+
+

Virtual Machines

+ +
Running LEAP platform on remote virtual machines
+
+
+ + +

Introduction

+ +

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

+ +

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

+ +
    +
  • Local virtual machines running with vagrant, for use in testing.
    • +
  • Remote virtual machines hosted by a cloud provider like AWS or Rackspace.
    • +
+ + +

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

+ +
    +
  • $profile: In this case, ‘my_aws’.
    • +
  • $profile.api: For now, must always be “aws”.
    • +
  • $profile.vendor: For now, must always be “aws”.
    • +
  • $profile.auth: API specific authentication configuration for this profile. In the case of AWS, it must include auth.region, auth.aws_access_key_id, and aws_secret_access_key.
    • +
+ + +

Additional cloud.json properties

+ +

In addition to required configuration properties, these are optional:

+ +
    +
  • $profile.default_image: What image to use for new nodes by default. Generally, you should not specify this, because it will automatically select the right Debian image for your region. A node can override this with the property vm.image.
    • +
  • $profile.default_options: This is passed directly to the cloud API, and so is specific to whichever API you are using. The node can override this with the property vm.options.
    • +
+ + +

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
+
+ +

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:

+ +
    +
  • Set the vm.auth property in the node configuration to match the name of the authentication profile.
    • +
  • Or, pass --auth PROFILE_NAME on the command line.
    • +
+ + +
+
+ + -- cgit v1.2.3