Skip to content

Deployment Config

Note

This feature is available with bosh-release v255.4+.

Warning

If you are using director version between v241 and v256, once you opt into using cloud config all deployments must be converted to use new format. If you want to deploy both v1 and v2 manifests, update to director v257+.

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 manifest and creates or updates a deployment with matching name.

Assuming that you are using cloud config, your deployment manifest is expected to have:

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]: Not required by CLI v2. 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

Features Block

features [Hash, options]: Specifies Director features that should be used within this deployment.

Warning

The converge_variables feature can result in unintended side effects. It will regenerate all variables associated with a deployment, even those that are specified in a runtime config. For this reason we strongly recommend that you use the update_mode configuration on the variable that you wish to converge.

  • converge_variables [Boolean, optional]: Enable variables to be regenerated by the backend config server (e.g. CredHub) when the variable options change. Default false. Available in bosh-release 267+.
  • randomize_az_placement [Boolean, optional]: Randomizes AZs for left over instances that cannot be distributed equally between AZs. For example, given an instance group with 5 instances and only 3 AZs, 1 remaining instance will be placed in randomly chosen AZ out of specified 3 AZs. Available in bosh-release 264+.
  • use_dns_addresses [Boolean, optional]: Enables or disables returning of DNS addresses in links. Defaults to global Director use_dns_addresses configuration.
  • use_tmpfs_config [Boolean, optional]: Mounts all directories which contain rendered job templates on tmpfs by default on every instance group. Default false.
  • use_short_dns_addresses [Boolean, optional]: Uses a shorter DNS query format to reduce length of DNS name, for use in certificate common names. Default: false. See DNS and variables integration for more.

Example:

features:
  use_dns_addresses: true

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 or create.
  • url [String, optional]: URL of a release to download or local directory path when version is create. Works with CLI v2. Example: https://bosh.io/d/github.com/cloudfoundry/syslog-release?v=11.
  • sha1 [String, optional]: SHA1 of asset referenced via URL. Works with CLI v2. Example: 332ac15609b220a3fdf5efad0e0aa069d8235788.
  • stemcell [Hash, optional]: When url refers to a compiled release, the stemcell on which it was compiled (recommended when url refers to a compiled release).
    • os [String, required]: Operating system of the stemcell. Example: ubuntu-xenial.
    • version [String, required]: Version of the stemcell. Example: 97.18.
  • exported_from [Array, optional]: Require the release be deployed from previously-compiled releases of specific stemcell versions.
    • os [String, required]: Operating system of the stemcell. Example: ubuntu-xenial.
    • version [String, required]: Version of the stemcell. Example: 97.18.

See Release URLs for more details.

Example:

releases:
- name: redis
  version: 12

Example with a URL:

releases:
- name: concourse
  version: 3.3.2
  url: https://bosh.io/d/github.com/concourse/concourse?v=3.3.2
  sha1: 2c876303dc6866afb845e728eab58abae8ff3be2

Example with a compiled release:

releases:
- name: cf-mysql
  version: 36.15.0
  url: https://storage.googleapis.com/cf-deployment-compiled-releases/cf-mysql-36.15.0-ubuntu-xenial-97.18-20181006-041256-899428687.tgz
  sha1: 6466c44827c3493645ca34b084e7c21de23272b4
  stemcell:
    os: ubuntu-xenial
    version: 97.18
  exported_from:
  - os: ubuntu-xenial
    version: 97.18

Example with a local release directory:

releases:
- name: diego
  url: file:///home/pivotal/workspace/diego-release
  version: create

Stemcells Block

stemcells [Array, required]: The name and version of each stemcell in the deployment.

  • alias [String, required]: Name of a stemcell used in the deployment
  • os [String, optional]: Operating system of a matching stemcell. Example: ubuntu-xenial.
  • version [String, required]: The version of a matching stemcell. Version can be latest.
  • name [String, optional]: Full name of a matching stemcell. Either name or os keys can be specified.

IaaS-agnostic Configuration

To ensure your manifest can easily be used across multiple IaaSes, prefer using os instead of the IaaS-specific name field. Note: unlike releases, this does not support automatic downloading of a stemcell through a url field.

Example:

stemcells:
- alias: default
  os: ubuntu-xenial
  version: 621.74
- alias: default2
  name: bosh-aws-xen-hvm-ubuntu-xenial-go_agent
  version: 621.74

Update Block

