bosh-bootstrap 0.5.0

data/.gitignore

@@ -0,0 +1,18 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+.DS_Store

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in bosh-bootstrap.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2012 Stark & Wayne LLC
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,318 @@
+# Stark & Wayne's Bosh Bootstrapper
+
+In order to deploy CloudFoundry, and a growing number of other complex systems, you will need a BOSH. BOSH provides a complete lifecycle manager/deployer for complex systems. CloudFoundry is a very complex system when it comes to deployment/upgrades.
+
+The Stark & Wayne Bosh Bootstrapper is the simplest way to get a Micro BOSH running, to upgrade an existing Micro BOSH, and to delete it if you change your mind. 
+
+Bootstrap a Micro BOSH universe from one CLI command. Also allows SSH access and the ability to delete created Micro BOSHes.
+
+```
+$ bosh-bootstrap deploy --latest-stemcell
+Creating inception VM...
+Creating micro BOSH VM...
+
+$ bosh-bootstrap ssh
+Open SSH tunnel to inception VM...
+
+$ bosh-bootstrap delete
+Deleting micro BOSH VM...
+```
+
+It is now very simple to bootstrap a micro BOSH from a single, local CLI. The bootstrapper first creates an inception VM and then uses the `bosh_deployer` (`bosh micro deploy`) to deploy micro BOSH.
+
+To be cute about it, the Stark & Wayne Bosh Bootstrapper aims to provide lifecycle management for the BOSH lifecycle manager. Zing! See the "Deep dive into deploy command" section below for greater understanding why the Stark & Wayne Bosh Bootstrapper is very useful.
+
+## Installation
+
+This bootstrapper for BOSH is distributed as a RubyGem for Ruby 1.8+.
+
+```
+$ gem install bosh-bootstrap
+```
+
+## Usage
+
+### First time usage
+
+The first time you use `bosh-bootstrap` it will create everything necessary. The example output below includes user prompts.
+
+```
+$ bosh-bootstrap deploy --latest-stemcell
+
+Stage 1: Choose infrastructure
+
+Found infrastructure API credentials at ~/.fog (override with --fog)
+1. AWS (default)
+2. AWS (bosh)
+3. Rackspace (default)
+Choose infrastructure:  1
+
+Confirming: using AWS infrastructure.
+
+1. ap-northeast-1
+2. ap-southeast-1
+3. eu-west-1
+4. us-east-1
+5. us-west-1
+6. us-west-2
+7. sa-east-1
+Choose AWS region:  6
+Confirming: Using AWS us-west-2 region.
+
+
+Stage 2: Configuration
+
+Confirming: Micro BOSH will be named microbosh_aws_us_east_1
+
+BOSH username: drnic
+BOSH password: ********
+Confirming: After BOSH is created, your username will be drnic
+
+Confirming: Micro BOSH will be assigned IP address 174.129.227.124
+
+Confirming: Micro BOSH protected by security group named microbosh_aws_us_east_1, with ports [22, 6868, 25555, 25888]
+
+Confirming: Micro BOSH accessible via key pair named microbosh_aws_us_east_1
+
+Confirming: Micro BOSH will be created with stemcell micro-bosh-stemcell-aws-0.6.4.tgz
+
+
+Stage 3: Create/Allocate the Inception VM
+
+1. create new inception VM
+2. use an existing Ubuntu server
+3. use this server (must be ubuntu & on same network as bosh)
+Create or specify an Inception VM:  1
+
+Confirming: Inception VM has been created
+
+Stage 4: Preparing the Inception VM
+
+Successfully created vcap user
+Successfully installed base packages
+Successfully installed ruby 1.9.3
+Successfully installed useful ruby gems
+Successfully installed bosh
+Successfully captured value of salted password
+Successfully validated bosh deployer
+
+Stage 5: Deploying micro BOSH
+
+Successfully downloaded micro-bosh stemcell
+Successfully uploaded micro-bosh deployment manifest file
+Successfully installed key pair for user
+Successfully deploy micro bosh
+```
+
+### Local usage
+
+During the `bosh-bootstrap deploy` sequence above, you could choose to use the local VM as the Inception VM. 
+
+For AWS, it is important that you only use a VM that is on the same infrastructure region. The process of creating a micro-bosh VM is to use a local
+EBS volume to create an AMI. The target region for the micro-bosh VM must therefore be in the same region.
+
+### Repeat usage
+
+The `deploy` command can be re-run and it will not prompt again for inputs. It aims to be idempotent. This means that if you see any errors when running `deploy`, such as unavailability of VMs or IP addresses, then when you resolve those issues you can re-run the `deploy` command and it will resume the bootstrap of micro-bosh (and the optional inception VM).
+
+## SSH access
+
+You can open an SSH shell with the Inception VM:
+
+```
+$ bosh-bootstrap ssh
+```
+
+You can also pass a COMMAND argument and that command will be run instead of the shell being opened.
+
+```
+$ bosh-bootstrap ssh 'whoami'
+ubuntu
+```
+
+## Deleting micro BOSH
+
+The `bosh-bootstrap delete`  command will delete the target micro-bosh.
+
+```
+$ bosh-bootstrap delete
+Stage 1: Target inception VM to use to delete micro-bosh
+
+Confirming: Using inception VM ubuntu@ec2-184-73-231-239.compute-1.amazonaws.com
+
+Stage 2: Deleting micro BOSH
+Delete micro BOSH
+  stopping agent services (00:00:01)                                            
+  unmount disk (00:00:10)                                                       
+  detach disk (00:00:13)                                                        
+  delete disk (00:02:35)                                                        
+  delete VM (00:00:37)                                                          
+  delete stemcell (00:00:00)                                                    
+Done                          6/6 00:03:37                                      
+Deleted deployment 'microbosh-aws-us-east-1', took 00:03:37 to complete
+```
+
+## Deep dive into the BOSH Bootstrap deploy command
+
+What is actually happening when you run `bosh-bootstrap deploy`?
+
+At the heart of `bosh-bootstrap deploy` is the execution of the BOSH Deployer, a command provided with BOSH to bootstrap a single VM with all the parts of BOSH running on it. If you ran this command yourself you would run:
+
+```
+$ gem install bosh-deployer
+$ bosh download public stemcell some-microbosh-stemcell.tgz
+$ bosh micro deploy some-microbosh-stemcell.tgz
+```
+
+Unfortunately for this simple scenario, there are many little prerequisite steps before those three commands. The Stark & Wayne Bosh Bootstrapper replaces pages and pages of step-by-step instructions with a single command line that does everything. It even allows you to upgrade your Micro BOSH with newer BOSH releases: both publicly available stemcells and custom stemcells generated from the BOSH source code.
+
+To understand exactly what the `bosh-bootstrap deploy` command is doing, let's start with what the running parts of BOSH are and how `bosh micro deploy` deploys them.
+
+### What is in BOSH?
+
+A running BOSH, whether it is running on a single server or a cluster of servers, is a collection of processes. The core of BOSH is the Director and the Blobstore. The remaining processes provide support, storage or messaging.
+
+* The Director, the public API for the bosh CLI and coordinator of BOSH behavior
+* The Blobstore, to store and retrieve precompiled packages
+* Agents, run on each server within deployments
+* The Health Manager, to track the state of deployed systems (the infrastructure and running jobs)
+* Internal DNS, called PowerDNS, for internal unique naming of servers within BOSH deployments
+* Registry, for example AWS Registry, for tracking the infrastructure that has been provisioned (servers, persistent disks)
+* PostgreSQL
+* Redis
+
+When you deploy a BOSH using the BOSH Deployer (`bosh micro deploy`) or indirectly via the BOSH Bootstrapper, you are actually deploying a BOSH release that describes a BOSH called [bosh-release](https://github.com/cloudfoundry/bosh-release). The processes listed above are called "jobs" and you can see the full list of jobs inside a BOSH within the [jobs/ directory](https://github.com/cloudfoundry/bosh-release/jobs) of `bosh-release`.
+
+But you don't yet have a BOSH to deploy another BOSH.
+
+### How to get your first BOSH?
+
+The BOSH Deployer (`bosh micro deploy`) exists to spin you up a pre-baked server with all the packages and jobs running.
+
+When you run the BOSH Deployer on a server, it does not convert that server into a BOSH. Rather, it provisions a single brand new server, with all the required packages, configuration and startup scripts. We call this pre-baked server a Micro BOSH.
+
+A Micro BOSH server is a normal running server built from a base OS image that already contains all the packages, configuration and startup scripts for the jobs listed above.
+
+In BOSH terminology, call these pre-packaged base OS images "stemcells".
+
+For AWS, vSphere and OpenStack there are publicly available stemcells that can bootstrap a Micro BOSH for that infrastructure. To see the current list of all public Micro BOSH stemcells for all infrastructure providers; and to download one of them:
+
+```
+$ bosh public stemcells --tag micro
+$ bosh download public stemcell micro-bosh-stemcell-aws-0.6.4.tgz
+```
+
+The CloudFoundry BOSH team will release new public stemcells overtime. The BOSH Deployer allows you to upgrade to newer stemcells as easily as it is to deploy a Micro BOSH initially.
+
+```
+$ bosh micro deploy micro-bosh-stemcell-aws-0.6.4.tgz
+$ bosh micro deploy micro-stemcell-aws-0.7.0.tgz --update
+```
+
+### Configuring a Micro BOSH
+
+The command above will not work without first providing BOSH Deployer with configuration details. The stemcell file alone is not sufficient information. When we deploy or update a Micro BOSH we need to provide the following:
+
+* A static IP address - this IP address will be bound to the initial Micro BOSH server, and when the Micro BOSH is updated in future and the server is thrown away and replaced, then it is bound to the replacement servers
+* Server properties - the instance type (such as m1.large on AWS) or RAM/CPU combination (on vSphere)
+* Server persistent disk - a single persistent, attached disk volume will be provisioned and mounted at `/var/vcap/store`; when the Micro BOSH is updated is is unmounted, unattached from the current server and then reattached and remounted to the upgraded server
+* Infrastructure API credentials - the magic permissions for the Micro BOSH to provision servers and persistent disks for its BOSH deployments
+
+This information is to go into a file called `/path/to/deployments/NAME/micro_bosh.yml`. Before `bosh micro deploy` is run, we first need to tell BOSH Deployer which file contains the Micro BOSH deployment manifest.
+
+In the Stark & Wayne Bosh Bootstrapper, the manifests are stored at `/var/vcap/store/microboshes/deployments/NAME/micro_bosh.yml`.
+
+So the BOSH Deployer command that is run to specify the deployment manifest and run the deployment is:
+
+```
+$ bosh micro deployment `/var/vcap/store/microboshes/deployments/NAME/micro_bosh.yml`
+$ bosh micro deploy /var/vcap/store/stemcells/micro-bosh-stemcell-aws-0.6.4.tgz
+```
+
+### Why does it take so long to deploy Micro BOSH on AWS?
+
+On AWS it can take over 20 minutes to deploy or upgrade a Micro BOSH from a public stemcell. The majority of this time is taken with converting the stemcell file (such as `micro-bosh-stemcell-aws-0.6.4.tgz`) into an Amazon AMI.
+
+When you boot a new server on AWS you provide the base machine image for the root filesystem. This is called the Amazon Machine Image (AMI). For our Micro BOSH, we need an AMI that contains all the packages, process configuration and startup scripts. That is, we need to convert our stemcell into an AMI; then use the AMI to boot the Micro BOSH server.
+
+The BOSH Deployer performs all the hard work to create an AMI. Believe me, it is a lot of hard work.
+
+The summary of the process of creating the Micro BOSH AMI is:
+
+1. Create a new EBS volume (an attached disk) on the server running BOSH Deployer
+2. Unpack/upload the stemcell onto the EBS volume
+3. Create a snapshot of the EBS volume
+4. Register the snapshot as an AMI
+
+This process takes the majority of the time to deploy a new/replacement Micro BOSH server.
+
+### Why can't I run BOSH Deployer from my laptop?
+
+One of the feature of the BOSH Bootstrapper is that you can run it from your local laptop. BOSH Deployer itself cannot be run from your laptop. The reason is hidden in the step-by-step AMI example above. In AWS, to create an EBS volume, create a snapshot and register it as an AMI, you need to be running the commands on an AWS server in the same target region as your future Micro BOSH server.
+
+The server that runs the BOSH Deployer is commonly called the Inception VM. For AWS you need an Inception VM in the same AWS region that you will provision your Micro BOSH server. Since a BOSH also manages a stemcell process similar to the above, your BOSH must be in the same AWS region that you a deploying BOSH releases.
+
+### How does BOSH Bootstrapper get around this requirement?
+
+The BOSH Bootstrapper can run from your laptop or locally from an Inception VM. 
+
+If you run it from your laptop, then it will prompt you to create a new Inception VM or for the host/username of a pre-existing Ubuntu server. The BOSH Bootstrapper will then use SSH to command the Inception VM to perform all the deployment steps discussed above.
+
+That is the core of the service being provided by the BOSH Bootstrapper - to prepare an Inception VM and to command it to deploy and upgrade Micro BOSHes.
+
+## Internal configuration/settings
+
+Once you've used the CLI it stores your settings for your BOSH, so that you can re-run the tool for upgrades or other future functionality.
+
+By default, the settings file is stored at `~/.bosh_bootstrap/manifest.yml`.
+
+For an AWS BOSH it looks like:
+
+``` yaml
+---
+fog_path: /Users/drnic/.fog
+fog_credentials:
+  provider: AWS
+  aws_access_key_id: ACCESS_KEY
+  aws_secret_access_key: SECRET_KEY
+  region: us-east-1
+bosh_cloud_properties:
+  aws:
+    access_key_id: ACCESS_KEY
+    secret_access_key: SECRET_KEY
+    default_key_name: microbosh
+    default_security_groups:
+    - microbosh
+    ec2_private_key: /home/vcap/.ssh/microbosh.pem
+bosh_resources_cloud_properties:
+  instance_type: m1.medium
+bosh_provider: aws
+region_code: us-east-1
+bosh_username: drnic
+bosh_password: PASSWORD
+bosh:
+  password: PASSWORD
+  salted_password: 'sdfkjhadsjkadsfjhdsf'
+  persistent_disk: 16384
+  ip_address: 107.22.247.45
+micro_bosh_stemcell_name: "micro-bosh-stemcell-aws-0.6.4.tgz"
+```
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request
+
+## Copyright
+
+All documentation and source code is copyright of Stark & Wayne LLC.
+
+## Subscription and Support
+
+This documentation & tool is freely available to all people and companies coming to CloudFoundry and BOSH.
+
+If you decide to run CloudFoundry and BOSH in production, please purchase a Subscription and Support Agreement with Stark & Wayne so we can continue to create and maintain top quality documentation and tools; and also provide you with bespoke support for your deployments. We want to help you be successfully.
+

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/bin/bosh-bootstrap

@@ -0,0 +1,8 @@
+#!/usr/bin/env ruby
+$:.push File.dirname(__FILE__) + '/../lib'
+
+require "rubygems"
+require "bosh-bootstrap"
+require "bosh-bootstrap/cli"
+
+Bosh::Bootstrap::Cli.start

data/bosh-bootstrap.gemspec

@@ -0,0 +1,34 @@
+# -*- encoding: utf-8 -*-
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'bosh-bootstrap/version'
+
+Gem::Specification.new do |gem|
+  gem.name          = "bosh-bootstrap"
+  gem.version       = Bosh::Bootstrap::VERSION
+  gem.authors       = ["Dr Nic Williams"]
+  gem.email         = ["drnicwilliams@gmail.com"]
+  gem.description   = %q{Bootstrap a micro BOSH universe from one CLI}
+  gem.summary       = <<-EOS
+Now very simple to bootstrap a micro BOSH from a single, local CLI.
+The bootstrapper first creates an inception VM and then uses
+bosh_deployer (bosh micro deploy) to deploy micro BOSH from
+an available stemcell.
+EOS
+  gem.homepage      = "https://github.com/StarkAndWayne/bosh-bootstrap"
+
+  gem.files         = `git ls-files`.split($/)
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.require_paths = ["lib"]
+  
+  gem.add_dependency "thor"
+  gem.add_dependency "highline"
+  gem.add_dependency "settingslogic"
+  gem.add_dependency "POpen4"
+  gem.add_dependency "net-scp"
+  gem.add_dependency "fog", "~>1.8.0"
+  gem.add_dependency "escape"
+  gem.add_dependency "bosh_cli"
+  gem.add_development_dependency "bosh_deployer"
+end

data/lib/bosh-bootstrap.rb

@@ -0,0 +1,10 @@
+module Bosh
+  module Bootstrap
+  end
+end
+
+require "bosh-bootstrap/version"
+require "bosh-bootstrap/commander"
+require "bosh-bootstrap/stages"
+
+require "bosh/providers"

data/lib/bosh-bootstrap/cli.rb

@@ -0,0 +1,1024 @@
+require "thor"
+require "highline"
+require "fileutils"
+
+# for the #sh helper
+require "rake"
+require "rake/file_utils"
+
+require "escape"
+
+require "bosh-bootstrap/helpers"
+
+module Bosh::Bootstrap
+  class Cli < Thor
+    include Thor::Actions
+    include Bosh::Bootstrap::Helpers::FogSetup
+    include Bosh::Bootstrap::Helpers::Settings
+    include FileUtils
+
+    attr_reader :fog_credentials
+    attr_reader :server
+
+    desc "deploy", "Bootstrap Micro BOSH, and optionally an Inception VM"
+    method_option :fog, :type => :string, :desc => "fog config file (default: ~/.fog)"
+    method_option :"private-key", :type => :string, :desc => "Local passphrase-less private key path"
+    method_option :"upgrade-deps", :type => :boolean, :desc => "Force upgrade dependencies, packages & gems"
+    method_option :"edge-deployer", :type => :boolean, :desc => "Install bosh deployer from git instead of rubygems"
+    method_option :"latest-stemcell", :type => :boolean, :desc => "Use latest micro-bosh stemcell; possibly not tagged stable"
+    method_option :"edge-stemcell", :type => :boolean, :desc => "Create custom stemcell from BOSH git source"
+    def deploy
+      load_deploy_options # from method_options above
+
+      deploy_stage_1_choose_infrastructure_provider
+      deploy_stage_2_bosh_configuration
+      deploy_stage_3_create_allocate_inception_vm
+      deploy_stage_4_prepare_inception_vm
+      deploy_stage_5_deploy_micro_bosh
+      deploy_stage_6_setup_new_bosh
+    end
+
+    # desc "delete", "Delete Micro BOSH"
+    # method_option :all, :type => :boolean, :desc => "Delete all micro-boshes and inception VM [coming soon]"
+    # def delete
+    #   delete_stage_1_target_inception_vm
+    # 
+    #   if options[:all]
+    #     error "I'm sorry; the awesome --all flag is not yet implemented"
+    #     delete_all_stage_2_delete_micro_boshes
+    #     delete_all_stage_3_delete_inception_vm
+    #   else
+    #     delete_one_stage_2_delete_micro_bosh
+    #   end
+    # end
+    # 
+    desc "ssh [COMMAND]", "Open an ssh session to the inception VM [do nothing if local machine is inception VM]"
+    long_desc <<-DESC
+      If a command is supplied, it will be run, otherwise a session will be
+      opened.
+    DESC
+    def ssh(cmd=nil)
+      run_ssh_command_or_open_tunnel(cmd)
+    end
+
+    no_tasks do
+      DEFAULT_INCEPTION_VOLUME_SIZE = 32 # Gb
+
+      def deploy_stage_1_choose_infrastructure_provider
+        header "Stage 1: Choose infrastructure"
+        unless settings[:fog_credentials]
+          choose_fog_provider
+        end
+        confirm "Using infrastructure provider #{settings.fog_credentials.provider}"
+
+        unless settings[:region_code]
+          choose_provider_region
+        end
+        if settings[:region_code]
+          confirm "Using #{settings.fog_credentials.provider} region #{settings.region_code}"
+        else
+          confirm "No specific region/data center for #{settings.fog_credentials.provider}"
+        end
+      end
+      
+      def deploy_stage_2_bosh_configuration
+        header "Stage 2: BOSH configuration"
+        unless settings[:bosh_name]
+          provider, region = settings.bosh_provider, settings.region_code
+          if region
+            default_name = "microbosh-#{provider}-#{region}".gsub(/\W+/, '-')
+          else
+            default_name = "microbosh-#{provider}".gsub(/\W+/, '-')
+          end
+          bosh_name = hl.ask("Useful name for Micro BOSH?  ") { |q| q.default = default_name }
+          settings[:bosh_name] = bosh_name
+          save_settings!
+        end
+        confirm "Micro BOSH will be named #{settings.bosh_name}"
+
+        unless settings[:bosh_username]
+          prompt_for_bosh_credentials
+        end
+        confirm "After BOSH is created, your username will be #{settings.bosh_username}"
+
+        unless settings[:bosh]
+          say "Defaulting to 16Gb persistent disk for BOSH"
+          password        = settings.bosh_password # FIXME dual use of password?
+          settings[:bosh] = {}
+          settings[:bosh][:password] = password
+          settings[:bosh][:persistent_disk] = 16384
+          save_settings!
+        end
+        unless settings[:bosh]["ip_address"]
+          say "Acquiring IP address for micro BOSH..."
+          ip_address = acquire_ip_address
+          settings[:bosh]["ip_address"] = ip_address
+        end
+        unless settings[:bosh]["ip_address"]
+          error "IP address not available/provided currently"
+        else
+          confirm "Micro BOSH will be assigned IP address #{settings[:bosh]['ip_address']}"
+        end
+        save_settings!
+
+        unless settings[:bosh_security_group]
+          security_group_name = settings.bosh_name
+          create_security_group(security_group_name)
+        end
+        ports = settings.bosh_security_group.ports.values
+        confirm "Micro BOSH protected by security group " +
+          "named #{settings.bosh_security_group.name}, with ports #{ports}"
+
+        unless settings[:bosh_key_pair]
+          key_pair_name = settings.bosh_name
+          create_key_pair(key_pair_name)
+        end
+        confirm "Micro BOSH accessible via key pair named #{settings.bosh_key_pair.name}"
+
+        unless settings[:micro_bosh_stemcell_name]
+          settings[:micro_bosh_stemcell_name] = micro_bosh_stemcell_name
+          save_settings!
+        end
+
+        confirm "Micro BOSH will be created with stemcell #{settings.micro_bosh_stemcell_name}"
+      end
+
+      def deploy_stage_3_create_allocate_inception_vm
+        header "Stage 3: Create/Allocate the Inception VM"
+        unless settings["inception"] && settings["inception"]["host"]
+          hl.choose do |menu|
+            menu.prompt = "Create or specify an Inception VM:  "
+            if aws? || openstack?
+              menu.choice("create new inception VM") do
+                aws? ? boot_aws_inception_vm : boot_openstack_inception_vm
+              end
+            end
+            menu.choice("use an existing Ubuntu server") do
+              settings["inception"] = {}
+              settings["inception"]["host"] = \
+                hl.ask("Host address (IP or domain) to inception VM? ")
+              settings["inception"]["username"] = \
+                hl.ask("Username that you have SSH access to? ") {|q| q.default = "ubuntu"}
+            end
+            menu.choice("use this server (must be ubuntu & on same network as bosh)") do
+              # dummy data for settings.inception
+              settings["inception"] = {}
+              settings["inception"]["username"] = `whoami`.strip
+            end
+          end
+        end
+        # If successfully validate inception VM, then save those settings.
+        save_settings!
+
+        if settings["inception"]["host"]
+          @server = Commander::RemoteServer.new(settings.inception.host)
+          confirm "Using inception VM #{settings.inception.username}@#{settings.inception.host}"
+        else
+          @server = Commander::LocalServer.new
+          confirm "Using this server as the inception VM"
+        end
+        unless settings["inception"]["validated"]
+          unless server.run(Bosh::Bootstrap::Stages::StageValidateInceptionVm.new(settings).commands)
+            error "Failed to complete Stage 3: Create/Allocate the Inception VM"
+          end
+          settings["inception"]["validated"] = true
+        end
+        # If successfully validate inception VM, then save those settings.
+        save_settings!
+      end
+
+      def deploy_stage_4_prepare_inception_vm
+        unless settings["inception"]["prepared"] && !settings["upgrade_deps"]
+          header "Stage 4: Preparing the Inception VM"
+          unless server.run(Bosh::Bootstrap::Stages::StagePrepareInceptionVm.new(settings).commands)
+            error "Failed to complete Stage 4: Preparing the Inception VM"
+          end
+          # Settings are updated by this stage
+          # it generates a salted password from settings.bosh.password
+          # and stores it in settings.bosh.salted_password
+          settings["inception"]["prepared"] = true
+          save_settings!
+        else
+          header "Stage 4: Preparing the Inception VM", :skipping => "Already prepared inception VM."
+        end
+      end
+
+      def deploy_stage_5_deploy_micro_bosh
+        header "Stage 5: Deploying micro BOSH"
+        unless server.run(Bosh::Bootstrap::Stages::MicroBoshDeploy.new(settings).commands)
+          error "Failed to complete Stage 5: Deploying micro BOSH"
+        end
+
+        confirm "Successfully built micro BOSH"
+      end
+
+      def deploy_stage_6_setup_new_bosh
+        # TODO change to a polling test of director being available
+        say "Pausing to wait for BOSH Director..."
+        sleep 5
+
+        header "Stage 6: Setup bosh"
+        unless server.run(Bosh::Bootstrap::Stages::SetupNewBosh.new(settings).commands)
+          error "Failed to complete Stage 6: Setup bosh"
+        end
+
+        say "Locally targeting and login to new BOSH..."
+        sh "bosh -u #{settings.bosh_username} -p #{settings.bosh_password} target #{settings.bosh.ip_address}"
+        sh "bosh login #{settings.bosh_username} #{settings.bosh_password}"
+
+        save_settings!
+
+        confirm "You are now targeting and logged in to your BOSH"
+      end
+
+      def delete_stage_1_target_inception_vm
+        header "Stage 1: Target inception VM to use to delete micro-bosh"
+        if settings["inception"]["host"]
+          @server = Commander::RemoteServer.new(settings.inception.host)
+          confirm "Using inception VM #{settings.inception.username}@#{settings.inception.host}"
+        else
+          @server = Commander::LocalServer.new
+          confirm "Using this server as the inception VM"
+        end
+      end
+
+      def delete_one_stage_2_delete_micro_bosh
+        header "Stage 2: Deleting micro BOSH"
+        unless server.run(Bosh::Bootstrap::Stages::MicroBoshDelete.new(settings).commands)
+          error "Failed to complete Stage 1: Delete micro BOSH"
+        end
+        save_settings!
+      end
+
+      def delete_all_stage_2_delete_micro_boshes
+        
+      end
+
+      def delete_all_stage_3_delete_inception_vm
+        
+      end
+
+      def run_ssh_command_or_open_tunnel(cmd)
+        unless settings[:inception]
+          say "No inception VM being used", :yellow
+          exit 0
+        end
+        unless host = settings.inception[:host]
+          exit "Inception VM has not finished launching; run to complete: #{self.class.banner_base} deploy"
+        end
+        username = 'vcap'
+        exit system Escape.shell_command(['ssh', "#{username}@#{host}", cmd].compact)
+
+        # TODO how to use the specific private_key_path as configured in settings
+        # _, private_key_path = local_ssh_key_paths
+        # exit system Escape.shell_command(['ssh', "-i #{private_key_path}", "#{username}@#{host}", cmd].compact)
+        #
+        # Currently this shows:
+        # Warning: Identity file  /Users/drnic/.ssh/id_rsa not accessible: No such file or directory.
+      end
+
+      # Display header for a new section of the bootstrapper
+      def header(title, options={})
+        say "" # golden whitespace
+        if skipping = options[:skipping]
+          say "Skipping #{title}", [:yellow, :bold]
+          say skipping
+        else
+          say title, [:green, :bold]
+        end
+        say "" # more golden whitespace
+      end
+
+      def error(message)
+        say message, :red
+        exit 1
+      end
+
+      def confirm(message)
+        say "Confirming: #{message}", green
+        say "" # bonus golden whitespace
+      end
+
+      def load_deploy_options
+        settings["fog_path"] = File.expand_path(options[:fog] || "~/.fog")
+
+        settings["bosh_git_source"] = options[:"edge-deployer"] # use bosh git repo instead of rubygems
+
+        # determine which micro-bosh stemcell to download/create
+        if options[:"latest-stemcell"]
+          settings["micro_bosh_stemcell_type"] = "latest"
+          settings["micro_bosh_stemcell_name"] = nil # force name to be refetched
+        elsif options[:"edge-stemcell"]
+          settings["micro_bosh_stemcell_type"] = "custom"
+          settings["micro_bosh_stemcell_name"] = "custom"
+        else
+          # may have already been set from previous deploy run
+          settings["micro_bosh_stemcell_type"] ||= "stable"
+        end
+
+        # once a stemcell is downloaded or created; these fields above should
+        # be uploaded with values such as:
+        #  -> settings["micro_bosh_stemcell_name"] = "micro-bosh-stemcell-aws-0.8.1.tgz"
+
+        if options["private-key"]
+          private_key_path = File.expand_path(options["private-key"])
+          unless File.exists?(private_key_path)
+            error "Cannot find a file at #{private_key_path}"
+          end
+          public_key_path = "#{private_key_path}.pub"
+          unless File.exists?(public_key_path)
+            error "Cannot find a file at #{public_key_path}"
+          end
+
+          settings["local"] ||= {}
+          settings["local"]["private_key_path"] = private_key_path
+          settings["local"]["public_key_path"] = public_key_path
+        end
+
+        if options["upgrade-deps"]
+          settings["upgrade_deps"] = options["upgrade-deps"]
+        else
+          settings.delete("upgrade_deps")
+        end
+        save_settings!
+      end
+
+      # Displays a prompt for known IaaS that are configured
+      # within .fog config file.
+      #
+      # For example:
+      #
+      # 1. AWS (default)
+      # 2. AWS (bosh)
+      # 3. Alternate credentials
+      # Choose infrastructure:  1
+      #
+      # If .fog config only contains one provider, do not prompt.
+      #
+      # fog config file looks like:
+      # :default:
+      #   :aws_access_key_id:     PERSONAL_ACCESS_KEY
+      #   :aws_secret_access_key: PERSONAL_SECRET
+      # :bosh:
+      #   :aws_access_key_id:     SPECIAL_IAM_ACCESS_KEY
+      #   :aws_secret_access_key: SPECIAL_IAM_SECRET_KEY
+      #
+      # Convert this into:
+      # { "AWS (default)" => {:aws_access_key_id => ...}, "AWS (bosh)" => {...} }
+      #
+      # Then display options to user to choose.
+      #
+      # Currently detects following fog providers:
+      # * AWS
+      # * OpenStack
+      #
+      # If "Alternate credentials" is selected, then user is prompted for fog
+      # credentials:
+      # * provider?
+      # * access keys?
+      # * API URI or region?
+      #
+      # At the end, settings.fog_credentials contains the credentials for target IaaS
+      # and :provider key for the IaaS name.
+      #
+      #   {:provider=>"AWS",
+      #    :aws_access_key_id=>"PERSONAL_ACCESS_KEY",
+      #    :aws_secret_access_key=>"PERSONAL_SECRET"}
+      #
+      # settings.fog_credentials.provider is the provider name
+      # settings.bosh_provider is the BOSH name for the provider (aws,vsphere,openstack)
+      #   so as to local stemcells (see +micro_bosh_stemcell_name+)
+      def choose_fog_provider
+        @fog_providers = {}
+        # Prepare menu options:
+        # each provider/profile name gets a menu choice option
+        fog_config.inject({}) do |iaas_options, fog_profile|
+          profile_name, profile = fog_profile
+          if profile[:aws_access_key_id]
+            # TODO does fog have inbuilt detection algorithm?
+            @fog_providers["AWS (#{profile_name})"] = {
+              "provider" => "AWS",
+              "aws_access_key_id" => profile[:aws_access_key_id],
+              "aws_secret_access_key" => profile[:aws_secret_access_key]
+            }
+          end
+          if profile[:openstack_username]
+            # TODO does fog have inbuilt detection algorithm?
+            @fog_providers["OpenStack (#{profile_name})"] = {
+              "provider" => "OpenStack",
+              "openstack_username" => profile[:openstack_username],
+              "openstack_api_key" => profile[:openstack_api_key],
+              "openstack_tenant" => profile[:openstack_tenant],
+              "openstack_auth_url" => profile[:openstack_auth_url]
+            }
+          end
+        end
+        # Display menu
+        # Include "Alternate credentials" as the last option
+        if @fog_providers.keys.size > 0
+          hl.choose do |menu|
+            menu.prompt = "Choose infrastructure:  "
+            @fog_providers.each do |label, credentials|
+              menu.choice(label) { @fog_credentials = credentials }
+            end
+            menu.choice("Alternate credentials") { prompt_for_alternate_fog_credentials }
+          end
+        else
+          prompt_for_alternate_fog_credentials
+        end
+        settings[:fog_credentials] = {}
+        @fog_credentials.each do |key, value|
+          settings[:fog_credentials][key] = value
+        end
+        setup_bosh_cloud_properties
+        settings[:bosh_resources_cloud_properties] = bosh_resources_cloud_properties
+        settings[:bosh_provider] = settings.bosh_cloud_properties.keys.first # aws, vsphere...
+        save_settings!
+      end
+
+      # If no .fog file is found, or if user chooses "Alternate credentials",
+      # then this method prompts the user:
+      # * provider?
+      # * access keys?
+      # * API URI or region?
+      #
+      # Populates +@fog_credentials+ with a Hash that includes :provider key
+      # For example:
+      # {
+      #   :provider => "AWS",
+      #   :aws_access_key_id => ACCESS_KEY,
+      #   :aws_secret_access_key => SECRET_KEY
+      # }
+      def prompt_for_alternate_fog_credentials
+        say ""  # glorious whitespace
+        creds = {}
+        hl.choose do |menu|
+          menu.prompt = "Choose infrastructure:  "
+          menu.choice("AWS") do
+            creds[:provider] = "AWS"
+            creds[:aws_access_key_id] = hl.ask("Access key: ")
+            creds[:aws_secret_access_key] = hl.ask("Secret key: ")
+          end
+          menu.choice("OpenStack") do
+            creds[:provider] = "OpenStack"
+            creds[:openstack_username] = hl.ask("Username: ")
+            creds[:openstack_api_key] = hl.ask("API key: ")
+            creds[:openstack_tenant] = hl.ask("Tenant: ")
+            creds[:openstack_auth_url] = hl.ask("Authorization URL: ")
+          end
+        end
+        @fog_credentials = creds
+      end
+
+      def setup_bosh_cloud_properties
+        if aws?
+          settings[:bosh_cloud_properties] = {}
+          settings[:bosh_cloud_properties][:aws] = {}
+          props = settings[:bosh_cloud_properties][:aws]
+          props[:access_key_id] = settings.fog_credentials.aws_access_key_id
+          props[:secret_access_key] = settings.fog_credentials.aws_secret_access_key
+          # props[:ec2_endpoint] = "ec2.REGION.amazonaws.com" - via +choose_aws_region+
+          # props[:region] = REGION - via +choose_aws_region+            
+          # props[:default_key_name] = "microbosh"  - via +create_aws_key_pair+
+          # props[:ec2_private_key] = "/home/vcap/.ssh/microbosh.pem" - via +create_aws_key_pair+
+          # props[:default_security_groups] = ["microbosh"], - via +create_aws_security_group+
+        elsif openstack?
+          settings[:bosh_cloud_properties] = {}
+          settings[:bosh_cloud_properties][:openstack] = {}
+          props = settings[:bosh_cloud_properties][:openstack]
+          props[:username] = settings.fog_credentials.openstack_username
+          props[:api_key] = settings.fog_credentials.openstack_api_key
+          props[:tenant] = settings.fog_credentials.openstack_tenant
+          props[:auth_url] = settings.fog_credentials.openstack_auth_url
+          # props[:default_key_name] = "microbosh"  - via +create_openstack_key_pair+
+          # props[:private_key] = "/home/vcap/.ssh/microbosh.pem" - via +create_openstack_key_pair+
+          # props[:default_security_groups] = ["microbosh"], - via +create_openstack_security_group+
+        else
+          raise "implement #bosh_cloud_properties for #{settings.fog_credentials.provider}"
+        end
+      end
+
+      def bosh_resources_cloud_properties
+        if aws?
+          {"instance_type" => "m1.medium"}
+        elsif openstack?
+          # TODO: Ask for instance type
+          {"instance_type" => "m1.medium"}
+        else
+          raise "implement #bosh_resources_cloud_properties for #{settings.fog_credentials.provider}"
+        end
+      end
+
+      # Ask user to provide region information (URI)
+      # or choose from a known list of regions (e.g. AWS)
+      # Return true if region selected (@region_code is set)
+      # Else return false
+      def choose_provider_region
+        if aws?
+          choose_aws_region
+        else
+          settings["region_code"] = nil
+          false
+        end
+      end
+
+      def choose_aws_region
+        aws_regions = provider.region_labels
+        default_aws_region = provider.default_region_label
+
+        hl.choose do |menu|
+          menu.prompt = "Choose AWS region (default: #{default_aws_region}): "
+          aws_regions.each do |region|
+            menu.choice(region) do
+              settings["region_code"] = region
+              settings["fog_credentials"]["region"] = region
+              settings["bosh_cloud_properties"]["aws"]["region"] = region
+              settings["bosh_cloud_properties"]["aws"]["ec2_endpoint"] = "ec2.#{region}.amazonaws.com"
+              save_settings!
+            end
+            menu.default = default_aws_region
+          end
+        end
+        reset_fog_compute
+        true
+      end
+
+      # Creates a security group.
+      # Also sets up the bosh_cloud_properties for the remote server
+      #
+      # Adds settings:
+      # * bosh_security_group.name
+      # * bosh_security_group.ports
+      # * bosh_cloud_properties.<bosh_provider>.default_security_groups
+      def create_security_group(security_group_name)
+        ports = {
+          ssh_access: 22,
+          nats_server: 4222,
+          message_bus: 6868,
+          blobstore: 25250,
+          bosh_director: 25555
+        }
+        if aws?
+          ports[:aws_registry] = 25777
+        elsif openstack?
+          ports[:openstack_registry] = 25889
+        end
+
+        provider.create_security_group(security_group_name, "microbosh", ports)
+
+        settings["bosh_cloud_properties"][provider_name]["default_security_groups"] = [security_group_name]
+        settings["bosh_security_group"] = {}
+        settings["bosh_security_group"]["name"] = security_group_name
+        settings["bosh_security_group"]["ports"] = {}
+        ports.each { |name, port| settings["bosh_security_group"]["ports"][name.to_s] = port }
+        save_settings!
+      end
+
+      # Creates a key pair.
+      def create_key_pair(key_pair_name)
+        if aws?
+          create_aws_key_pair(key_pair_name)
+        elsif openstack?
+          create_openstack_key_pair(key_pair_name)
+        else
+          raise "implement #create_key_pair for #{settings.fog_credentials.provider}"
+        end
+      end
+
+      # Creates an AWS key pair, and stores the private key
+      # in settings manifest.
+      # Also sets up the bosh_cloud_properties for the remote server
+      # to have the .pem key installed.
+      #
+      # Adds settings:
+      # * bosh_key_pair.name
+      # * bosh_key_pair.private_key
+      # * bosh_key_pair.fingerprint
+      # * bosh_cloud_properties.aws.default_key_name
+      # * bosh_cloud_properties.aws.ec2_private_key
+      def create_aws_key_pair(key_pair_name)
+        unless fog_compute.key_pairs.get(key_pair_name)
+          say "creating key pair #{key_pair_name}..."
+          kp = fog_compute.key_pairs.create(:name => key_pair_name)
+          settings[:bosh_key_pair] = {}
+          settings[:bosh_key_pair][:name] = key_pair_name
+          settings[:bosh_key_pair][:private_key] = kp.private_key
+          settings[:bosh_key_pair][:fingerprint] = kp.fingerprint
+          settings["bosh_cloud_properties"]["aws"]["default_key_name"] = key_pair_name
+          settings["bosh_cloud_properties"]["aws"]["ec2_private_key"] = "/home/vcap/.ssh/#{key_pair_name}.pem"
+          save_settings!
+        else
+          error "AWS key pair '#{key_pair_name}' already exists. Rename BOSH or delete old key pair manually and re-run CLI."
+        end
+      end
+
+      # Creates an OpenStack key pair, and stores the private key
+      # in settings manifest.
+      # Also sets up the bosh_cloud_properties for the remote server
+      # to have the .pem key installed.
+      #
+      # Adds settings:
+      # * bosh_key_pair.name
+      # * bosh_key_pair.private_key
+      # * bosh_key_pair.fingerprint
+      # * bosh_cloud_properties.openstack.default_key_name
+      # * bosh_cloud_properties.openstack.ec2_private_key
+      def create_openstack_key_pair(key_pair_name)
+        unless fog_compute.key_pairs.get(key_pair_name)
+          say "creating key pair #{key_pair_name}..."
+          kp = fog_compute.key_pairs.create(:name => key_pair_name)
+          settings[:bosh_key_pair] = {}
+          settings[:bosh_key_pair][:name] = key_pair_name
+          settings[:bosh_key_pair][:private_key] = kp.private_key
+          settings[:bosh_key_pair][:fingerprint] = kp.fingerprint
+          settings["bosh_cloud_properties"]["openstack"]["default_key_name"] = key_pair_name
+          settings["bosh_cloud_properties"]["openstack"]["private_key"] = "/home/vcap/.ssh/#{key_pair_name}.pem"
+          save_settings!
+        else
+          error "OpenStack key pair '#{key_pair_name}' already exists. Rename BOSH or delete old key pair manually and re-run CLI."
+        end
+      end
+
+      # Provisions an AWS m1.small VM as the inception VM
+      # Updates settings.inception.host/username
+      #
+      # NOTE: if any stage fails, when the CLI is re-run
+      # and "create new server" is selected again, the process should
+      # complete
+      #
+      # Assumes that local CLI user has public/private keys at ~/.ssh/id_rsa.pub
+      def boot_aws_inception_vm
+        say "" # glowing whitespace
+
+        public_key_path, private_key_path = local_ssh_key_paths
+        unless settings["inception"] && settings["inception"]["server_id"]
+          username = "ubuntu"
+          size = "m1.small"
+          say "Provisioning #{size} for inception VM..."
+          server = fog_compute.servers.bootstrap({
+            :public_key_path => public_key_path,
+            :private_key_path => private_key_path,
+            :flavor_id => size,
+            :bits => 64,
+            :username => "ubuntu"
+          })
+          unless server
+            error "Something mysteriously cloudy happened and fog could not provision a VM. Please check your limits."
+          end
+
+          settings["inception"] = {}
+          settings["inception"]["server_id"] = server.id
+          settings["inception"]["username"] = username
+          save_settings!
+        end
+
+        server ||= fog_compute.servers.get(settings["inception"]["server_id"])
+
+        unless settings["inception"]["ip_address"]
+          say "Provisioning IP address for inception VM..."
+          ip_address = acquire_ip_address
+          associate_ip_address_with_server(ip_address, server)
+          host = server.dns_name
+
+          settings["inception"]["ip_address"] = ip_address
+          save_settings!
+        end
+
+        unless settings["inception"]["disk_size"]
+          disk_size = DEFAULT_INCEPTION_VOLUME_SIZE # Gb
+          device = "/dev/sdi"
+          provision_and_mount_volume(server, disk_size, device)
+
+          settings["inception"]["disk_size"] = disk_size
+          settings["inception"]["disk_device"] = device
+          save_settings!
+        end
+
+        # settings["inception"]["host"] is used externally to determine
+        # if an inception VM has been assigned already; so we leave it
+        # until last in this method to set this setting.
+        # This way we can always rerun the CLI and rerun this method
+        # and idempotently get an inception VM
+        unless settings["inception"]["host"]
+          settings["inception"]["host"] = server.dns_name
+          save_settings!
+        end
+
+        confirm "Inception VM has been created"
+        display_inception_ssh_access
+      end
+
+      # Provisions an OpenStack m1.small VM as the inception VM
+      # Updates settings.inception.host/username
+      #
+      # NOTE: if any stage fails, when the CLI is re-run
+      # and "create new server" is selected again, the process should
+      # complete
+      #
+      # Assumes that local CLI user has public/private keys at ~/.ssh/id_rsa.pub
+      def boot_openstack_inception_vm
+        say "" # glowing whitespace
+
+        public_key_path, private_key_path = local_ssh_key_paths
+
+        # make sure we've a fog key pair
+        key_pair_name = Fog.respond_to?(:credential) && Fog.credential || :default
+        unless key_pair = fog_compute.key_pairs.get("fog_#{key_pair_name}")
+          say "creating key pair fog_#{key_pair_name}..."
+          public_key = File.open(public_key_path, 'rb') { |f| f.read }
+          key_pair = fog_compute.key_pairs.create(
+            :name => "fog_#{key_pair_name}",
+            :public_key => public_key
+          )
+        end
+        confirm "Using key pair #{key_pair.name} for Inception VM"
+
+        # make sure port 22 is open in the default security group
+        security_group = fog_compute.security_groups.find { |sg| sg.name == 'default' }
+        authorized = security_group.rules.detect do |ip_permission|
+            ip_permission['ip_range'].first && ip_permission['ip_range']['cidr'] == '0.0.0.0/0' &&
+            ip_permission['from_port'] == 22 &&
+            ip_permission['ip_protocol'] == 'tcp' &&
+            ip_permission['to_port'] == 22
+        end
+        unless authorized
+          security_group.create_security_group_rule(22, 22)
+        end
+        confirm "Inception VM port 22 open"
+
+        unless settings["inception"] && settings["inception"]["server_id"]
+          username = "ubuntu"
+          say "Provisioning server for inception VM..."
+          settings["inception"] = {}
+
+          # Select OpenStack flavor
+          unless settings["inception"]["flavor_id"]
+            say ""
+            hl.choose do |menu|
+              menu.prompt = "Choose OpenStack flavor:  "
+              fog_compute.flavors.each do |flavor|
+                menu.choice(flavor.name) do
+                  settings["inception"]["flavor_id"] = flavor.id
+                  save_settings!
+                end
+              end
+            end
+          end
+
+          # Select OpenStack image
+          unless settings["inception"]["image_id"]
+            say ""
+            hl.choose do |menu|
+              menu.prompt = "Choose OpenStack image (Ubuntu):  "
+              fog_compute.images.each do |image|
+                menu.choice(image.name) do
+                  settings["inception"]["image_id"] = image.id
+                  save_settings!
+                end
+              end
+            end
+          end
+
+          # Boot OpenStack server
+          server = fog_compute.servers.create(
+            :name => "Inception VM",
+            :key_name => key_pair.name,
+            :public_key_path => public_key_path,
+            :private_key_path => private_key_path,
+            :flavor_ref => settings["inception"]["flavor_id"],
+            :image_ref => settings["inception"]["image_id"],
+            :username => username
+          )
+          unless server
+            error "Something mysteriously cloudy happened and fog could not provision a VM. Please check your limits."
+          end
+          server.wait_for { ready? }
+
+          settings["inception"]["server_id"] = server.id
+          settings["inception"]["username"] = username
+          save_settings!
+        end
+
+        server ||= fog_compute.servers.get(settings["inception"]["server_id"])
+
+        unless settings["inception"]["ip_address"]
+          say "Provisioning IP address for inception VM..."
+          ip_address = acquire_ip_address
+          associate_ip_address_with_server(ip_address, server)
+
+          settings["inception"]["ip_address"] = ip_address
+          save_settings!
+        end
+
+        unless settings["inception"]["disk_size"]
+          disk_size = DEFAULT_INCEPTION_VOLUME_SIZE # Gb
+          device = "/dev/vdc"
+          provision_and_mount_volume(server, disk_size, device)
+
+          settings["inception"]["disk_size"] = disk_size
+          settings["inception"]["disk_device"] = device
+          save_settings!
+
+          # TODO use provision_and_mount_volume
+          
+          disk_size = 16 # Gb
+          va = fog_compute.get_server_volumes(server.id).body['volumeAttachments']
+          unless vol = va.find { |v| v["device"] == "/dev/vdc" }
+            say "Provisioning #{disk_size}Gb persistent disk for inception VM..."
+            volume = fog_compute.volumes.create(:name => "Inception Disk",
+                                                :description => "",
+                                                :size => disk_size,
+                                                :availability_zone => server.availability_zone)
+            volume.wait_for { volume.status == 'available' }
+            volume.attach(server.id, "/dev/vdc")
+            volume.wait_for { volume.status == 'in-use' }
+          end
+
+          # Format and mount the volume
+          # TODO: Hack
+          unless server.public_ip_address
+            server.addresses["public"] = [settings["inception"]["ip_address"]]
+          end
+          unless server.public_key_path
+            server.public_key_path = public_key_path
+          end
+          unless server.private_key_path
+            server.private_key_path = private_key_path
+          end
+          server.username = settings["inception"]["username"]
+          server.sshable?
+
+          say "Mounting persistent disk as volume on inception VM..."
+          # TODO if any of these ssh calls fail; retry
+          server.ssh(['sudo mkfs.ext4 /dev/vdc -F'])
+          server.ssh(['sudo mkdir -p /var/vcap/store'])
+          server.ssh(['sudo mount /dev/vdc /var/vcap/store'])
+
+          settings["inception"]["disk_size"] = disk_size
+          save_settings!
+        end
+
+        # settings["inception"]["host"] is used externally to determine
+        # if an inception VM has been assigned already; so we leave it
+        # until last in this method to set this setting.
+        # This way we can always rerun the CLI and rerun this method
+        # and idempotently get an inception VM
+        unless settings["inception"]["host"]
+          settings["inception"]["host"] = settings["inception"]["ip_address"]
+          save_settings!
+        end
+
+        confirm "Inception VM has been created"
+        display_inception_ssh_access
+      end
+
+      # Provision or provide an IP address to use
+      # For AWS, it will dynamically provision an elastic IP
+      # For OpenStack, it will dynamically provision a floating IP
+      def acquire_ip_address
+        unless public_ip = provider.provision_public_ip_address
+          say "Unable to acquire a public IP. Please check your account for capacity or service issues.".red
+          exit 1
+        end
+        public_ip
+      end
+
+      def associate_ip_address_with_server(ip_address, server)
+        address = fog_compute.addresses.get(ip_address)
+        address.server = server
+        server.reload
+      end
+
+      # Provision a volume for a specific device (unless already provisioned)
+      # Request that the +server+ mount the volume at the +device+ location.
+      #
+      # Requires that we can SSH into +server+.
+      def provision_and_mount_volume(server, disk_size, device)
+        unless volume = server.volumes.all.find {|v| v.device == device}
+          say "Provisioning #{disk_size}Gb persistent disk for inception VM..."
+          volume = fog_compute.volumes.create(
+            size: disk_size,
+            name: "Inception Disk",
+            description: '',
+            device: "/dev/sdi",
+            availability_zone: server.availability_zone)
+          # TODO: the following works in fog 1.9.0+ (but which has a bug in bootstrap)
+          # https://github.com/fog/fog/issues/1516
+          #
+          # volume.wait_for { volume.status == 'available' }
+          # volume.attach(server.id, "/dev/vdc")
+          # volume.wait_for { volume.status == 'in-use' }
+          #
+          # Instead, using:
+          volume.server = server
+        end
+
+        # Format and mount the volume
+        say "Mounting persistent disk as volume on inception VM..."
+        disk_mounted = false
+        until disk_mounted
+          begin
+            # TODO catch Errno::ETIMEDOUT and re-run ssh commands
+            server.ssh(["sudo mkfs.ext4 #{device} -F"]) 
+            server.ssh(["sudo mkdir -p /var/vcap/store"])
+            server.ssh(["sudo mount #{device} /var/vcap/store"])
+            disk_mounted = true
+          rescue Errno::ETIMEDOUT => e
+            say "Timeout error/warning mounting volume, retrying...", yellow
+          end
+        end
+      end
+
+      def display_inception_ssh_access
+        _, private_key_path = local_ssh_key_paths
+        say "SSH access: ssh -i #{private_key_path} #{settings["inception"]["username"]}@#{settings["inception"]["host"]}"
+      end
+
+      # Discover/create local passphrase-less SSH keys to allow
+      # communication with Inception VM
+      #
+      # Returns [public_key_path, private_key_path]
+      def local_ssh_key_paths
+        unless settings["local"] && settings["local"]["private_key_path"]
+          settings["local"] = {}
+          public_key_path = File.expand_path("~/.ssh/id_rsa.pub")
+          private_key_path = File.expand_path("~/.ssh/id_rsa")
+          raise "Please create public keys at ~/.ssh/id_rsa.pub or use --private-key flag" unless File.exists?(public_key_path)
+
+          settings["local"]["public_key_path"] = public_key_path
+          settings["local"]["private_key_path"] = private_key_path
+          save_settings!
+        end
+        [settings.local.public_key_path, settings.local.private_key_path]
+      end
+
+      def aws?
+        settings.fog_credentials.provider == "AWS"
+      end
+
+      def openstack?
+        settings.fog_credentials.provider == "OpenStack"
+      end
+
+      def prompt_for_bosh_credentials
+        prompt = hl
+        say "Please enter a user/password for the BOSH that will be created."
+        settings[:bosh_username] = prompt.ask("BOSH username: ") { |q| q.default = `whoami`.strip }
+        settings[:bosh_password] = prompt.ask("BOSH password: ") { |q| q.echo = "x" }
+        save_settings!
+      end
+
+      # Returns the latest micro-bosh stemcell
+      # for the target provider (aws, vsphere, openstack)
+      def micro_bosh_stemcell_name
+        @micro_bosh_stemcell_name ||= begin
+          provider = settings.bosh_provider.downcase # aws, vsphere, openstack
+          stemcell_filter_tags = ['micro', provider]
+          if openstack?
+            # FIXME remove this if when openstack has its first stable
+          else
+            if settings["micro_bosh_stemcell_type"] == "stable"
+              stemcell_filter_tags << "stable" # latest stable micro-bosh stemcell by default
+            end
+          end
+          tags = stemcell_filter_tags.join(",")
+          bosh_stemcells_cmd = "bosh public stemcells --tags #{tags}"
+          say "Locating micro-bosh stemcell, running '#{bosh_stemcells_cmd}'..."
+          #
+          # The +bosh_stemcells_cmd+ has an output that looks like:
+          # +-----------------------------------+--------------------+
+          # | Name                              | Tags               |
+          # +-----------------------------------+--------------------+
+          # | micro-bosh-stemcell-aws-0.6.4.tgz | aws, micro, stable |
+          # | micro-bosh-stemcell-aws-0.7.0.tgz | aws, micro, test   |
+          # +-----------------------------------+--------------------+
+          #
+          # So to get the latest version for the filter tags,
+          # get the Name field, reverse sort, and return the first item
+          `#{bosh_stemcells_cmd} | grep micro | awk '{ print $2 }' | sort -r | head -n 1`.strip
+        end
+      end
+
+      def provider_name
+        settings.bosh_provider
+      end
+
+      # a helper object for the target BOSH provider
+      def provider
+        @provider ||= Bosh::Providers.for_bosh_provider_name(settings.bosh_provider, fog_compute)
+      end
+
+      def cyan; "\033[36m" end
+      def clear; "\033[0m" end
+      def bold; "\033[1m" end
+      def red; "\033[31m" end
+      def green; "\033[32m" end
+      def yellow; "\033[33m" end
+
+      # Helper to access HighLine for ask & menu prompts
+      def hl
+        @hl ||= HighLine.new
+      end
+    end
+  end
+end