Relax hostonly net create

docs/cloud-props.md

@@ -8,51 +8,172 @@ Example:
 
 ```yaml
 azs:
-- name: z1
+  - name: z1
 ```
 
 ### Network
 
 Schema for `cloud_properties` section used by network subnet:
 
-* **name** [String, optional]: Name of the network. Example: `vboxnet0`.
-* **type** [String, optional]: Type of the network. See [`VBoxManage modifyvm` networking settings](https://www.virtualbox.org/manual/ch08.html#idp46691722135120) for valid values. Example: `hostonly`. Default: `hostonly`.
-
-Example of manual network matching any name:
+* **name** [String, optional]: Name of the VirtualBox network. When not
+  specified (i.e. empty or null value), a new network of the specified type
+  will be created. For convenience, when the specified network does not exist,
+  the CPI will try to create one with that name (see the many caveats about
+  this below). Example: `vboxnet0`.
+* **type** [String, optional]: Type of the VirtualBox network. Supported
+  values: `hostonly`, `bridged`, `natnetwork`.
+  See [`VBoxManage modifyvm` networking settings][modifyvm_net_settings] for
+  more info. Default: `hostonly`.
+
+[modifyvm_net_settings]: https://www.virtualbox.org/manual/ch08.html#vboxmanage-modifyvm-networking
+
+!!! Caveats on `hostonly` networking names
+    When a `hostonly` network name si specified, but no such network exist,
+    the diffetent version of the CPI will behave differently, depending on the
+    VirtualBox version an operating system version.
+    With CPI version 0.4.x or earlier, then only `vboxnet0` is accepted as a
+    name for a network to create, and any other name will produce an error.
+    When the `name` property is not specified, then it will default to
+    `vboxnet0`.
+    With version 0.5.x and later, the name of the created network may be
+    specified with more freedom, with two dinstinct behaviors: VirtualBox v7+
+    on macOS will create a `hostonlynet` honoring the specified name, whereas
+    all Linux versions and macOS version 6.x (or earlier) will use the
+    specified name as a guess for the name that VirtulBox will pick when
+    creating the `hostonlyif` network (indeed those versions of VirtualBox are
+    naming `hostonlyif` networks sequentially using the `vboxnetX` pattern
+    where `X` is a digit, starting at 0). And whenever the guess is wrong, the
+    CPI will produce an error.
+
+Example of manual network:
 
 ```yaml
 networks:
 - name: private
   type: manual
   subnets:
-  - range:   192.168.50.0/24
-    gateway: 192.168.50.1
-    dns:     [192.168.50.1]
+  - range:   192.168.56.0/24
+    gateway: 192.168.56.1
+    dns:     [192.168.56.1]
+    cloud_properties:
+      name: vboxnet0
 ```
 
-### VM
+### VM Types / VM Extensions
 
 Schema for `cloud_properties` section:
 
 * **cpus** [Integer, optional]: Number of CPUs. Example: `1`. Default: `1`.
-* **memory** [Integer, optional]: RAM in megabytes. Example: `1024`. Default: `512`.
-* **ephemeral_disk** [Integer, optional]: Ephemeral disk size in megabytes. Example: `10240`. Default: `5000`.
-* **paravirtprovider** [String, optional]: Paravirtual provider type. See [`VBoxManage modifyvm` general settings](https://www.virtualbox.org/manual/ch08.html#vboxmanage-modifyvm) for valid values. Default: `default`.
-* **audio** [String, optional]: Audio type. See [`VBoxManage modifyvm` general settings](https://www.virtualbox.org/manual/ch08.html#vboxmanage-modifyvm) for valid values. Default: `none`.
+* **memory** [Integer, optional]: RAM in megabytes. Example: `1024`. Default:
+  `512`.
+* **ephemeral_disk** [Integer, optional]: Ephemeral disk size in megabytes.
+  Example: `10240`. Default: `5000`.
+* **paravirtprovider** [String, optional]: Paravirtual provider type. See
+  [`VBoxManage modifyvm` General Settings][modifyvm_general_settings] for
+  valid values. Default: `default`.
+* **audio** [String, optional]: Audio type. See [`VBoxManage modifyvm` Other
+  Hardware Settings][modifyvm_other_hardware] for valid values, e.g. `none`,
+  `default`, `null`, `dsound`, `was`, `oss`, `alsa`, `pulse`, `coreaudio`.
+  Default: `none`.
+
+!!! Caveats on audio
+    Audio is expected to be broken with VirtualBox 7+ on macOS. Contributions
+    are welcome.
+
+[modifyvm_general_settings]: https://www.virtualbox.org/manual/ch08.html#vboxmanage-modifyvm-general
+[modifyvm_other_hardware]: https://www.virtualbox.org/manual/ch08.html#vboxmanage-modifyvm-other-hardware
 
 Example of a VM type:
 
 ```yaml
 vm_types:
-- name: default
-  cloud_properties:
-    cpus: 2
-    memory: 2_048
-    ephemeral_disk: 4_096
-    paravirtprovider: kvm
-    audio: alsa
+  - name: default
+    cloud_properties:
+      cpus: 2
+      memory: 2_048
+      ephemeral_disk: 4_096
+      paravirtprovider: kvm
+      audio: alsa
 ```
 
-### Disk
+### Disk Types
 
 Currently the CPI does not support any cloud properties for disks.
+
+Example of 10GB disk:
+
+```yaml
+disk_types:
+  - name: default
+    disk_size: 10_240
+```
+
+---
+## Global Configuration {: #global }
+
+The CPI uses individual VirtualBox VMs and disks. Since the CPI can only talk to a single VirtualBox server it can only manage resources on a single machine.
+
+Example of a CPI configuration:
+
+```yaml
+properties:
+  host: 192.168.56.1
+  username: ubuntu
+  private_key: |
+    -----BEGIN RSA PRIVATE KEY-----
+    MIIEowIBAAKCAQEAr/c6pUbrq/U+s0dSU+Z6dxrHC7LOGDijv8LYN5cc7alYg+TV
+    ...
+    fe5h79YLG+gJDqVQyKJm0nDRCVz0IkM7Nhz8j07PNJzWjee/kcvv
+    -----END RSA PRIVATE KEY-----
+
+  agent:
+    mbus: "https://mbus:mbus-password@0.0.0.0:6868"
+
+  ntp:
+    - 0.pool.ntp.org
+    - 1.pool.ntp.org
+
+  blobstore:
+    provider: local
+    path: /var/vcap/micro_bosh/data/cache
+```
+
+See the docuemtnation for [the `virtualbox_cpi` job][virtualbox_cpi_job] for
+more details.
+
+[virtualbox_cpi_job]: https://bosh.io/jobs/virtualbox_cpi?source=github.com/cppforlife/bosh-virtualbox-cpi-release
+
+---
+## Example Cloud Config {: #cloud-config }
+
+```yaml
+azs:
+  - name: z1
+  - name: z2
+
+vm_types:
+  - name: default
+
+disk_types:
+  - name: default
+    disk_size: 3000
+
+networks:
+  - name: default
+    type: manual
+    subnets:
+      - range: 192.168.56.0/24
+        gateway: 192.168.56.1
+        azs: [z1, z2]
+        reserved: [192.168.56.6]
+        dns: [192.168.56.1]
+        cloud_properties:
+          name: vboxnet0
+
+compilation:
+  workers: 2
+  reuse_compilation_vms: true
+  az: z1
+  vm_type: default
+  network: default
+```

src/bosh-virtualbox-cpi/vm/host.go

@@ -30,6 +30,11 @@ func (h Host) FindNetwork(net Network) (bnet.Network, error) {
 	}
 }
 
+// Enable the network that the VM is to be attached to, and create that
+// network if necessary.
+//
+// In the VM creation workflow, the network is enabled _before_ being looked
+// up with (vm.Host).FindNetworks(Network).
 func (h Host) EnableNetworks(nets Networks) error {
 	for _, net := range nets {
 		switch net.CloudPropertyType() {
@@ -86,6 +91,8 @@ func (n *hostNetwork) Find() (bnet.Network, error) {
 	return nil, fmt.Errorf("Expected to find network '%s'", n.net.CloudPropertyName())
 }
 
+// Enable the network, and try to create it if it does not exist and if is not
+// already been tried.
 func (n *hostNetwork) Enable() error {
 	actualNets, err := n.adapter.List()
 	if err != nil {
@@ -189,13 +196,7 @@ func (n hostOnlysAdapter) List() ([]bnet.Network, error) {
 }
 
 func (n hostOnlysAdapter) Create(net Network) error {
-	canCreate, err := n.AddHostOnly(net.CloudPropertyName(), net.Gateway(), net.Netmask())
-	if err != nil {
-		return err
-	} else if !canCreate {
-		return fmt.Errorf("Expected to find Host-only network '%s'", net.CloudPropertyName())
-	}
-	return nil
+	return n.AddHostOnly(net.CloudPropertyName(), net.Gateway(), net.Netmask())
 }
 
 func (n hostOnlysAdapter) Matches(net Network, actualNet bnet.Network) bool {