update [Hash, required]: This specifies instance update properties. These properties control how BOSH updates 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]: Only applies to monit start operation.
    • 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]: Only applies to monit start operation.
    • 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), instance groups will be deployed in parallel, otherwise - sequentially. Instances within a group will still follow canary and max_in_flight configuration. Defaults to true.
  • vm_strategy [String, optional]: Influence how instances are updated when their VM needs to be recreated due to IaaS-related changes. Choose from one of the following strategies. Defaults to delete-create. Introduced in bosh/267.2.
    • delete-create - fully stop processes and delete the VM before creating and provisioning a new VM.
    • create-swap-delete - create and provision a new VM before stopping processes and transferring responsibilities from the old VM. Some configurations (e.g. static IPs) are not supported and will automatically revert to the delete-create strategy.
  • initial_deploy_az_update_strategy [String, optional]: Configure how instances are updated across multiple availability zones on the first deploy of a new deployment. Instances will still be updated with respect to canaries and max_in_flight. Defaults to serial. Note: VMs are all created in parallel regardless.
    • serial - Instances in each instance group will be updated one availability zone at a time.
    • parallel - Instances in each instance group will be updated all at once, regardless of availability zone.

See job lifecycle for more details on startup/shutdown procedure within each VM.

Examples:

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

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

Instance Groups Block

instance_groups [Array, required]: Specifies the mapping between release jobs and instance groups.

  • name [String, required]: A unique name used to identify and reference instance group.
  • azs [Array, required]: List of AZs associated with this instance group (should only be used when using first class AZs). Example: [z1, z2].
  • instances [Integer, required]: The number of instances in this group. Each instance is a VM.
  • jobs [Array, required]: Specifies the name and release of jobs that will be installed on each instance.
    • name [String, required]: The job name
    • release [String, required]: The release where the job exists
    • consumes [Hash, optional]: Links consumed by the job. Read more about link configuration
    • provides [Hash, optional]: Links provided by the job. Read more about link configuration
    • 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. If properties are specified, only these will be provided to the job and instance group properties will be ignored.
  • vm_type [String, required]: A valid VM type name from the cloud config. Alternatively you can specify vm_resources key.
  • vm_extensions [Array, optional]: A valid list of VM extension names from the cloud config.
  • vm_resources [Hash, optional]: Specifies generic VM resources such as CPU, RAM and disk size that are automatically translated into correct VM cloud properties to determine VM size. VM size is determined on best effort basis as some IaaSes may not support exact size configuration. Available in bosh-release v264+.
    • cpu [Integer, required]: Number of CPUs.
    • ram [Integer, required]: Amount of RAM in MB.
    • ephemeral_disk_size [Integer, required]: Ephemeral disk size in MB.
  • stemcell [String, required]: A valid stemcell alias from the Stemcells Block.
  • persistent_disk [Integer, optional]: Persistent disk size in MB. Alternatively you can specify persistent_disk_type key. Read more about persistent disks
  • persistent_disk_type [String, optional]: A valid disk type name from the cloud config. Read more about persistent disks
  • networks [Array, required]: Specifies the networks this instance requires. Each network can have the following properties specified:
    • name [String, required]: A valid network name from the cloud config.
    • static_ips [Array, optional]: Array of IP addresses reserved for the instances on the network.
    • default [Array, optional]: Specifies which network components (DNS, Gateway) BOSH populates by default from this network. This property is required if more than one network is specified.
  • update [Hash, optional]: Specific update settings for this instance group. Use this to override global job update settings on a per-instance-group basis.
  • migrated_from [Array, optional]: Specific migration settings for this instance group. Use this to rename and/or migrate instance groups.
  • lifecycle [String, optional]: Specifies the kind of workload the instance group 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.
  • properties [Hash, optional]: Specifies instance group properties. Deprecated in favor of job level properties and links.
  • tags [Hash, optional]: Specifies instance group tags. Specifies key value pairs to be sent to the CPI for VM tagging. Combined with deployment tags during VM creation. Available in bosh-release v277.4.0+.
  • env [Hash, optional]: Specifies advanced BOSH Agent configuration for each instance in the group. Read more about the agent.
    • persistent_disk_fs [String, optional]: Filesystem type to use when formatting persistent disk. Supported values: ext4, xfs. Default is currently set to ext4 but may change. See details
    • persistent_disk_mount_options [Array of strings, optional]: Mount options when mounting persistent disk. Example: ["noatime"].
    • bosh [Hash, optional]:
      • password [String, optional]: Crypted password for vcap/root user (will be placed into /etc/shadow on Linux).
      • authorized_keys [Array, optional]: Public keys for the vcap user, will be placed in .ssh/authorized_keys. This value can be used to enable SSH access onto VMs in this instance group.
      • keep_root_password [Boolean, optional]: Keep password for root and only change password for vcap. Default: false.
      • remove_dev_tools [Boolean, optional]: Remove compilers and dev tools on non-compilation VMs. Default: false.
      • remove_static_libraries [Boolean, optional]: Remove static libraries on non-compilation VMs. Default: false.
      • swap_size [Integer, optional]: Size of swap partition in MB to create. Set this to 0 to avoid having a swap partition created. Default: RAM size of used VM type up to half of the ephemeral disk size.
      • ipv6 [Hash, optional]:
        • enable [Boolean, optional]: Force IPv6 enabled in kernel (this configuration is not necessary if one of the VM addresses is IPv6). Default: false.
      • job_dir [Hash, optional]:
        • tmpfs [Boolean, optional]: Mount all directories which contain rendered job templates on tmpfs. Default: false.
        • tmpfs_size [String, optional]: The size of the tmpfs mount. Accepted values are a number of bytes or a number with a suffix e.g. 64m or 1g. Default: 100m.
      • run_dir [Hash, optional]:
        • tmpfs_size [String, optional]: The size of the tmpfs mount /var/vcap/data/sys/run. Accepted values are a number of bytes or a number with a suffix e.g. 64m or 1g .Default: 16m.
      • agent [Hash, optional]:
        • settings [Hash, optional]:
        • tmpfs [Boolean, optional]: Mount agent settings on a tmpfs directory. Default: false.
      • ntp [Array, optional]: list of ntp servers to synchronize to. Default: director-configured ntp servers.

