From 002a366d9dfde824cf8425fec5e2d6a56979a0c1 Mon Sep 17 00:00:00 2001 From: Mitchell Hashimoto Date: Thu, 3 Jun 2010 16:02:11 -0700 Subject: [PATCH] Multi-VM documentation --- _layouts/documentation.html | 4 +- docs/multivm.md | 112 ++++++++++++++++++++++++++++++++++++ 2 files changed, 115 insertions(+), 1 deletion(-) create mode 100644 docs/multivm.md diff --git a/_layouts/documentation.html b/_layouts/documentation.html index 2357f5daa..0bc041119 100644 --- a/_layouts/documentation.html +++ b/_layouts/documentation.html @@ -13,6 +13,8 @@
  • Boxes
    • +
  • Multi-VM Environments
    • +
  • Host Only Networking
  • Base Boxes
  • Systems
  • Rake Integration
    • @@ -24,4 +26,4 @@
    {{ content }}
    -{% include footer.html %} \ No newline at end of file +{% include footer.html %} diff --git a/docs/multivm.md b/docs/multivm.md new file mode 100644 index 000000000..9455ec3ab --- /dev/null +++ b/docs/multivm.md @@ -0,0 +1,112 @@ +--- +layout: documentation +title: Documentation - Multi-VM Environments +--- +# Multi-VM Environments + +Vagrant supports what are known as "Multi-VM Environments." These are Vagrant +environments which contain multiple virtual machines which typically work +together or are somehow associated with each other. An example of some uses of +Multi-VM environments: + +* Accurately modeling a separate _web_ and _database_ server within the + same development environment. +* Running separate _web_ and _worker_ servers, for example a server which + handles media transcoding. +* Testing an interface, such as API calls or a chat interface. +* Testing a load balancer configuration, or the effects of "unplugging" + a machine. + +Historically, running complex environments such as these was done by flattening +them onto a developer's machine. For example, in the case where there may typically +be a separate worker server which may process images, the web, queue, and workers +would all run side by side on the same development machine. + +The problem with this is that it is an inaccurate model of the production setup. +Vagrant and Multi-VM environments allow developers to model complex multi-server +setups on a single development machine without getting in the way of the +development process (continue to use the same editors, tools, etc.). + +## Defining Multiple VMs + +The multiple VMs are all defined within the same single Vagrantfile which you're +probably already used to. A small example is shown below: + +{% highlight ruby %} +Vagrant::Config.run do |config| + config.vm.define :web do |web_config| + web_config.vm.box = "web" + web_config.vm.forward_port("http", 80, 8080) + end + + config.vm.define :db do |db_config| + db_config.vm.box = "db" + db_config.vm.forward_port("db", 3306, 3306) + end +end +{% endhighlight %} + +Using `config.vm.define`, you can create multiple VMs (as many as you'd like) within +a single Vagrantfile. The `web_config` or `db_config` variables used within the +definitions are the exact same, functionally, as a Vagrantfile's typical `config`. +This allows the VMs to have their own custom configuration on any configurable +value. + +In the case above, we're defining two VMs: "web" and "db." These two VMs are based +on two different boxes. The web VM forwards port 80 while the database VM forwards +port 3306. + +## Controlling Multiple VMs + +The moment that multiple VMs are introduced in a Vagrantfile, the usage of +the various `vagrant` command line commands change slightly. This change is hopefully +mostly intuitive, and will be shown using a very simple example based on `vagrant up`. + +In a single VM environment, `vagrant up` starts that VM. In a multi-VM environment +`vagrant up` starts _every_ VM. If a name is specified to the command such as +`vagrant up web` then it will start only that specific VM. + +This pattern follows for every other command as well, although some don't implement +the "every VM" functionality when it doesn't make sense, such as `vagrant ssh`, which +requires that a VM name be specified if its in a multi-VM environment. + +## Communication Between VMs + +With multiple VMs up and running, the next step is to support inter-VM +communication so that, say, a web server can talk to its associated database +server. + +This communication is done through [host only networking](/docs/host_only_networking.html). There is an entire page dedicated to the topic, but a relatively simple +example is given below, based on the example given earlier: + +{% highlight ruby %} +Vagrant::Config.run do |config| + config.vm.define :web do |web_config| + # ... + web_config.vm.network("192.168.1.10") + end + + config.vm.define :db do |db_config| + # ... + db_config.vm.network("192.168.1.11") + end +end +{% endhighlight ruby %} + +The above assigns a static IP to both the web and database VMs. This +static IP can then be used to communicate directly to the other VMs. +For more details on how to do things such as creating separate networks, +joining the same network from separate Vagrantfiles, etc. please read +the [host only networking](/docs/host_only_networking.html) page. + +
    +

    All ports are open!

    +

    + When assigning a static IP like the above, VirtualBox makes no attempt + to block any access to any port. Therefore, it is up to you to make sure + that the iptables or firewall are properly setup on each VM. This issue + does not pose a security threat, since the network is private to your machine, + but it is important to note for modeling production as accurately as possible. +

    +
    +