init-openstack.html.md.erb

---
title: Initializing BOSH environment on OpenStack
---

This document shows how to initialize new [environment](terminology.html#environment) on OpenStack.

## <a id="create-manifest"></a>Step 1: Create a Deployment Manifest

1. Create a deployment directory.

    <pre class='terminal'>
    $ mkdir ~/my-bosh
    </pre>

1. Create a deployment manifest file named `bosh.yml` in the deployment directory based on the template below.

    In the template, you must replace the `NETWORK-UUID`, `PRIVATE-IP`, `PRIVATE-CIDR`, `PRIVATE-GATEWAY-IP`, `DNS-IP`, `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](#prepare-openstack).

    <p class="note"><strong>Note</strong>: The example below uses several predefined passwords. We recommend replacing them with passwords of your choice.</p>

<pre>
---
name: bosh

releases:{{ range .Releases }}
- name: {{ .Name }}
  url: {{ .UserVisibleDownloadURL }}
  sha1: {{ .TarballSHA1 }}{{ end }}

resource_pools:
- name: vms
  network: private
  stemcell:
    url: https://bosh.io/d/stemcells/bosh-openstack-kvm-ubuntu-trusty-go_agent?v=3012
    sha1: e92f3bd5081301652005bdc3dd11bff545a304ef
  cloud_properties:
    instance_type: m1.xlarge

disk_pools:
- name: disks
  disk_size: 20_000

networks:
- name: private
  type: manual
  subnets:
  - range: PRIVATE-CIDR # <--- Replace with a private subnet CIDR
    gateway: PRIVATE-GATEWAY-IP # <--- Replace with a private subnet's gateway
    dns: [DNS-IP] # <--- Replace with your DNS
    cloud_properties: {net_id: NETWORK-UUID} # <--- # Replace with private network UUID
- name: public
  type: vip

jobs:
- name: bosh
  instances: 1

  templates:
  - {name: nats, release: bosh}
  - {name: redis, release: bosh}
  - {name: postgres, release: bosh}
  - {name: blobstore, release: bosh}
  - {name: director, release: bosh}
  - {name: health_monitor, release: bosh}
  - {name: registry, release: bosh}
  - {name: openstack_cpi, release: bosh-openstack-cpi}

  resource_pool: vms
  persistent_disk_pool: disks

  networks:
  - name: private
    static_ips: [PRIVATE-IP] # <--- Replace with a private IP
    default: [dns, gateway]
  - name: public
    static_ips: [FLOATING-IP] # <--- Replace with a floating IP

  properties:
    nats:
      address: 127.0.0.1
      user: nats
      password: nats-password

    redis:
      listen_address: 127.0.0.1
      address: 127.0.0.1
      password: redis-password

    postgres: &db
      listen_address: 127.0.0.1
      host: 127.0.0.1
      user: postgres
      password: postgres-password
      database: bosh
      adapter: postgres

    registry:
      address: PRIVATE-IP # <--- Replace with a private IP
      host: PRIVATE-IP # <--- Replace with a private IP
      db: *db
      http: {user: admin, password: admin, port: 25777}
      username: admin
      password: admin
      port: 25777

    blobstore:
      address: PRIVATE-IP # <--- Replace with a private IP
      port: 25250
      provider: dav
      director: {user: director, password: director-password}
      agent: {user: agent, password: agent-password}

    director:
      address: 127.0.0.1
      name: my-bosh
      db: *db
      cpi_job: openstack_cpi
      max_threads: 3
      user_management:
        provider: local
        local:
          users:
          - {name: admin, password: admin}
          - {name: hm, password: hm-password}

    hm:
      director_account: {user: hm, password: hm-password}
      resurrector_enabled: true

    openstack: &openstack
      auth_url: IDENTITY-API-ENDPOINT # <--- Replace with 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 OpenStack password
      default_key_name: bosh
      default_security_groups: [bosh]

    agent: {mbus: "nats://nats:nats-password@PRIVATE-IP:4222"} # <--- Replace with a private IP

    ntp: &ntp [0.pool.ntp.org, 1.pool.ntp.org]

cloud_provider:
  template: {name: openstack_cpi, release: bosh-openstack-cpi}

  ssh_tunnel:
    host: FLOATING-IP # <--- Replace with a floating IP
    port: 22
    user: vcap
    private_key: ./bosh.pem # Path relative to this manifest file

  mbus: "https://mbus:mbus-password@FLOATING-IP:6868" # <--- Replace with a floating IP

  properties:
    openstack: *openstack
    agent: {mbus: "https://mbus:mbus-password@0.0.0.0:6868"}
    blobstore: {provider: local, path: /var/vcap/micro_bosh/data/cache}
    ntp: *ntp
</pre>

---
## <a id="prepare-openstack"></a>Step 2: Prepare an OpenStack environment

### <a id="prerequisites"></a> Prerequisites

1. An OpenStack environment running one of the following supported releases:
    * [Icehouse](http://www.openstack.org/software/icehouse)
    * [Juno](http://www.openstack.org/software/juno)
    * [Kilo](http://www.openstack.org/software/kilo)

    <p class="note">Note: Juno has a <a href="https://bugs.launchpad.net/nova/+bug/1396854">bug</a> that prevents BOSH to assign specific IPs to VMs. You have to apply a Nova patch to avoid this problem.</p>

1. The following OpenStack services:
    * [Identity](http://www.openstack.org/software/openstack-shared-services/):
        BOSH authenticates credentials and retrieves the endpoint URLs for other OpenStack services.
    * [Compute](http://www.openstack.org/software/openstack-compute/):
        BOSH boots new VMs, assigns floating IPs to VMs, and creates and attaches volumes to VMs.
    * [Image](http://www.openstack.org/software/openstack-shared-services/):
        BOSH stores stemcells using the Image service.
    * **(Optional)** [OpenStack Networking](http://www.openstack.org/software/openstack-networking/):
        Provides network scaling and automated management functions that are useful when deploying complex distributed systems.

1. 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.

1. A new OpenStack project.

<p class="note"><strong>Note</strong>: See the <a href="http://docs.openstack.org/">OpenStack documentation</a> for help finding more information.</p>


You need to prepare your OpenStack project for deploying BOSH:
* Create a [Keypair](#keypair).
* Create and configure [Security Groups](#security-groups).
* Allocate a [floating IP address](#floating-ip).

You can achieve this in two ways:
* use the [Terraform enviroment template](https://github.com/cloudfoundry-incubator/bosh-openstack-environment-templates/tree/master/bosh-init-tf)
* use the OpenStack GUI to perform the steps described below manually

---
### <a id="keypair"></a>Create a Keypair

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

1. Select the **Keypairs** tab.

    <%= image_tag("images/micro-openstack/keypair.png") %>

1. Click **Create Keypair**.

1. Name the Keypair "bosh" and click **Create Keypair**.

    <%= image_tag("images/micro-openstack/create-keypair.png") %>

1. Save the `bosh.pem` file.

    <%= image_tag("images/micro-openstack/save-keypair.png") %>

1. Move the `bosh.pem` file into your deployment directory. For example, on UNIX run this command:

    <pre class="terminal">
    $ mv ~/Downloads/bosh.pem ~/my-bosh/bosh.pem
    </pre>

---
### <a id="security-groups"></a>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.

1. Select the **Security Groups** tab.

    <%= image_tag("images/micro-openstack/security-groups.png") %>

1. Click **Create Security Group**.

1. Name the security group "bosh" and add the description "BOSH Security Group"

    <%= image_tag("images/micro-openstack/create-bosh-sg.png") %>

1. Click **Create Security Group**.

1. Select the BOSH Security Group and click **Edit Rules**.

1. Click **Add Rule**.

    <%= image_tag("images/micro-openstack/edit-bosh-sg.png") %>

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

    <p class="note"><strong>Note</strong>: It highly discouraged to run any production environment with <code>0.0.0.0/0</code> source or to make any BOSH management ports publicly accessible.</p>

    <table border="1" class="nice" >
      <tr>
        <th>Direction</th>
        <th>Ether Type</th>
        <th>IP Protocol</th>
        <th>Port Range</th>
        <th>Remote</th>
        <th>Purpose</th>
      </tr>

      <tr><td>Ingress</td><td>IPv4</td><td>TCP</td><td>22</td><td>0.0.0.0/0 (CIDR)</td><td>SSH access from bosh-init</td></tr>
      <tr><td>Ingress</td><td>IPv4</td><td>TCP</td><td>6868</td><td>0.0.0.0/0 (CIDR)</td><td>BOSH Agent access from bosh-init</td></tr>
      <tr><td>Ingress</td><td>IPv4</td><td>TCP</td><td>25555</td><td>0.0.0.0/0 (CIDR)</td><td>BOSH Director access from CLI</td></tr>

      <tr><td>Egress</td><td>IPv4</td><td>Any</td><td>-</td><td>0.0.0.0/0 (CIDR)</td></tr>
      <tr><td>Egress</td><td>IPv6</td><td>Any</td><td>-</td><td>::/0 (CIDR)</td></tr>

      <tr><td>Ingress</td><td>IPv4</td><td>TCP</td><td>1-65535</td><td>bosh</td><td>Management and data access</td></tr>
    </table>

---
### <a id="floating-ip"></a>Allocate a floating IP address

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

1. Select the **Floating IPs** tab.

    <%= image_tag("images/micro-openstack/create-floating-ip.png") %>

1. Click **Allocate IP to Project**.

1. Select **External** from the **Pool** dropdown menu.

1. Click **Allocate IP**.

    <%= image_tag("images/micro-openstack/allocate-ip.png") %>

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

    <%= image_tag("images/micro-openstack/floating-ip.png") %>

---
## <a id="deploy"></a> Step 3: Deploy

1. Install [bosh-init](./install-bosh-init.html).

1. Run `bosh-init deploy ./bosh.yml` to start the deployment process.

    <pre class='terminal'>
    $ bosh-init deploy ./bosh.yml
    ...
    </pre>

    See [OpenStack CPI errors](openstack-cpi.html#errors) for list of common errors and resolutions.

1. Install the [BOSH Command Line Interface (CLI)](./bosh-cli.html).

1. Use `bosh target FLOATING-IP-ADDRESS` to log into your new BOSH Director. The default username and password are `admin` and `admin`.

    <pre class="terminal">
    $ bosh target 173.81.16.12

    Target set to 'bosh'
    Your username: admin
    Enter password: *****
    Logged in as 'admin'

    $ bosh vms

    No deployments
    </pre>

1. Save the deployment state file left in your deployment directory so you can later update/delete your Director. See [Deployment state](using-bosh-init.html#deployment-state) section of 'Using bosh-init' for more details.

---
[Back to Table of Contents](index.html#install)

Previous: [Bootstrapping an environment](init.html)