forked from cloudfoundry/docs-bosh
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathbuild-stemcell.html.md.erb
99 lines (72 loc) · 5.11 KB
/
build-stemcell.html.md.erb
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
---
title: Stemcell Building
---
(See [What is a Stemcell?](stemcell.html) for an introduction to stemcells.)
To build a stemcell tarball for a supported IaaS-OS combination follow instructions in the [bosh-linux-stemcell-builder's README](https://github.com/cloudfoundry/bosh-linux-stemcell-builder/blob/master/README.md).
Stemcell tarballs are currently specific to an IaaS-OS/CPI because they may:
- include custom Agent configuration (e.g. [OpenStack's Agent configuration](https://github.com/cloudfoundry/bosh/blob/ede389a2e112e1b4f2dbc4495c08977da4439483/stemcell_builder/stages/bosh_openstack_agent_settings/apply.sh#L12-L41))
- include custom OS packages/configuration (e.g. [OpenStack's OS customizations](https://github.com/cloudfoundry/bosh/blob/cdd7c7b333d076aa96c648825b1e9ba4ba7a22ba/bosh-stemcell/lib/bosh/stemcell/stage_collection.rb#L93-L94))
- be packaged into a custom image format (qcow, vmdk, etc.)
In the future, BOSH team will investigate how to best consolidate stemcells into a single OS image. In the meantime, if you're developing a CPI for a new IaaS, you may consider reusing one of the officially generated stemcells, or making changes to the following projects:
- [bosh-linux-stemcell-builder](https://github.com/cloudfoundry/bosh-linux-stemcell-builder)
- [bosh-agent](https://github.com/cloudfoundry/bosh-agent)
---
## <a id="tarball-structure"></a> Tarball Structure
<p class="note">Note that tarball structure is subject to change without notice.</p>
<pre class="terminal">
$ tar tvf light-bosh-stemcell-3033-aws-xen-hvm-ubuntu-trusty-go_agent.tgz
-rw-rw-r-- 0 ubuntu ubuntu 0 Aug 4 09:45 image
-rw-rw-r-- 0 ubuntu ubuntu 710 Aug 4 10:06 stemcell.MF
-rw-r--r-- 0 ubuntu ubuntu 50594 Aug 4 09:23 packages.txt
-rw-r--r-- 0 ubuntu ubuntu 12543 Aug 4 09:22 dev_tools_file_list.txt
</pre>
* `image`: OS image in a format (raw, qcow, ova, etc.) understood by the CPI/IaaS.
* `stemcell.MF`: YAML file with stemcell metadata.
* `packages.txt`: Text file that includes list of packages installed. (Used to be included as `stemcell_dpkg_l.txt`)
* `dev_tools_file_list.txt`: Text file that includes list of files removed by the agent if Agent's `remove_dev_tools` feature is enabled.
### <a id="metadata"></a> Metadata
<p class="note">Note that content of `stemcell.MF` is subject to change without notice.</p>
* **name** [String, required]: A unique name used to identify stemcell series.
* **operating_system** [String, required]: Operating system in the stemcell. Example: `ubuntu-trusty`.
* **version** [String, required]: Version of the stemcell. Example: `3033`.
* **sha1** [String, required]: The SHA1 of the image file included in the stemcell tarball.
* **bosh_protocol** [Integer, optional]: Deprecated.
* **cloud_properties** [Hash, required]: Describes any IaaS-specific properties needed to import OS image. These properties will be passed in to the [`create_stemcell` CPI call](cpi-api-v1.html#create-stemcell).
Name, operating system and version values will be visible via `bosh stemcells` command once a stemcell is imported into the Director.
Example:
<pre class="terminal">
$ tar -Oxzf light-bosh-stemcell-3033-aws-xen-hvm-ubuntu-trusty-go_agent.tgz stemcell.MF
</pre>
```yaml
---
name: bosh-aws-xen-hvm-ubuntu-trusty-go_agent
operating_system: ubuntu-trusty
version: '3033'
sha1: c13273b00b762c5aa29240ea62e1b9b5a03ae02c
bosh_protocol: 1
cloud_properties:
name: bosh-aws-xen-hvm-ubuntu-trusty-go_agent
version: '3033'
infrastructure: aws
hypervisor: xen
root_device_name: /dev/sda1
ami:
us-east-1: ami-3dc56656
us-west-1: ami-db9a659f
us-west-2: ami-dd5850ed
```
---
## <a id="light-stemcells"></a> Light Stemcells
Some IaaSes (or how they are configured) limit how OS images can be imported. Here are couple of examples:
- AWS only allows creation of AMIs from running VMs on AWS
- OpenStack can be configured to disallow Glance image upload
- an IaaS may take long time to import an image making it beneficial to reuse existing images
In such cases CPI must use already imported OS image and that's where light stemcells come in. Light stemcell tarballs include additional details about already imported OS images in the `cloud_properties` section. For example light stemcells for AWS have `ami` key in the `cloud_properties` section (as shown above), that contains region-to-AMI-ID mappings. When AWS CPI's [`create_stemcell` call](cpi-api-v1.html#create-stemcell) is made, it will return matching AMI ID without doing any IaaS API calls.
---
## <a id="testing"></a> Testing
There are two test suites each stemcell is expected to pass before it's considered to be production-ready:
- shared [Stemcell Tests](https://github.com/cloudfoundry/bosh-linux-stemcell-builder/tree/master/bosh-stemcell/spec) which verify that proper packages and configurations are installed
- shared [BOSH Acceptance Tests (BATS)](https://github.com/cloudfoundry/bosh/blob/master/docs/running_tests.md#bosh-acceptance-tests-bats) (provided by the BOSH team) which verify high level Director behavior with the stemcell being used
---
[Back to Table of Contents](index.html#extend)
Previous: [Agent-CPI interactions](agent-cpi-interactions.html)