Networks

A BOSH network is an IaaS-agnostic representation of the networking layer. The Director is responsible for configuring each deployment job's networks with the help of the BOSH Agent and the IaaS. Networking configuration is usually assigned at the boot of the VM and/or when network configuration changes in the deployment manifest for already-running deployment jobs.

There are three types of networks that BOSH supports:

manual: The Director decides how to assign IPs to each job instance based on the specified network subnets in the deployment manifest

Manual networking allows you to specify one or more subnets and let the Director choose available IPs from one of the subnet ranges. A subnet definition specifies the CIDR range and, optionally, the gateway and DNS servers. In addition, certain IPs can be blacklisted (the Director will not use these IPs) via the reserved property.

Each manual network attached to a job instance is typically represented as its own NIC in the IaaS layer.

Schema for manual network definition:

name [String, required]: Name used to reference this network configuration

type [String, required]: Value should be manual

subnets [Array, required]: Lists subnets in this network

range [String, required]: Subnet IP range that includes all IPs from this subnet

gateway [String, required]: Subnet gateway IP

dns [Array, optional]: DNS IP addresses for this subnet

reserved [Array, optional]: Array of reserved IPs and/or IP ranges. BOSH does not assign IPs from this range to any VM

networks:-name:my-networktype:manualsubnets:-range:10.10.0.0/24gateway:10.10.0.1dns:[10.10.0.2]# IPs that will not be used for anythingreserved:[10.10.0.2-10.10.0.10]cloud_properties:{subnet:subnet-9be6c3f7}-range:10.10.1.0/24gateway:10.10.1.1dns:[10.10.1.2]# IPs that can only be used for static IP reservations within this subnetstatic:[10.10.1.11-10.10.1.20]cloud_properties:{subnet:subnet-9be6c6gh}

Manual networks use automatic IP reservation by default. They also support static IP reservation. To assign specific IPs to instances of the deployment job, they must be specified in deployment job's networks section, in the static_ips property for the associated network. That network's subnet definition must also specify them in its static property:

If a deployment job uses static IP reservation, all instances must be given static IPs.

A common problem that you may run into is configuring multiple deployments to use overlapping IP ranges. The Director does not consider an IP to be "used" even if the Director used that IP in a different deployment. There are two possible solutions for this problem: reconfigure one of the deployments to use a different IP range, or use the same IP range but configure each deployment such that reserved IPs exclude the deployment from each other.

Note

While the Director usually selects the next available IP address, this behavior is not guaranteed.

Dynamic networking defers IP selection to the IaaS. For example, AWS assigns a private IP to each instance in the VPC by default. By associating a deployment job to a dynamic network, BOSH will pick up AWS-assigned private IP addresses.

Each dynamic network attached to a job instance is typically represented as its own NIC in the IaaS layer.

Dynamic networking only supports automatic IP reservations.

Schema for dynamic network definition:

name [String, required]: Name used to reference this network configuration

A deployment job can be configured to have multiple IP addresses (multiple NICs) by being on multiple networks. Given that there are multiple network settings available for a deployment job, the Agent needs to decide which network's DNS settings to use and which network's gateway should be the default gateway on the VM. Agent performs such selection based on the network's default property specified in the deployment job.

Schema for default property:

default [Array, optional]: Configures this network to provide its settings for specific category as a default. Possible values are: dns, gateway and since bosh-release v258 addressable. All values can be specified together. addressable can be used to specify which IP address other jobs see.

In the above example, VM allocated to my-multi-homed-job deployment job will have 8.8.8.8 as its primary DNS server and the default gateway will be set to my-network-1's gateway. VM allocated to my-other-multi-homed-job deployment job will also have 8.8.8.8 as its primary DNS server but the default gateway will be set to my-network-2's gateway.

The Director does not enforce how many networks can be assigned to each job instance; however, each CPI might impose custom requirements either due to the IaaS limitations or simply because support was not yet implemented.