

Deployment Manifest v1

Note

Once you opt into using cloud config all deployments must be converted to use manifest v2 format that disallows IaaS specific configuration. See manifest v2 schema for allowed configurations. v257+ supports deploying both v1 and v2 manifests to the same director.

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: A name for the deployment and the UUID of the Director managing the deployment
Releases Block: Name and version of each release in a deployment
Networks Block: Network configuration information
Resource Pools Block: Properties of VMs that BOSH creates and manages
Disk Pools Block: Properties of disk pools that BOSH creates and manages
Compilation Block: Properties of compilation VMs
Update Block: Defines how BOSH updates job instances during deployment
Jobs Block: Configuration and resource information for jobs
Properties Block: Describes global properties and generalized configuration information

The examples below originate from a sample deployment manifest.

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:

name: my-redis-deployment

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

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:

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

Releases Block using URLs¶

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:

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

Releases Block using local release directory¶

releases [Array, required]: The name and local release directory of a release in the deployment.

name [String, required]: Name of a release used in the deployment.
url [String, required]: Path to release directory on local filesystem (relative to working directory).
version [String, required]: Must be create

Example:

releases:
- name: bosh-aws-cpi
  url: /Users/cloudfoundry/workspace/bosh-aws-cpi-release
  version: create

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 for more details.

CPI Specific `cloud_properties`¶

Resource Pools Block¶

resource_pools [Array, required]: Specifies the resource pools 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 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:

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

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:

resource_pools:
- name: redis-servers
  network: default
  stemcell:
    url: https://bosh.io/d/stemcells/bosh-aws-xen-hvm-ubuntu-xenial-go_agent?v=621.74
    sha1: 5a81413223bcee987955038dc903345720fc22a4
  cloud_properties:
    instance_type: m1.small
    availability_zone: us-east-1c

CPI Specific `cloud_properties`¶

Disk Pools Block¶

disk_pools [Array, required]: Specifies the 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 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:

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

CPI Specific `cloud_properties`¶

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 for Resource Pools. Examples: instance_type, availability_zone. Default is {} (empty Hash).

Example:

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

Update Block¶

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

canaries [Integer or Percentage, required]: The number of canary instances.
max_in_flight [Integer or Percentage, required]: The maximum number of non-canary instances to update in parallel within an availability zone. Updates will not begin in another availability zone until all VMs are updated in the current availability zone.
- If the max_in_flight is a percentage, the minimum max_in_flight will never fall below 1.
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.

Examples:

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

update:
  canaries: 10%
  max_in_flight: 50%
  canary_watch_time: 1000-30000
  update_watch_time: 1000-30000
  initial_deploy_az_update_strategy: serial

Jobs Block¶

jobs [Array, required]: Specifies the mapping between BOSH release jobs 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
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 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:

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

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 block are accessible to all jobs. Any identically named properties in the 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:

properties:
  redis:
    max_connections: 10

Job Property Precedence¶

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

Note

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.

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:[email protected]:6868".
properties [Hash, required]: Properties required by the CPI job.

Example from Initializing BOSH environment on vSphere:

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

  mbus: "https://mbus:[email protected]:6868"

  properties:
    vcenter: { ... }

    agent: {mbus: "https://mbus:[email protected]:6868"}

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

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

Deployment Manifest v1

Deployment Identification¶

Releases Block¶

Releases Block using URLs¶

Releases Block using local release directory¶

Networks Block¶

CPI Specific cloud_properties¶

Resource Pools Block¶

Custom bosh-init Stemcell Key Schema¶

CPI Specific cloud_properties¶

Disk Pools Block¶

CPI Specific cloud_properties¶

Compilation Block¶

Update Block¶

Jobs Block¶

Properties Block¶

Job Property Precedence¶

Cloud Provider Block¶

CPI Specific `cloud_properties`¶

CPI Specific `cloud_properties`¶

CPI Specific `cloud_properties`¶