create-micro-manifest.html.md.erb

---
title: Creating a MicroBOSH Deployment Manifest
---

<p class="note">Note: Micro CLI plugin is deprecated, but is still supported. To set up a new Director VM or upgrade your MicroBOSH, please follow <a href="/docs/init.html">Bootstrapping an environment</a> document.</p>

The deployment manifest for MicroBOSH is similar to the deployment manifest for
multi-VM BOSH.

Parts of the manifest are IaaS-specific.
Refer to the example for the IaaS you plan to use:

* [AWS](#ex-aws)
* [OpenStack](#ex-openstack)
* [vSphere](#ex-vsphere)

## <a id="anatomy"></a> Anatomy of a Manifest ##

Begin the BOSH deployment manifest with three dashes, followed by your name for
the deployment.

For example:

<pre class="terminal">
---
name: microbosh-test
</pre>

After that, there are five required _blocks_:

* [logging](#logging)
* [network](#network)
* [resources](#resources)
* [cloud](#cloud)
* [apply_spec](#apply)

The manifest is in YAML, so the YAML parser translates each block into a hash.
For this reason, you can put the blocks in any order.

### <a id='logging'></a> The logging block ###

Logging should normally be set to `debug`.
Other valid levels are `info` (the default), `warn`, and `error`.
You can also specify the file to which MicroBOSH writes logs.

<pre class="terminal">
logging:
  # If needed increase the default logging level to trace REST traffic with IaaS providers. Default is info
  level: debug
  # Default location is &lt;deployment_directory&gt;/bosh_micro_deploy.log
  # file:
</pre>

### <a id='network'></a> The network block ###

You specify network configuration information for the deployment in the `network` block.

<p class="note"><strong>Note</strong>: In a multi-VM BOSH deployment manifest, this block is named <code>networks</code>.</p>

The `type` attribute can be set to either of two values:

* `dynamic` means that DHCP is used to assign the MicroBOSH VM an IP address.
* `manual` means that you set the IP address for the MicroBOSH VM, in the manifest.

The `dns` sub-block is for nameservers you want the operating system of the
MicroBOSH VM to use in resolving domain names that internal MicroBOSH nameserver
cannot resolve.
The nameservers are written to the `/etc/resolv.conf` file.
MicroBOSH components could use them to resolve IaaS FQDNs, for example.

The optional `vip` attribute allows you to assign a floating IP address to the
MicroBOSH VM.
Then you can access the VM from outside of the its network.
If set, `allocated_floating_ip` **must** be a floating IP that was allocated before you deploy.

<p class="note"><strong>Note</strong>: The <code>vip</code> and <code>allocated_floating_ip</code> attributes exist in AWS and
OpenStack but not in vSphere.</p>

The `network` sub-block is IaaS-dependent, because subnets, and other
keys may differ from IaaS to IaaS.

For example:

<pre class="terminal">
network:
  type: manual
  subnets:
  - range: 10.10.0.0/24
    gateway: 10.10.0.1
    static:
    - 10.10.0.7 - 10.10.0.9
    reserved:
    - 10.10.0.2 - 10.10.0.6
    - 10.10.0.10 - 10.10.0.10
    dns:
    - 10.10.0.6
    cloud_properties:
      subnet: subnet-d597b993
</pre>

### <a id='resources'></a> The resources block ###

The resources block specifies the size of a persistent disk to be created and
attached to the MicroBOSH VM.
MicroBOSH stores its data on the persistent disk such that no data is lost when
the VM is restarted or when you update MicroBOSH.

`persistent_disk` is specified in megabytes.
For example, a value of `16384` equates to 16 Gigabytes.

Persistent disk differs from ephemeral disk, that is, the disk space allocated
to the MicroBOSH VM.

Next comes the `cloud_properties` sub-block, whose content varies from IaaS to IaaS.

For example:

<pre class="terminal">
resources:
   persistent_disk: 16384
   cloud_properties:
      ram: 8192
      disk: 16384
      cpu: 4
</pre>

### <a id='cloud'></a> The cloud block ###

The cloud block specifies the IaaS you want to use, in the `plugin` attribute.
Next comes the `properties` sub-block, whose content differs from IaaS to IaaS.

For example:

<pre class="terminal">
cloud:
  plugin: openstack
  properties:
    openstack:
      auth_url: http://&lt;identity_server&gt;:5000/v2.0
      username: &lt;username&gt;
      api_key: &lt;password&gt;
      tenant: &lt;tenant&gt;
      region: &lt;region&gt; # Optional
      default_security_groups: ["ssh", "bosh"]
      default_key_name: &lt;microbosh_keypair&gt;
      private_key: &lt;path_to_microbosh_keypar_private_key&gt;
</pre>

### <a id='apply'></a> The apply_spec block ###

The content of the `apply_spec` block varies from IaaS to IaaS.

In this block you specify configuration information for MicroBOSH components
like the Director and the Health Monitor, as well as for elements of
infrastructure like the vCenter in vSphere.

MicroBOSH has a nameserver component called `powerDNS`.
If, after you deploy MicroBOSH, you use it deploy other software, MicroBOSH will
create VMs as it deploys that software.
VMs that MicroBOSH creates use the powerDNS on their parent VM to resolve IP
addresses.

In the `dns` sub-block of the `apply_spec` block, you specify the IP of the
nameserver, or recursor, that powerDNS should use to resolve names external to
its domain.

For example:

<pre class="terminal">
apply_spec:
  properties:
    director:
      max_threads: 3
    hm:
      resurrector_enabled: true
    ntp:
      - 0.north-america.pool.ntp.org
      - 1.north-america.pool.ntp.org
    dns:
      recursor: &lt;ip_for_dns&gt;
</pre>

## <a id="creating"></a> How to Create a Manifest ##

You can modify example manifests to suit your purposes.
Another approach is to use a tool like
[spiff](https://github.com/cloudfoundry-incubator/spiff) to create a manifest.

## <a id="examples"></a> Example Manifests ##

These examples are designed to illuminate what each IaaS requires in a MicroBOSH deployment manifest.

### <a id="ex-aws"></a> AWS ###

You can adapt this example to your environment settings.

You will need the "Elastic IP" address for the MicroBOSH VM.
This was configured when you set up AWS for MicroBOSH.

~~~yaml
name: microbosh-aws

logging:
  # If needed increase the default logging level to trace REST traffic with IaaS providers. Default is info
  level: debug
  # Default location is deployment_dir>/bosh_micro_deploy.log
  # file :

network:
  type: dynamic
  vip: <elastic_ip_for_microbosh_vm>

resources:
  persistent_disk: 20000
  cloud_properties:
    instance_type: m1.small
    availability_zone: us-east-1a

cloud:
  plugin: aws
  properties:
    aws:
      access_key_id: <access_key_id>
      secret_access_key: <secret_access_key>
      default_key_name: bosh
      default_security_groups: ["bosh"]
      ec2_private_key: ~/.ssh/bosh
      ec2_endpoint: ec2.us-east-1.amazonaws.com
      region: us-east-1

apply_spec:
  agent:
    blobstore:
      address: <elastic_ip_for_microbosh_vm>
    nats:
      address: <elastic_ip_for_microbosh_vm>
  properties:
    registry:
      address: <elastic_ip_for_microbosh_vm>
~~~

### <a id="ex-openstack"></a> OpenStack ###

You can adapt this example to your environment settings.

~~~yaml
---
name: microbosh-openstack

logging:
  # If needed increase the default logging level to trace REST traffic with IaaS providers. Default is info
  level: debug
  # Default location is <deployment_dir>/bosh_micro_deploy.log
  # file :

network:
  type: manual
  vip: <allocated_floating_ip> # Optional
  ip: <tatic_ip>
  cloud_properties:
    net_id: <network_uuid>

resources:
  persistent_disk: 16384
  cloud_properties:
    instance_type: <flavor_name>

cloud:
  plugin: openstack
  properties:
    openstack:
      auth_url: http://<identity_server>:5000/v2.0
      username: <username>
      api_key: <password>
      tenant: <tenant>
      region: <region> # Optional
      default_security_groups: ["ssh", "bosh"]
      default_key_name: <microbosh_keypair>
      private_key: <path_to_microbosh_keypar_private_key>

apply_spec:
  properties:
    director:
      max_threads: 3
    hm:
      resurrector_enabled: true
    ntp:
      - 0.north-america.pool.ntp.org
      - 1.north-america.pool.ntp.org
~~~

#### <a id="openstack-nw"></a>OpenStack networking options ####

If you are using nova-network, the network block takes the following form:

~~~yaml
network:
  type: dynamic
  vip: <allocated_floating_ip> # Optional
~~~


If you are using the [OpenStack Networking](http://www.openstack.org/software/openstack-networking/) component,
the network block takes one of two forms, depending on whether you specify
dynamic or manual networking.

In both cases, use the `net_id` attribute to set the `network_uuid` of the
OpenStack network you want to use.
You must use an existing Network UUID.
You can list your OpenStack networks using the command `neutron net-list`.

For dynamic networking, the network block takes the following form:

~~~yaml
network:
  type: dynamic
  vip: <allocated_floating_ip> # Optional
  cloud_properties:
    net_id: <network_uuid>
~~~


For manual networking, the network block takes the following form:

~~~yaml
network:
  type: manual
  vip: <allocated_floating_ip> # Optional
  ip: <static_ip>
  cloud_properties:
    net_id: <network_uuid>
~~~

<p class="note"><strong>Note</strong>: Manual networking requires you to set the IP address of the MicroBOSH VM.
The IP address you choose must be within the IP range of a subnet set of the
network specified in <code>net_id</code>.</p>

#### <a id="flavors"></a>OpenStack flavors ####

OpenStack describes VMs in terms of flavors.
You specify the flavor in the `instance_type` attribute of the
`cloud_properties` sub-block of the `resources` block.
Choose a flavor that has some ephemeral disk.

~~~yaml
resources:
  persistent_disk: 16384
  cloud_properties:
    instance_type: <flavor_name>
~~~

#### <a id="openstack-cloud-props"></a>OpenStack cloud properties ####

The `properties` sub-block of the `cloud` block is where you set the following OpenStack configuration information:

* `auth_url` is the [OpenStack identity](http://www.openstack.org/software/openstack-shared-services/) server.
* `username`, `api_key` and `tenant` are your OpenStack credentials.
* `region` is the OpenStack region (optional).
* `default_security_groups` sets the security groups used by MicroBOSH. These security groups must exist before deployment.
* `default_key_name` and `private_key` are the key pair used by MicroBOSH. This keypair must exist before deployment.

~~~yaml
cloud:
  plugin: openstack
  properties:
    openstack:
      auth_url: http://<identity_server>:5000/v2.0
      username: <username>
      api_key: <password>
      tenant: <tenant>
      region: <region> # Optional
      default_security_groups: ["default", <microbosh_security_group>]
      default_key_name: <microbosh_keypair>
      private_key: <path_to_microbosh_keypar_private_key>
~~~

### <a id="ex-vsphere"></a> vSphere ###

You can adapt this example to your environment settings.

~~~yaml
---
name: microbosh-vsphere

logging:
  # If needed increase the default logging level to trace REST traffic with IaaS providers. Default is info
  level: debug
  # Default location is <deployment_dir>/bosh_micro_deploy.log
  # file :

network:
  ip: <ip_address_you_want_for_microbosh>
  netmask: <netmask_for_the_subnet_you_are_deploying_to>
  gateway: <gateway_for_the_subnet_you_are_deploying_to>
  dns:
  # The MicroBOSH VM has the following DNS entries in its /etc/resolv.conf, allowing it to resolve, for example, IaaS FQDNs.
  - <ip_for_dns>
  cloud_properties:
    name: <network_name_according_to_vsphere>

resources: # this seems like good sizing for microbosh
   persistent_disk: 16384
   cloud_properties:
      ram: 8192
      disk: 16384
      cpu: 4
cloud:
  plugin: vsphere
  properties:
    agent:
      ntp:
        - <ntp_host_1>
        - <ntp_host_2>
     vcenters:	# here, list all vCenters that you want MicroBOSH to know about
       - host: <vcenter_ip>
         user: <vcenter_userid>
         password: <vcenter_password>
         datacenters:
           - name: <datacenter_name>
             vm_folder: <vm_folder_name>
             template_folder: <template_folder_name>
             disk_path: <subdir_to_store_disks>
             datastore_pattern: <data_store_pattern>
             persistent_datastore_pattern: <persistent_datastore_pattern>
             allow_mixed_datastores: <true_if_persistent_datastores_and_datastore_patterns_are_the_same>
             clusters:
             - <cluster_name>:
                 resource_pool: <resource_pool_name_optional>

apply_spec:
  properties:
    vcenter:	# here, specify the vCenter where you want MicroBOSH to run
      host: <vcenter_ip>
      user: <vcenter_userid>
      password: <vcenter_password>
      datacenters:
        - name: <datacenter_name>
          vm_folder: <vm_folder_name>
          template_folder: <template_folder_name>
          disk_path: <subdir_to_store_disks>
          datastore_pattern: <data_store_pattern>
          persistent_datastore_pattern: <persistent_datastore_pattern>
          allow_mixed_datastores: <true_if_persistent_datastores_and_datastore_patterns_are_the_same>
          clusters:
          - <cluster_name>:
              resource_pool: <resource_pool_name_optional>
    dns:
        # The BOSH powerDNS contacts the following DNS server for serving DNS entries from other domains.
        recursor: <ip_for_dns>

~~~

#### <a id="datastore"></a> Configuring Datastores in vSphere  ####

The `datastore_pattern` attribute can either be the name of a datastore or a
regular expression that matches one or more datastore names.

If you want to use a datastore called "vc\_data\_store\_1" for both persistent
and ephemeral disks, use the following configuration:

~~~yaml
               datastore_pattern: vc_data_store_1
               persistent_datastore_pattern:  vc_data_store_1
               allow_mixed_datastores: true
~~~

If you want to use two datastores, called "vc\_data\_store\_1" and
"vc\_data\_store\_2", for both persistent and ephemeral disks, use the following
configuration:

~~~yaml
               datastore_pattern: vc_data_store_?
               persistent_datastore_pattern:  vc_data_store_?
               allow_mixed_datastores: true
~~~

If you want to use two datastores, named "vnx:1" and "vnx:2", and you want to
separate your persistent and ephemeral disks, use the following configuration:

~~~yaml
               datastore_pattern: vnx:1
               persistent_datastore_pattern: vnx:2
               allow_mixed_datastores: false
~~~