Skip to content

Commit 6491479

Browse files
bgandonbgandon
committed
Update docs and align the text with the copy published in bosh.io
1 parent 2f8f41d commit 6491479

File tree

1 file changed

+142
-21
lines changed

1 file changed

+142
-21
lines changed

‎docs/cloud-props.md‎

Lines changed: 142 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -8,51 +8,172 @@ Example:
88

99
```yaml
1010
azs:
11-
- name: z1
11+
- name: z1
1212
```
1313
1414
### Network
1515
1616
Schema for `cloud_properties` section used by network subnet:
1717

18-
* **name** [String, optional]: Name of the network. Example: `vboxnet0`.
19-
* **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`.
20-
21-
Example of manual network matching any name:
18+
* **name** [String, optional]: Name of the VirtualBox network. When not
19+
specified (i.e. empty or null value), a new network of the specified type
20+
will be created. For convenience, when the specified network does not exist,
21+
the CPI will try to create one with that name (see the many caveats about
22+
this below). Example: `vboxnet0`.
23+
* **type** [String, optional]: Type of the VirtualBox network. Supported
24+
values: `hostonly`, `bridged`, `natnetwork`.
25+
See [`VBoxManage modifyvm` networking settings][modifyvm_net_settings] for
26+
more info. Default: `hostonly`.
27+
28+
[modifyvm_net_settings]: https://www.virtualbox.org/manual/ch08.html#vboxmanage-modifyvm-networking
29+
30+
!!! Caveats on `hostonly` networking names
31+
When a `hostonly` network name si specified, but no such network exist,
32+
the diffetent version of the CPI will behave differently, depending on the
33+
VirtualBox version an operating system version.
34+
With CPI version 0.4.x or earlier, then only `vboxnet0` is accepted as a
35+
name for a network to create, and any other name will produce an error.
36+
When the `name` property is not specified, then it will default to
37+
`vboxnet0`.
38+
With version 0.5.x and later, the name of the created network may be
39+
specified with more freedom, with two dinstinct behaviors: VirtualBox v7+
40+
on macOS will create a `hostonlynet` honoring the specified name, whereas
41+
all Linux versions and macOS version 6.x (or earlier) will use the
42+
specified name as a guess for the name that VirtulBox will pick when
43+
creating the `hostonlyif` network (indeed those versions of VirtualBox are
44+
naming `hostonlyif` networks sequentially using the `vboxnetX` pattern
45+
where `X` is a digit, starting at 0). And whenever the guess is wrong, the
46+
CPI will produce an error.
47+
48+
Example of manual network:
2249

2350
```yaml
2451
networks:
2552
- name: private
2653
type: manual
2754
subnets:
28-
- range: 192.168.50.0/24
29-
gateway: 192.168.50.1
30-
dns: [192.168.50.1]
55+
- range: 192.168.56.0/24
56+
gateway: 192.168.56.1
57+
dns: [192.168.56.1]
58+
cloud_properties:
59+
name: vboxnet0
3160
```
3261

33-
### VM
62+
### VM Types / VM Extensions
3463

3564
Schema for `cloud_properties` section:
3665

3766
* **cpus** [Integer, optional]: Number of CPUs. Example: `1`. Default: `1`.
38-
* **memory** [Integer, optional]: RAM in megabytes. Example: `1024`. Default: `512`.
39-
* **ephemeral_disk** [Integer, optional]: Ephemeral disk size in megabytes. Example: `10240`. Default: `5000`.
40-
* **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`.
41-
* **audio** [String, optional]: Audio type. See [`VBoxManage modifyvm` general settings](https://www.virtualbox.org/manual/ch08.html#vboxmanage-modifyvm) for valid values. Default: `none`.
67+
* **memory** [Integer, optional]: RAM in megabytes. Example: `1024`. Default:
68+
`512`.
69+
* **ephemeral_disk** [Integer, optional]: Ephemeral disk size in megabytes.
70+
Example: `10240`. Default: `5000`.
71+
* **paravirtprovider** [String, optional]: Paravirtual provider type. See
72+
[`VBoxManage modifyvm` General Settings][modifyvm_general_settings] for
73+
valid values. Default: `default`.
74+
* **audio** [String, optional]: Audio type. See [`VBoxManage modifyvm` Other
75+
Hardware Settings][modifyvm_other_hardware] for valid values, e.g. `none`,
76+
`default`, `null`, `dsound`, `was`, `oss`, `alsa`, `pulse`, `coreaudio`.
77+
Default: `none`.
78+
79+
!!! Caveats on audio
80+
Audio is expected to be broken with VirtualBox 7+ on macOS. Contributions
81+
are welcome.
82+
83+
[modifyvm_general_settings]: https://www.virtualbox.org/manual/ch08.html#vboxmanage-modifyvm-general
84+
[modifyvm_other_hardware]: https://www.virtualbox.org/manual/ch08.html#vboxmanage-modifyvm-other-hardware
4285

4386
Example of a VM type:
4487

4588
```yaml
4689
vm_types:
47-
- name: default
48-
cloud_properties:
49-
cpus: 2
50-
memory: 2_048
51-
ephemeral_disk: 4_096
52-
paravirtprovider: kvm
53-
audio: alsa
90+
- name: default
91+
cloud_properties:
92+
cpus: 2
93+
memory: 2_048
94+
ephemeral_disk: 4_096
95+
paravirtprovider: kvm
96+
audio: alsa
5497
```
5598

56-
### Disk
99+
### Disk Types
57100

58101
Currently the CPI does not support any cloud properties for disks.
102+
103+
Example of 10GB disk:
104+
105+
```yaml
106+
disk_types:
107+
- name: default
108+
disk_size: 10_240
109+
```
110+
111+
---
112+
## Global Configuration {: #global }
113+
114+
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.
115+
116+
Example of a CPI configuration:
117+
118+
```yaml
119+
properties:
120+
host: 192.168.56.1
121+
username: ubuntu
122+
private_key: |
123+
-----BEGIN RSA PRIVATE KEY-----
124+
MIIEowIBAAKCAQEAr/c6pUbrq/U+s0dSU+Z6dxrHC7LOGDijv8LYN5cc7alYg+TV
125+
...
126+
fe5h79YLG+gJDqVQyKJm0nDRCVz0IkM7Nhz8j07PNJzWjee/kcvv
127+
-----END RSA PRIVATE KEY-----
128+
129+
agent:
130+
mbus: "https://mbus:[email protected]:6868"
131+
132+
ntp:
133+
- 0.pool.ntp.org
134+
- 1.pool.ntp.org
135+
136+
blobstore:
137+
provider: local
138+
path: /var/vcap/micro_bosh/data/cache
139+
```
140+
141+
See the docuemtnation for [the `virtualbox_cpi` job][virtualbox_cpi_job] for
142+
more details.
143+
144+
[virtualbox_cpi_job]: https://bosh.io/jobs/virtualbox_cpi?source=github.com/cppforlife/bosh-virtualbox-cpi-release
145+
146+
---
147+
## Example Cloud Config {: #cloud-config }
148+
149+
```yaml
150+
azs:
151+
- name: z1
152+
- name: z2
153+
154+
vm_types:
155+
- name: default
156+
157+
disk_types:
158+
- name: default
159+
disk_size: 3000
160+
161+
networks:
162+
- name: default
163+
type: manual
164+
subnets:
165+
- range: 192.168.56.0/24
166+
gateway: 192.168.56.1
167+
azs: [z1, z2]
168+
reserved: [192.168.56.6]
169+
dns: [192.168.56.1]
170+
cloud_properties:
171+
name: vboxnet0
172+
173+
compilation:
174+
workers: 2
175+
reuse_compilation_vms: true
176+
az: z1
177+
vm_type: default
178+
network: default
179+
```

0 commit comments

Comments
 (0)