Skip to content

Usage

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

Previously each deployment manifest specified IaaS and IaaS agnostic configuration in a single file. As more deployments are managed by the Director, it becomes inconvenient to keep shared IaaS configuration in sync in all deployment manifests. In addition, multiple deployments typically want to use the same network subnet, hence IP ranges need to be separated and reserved.

The cloud config is a YAML file that defines IaaS specific configuration used by the Director and all deployments. It allows us to separate IaaS specific configuration into its own file and keep deployment manifests IaaS agnostic.

Updating and retrieving cloud config

To update cloud config on the Director use bosh update-cloud-config command.

Note

See example cloud config for AWS below.

bosh -e vbox update-cloud-config cloud.yml

bosh -e vbox cloud-config

Acting as user 'admin' on 'micro'

azs:
- name: z1
  cloud_properties:
    availability_zone: us-east-1b
- name: z2
  cloud_properties:
    availability_zone: us-east-1c
...

Once cloud config is updated, all existing deployments will be considered outdated, as indicated by bosh deployments command. The Director will apply cloud config changes to each deployment during the next run of bosh deploy command for that deployment.

bosh -e vbox deployments

Using environment '192.168.56.6' as '?'

Name       Release(s)       Stemcell(s)             Team(s)  Cloud Config
zookeeper  zookeeper/0.0.5  bosh-warden-.../3421.4  -        outdated

1 deployment

Succeeded

Example

azs:
- name: z1
  cloud_properties: {availability_zone: us-east-1a}
- name: z2
  cloud_properties: {availability_zone: us-east-1b}

vm_types:
- name: small
  cloud_properties:
    instance_type: t2.micro
    ephemeral_disk: {size: 3000, type: gp2}
- name: medium
  cloud_properties:
    instance_type: m3.medium
    ephemeral_disk: {size: 30000, type: gp2}

disk_types:
- name: small
  disk_size: 3000
  cloud_properties: {type: gp2}
- name: large
  disk_size: 50_000
  cloud_properties: {type: gp2}

networks:
- name: private
  type: manual
  subnets:
  - range: 10.10.0.0/24
    gateway: 10.10.0.1
    az: z1
    static: [10.10.0.62]
    dns: [10.10.0.2]
    cloud_properties: {subnet: subnet-f2744a86}
  - range: 10.10.64.0/24
    gateway: 10.10.64.1
    az: z2
    static: [10.10.64.121, 10.10.64.122]
    dns: [10.10.0.2]
    cloud_properties: {subnet: subnet-eb8bd3ad}
- name: vip
  type: vip

compilation:
  workers: 5
  reuse_compilation_vms: true
  az: z1
  vm_type: medium
  network: private

AZs Block

azs [Array, required]: Specifies the AZs available to deployments. At least one should be specified.

  • name [String, required]: Name of an AZ within the Director.
  • cloud_properties [Hash, optional]: Describes any IaaS-specific properties needed to associated with AZ; for most IaaSes, some data here is actually required. See CPI Specific cloud_properties below. Example: availability_zone. Default is {} (empty Hash).

See first class AZs for more details.

Example:

azs:
- name: z1
  cloud_properties:
    availability_zone: us-east-1c
- name: z2
  cloud_properties:
    availability_zone: us-east-1d

CPI Specific cloud_properties

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. At least one should be specified.

See networks for more details.

CPI Specific cloud_properties

VM Types Block

vm_types [Array, required]: Specifies the VM types available to deployments. At least one should be specified.

  • name [String, required]: A unique name used to identify and reference the VM type
  • cloud_properties [Hash, optional]: Describes any IaaS-specific properties needed to create VMs; for most IaaSes, some data here is actually required. See CPI Specific cloud_properties below. Example: instance_type: m3.medium. Default is {} (empty Hash).

Example:

vm_types:
- name: default
  cloud_properties:
    instance_type: m1.small

CPI Specific cloud_properties

VM Extensions Block

Note

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

vm_extensions [Array, optional]: Specifies the VM extensions available to deployments.

  • name [String, required]: A unique name used to identify and reference the VM extension
  • cloud_properties [Hash, optional]: Describes any IaaS-specific properties needed to configure VMs. Example: elbs: [...]. Default is {} (empty Hash).

Example:

vm_extensions:
- name: pub-lbs
  cloud_properties:
    elbs: [main]

Any IaaS specific configuration could be placed into a VM extension's cloud_properties.

Disk Types Block

disk_types [Array, required]: Specifies the disk types available to deployments. At least one should be specified.

  • name [String, required]: A unique name used to identify and reference the disk type
  • 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_types:
- name: default
  disk_size: 2
  cloud_properties:
    type: gp2

CPI Specific cloud_properties

Compilation Block

The Director creates compilation VMs for release compilation. The Director will compile each release on every necessary stemcell used in a deployment. A compilation definition allows to specify VM characteristics.

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

  • workers [Integer, required]: The maximum number of compilation VMs.
  • az [String, required]: Name of the AZ defined in AZs section to use for creating compilation VMs.
  • vm_type [String, optional]: Name of the VM type defined in VM types section to use for creating compilation VMs. Alternatively, you can specify the vm_resources, or cloud_properties key.
  • orphan_workers [Boolean, optional]: When enabled, BOSH will orphan compilation VMs after they finishing compiling packages for the VMs to be deleted asynchronously (instead of blocking the deployment). Default false. Available in bosh-release v267+.
  • 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. Currently some CPIs (Google and Azure) do not support this functionality. Available in bosh-release v264+.
  • vm_extensions [Array, optional]: Names of the VM extensions defined in the VM extensions section to use for creating compilation VMs.
  • cloud_properties [Hash, optional]: Describes any IaaS-specific properties needed to create VMs. Most IaaSes require this. Examples: instance_type, availability_zone. Default is {} (empty Hash).
  • 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.
  • env [Hash, optional]: Same as env for instance groups.

Example:

compilation:
  workers: 2
  reuse_compilation_vms: true
  az: z1
  vm_type: default
  network: private
  vm_extensions: [default, load-balancer]