This topic explains how to deploy MicroBOSH to OpenStack.

Step 1: Create a Deployment Manifest

The MicroBOSH deployment manifest is a YAML file that defines the components and properties of the deployment. Create a manifest for your deployment as follows:

  1. Create a local deployment directory to store your manifest.

    $ mkdir ~/my-micro-deployment
  2. Create a deployment manifest YAML file.

    The example below is a MicroBOSH deployment manifest template. Copy and paste the template into a text editor and save the manifest to your deployment directory.

    In the template, you must replace the NETWORK-UUID, SUBNET-POOL-IP-ADDRESS, FLOATING-IP, OPENSTACK-PASSWORD, IDENTITY-API-ENDPOINT, OPENSTACK-TENANT, and OPENSTACK-USERNAME properties. We describe replacing these properties in Step 2: Prepare an OpenStack environment.

Note: The example below has the file name manifest.yml, which we reference in other examples in this topic.

name: microbosh

  type: manual
  vip: FLOATING-IP # Replace with a floating IP address
  ip: SUBNET-POOL-IP-ADDRESS # Replace with an address from the subnet IP address allocation pool of your OpenStack internal network
    net_id: NETWORK-UUID # Replace with your OpenStack internal network UUID

  persistent_disk: 20000
    instance_type: m1.xlarge

  plugin: openstack
      auth_url: IDENTITY-API-ENDPOINT # Replace with your OpenStack Identity API endpoint
      tenant: OPENSTACK-TENANT # Replace with OpenStack tenant name
      username: OPENSTACK-USERNAME # Replace with OpenStack username
      api_key: OPENSTACK-PASSWORD # Replace with your OpenStack password
      default_key_name: microbosh # OpenStack Keypair name
      private_key: microbosh.pem # Path to OpenStack Keypair private key
      default_security_groups: [bosh]

    director: {max_threads: 3}
    hm: {resurrector_enabled: true}
    ntp: [,]

Step 2: Prepare an OpenStack environment

To prepare your OpenStack project for deploying MicroBOSH, use the OpenStack GUI to perform the following tasks:


  1. An OpenStack environment running one of the following supported releases:

  2. The following OpenStack services:

    • Identity: MicroBOSH authenticates credentials and retrieves the endpoint URLs for other OpenStack services.
    • Compute: MicroBOSH boots new VMs, assigns floating IPs to VMs, and creates and attaches volumes to VMs.
    • Image: MicroBOSH stores stemcells using the Image service.
    • (Optional) OpenStack Networking: Provides network scaling and automated management functions that are useful when deploying complex distributed systems.

  3. The following OpenStack networks:

    • An external network with a subnet.
    • An internal network with a subnet. The subnet must have an IP address allocation pool.

  4. A new OpenStack project.

Note: See the OpenStack documentation for help finding more information.

Create a Keypair

  1. Select Access & Security from the left navigation panel.

  2. Select the Keypairs tab.

  3. Click Create Keypair.

  4. Name the Keypair “microbosh” and click Create Keypair.

  5. Save the microbosh.pem file.

  6. Move the microbosh.pem file into your local deployment directory. For example, on UNIX run this command:

    mv ~/Downloads/bosh.pem ~/my-micro-deployment/microbosh.pem

Create and Configure Security Groups

You must create and configure two Security Groups to restrict incoming network traffic to the BOSH VMs.

BOSH Security Group

  1. Select Access & Security from the left navigation panel.

  2. Select the Security Groups tab.

  3. Click Create Security Group.

  4. Name the security group “bosh” and add the description “BOSH Security Group”

  5. Click Create Security Group.

  6. Select the BOSH Security Group and click Edit Rules.

  7. Click Add Rule.

  8. Add the following rules to the BOSH Security Group:

    Direction Ether Type IP Protocol Port Range Remote
    IngressIPv4TCP257770.0.0.0/0 (CIDR)
    IngressIPv4TCP255550.0.0.0/0 (CIDR)
    IngressIPv4TCP252500.0.0.0/0 (CIDR)
    IngressIPv4TCP68680.0.0.0/0 (CIDR)
    IngressIPv4TCP42220.0.0.0/0 (CIDR)
    IngressIPv4UDP680.0.0.0/0 (CIDR)
    IngressIPv4TCP530.0.0.0/0 (CIDR)
    IngressIPv4UDP530.0.0.0/0 (CIDR)
    EgressIPv4Any- (CIDR)
    EgressIPv6Any-::/0 (CIDR)

    Note: It highly discouraged to run any production environment with source. Production environments should have MicroBOSH deployed without a floating IP on the private subnet.

Allocate a floating IP address

  1. Select Access & Security from the left navigation panel.

  2. Select the Floating IPs tab.

  3. Click Allocate IP to Project.

  4. Select External from the Pool dropdown menu.

  5. Click Allocate IP.

  6. Replace FLOATING-IP in your deployment manifest with the allocated Floating IP Address.

Step 3: Download a Stemcell

  1. Install the BOSH Command Line Interface (CLI).

  2. In a terminal window, run bosh public stemcells from your deployment directory to view a list of publicly available stemcells. The list displays the most recent build of each flavor.

    $ bosh public stemcells
    | Name                                                           |
    | bosh-stemcell-2751-openstack-kvm-ubuntu-trusty-go_agent.tgz    |
    | bosh-stemcell-2751-openstack-kvm-centos-go_agent.tgz           |
                        ... older stemcells ...
  3. Run bosh download public stemcell STEMCELL-NAME to download an OpenStack stemcell.

    BOSH stemcell names include the type, BOSH build number, target IaaS and hypervisior, and underlying operating system.

    $ bosh download public stemcell bosh-stemcell-2751-openstack-kvm-ubuntu-trusty-go_agent.tgz

Step 4: Deploy MicroBOSH

  1. In a terminal window, run bosh micro deployment microbosh.yml from your deployment directory to instruct MicroBOSH to use your manifest file.

    $ cd ~/my-micro-deployment
    $ bosh micro deployment manifest.yml
    WARNING! Your target has been changed to!
    Deployment set to ~/my-micro-deployment/manifest.yml

    Note: BOSH displays a red WARNING! message. This is not an error message.

  2. Run bosh micro deploy STEMCELL-NAME to deploy MicroBOSH.

    Note: BOSH may displays a red No bosh-deployments.yml file found message. If prompted to allow MicroBOSH to the save state in the current directory, type yes.

    $ bosh micro deploy bosh-stemcell-2751-openstack-kvm-ubuntu-trusty-go_agent.tgz
    No 'bosh-deployments.yml' file found in current directory.
    Is ~/my-micro-deployment a directory where you can save state? (type 'yes' to continue): yes
    Deploying new micro BOSH instance ~/my-micro-deployment/manifest.yml to '' (type 'yes' to continue): yes
      Started deploy micro bosh
      Done deploy micro bosh
    Deployed '~/my-micro-deployment/manifest.yml' to '', took 00:04:51 to complete
  3. Use bosh target FLOATING-IP-ADDRESS to log into your new MicroBOSH server. The default username and password are admin and admin.

    $ bosh target
    Target set to 'microbosh'
    Your username: admin
    Enter password: *****
    Logged in as 'admin'
    $ bosh vms
    No deployments


If the deployment fails, run bosh micro delete, then deploy again.

If an API Key error message appears, check the accuracy of the OPENSTACK-PASSWORD in the deployment manifest.

If other error messages appear:

  • Check your deployment manifest for typographical or formatting errors.
  • Review your OpenStack configuration.

Back to Table of Contents

Previous: Bootstrapping an environment