diff options
Diffstat (limited to 'pages/docs')
| -rw-r--r-- | pages/docs/platform/guide/virtual-machines.md | 136 |
1 files changed, 136 insertions, 0 deletions
diff --git a/pages/docs/platform/guide/virtual-machines.md b/pages/docs/platform/guide/virtual-machines.md new file mode 100644 index 0000000..064239d --- /dev/null +++ b/pages/docs/platform/guide/virtual-machines.md @@ -0,0 +1,136 @@ +@title = 'Virtual Machines' +@summary = "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: + +* [[Available instance types for AWS => https://aws.amazon.com/ec2/instance-types/]] + +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.
\ No newline at end of file |