Skip to content


This document shows how to initialize new environment on OpenStack.

Step 1: Prepare an OpenStack environment


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


    Juno has a bug that prevents BOSH to assign specific IPs to VMs. You have to apply a Nova patch to avoid this problem.

  2. The following OpenStack services:

    • Identity: BOSH authenticates credentials and retrieves the endpoint URLs for other OpenStack services.
    • Compute: BOSH boots new VMs, assigns floating IPs to VMs, and creates and attaches volumes to VMs.
    • Image: BOSH stores stemcells using the Image service.
    • (Optional) OpenStack Networking: Provides network scaling and automated management functions that are useful when deploying complex distributed systems. Note: OpenStack networking is used as default as of v28 of the OpenStack CPI. To disable the use of the OpenStack Networking project, see using nova-networking.
  3. The following OpenStack networks:

    • An external network with a subnet.
    • An private network with a subnet. The subnet must have an IP address allocation pool.
  4. Configuration of a new OpenStack Project

    1. Automated configuration

      You can use a Terraform enviroment template to configure your OpenStack project.

    2. Manual configuration


      See the OpenStack documentation for help finding more information.

      Alternatively, you can do the following things manually as described below: * Create a Keypair. * Create and configure Security Groups. * Allocate a floating IP address.

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 "bosh" and click Create Keypair.


  5. Save the bosh.pem file to ~/Downloads/bosh.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:


    It highly discouraged to run any production environment with source or to make any BOSH management ports publicly accessible.

    Direction Ether Type IP Protocol Port Range Remote Purpose
    IngressIPv4TCP220.0.0.0/0 (CIDR)SSH access from CLI
    IngressIPv4TCP68680.0.0.0/0 (CIDR)BOSH Agent access from CLI
    IngressIPv4TCP255550.0.0.0/0 (CIDR)BOSH Director access from CLI
    EgressIPv4Any- (CIDR)
    EgressIPv6Any-::/0 (CIDR)
    IngressIPv4TCP1-65535boshManagement and data access

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 2: Deploy

  1. Install CLI v2.

  2. Use bosh create-env command to deploy the Director.

    # Create directory to keep state
    $ mkdir bosh-1 && cd bosh-1
    # Clone Director templates
    $ git clone
    # Fill below variables (replace example values) and deploy the Director
    $ bosh create-env bosh-deployment/bosh.yml \
        --state=state.json \
        --vars-store=creds.yml \
        -o bosh-deployment/openstack/cpi.yml \
        -v director_name=bosh-1 \
        -v internal_cidr= \
        -v internal_gw= \
        -v internal_ip= \
        -v auth_url=test \
        -v az=test \
        -v default_key_name=test \
        -v default_security_groups=[test] \
        -v net_id=test \
        -v openstack_password=test \
        -v openstack_username=test \
        -v openstack_domain=test \
        -v openstack_project=test \
        -v private_key=test \
        -v region=test

    If running above commands outside of an OpenStack network, refer to Exposing environment on a public IP for additional CLI flags.

    See OpenStack CPI errors for list of common errors and resolutions.

  3. Connect to the Director.

    # Configure local alias
    $ bosh alias-env bosh-1 -e --ca-cert <(bosh int ./creds.yml --path /director_ssl/ca)
    # Log in to the Director
    $ export BOSH_CLIENT=admin
    $ export BOSH_CLIENT_SECRET=`bosh int ./creds.yml --path /admin_password`
    # Query the Director for more info
    $ bosh -e bosh-1 env
  4. Save the deployment state files left in your deployment directory bosh-1 so you can later update/delete your Director. See Deployment state for details.