deployment-manifest.html.md.erb

---
title: Deployment Manifest Schema
---

<p class="note">Note: Once you opt into using cloud config all deployments must be converted to use manifest v2 format that disallows IaaS specific configuration. See <a href="manifest-v2.html">manifest v2 schema</a> for allowed configurations. v257+ supports deploying both v1 and v2 manifests to the same director.</p>

The deployment manifest is a YAML file that defines the components and properties of the deployment. When an operator initiates a new deployment using the CLI, the Director receives a version of the deployment manifest and creates a new deployment using this manifest.

Contents of a deployment manifest:

* [Deployment Identification](#deployment): A name for the deployment and the UUID of the Director managing the deployment
* [Releases Block](#releases): Name and version of each release in a deployment
* [Networks Block](#networks): Network configuration information
* [Resource Pools Block](#resource-pools): Properties of VMs that BOSH creates and manages
* [Disk Pools Block](#disk-pools): Properties of disk pools that BOSH creates and manages
* [Compilation Block](#compilation): Properties of compilation VMs
* [Update Block](#update): Defines how BOSH updates job instances during deployment
* [Jobs Block](#jobs): Configuration and resource information for jobs
* [Properties Block](#properties): Describes global properties and generalized configuration information

The examples below originate from a [sample deployment manifest](./sample-manifest.html).

---
## <a id='deployment'></a>Deployment Identification

**name** [String, required]: The name of the deployment. A single Director can manage multiple deployments and distinguishes them by name.

**director_uuid** [String, required]: This string must match the UUID of the currently targeted Director for the CLI to allow any operations on the deployment. Use `bosh status` to display the UUID of the currently targeted Director.

Example:

```yaml
name: my-redis-deployment

director_uuid: cf8dc1fc-9c42-4ffc-96f1-fbad983a6ce6
```

---
## <a id='releases'></a>Releases Block

**releases** [Array, required]: The name and version of each release in the deployment.

* **name** [String, required]: Name of a release used in the deployment.
* **version** [String, required]: The version of the release to use. Version can be `latest`.

Example:

```yaml
releases:
- {name: redis, version: 12}
```

### <a id='bosh-init-releases'></a> Custom bosh-init Releases Block

**releases** [Array, required]: The name, url and possibly SHA1 of each release in the deployment.

* **name** [String, required]: Name of a release used in the deployment.
* **url** [String, required]: URL of the release to use. URL may use the file protocol (`file://`) or HTTP(s) (`http(s)://`). File URLs can be absolute or relative to the current directory of `bosh-init` execution.
* **sha1** [String, required]: The SHA1 of the release tarball. SHA1 is only required when using HTTP(s) URLs.

Example:

```yaml
releases:
- name: bosh
  url: https://bosh.io/d/github.com/cloudfoundry/bosh?v=158
  sha1: a97811864b96bee096477961b5b4dadd449224b4
- name: bosh-aws-cpi
  url: file://bosh-aws-cpi-release-158.tgz
```

---
## <a id='networks'></a>Networks Block

**networks** [Array, required]: Each sub-block listed in the Networks block specifies a network configuration that jobs can reference. There are three different network types: `manual`, `dynamic`, and `vip`.

See [networks](networks.html) for more details.

### <a id='networks-cloud-properties'></a> CPI Specific `cloud_properties`

- [See AWS CPI network cloud properties](aws-cpi.html#networks)
- [See Azure CPI network cloud properties](azure-cpi.html#networks)
- [See OpenStack CPI network cloud properties](openstack-cpi.html#networks)
- [See vSphere CPI network cloud properties](vsphere-cpi.html#networks)
- [See vCloud CPI network cloud properties](vcloud-cpi.html#networks)

---
## <a id='resource-pools'></a>Resource Pools Block

**resource_pools** [Array, required]: Specifies the [resource pools](./terminology.html#resource-pool) a deployment uses. A deployment manifest can describe multiple resource pools and uses unique names to identify and reference them.

* **name** [String, required]: A unique name used to identify and reference the resource pool
* **network** [String, required]: References a valid network name defined in the Networks block. Newly created resource pool VMs use the described configuration.
* **size** [Integer, optional]: The number of VMs in the resource pool. If you omit this value, BOSH calculates the resource pool size based on the total number of job instances that belong to this resource pool. If you specify this value, BOSH requires that the size be at least as large as the total number of job instances using it.
* **stemcell** [Hash, required]: The stemcell used to create resource pool VMs.
    * **name** [String, required]: The stemcell name
    * **version** [String, required]: The stemcell version
* **cloud_properties** [Hash, optional]: Describes any IaaS-specific properties needed to create VMs. Most IaaSes require this. See [CPI Specific `cloud_properties`](#resource-pools-cloud-properties) below. Examples: `instance_type`, `availability_zone`. Default is `{}` (empty Hash).
* **env** [Hash, optional]: Describes the VM environment and provides a specific VM environment to the CPI `create_stemcell` call. `env` data is available to BOSH Agents as VM settings. Default is `{}` (empty Hash).

Example:

```yaml
resource_pools:
- name: redis-servers
  network: default
  stemcell:
    name: bosh-aws-xen-ubuntu-trusty-go_agent
    version: 2708
  cloud_properties:
    instance_type: m1.small
    availability_zone: us-east-1c
```

### <a id='bosh-init-stemcells'></a> Custom bosh-init Stemcell Key Schema

**stemcell** [Hash, required]: The stemcell used to create resource pool VMs.

  - **url** [String, required]: URL of the stemcell tarball. URL may use the file protocol (`file://`) or HTTP(s) (`http(s)://`). File URLs can be absolute or relative to the current directory of `bosh-init` execution.
  - **sha1** [String, required]: The SHA1 of the stemcell tarball. SHA1 is only required when using HTTP(s) URLs.

Example:

```yaml
resource_pools:
- name: redis-servers
  network: default
  stemcell:
    url: https://bosh.io/d/stemcells/bosh-aws-xen-ubuntu-trusty-go_agent?v=2950
    sha1: 6489bff150d1ecbd12fda30267896f041dd279f0
  cloud_properties:
    instance_type: m1.small
    availability_zone: us-east-1c
```

### <a id='resource-pools-cloud-properties'></a> CPI Specific `cloud_properties`

- [See AWS CPI resource pool cloud properties](aws-cpi.html#resource-pools)
- [See Azure CPI resource pool cloud properties](azure-cpi.html#resource-pools)
- [See OpenStack CPI resource pool cloud properties](openstack-cpi.html#resource-pools)
- [See vSphere CPI resource pool cloud properties](vsphere-cpi.html#resource-pools)
- [See vCloud CPI resource pool cloud properties](vcloud-cpi.html#resource-pools)

---
## <a id='disk-pools'></a>Disk Pools Block

**disk_pools** [Array, required]: Specifies the [disk pools](./terminology.html#disk-pools) a deployment uses. A deployment manifest can describe multiple disk pools and uses unique names to identify and reference them.

* **name** [String, required]: A unique name used to identify and reference the disk pool
* **disk_size** [Integer, required]: Specifies the disk size. `disk_size` must be a positive integer. BOSH creates a [persistent disk](./persistent-disks.html) of that size in megabytes and attaches it to each job instance VM.
* **cloud_properties** [Hash, optional]: Describes any IaaS-specific properties needed to create disks. Examples: `type`, `iops`. Default is `{}` (empty Hash).

Example:

```yaml
disk_pools:
- name: default
  disk_size: 2
  cloud_properties:
    type: gp2
```

### <a id='disk-pools-cloud-properties'></a> CPI Specific `cloud_properties`

- [See AWS CPI disk pool cloud properties](aws-cpi.html#disk-pools)
- [See Azure CPI disk pool cloud properties](azure-cpi.html#disk-pools)
- [See OpenStack CPI disk pool cloud properties](openstack-cpi.html#disk-pools)
- [See vSphere CPI disk pool cloud properties](vsphere-cpi.html#disk-pools)
- [See vCloud CPI disk pool cloud properties](vcloud-cpi.html#disk-pools)

---
## <a id='compilation'></a>Compilation Block

**compilation** [Hash, required]: Properties of compilation VMs.

* **workers** [Integer, required]: The maximum number of compilation VMs.
* **network** [String, required]: References a valid network name defined in the Networks block. BOSH assigns network properties to compilation VMs according to the type and properties of the specified network.
* **reuse\_compilation\_vms** [Boolean, optional]: If `false`, BOSH creates a new compilation VM for each new package compilation and destroys the VM when compilation is complete. If `true`, compilation VMs are re-used when compiling packages. Defaults to `false`.
* **cloud_properties** [Hash, optional]: Describes any IaaS-specific properties needed to create compilation VMs; for most IaaSes, some data here is actually required. For the Compilation Block, the required `cloud_properties` are the same as for Resource Pools; see the [CPI Specific `cloud_properties`](#resource-pools-cloud-properties) for Resource Pools. Examples: `instance_type`, `availability_zone`. Default is `{}` (empty Hash).

Example:

```yaml
compilation:
  workers: 2
  network: default
  reuse_compilation_vms: true
  cloud_properties:
    instance_type: c1.medium
    availability_zone: us-east-1c
```

---
## <a id='update'></a>Update Block

**update** [Hash, required]: This specifies instance update properties. These properties control how BOSH updates job instances during the deployment.

* **canaries** [Integer, required]: The number of [canary](./terminology.html#canary) instances.
* **max\_in\_flight** [Integer, required]: The maximum number of non-canary instances to update in parallel.
* **canary\_watch\_time** [Integer or Range, required]
    * If the `canary_watch_time` is an integer, the Director sleeps for that many milliseconds, then checks whether the canary instances are healthy.
    * If the `canary_watch_time` is a range (low-high), the Director:
        * Waits for `low` milliseconds
        * Waits until instances are healthy or `high` milliseconds have passed since instances started updating
* **update\_watch\_time** [Integer or Range, required]
    * If the `update_watch_time` is an integer, the Director sleeps for that many milliseconds, then checks whether the instances are healthy.
    * If the `update_watch_time` is a range (low-high), the Director:
        * Waits for `low` milliseconds
        * Waits until instances are healthy or `high` milliseconds have passed since instances started updating
* **serial** [Boolean, optional]: If disabled (set to `false`), deployment jobs will be deployed in parallel, otherwise - sequentially. Instances within a deployment job will still follow `canary` and `max_in_flight` configuration. Defaults to `true`.

Example:

```yaml
update:
  canaries: 1
  max_in_flight: 10
  canary_watch_time: 1000-30000
  update_watch_time: 1000-30000
```

---
## <a id='jobs'></a>Jobs Block

**jobs** [Array, required]: Specifies the mapping between BOSH release [jobs](./terminology.html#job) and cloud instances. Jobs are defined in the BOSH release. The Jobs block defines how BOSH associates jobs with the VMs started by the IaaS. The most commonly used job properties are:

* **name** [String, required]: A unique name used to identify and reference this  association between a BOSH release job and a VM.
* **templates** [Array, required]: Specifies the name and release of a job template.
  * **name** [String, required]: The job template name
  * **release** [String, required]: The release where the job template exists
* **lifecycle** [String, optional]: Specifies the kind of task the job represents. Valid values are `service` and `errand`; defaults to `service`. A `service` runs indefinitely and restarts if it fails. An `errand` starts with a manual trigger and does not restart if it fails.
* **persistent_disk** [Integer, optional]: Specifies the persistent disk size; defaults to 0 (no persistent disk). If `persistent_disk` is a positive integer, BOSH creates a persistent disk of that size in megabytes and attaches it to each job instance VM. [Read more about persistent disks](./persistent-disks.html)
* **properties** [Hash, optional]: Specifies job properties. Properties allow BOSH to configure jobs to a specific environment. `properties` defined in a Job block are accessible only to that job, and override any identically named global properties.
* **resource_pool** [String, required]: A valid resource pool name from the Resource Pools block. BOSH runs instances of this job in a VM from the named resource pool.
* **update** [Hash, optional]: Specific update settings for this job. Use this to override [global job update settings](#update) on a per-job basis.
* **instances** [Integer, required]: The number of job instances. Each instance is a VM running this particular job.
* **networks** [Array, required]: Specifies the networks this job requires. Each network can have the following properties specified:
  * **name** [String, required]: A valid network name from the Networks block
  * **static_ips** [Array, optional]: Array of IP addresses reserved for the job on the network
  * **default** [Array, optional]: Specifies which network components (DNS, Gateway) BOSH populates by default from this network. BOSH references this property if the Networks block defines multiple networks.

Example:

```yaml
jobs:
  - name: redis-master
    instances: 1
    templates:
    - {name: redis-server, release: redis}
    persistent_disk: 10_240
    resource_pool: redis-servers
    networks:
    - name: default

  - name: redis-slave
    instances: 2
    templates:
    - {name: redis-server, release: redis}
    persistent_disk: 10_240
    resource_pool: redis-servers
    networks:
    - name: default
```

---
## <a id='properties'></a>Properties Block

**properties** [Hash, optional]: Describes global properties and general configuration information.

Global properties allow BOSH to configure jobs to a specific environment. `properties` defined in the [Properties](#properties) block are accessible to all jobs. Any identically named `properties` in the [Jobs](#jobs) block will override the global property for that job.

By default, general configuration information resides in the template spec file of a job in a BOSH release. If you move this information from the release into the manifest, you can reconfigure a deployment by changing the manifest instead of the release. To do this, add the general configuration information to the manifest in a sub-block of the Properties block. The name of the job template identifies the sub-block.

Typical general configuration information includes but is not limited to:

* Passwords
* Account names
* Shared secrets
* Host names
* IP addresses
* Port numbers

Example:

```yaml
properties:
  redis:
    max_connections: 10
```

### <a id='properties'></a>Job Property Precedence

1. BOSH applies the properties in the template spec file to the job.
1. If an identically named property exists in the [Properties](#properties) block of the deployment manifest, the value of this property overrides the previous value.
1. If an identically named property exists in the Properties sub-block of the [Jobs](#jobs) block of the deployment manifest, the value of this property overrides all previous values.

<p class="note"><strong>Note</strong>: If you declare specific properties in a job template spec, BOSH ignores all other properties. If you do not declare any specific properties in a job template spec, BOSH applies all properties from the deployment manifest to the job. </p>

---
## <a id='cloud-provider'></a> Cloud Provider Block

**cloud_provider** [Hash, required]: Specifies CPI configuration for the `bosh-init` to create VMs, etc. Regular deployment manifests cannot specify this block.

* **template** [Hash, required]: Specifies the name of the CPI job and release where the CPI job exists. It will be used by the `bosh-init` to create VMs, persistent disks, etc.
  * **name** [String, required]: The CPI job name.
  * **release** [String, required]: The CPI release name.
* **mbus** [String, required]: HTTPs URL used by the `bosh-init` to contact the Agent on a created VM. The URL includes basic auth credentials that should be customized for each deployment. Example: `"https://mbus:mbus-password@10.0.0.6:6868"`.
* **properties** [Hash, required]: Properties required by the CPI job.

Example from [Initializing BOSH environment on vSphere](init-vsphere.html):

```yaml
cloud_provider:
  template: {name: cpi, release: bosh-vsphere-cpi}

  mbus: "https://mbus:mbus-password@10.0.0.6:6868"

  properties:
    vcenter: { ... }

    agent: {mbus: "https://mbus:mbus-password@0.0.0.0:6868"}

    blobstore:
      provider: local
      path: /var/vcap/micro_bosh/data/cache

    ntp:
    - 0.pool.ntp.org
    - 1.pool.ntp.org
```