Example:

instance_groups:
- name: redis-master
  instances: 1
  azs: [z1, z2]
  jobs:
  - name: redis-server
    release: redis
    properties:
      port: 3606
  vm_type: medium
  vm_extensions: [public-lbs]
  stemcell: default
  persistent_disk_type: medium
  networks:
  - name: default
  tags:
    tag1: value1

- name: redis-slave
  instances: 2
  azs: [z1, z2]
  jobs:
  - name: redis-server
    release: redis
    properties: {}
  vm_type: medium
  stemcell: default
  persistent_disk_type: medium
  networks:
  - name: default

Addons Block

Note

This feature is available with bosh-release v262+.

addons [Array, required]: Specifies the addons to be applied to this deployments.

See Addons Block for the schema.

Unlike addons specified in a runtime config, addons specified in the deployment manifest do not respect inclusion and exclusion rules for deployments.

Example:

addons:
- name: logging
  jobs:
  - name: logging-agent
    release: logging
    properties:
      ...

Properties Block

properties [Hash, optional]: Describes global properties. Deprecated in favor of job level properties and links.

Variables Block

variables [Array, optional]: Describes variables.

  • name [String, required]: Unique name used to identify a variable. Example: admin_password
  • type [String, required]: Type of a variable. Currently supported variable types are certificate, password, rsa, and ssh.
  • update_mode [String, optional]: Update mode to use when generating credentials. Currently supported update modes are no-overwrite, overwrite, and converge. Defaults to no-overwrite. For further information about the behavior of the update modes, please refer to the CredHub documentation.
  • update [Hash, optional]: Available in bosh-release 279+.
    • strategy [String, optional]: Controls when BOSH retrieves the latest version for the variable from the config server during a deploy. Currently supported strategies are on-deploy, and on-stemcell-change. Defaults to on-deploy.
      • on-deploy: BOSH will look up the latest variable value on each deploy.
      • on-stemcell-change: BOSH will only look up the latest variable value when a deploy is occuring that updates all stemcells for the deployment. If one or more stemcells are not being updated, then BOSH will continue to use the previously deployed value for the variable.
  • options [Hash, optional]: Specifies generation options used for generating variable value if variable is not found. Example: {is_ca: true, common_name: some-ca}

Example:

variables:
- name: admin_password
  type: password
- name: default_ca
  type: certificate
  options:
    is_ca: true
    common_name: some-ca
- name: director_ssl
  type: certificate
  options:
    ca: default_ca
    common_name: cc.cf.internal
    alternative_names: [cc.cf.internal]

See CLI Variable Interpolation for more details about variables.

See Variable Types for more details about CLI-supported generation for variables.

Tags Block

tags [Hash, optional]: Specifies key value pairs to be sent to the CPI for VM and disk tagging. Combined with runtime config level tags during the deploy. Available in bosh-release v258+.

Both VMs and disks get tagged by these custom tags.

For VMs, the director, deployment, instance_group, job, id, name, index and created_at are default tags enforced by Bosh that cannot be overridden. See also the set_vm_metadata CPI method for more info about those default tags.

For disks, the director, deployment, instance_group, instance_id, instance_index and attached_at are default Bosh tags that cannot be overridden. See the set_disk_metadata CPI method for more info about those.

Example:

tags:
  project: cf