This topic explains how to deploy MicroBOSH to OpenStack.

Note: Micro CLI plugin is deprecated, but is still supported. To set up a new Director VM or upgrade your MicroBOSH, please follow Initializing on OpenStack document.

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
    Ingress IPv4 TCP 1-65535 bosh
    Ingress IPv4 TCP 25777 (CIDR)
    Ingress IPv4 TCP 25555 (CIDR)
    Ingress IPv4 TCP 25250 (CIDR)
    Ingress IPv4 TCP 6868 (CIDR)
    Ingress IPv4 TCP 4222 (CIDR)
    Ingress IPv4 UDP 68 (CIDR)
    Ingress IPv4 TCP 53 (CIDR)
    Ingress IPv4 UDP 53 (CIDR)
    Ingress IPv4 TCP 22 (CIDR)
    Egress IPv4 Any - (CIDR)
    Egress IPv6 Any - ::/0 (CIDR)

    Note: Production environments should have MicroBOSH deployed without a floating IP address on the private subnet. We highly recommend against running any production environment with source IP addresses.

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. Open in a web browser to view a list of publicly available BOSH stemcells. The list displays the most recent build numbers of BOSH stemcells, organized by operating system, target IaaS, and hypervisor.

  2. Choose a BOSH stemcell for OpenStack and click the build number to download.

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-3012-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

Contribute changes to this page