Skip to content

Usage

This topic describes cloud properties for different resources created by the AWS CPI.

AZs

Schema for cloud_properties section:

  • availability_zone [String, required]: Availability zone to use for creating instances. Example: us-east-1a.

Example:

azs:
- name: z1
  cloud_properties:
    availability_zone: us-east-1a

Networks

Schema for cloud_properties section used by dynamic network or manual network subnet:

  • subnet [String, required]: Subnet ID in which the instance will be created. Example: subnet-9be6c3f7.
  • security_groups [Array, optional]: Array of Security Groups, by name or ID, to apply to all VMs placed on this network. Security groups can be specified as follows, ordered by greatest precedence: vm_types, followed by networks, followed by default_security_groups.

Example of manual network:

networks:
- name: default
  type: manual
  subnets:
  - range: 10.10.0.0/24
    gateway: 10.10.0.1
    cloud_properties:
      subnet: subnet-9be6c3f7
      security_groups: [bosh]

Example of dynamic network:

networks:
- name: default
  type: dynamic
  cloud_properties:
    subnet: subnet-9be6c6gh

Example of vip network:

networks:
- name: default
  type: vip

VM Types / VM Extensions

Schema for cloud_properties section:

  • instance_type [String, required]: Type of the instance. Example: m3.medium.
  • availability_zone [String, required]: Availability zone to use for creating instances. Example: us-east-1a.
  • security_groups [Array, optional]: See description under networks. Available in v46+.
  • key_name [String, optional]: Key pair name. Defaults to key pair name specified by default_key_name in global CPI settings. Example: bosh.
  • spot_bid_price [Float, optional]: Bid price in dollars for AWS spot instance. Using this option will slow down VM creation. Example: 0.03.
  • spot_ondemand_fallback [Boolean, optional]: Set to true to use an on demand instance if a spot instance is not available during VM creation. Defaults to false. Available in v36.
  • elbs [Array, optional]: Array of Elastic (Classic) Load Balancer (ELB) names that should be attached to created VMs. Example: [prod-elb]. Default is [].
  • lb_target_groups [Array, optional]: Array of Load Balancer Target Groups to which created VMs should be attached. Target Groups can be used to link Application Load Balancers (ALB) and Network Load Balancers (NLB) to instances. Example: [prod-group1, prod-group2]. Default is []. Available in v63 or newer.
  • iam_instance_profile [String, optional]: Name of an IAM instance profile. Example: director.
  • placement_group [String, optional]: Name of a placement group. Example: my-group.
  • tenancy [String, optional]: VM tenancy configuration. Example: dedicated. Default is default.
  • auto_assign_public_ip [Boolean, optional]: Assigns a public IP address to the created VM. This IP is ephemeral and may change; use an Elastic IP instead for a persistent address. Defaults to false. Available in v55+.
  • advertised_routes [Array, optional]: Creates routes in an AWS Route Table with the created BOSH VM as the target. Requires IAM action ec2:CreateRoute, ec2:DescribeRouteTables, ec2:ReplaceRoute.
    • table_id [String, required]: ID of the route table in which to create the route (e.g. rt-abcdef123).
    • destination [String, required]: Destination CIDR for the route. All traffic with a destination within this CIDR will be routed through the created BOSH VM.
  • raw_instance_storage [Boolean, optional]: Exposes all available instance storage via labeled disks. Defaults to false.
  • source_dest_check [Boolean, optional]: Specifies whether the instance must be the source or destination of any traffic it sends or receives. If set to false, the instance does not need to be the source or destination. Used for network address translation (NAT) boxes, frequently to communicate between VPCs. Defaults to true. Requires IAM action ec2:ModifyInstanceAttribute. Available in v59+.
  • ephemeral_disk [Hash, optional]: EBS backed ephemeral disk of custom size. Default disk size is either the size of first instance storage disk, if the instance_type offers it, or 10GB. Before v53: Used EBS only if instance storage is not large enough or not available for selected instance type.
    • size [Integer, required]: Specifies the disk size in megabytes.
    • type [String, optional]: Type of the disk: standard, gp2, gp3. Defaults to gp3 (since v88).
      • standard stands for EBS magnetic drives
      • gp2 stands for EBS general purpose drives (SSD)
      • gp3 stands for EBS next-generation general purpose drives (SSD)
      • io1 stands for EBS provisioned IOPS drives (SSD)
    • iops [Integer, optional]: Specifies the number of I/O operations per second to provision for the drive.
      • Only valid for io1 and gp3 type drive.
      • Required when io1 type drive is specified.
      • Optional for gp3, defaults to AWS default iops count if iops < AWS default (added with v93).
    • throughput [Integer, optional]: Specifies Throughput in MBp/s
      • Only valid for gp3 type drive.
      • Optional, defaults to AWS default throughput if throughput < AWS default
      • Added with v93.
    • encrypted [Boolean, optional] Enables encryption for the EBS backed ephemeral disk. An error is raised, if the instance_type does not support it. Since v53. Defaults to false. Overrides the global encrypted property.
    • kms_key_arn [String, optional] The ARN of an Amazon KMS key to use when encrypting the disk.
    • use_instance_storage [Boolean, optional] Forces the usage of instance storage as ephemeral disk backing. Will raise an error, if the used instance_type does not have instance storage. Cannot be combined with any other option under ephemeral_disk or with raw_instance_storage. Since v53. Defaults to false.
  • root_disk [Hash, optional]: EBS backed root disk of custom size.
    • size [Integer, required]: Specifies the disk size in megabytes.
    • type [String, optional]: Type of the disk: standard, gp2, gp3. Defaults to gp3 (since v88).
      • standard stands for EBS magnetic drives
      • gp2 stands for EBS general purpose drives (SSD)
      • gp3 stands for EBS next-generation general purpose drives (SSD)
    • iops [Integer, optional]: Specifies the number of I/O operations per second to provision for the drive.
      • Only valid for io1 and gp3 type drive.
      • Required when io1 type drive is specified.
      • Optional for gp3, defaults to AWS default iops count if iops < AWS default (added with v93).
    • throughput [Integer, optional]: Specifies Throughput in MBp/s
      • Only valid for gp3 type drive.
      • Optional, defaults to AWS default throughput if throughput < AWS default
      • Added with v93.
  • metadata_options [Hash, optional]: Metadata configuration options that are set on a VM during creation. These options should be snake-cased properties accepted by the ModifyInstanceMetadataOptions endpoint. e.g. http_put_response_hop_limit. If metadata_options is configured both at the global CPI level and as a VM extension, the VM extension properties take precedence. Available in v91+.

