Manage SmartOS zones using Vagrant.
This plugin depends on using a SmartOS global zone built to be vagrant compatible.
config.vm.box = "livinginthepast/smartos"
See Vagrant Cloud for some boxes.
This plugin also depends on Vagrant recognizing the SmartOS guest. This is available in Vagrant 1.5.3 or newer.
Any outstanding issues with SmartOS integration in the current released version of Vagrant can be hacked into shape with the vagrant-smartos/vagrant-smartos-guest plugin. This tracks fixes that have been submitted as pull requests to Vagrant but may have not been yet released.
Quick Start Installation
vagrant plugin install vagrant-smartos-zones mkdir <directory_name> cd <directory_name> curl -sO https://raw.githubusercontent.com/vagrant-smartos/vagrant-smartos-zones/master/examples/Vagrantfile vagrant up vagrant ssh
Slow Start Installation
vagrant plugin install vagrant-smartos-zones
If you are using a development version of vagrant, or would like to use an unreleased version of this plugin, add the following to your Gemfile.
group :plugins do gem 'vagrant-smartos-zones', github: 'vagrant-smartos/vagrant-smartos-zones' end
In a local checkout of this repository, the following will work:
gem install bundler bundle bundle exec vagrant up bundle exec vagrant ssh
Please note that this will install vagrant into your local ruby environment, which may overwrite or conflict with the normal vagrant version installed in your system.
Vagrant.configure('2') do |config| config.vm.provider "virtualbox" do |v| v.memory = 3072 end config.ssh.insert_key = false # See https://vagrantcloud.com/livinginthepast for SmartOS boxes config.vm.box = "livinginthepast/smartos" config.vm.synced_folder ".", "/vagrant", disabled: true # This is required for the commands that talk to the global zone config.vm.communicator = 'smartos' # livinginthepast boxes include a default platform_image. Set # here to download/use a different image. # config.global_zone.platform_image = 'latest' # config.global_zone.platform_image = '20140312T071408Z' config.zone.name = 'base64' config.zone.brand = 'joyent' config.zone.image = 'c353c568-69ad-11e3-a248-db288786ea63' config.zone.memory = 2048 config.zone.disk_size = 5 config.zone.synced_folder ".", "/vagrant", type: 'rsync' end
Download or interact with SmartOS platform images:
vagrant smartos latest vagrant smartos list vagrant smartos install [platform_image]
Interact with zones running in a box:
vagrant zones config vagrant zones list vagrant zones show [name] vagrant zones start [name] vagrant zones stop [name]
Export a running zone as a dataset (image) in the local file system:
vagrant dataset create [zone] [identifier] vagrant dataset delete [identifier] vagrant dataset list
Single zone usage
When a single zone is configured (currently the only configuration
zonegate service is enabled in the global zone. This
makes it so that inbound packets in the global zone are forwarded to the
zonegate is disabled or when a zone is not running, then
vagrant ssh will access the global zone. When a zone is running while
zonegate is enabled, then
vagrant ssh will access the zone.
vagrant global-zone ssh
A secondary port forward is installed in VirtualBox, which allows us to
access the global zone even when
zonegate forwards normal ssh to the
vagrant global-zone ssh
vagrant zlogin [name]
This command accesses the zone, but through the global zone. It uses the
global zone ssh port to connect to the global zone, then runs
to access the zone.
This can by handy when, for instance, SSH becomes broken in the zone.
vagrant zlogin [name]
This plugin expects the Vagrant box to boot SmartOS from a mounted ISO
file, known as a platform image. To facilitate updates to the platform
image without having to continually create new boxes, the plugin
downloads platform image into a user's
.vagrant.d directory, and then
swaps out the ISO mounted in the Vagrant box with the one configured in
To help with this,
vagrant-smartos-zones provides the
vagrant smartos subcommand.
Show the name of the most up-to-date platform version hosted by Joyent:
vagrant smartos latest
List all locally-installed platform images:
vagrant smartos list
Download a new platform image:
vagrant smartos install [platform-image]
Using an arbitrary platform image url
An arbitrary URL can be used to download SmartOS platform images. When doing so, no checksum validation is performed (so if the image is interrupted when downloading, you may end up with a corrupt ISO file).
When using an arbitrary URL for the platform image, make sure you set
platform_image_url and include the full
URL to the ISO file. In this case,
platform_image will be used to name
(and find) the file in the local file system.
config.global_zone.platform_image = 'omglol-2131234' config.global_zone.platform_image_url = 'http://example.com/path/to/smartos-2131234.iso'
Vagrant allows synced folders into any SmartOS guest. When the guest is a global zone, be aware that the root partition is a RAM disk of a little more than 256M.
VirtualBox guest additions
Shared folders using VirtualBox guest additions currently do not work.
In single-zone environments, synced folders of type
rsync work as
zonegate forwards all packets into the zone, and the built-in
synced folders code in Vagrant runs after the zone is configured.
# Vagrantfile config.vm.synced_folder ".", "/vagrant", type: "rsync"
The vagrant box with the global zone requires a
vagrant user and
group with which to connect. This user should have
Primary Administrator privileges. When creating a local zone, a
user and group are also created in the zone.
The plugin allows for local configuration through the
vagrant zones config command. This can be used for local overrides of zone
vagrant zones config vagrant zones config key value vagrant zones config --delete key
Networks conflict, particularly when assumptions are made about local networks. For this reason, the network chosen by the plugin when configuring the Global Zone and its local zone can be globally overridden.
Since this is a facet of your current location and not of the box itself, this is configured in the plugin rather than in the Vagrantfile.
vagrant zones config network 10.0.0.0/24
What can go wrong? Well... basically, what can go wrong is that the Global Zone port forwarding will break, and we won't actually be able to create zones. It should be pretty obvious when this is the case.
- Does your network overlap with VirtualBox's local network space?
Using local zone images
When running vagrant from a location far away from where SmartOS images are hosted (anywhere other than the east coast of the USA, basically), setting up a zone can be very slow.
Zones can be modified in Vagrant, then exported locally to save time on repeated tasks. After modifying a zone, for instance by installing build tools, you can export the zone as follows (warning: this will take a while):
# vagrant dataset create [zone] [identifier] vagrant dataset create base64 base64-15.1.1-build-essential
The vagrant-smartos-zones plugin can be configured to use a local zone image in place of a remote one as follows:
vagrant zones config dataset.0edf00aa-0562-11e5-b92f-879647d45790 base64-15.1.1-build-essential
Now any Vagrantfile configured to use a local zone with the image 0edf00aa-0562-11e5-b92f-879647d45790 will instead install and use the local image.
vagrant zones config local.pkgsrc http://mirror.domain.com
This will replace the protocol and domain of the pkgsrc mirror used by pkgin in a SmartOS zone.
There is a basic test suite that uses
test-kitchen to converge
different brands of zones. Although it might not be comprehensive, it
should be ran after new features or after any significant refactoring to
ensure that nothing breaks the ability to stand up a zone.
bundle exec kitchen test
This may take a while...
References / Alternatives
Any success of this project depends heavily on the work of others, which I've either learned from or pulled in directly.
- https://github.com/joshado/vagrant-smartos - Vagrant plugin for managing zones on a global zone running on an arbitrary IP.
- https://github.com/groundwater/vagrant-smartos - Scripts for creating stand-alone boxes where GZ networking is twerked to pretend that the local zone is the only thing in the box.
- http://dlc-int.openindiana.org/aszeszo/vagrant - aszeszo's work, which led to the above repo.
- http://cuddletech.com/blog/?p=821 - @benr's writeup of the above work.
- http://vagrantup.com - Thank you so much to Michell Hashimoto for making Vagrant in the first place.
Please forgive any lapses of acknowledgment. I've read so many blog posts and so much source code in the course of working on this, many references have fallen by the wayside.
- Only one local zone per box. Working on it.
- Usage may change with each prerelease version until I get it right. Until a non .pre version is released, check commit logs.
See the Contributing page for guidelines/recommendations on contributions.