Example of an m3.medium instance:

resource_pools:
- name: default
  network: default
  stemcell:
    name: bosh-aws-xen-hvm-ubuntu-xenial-go_agent
    version: latest
  cloud_properties:
    instance_type: m3.medium
    availability_zone: us-east-1a

Disk Types

Schema for cloud_properties section:

  • type [String, optional]: Type of the disk: standard, gp2, gp3. Defaults to gp3 (since v88).
    • standard stands for EBS magnetic drives
    • gp2 stands for EBS general purpose drives (SSD)
    • gp3 stands for EBS next-generation general purpose drives (SSD)
    • io1 stands for EBS provisioned IOPS drives (SSD)
  • iops [Integer, optional]: Specifies the number of I/O operations per second to provision for the drive.
    • Only valid for io1 type drive.
    • Required when io1 type drive is specified.
    • Optional for gp3, defaults to AWS default iops count if iops < AWS default (added with v93).
  • throughput [Integer, optional]: Specifies Throughput in MBp/s
    • Only valid for gp3 type drive.
    • Optional, defaults to AWS default throughput if throughput < AWS default
    • Added with v93.
  • encrypted [Boolean, optional]: Turns on EBS volume encryption for this persistent disk. VM root and ephemeral disk are not encrypted. Defaults to false. Overrides the global encrypted property.
  • kms_key_arn [String, optional]: Encrypts the disk using an encryption key stored in the AWS Key Management Service (KMS). The format of the ID is XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX. Be sure to use the Key ID, not the Alias. If omitted the disk will be encrypted using the global kms_key_arn property. If, no global kms_key_arn is set will use your account's default aws/ebs encryption key.

EBS volumes are created in the availability zone of an instance that volume will be attached.

Example of 10GB disk:

- name: default
  disk_size: 10_240
  cloud_properties:
    type: gp3

Global Configuration

The CPI can only talk to a single AWS region.

Schema:

  • credentials_source [String, optional]: Selects credentials source between credentials provided in this configuration, or from an IAM instance profile. Default: static.
  • access_key_id [String, optional]: Accesss Key ID. Example: AKI....
  • secret_access_key [String, optional]: Secret Access Key. Example: 0kwh....
  • default_key_name [String, required]: Name of the Key Pair that will be applied to all created VMs. Example: bosh
  • default_security_groups [Array, required]: See description under networks.
  • default_iam_instance_profile [String, optional]: Name of the IAM instance profile that will be applied to all created VMs. Example: director.
  • region [String, required]: AWS region name. Example: us-east-1
  • max_retries [Integer, optional]: The maximum number of times AWS service errors (500) and throttling errors (AWS::EC2::Errors::RequestLimitExceeded) should be retried. There is an exponential backoff in between retries, so the more retries the longer it can take to fail. Defaults to 2.

  • encrypted [Boolean, optional]: Turns on EBS volume encryption for all VM's root (system), ephemeral and persistent disks. Defaults to false. Available in v67+.

    Warning

    EBS volume encryption does not work for Windows stemcells due to an AWS limitation. Enabling this will not encrypt the root disk of Windows VMs.

  • kms_key_arn [String, optional]: Encrypts the disks using an encryption key stored in the AWS Key Management Service (KMS). The format of the ID is XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX. Be sure to use the Key ID, not the Alias. If this property is omitted and encrypted is true, the disks will be encrypted using your account's default aws/ebs encryption key. Available in v67+.

  • metadata_options [Hash, optional]: Metadata configuration options that are set on a VM during creation. These options should be snake-cased properties accepted by the ModifyInstanceMetadataOptions endpoint. e.g. http_put_response_hop_limit. If metadata_options is configured both at the global CPI level and as a VM extension, the VM extension properties take precedence. Available in v91+.

See all configuration options.

Example with hard-coded credentials:

access_key_id: ACCESS-KEY-ID
secret_access_key: SECRET-ACCESS-KEY
default_key_name: bosh
default_security_groups: [bosh]
region: us-east-1

Example when IAM instance profiles are used:

credentials_source: env_or_profile
default_key_name: bosh
default_security_groups: [bosh]
default_iam_instance_profile: deployed-vm
region: us-east-1

Example Cloud Config

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

vm_types:
- name: default
  cloud_properties:
    instance_type: t2.micro
    ephemeral_disk: {size: 3000, type: gp3}
- name: large
  cloud_properties:
    instance_type: m3.large
    ephemeral_disk: {size: 30000, type: gp3}

disk_types:
- name: default
  disk_size: 3000
  cloud_properties: {type: gp3}
- name: large
  disk_size: 50_000
  cloud_properties: {type: gp3}

networks:
- name: default
  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: large
  network: default