Skip to content

Inital Resolute Raccoon stemcell changes #497

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
mkocher wants to merge 1 commit into
base: ubuntu-noble
Choose a base branch
from
Draft

Inital Resolute Raccoon stemcell changes #497

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions .gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,3 +14,5 @@ acceptance-tests/os-conf-release

ci/docker/VMware-ovftool-*.bundle
ci/docker/*/VMware-ovftool-*.bundle

tmp/*
3 changes: 2 additions & 1 deletion CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,8 @@
Please ensure that changes are made to any current branches. These are named
after the Ubuntu release they are based on, ex: `ubuntu-<short name>`

At the time of writing (2025-05-29) there are two "stemcell lines":
At the time of writing (2025-05-29) there are three "stemcell lines":
- `ubuntu-jammy`
- `ubuntu-noble`
- `ubuntu-resolute`

92 changes: 49 additions & 43 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,60 +3,64 @@
This repo contains tools for creating BOSH stemcells. A stemcell is a bootable
disk image that is used as a template by a BOSH Director to create VMs.

This branch (`ubuntu-resolute`) builds stemcells for **Ubuntu 26.04 LTS (Resolute)**.
For other Ubuntu releases, switch to the appropriate branch (e.g. `ubuntu-noble`
for 24.04).

## Quick Start: Building a Stemcell Locally

```bash
git clone git@github.com:cloudfoundry/bosh-linux-stemcell-builder.git
cd bosh-linux-stemcell-builder
git checkout ubuntu-noble/master
git checkout ubuntu-resolute/1.x
Copy link
Copy Markdown
Member

@aramprice aramprice Mar 26, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nit: I think the branch here should be ubuntu-resolute

Nit: Consider using git switch <branch>

mkdir -p tmp
docker build -t bosh/os-image-stemcell-builder:noble \
ci/docker/os-image-stemcell-builder-noble/
docker build -t bosh/os-image-stemcell-builder:resolute \
ci/docker/os-image-stemcell-builder-resolute/
docker run \
--privileged \
-v "$(pwd):/opt/bosh" \
--workdir /opt/bosh \
--user=1000:1000 \
-it \
bosh/os-image-stemcell-builder:noble
bosh/os-image-stemcell-builder:resolute
# You're now in the the Docker container
ulimit -n 16384 # only necessary if your host is Fedora
gem install bundler
bundle
# build OS image
bundle exec rake stemcell:build_os_image[ubuntu,noble,$PWD/tmp/ubuntu_base_image.tgz] # build OS image
bundle exec rake stemcell:build_os_image[ubuntu,resolute,$PWD/tmp/ubuntu_base_image.tgz]
# build vSphere stemcell
bundle exec rake stemcell:build_with_local_os_image[vsphere,esxi,ubuntu,noble,$PWD/tmp/ubuntu_base_image.tgz]
bundle exec rake stemcell:build_with_local_os_image[vsphere,esxi,ubuntu,resolute,$PWD/tmp/ubuntu_base_image.tgz]
```

When building a vSphere stemcell, you must download `VMware-ovftool-*.bundle`
and place it in the `ci/docker/os-image-stemcell-builder-noble/` directory. See
and place it in the `ci/docker/os-image-stemcell-builder-resolute/` directory. See
[External Assets](#external-assets) for download instructions.

### OS image

An OS image is a tarball that contains a snapshot of an OS filesystem,
including the libraries and system utilities needed by the BOSH agent; however,
it does not contain the BOSH agent nor the virtualization tools: [a subsequent
Rake task](#with-local-os-image) adds the BOSH agent and a set of
Rake task](#building-a-stemcell) adds the BOSH agent and a set of
virtualization tools to the base OS image to produce a stemcell.

The OS Image should be rebuilt when you are making changes to the packages
installed in the operating system or when making changes to the configuration
of those packages.

```bash
bundle exec rake stemcell:build_os_image[ubuntu,noble,$PWD/tmp/ubuntu_base_image.tgz]
bundle exec rake stemcell:build_os_image[ubuntu,resolute,$PWD/tmp/ubuntu_base_image.tgz]
```

The arguments to the `stemcell:build_os_image` rake task follow:

0. *`operating_system_name`* (`ubuntu`): identifies which type of OS to fetch.
Determines which package repository and packaging tool will be used to
download and assemble the files. Currently, only `ubuntu` is recognized.
0. *`operating_system_version`* (`noble`): an identifier that the system may use
to decide which release of the OS to download. Acceptable values depend on
the operating system. For `ubuntu`, use `noble`.
0. *`operating_system_version`* (`resolute`): an identifier that the system
uses to decide which release of the OS to download. For this branch, use
`resolute` (Ubuntu 26.04 LTS).
0. *`os_image_path`* (`$PWD/tmp/ubuntu_base_image.tgz`): the path to write the
finished OS image tarball to. If a file exists at this path already, it will
be overwritten without warning.
Expand All @@ -67,7 +71,7 @@ Rebuild the stemcell when you are making and testing BOSH-specific
changes such as a new BOSH agent.

```bash
bundle exec rake stemcell:build_with_local_os_image[vsphere,esxi,ubuntu,noble,$PWD/tmp/ubuntu_base_image.tgz,"0.0.8"]
bundle exec rake stemcell:build_with_local_os_image[vsphere,esxi,ubuntu,resolute,$PWD/tmp/ubuntu_base_image.tgz,"0.0.8"]
```

The arguments to `stemcell:build_with_local_os_image` are:
Expand All @@ -76,10 +80,11 @@ The arguments to `stemcell:build_with_local_os_image` are:
Determines which virtualization tools to package on top of the stemcell.
0. `hypervisor_name`: Depending on what the IAAS supports, which hypervisor to
target: `aws` → `xen-hvm`, `azure` → `hyperv`, `google` → `kvm`, `openstack` →
`kvm`, `vsphere` → `esxi`
`kvm`, `vsphere` → `esxi`, `warden` → `warden`
0. `operating_system_name` (`ubuntu`): Type of OS. Same as
0. `stemcell:build_os_image`. Can optionally include a variant suffix (`noble-fips`)
0. `operating_system_version` (`noble`): OS release. Same as
`stemcell:build_os_image`. Can optionally include a variant suffix (e.g. `resolute-fips`)
0. `operating_system_version` (`resolute`): OS release. Same as
`stemcell:build_os_image`.
0. `os_image_path` (`$PWD/tmp/ubuntu_base_image.tgz`): Path to base OS image
produced in `stemcell:build_os_image`
0. `build_number` (`0.0.8`): Stemcell version. Pro-tip: take the version number
Expand All @@ -91,17 +96,15 @@ The arguments to `stemcell:build_with_local_os_image` are:
You can find the resulting stemcell in the `tmp/` directory of the host, or in
the `/opt/bosh/tmp` directory in the Docker container. Using the above example,
the stemcell would be at
`tmp/bosh-stemcell-0.0.8-vsphere-esxi-ubuntu-noble-go_agent.tgz`. You can
upload the stemcell to a vSphere BOSH Director:
`tmp/bosh-stemcell-0.0.8-vsphere-esxi-ubuntu-resolute-go_agent.tgz`. You can
upload the stemcell to a BOSH Director:

```bash
bosh upload-stemcell tmp/bosh-stemcell-0.0.8-vsphere-esxi-ubuntu-noble-go_agent.tgz
bosh upload-stemcell tmp/bosh-stemcell-0.0.8-vsphere-esxi-ubuntu-resolute-go_agent.tgz
Copy link
Copy Markdown
Member

@aramprice aramprice Mar 26, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nit: noble has dropped -go_agent from the naming, though the current readme is out of date.

```

## Testing

_[Fixme: update Testing section to noble]_

### How to run tests for OS Images

The OS tests are meant to be run against the OS environment to which they
Expand All @@ -111,12 +114,12 @@ the rake task the first time you create your docker container, but everytime
after, as long as you do not destroy the container, you should be able to run
the specific tests.

To run the `ubuntu_noble_spec.rb` tests (**assuming you've already built the OS
To run the OS image tests (**assuming you've already built the OS
image** at the `tmp/ubuntu_base_image.tgz` and you're within the Docker
container):

cd /opt/bosh/bosh-stemcell
OS_IMAGE=/opt/bosh/tmp/ubuntu_base_image.tgz bundle exec rspec -fd spec/os_image/ubuntu_noble_spec.rb
OS_IMAGE=/opt/bosh/tmp/ubuntu_base_image.tgz bundle exec rspec -fd spec/os_image/ubuntu_spec.rb

### How to Run Tests for Stemcell

Expand Down Expand Up @@ -163,7 +166,7 @@ OSX=true OS_IMAGE=/opt/bosh/tmp/ubuntu_base_image.tgz bundle exec rspec spec/ --

### How to run tests for BOSH Linux Stemcell Builder

The BOSH Linux Stemcell Builder code itself can be tested with the following command's:
The BOSH Linux Stemcell Builder code itself can be tested with the following commands:

```shell
bundle install --local
Expand All @@ -189,7 +192,7 @@ If you find yourself debugging any of the above processes, here is what you need
Example usage:

```shell
bundle exec rake stemcell:build_os_image[ubuntu,noble,$PWD/tmp/ubuntu_base_image.tgz] resume_from=rsyslog_config
bundle exec rake stemcell:build_os_image[ubuntu,resolute,$PWD/tmp/ubuntu_base_image.tgz] resume_from=rsyslog_config
```

## Pro Tips
Expand All @@ -199,32 +202,35 @@ If you find yourself debugging any of the above processes, here is what you need
in section `How to run tests for OS Images`
* If the Stemcell has been built and you are only updating tests, you do not
need to re-build the stemcell. You can simply rerun the tests (without
rebuilding Stemcell. Details in section `How to run tests for Stemcell`
rebuilding Stemcell). Details in section `How to run tests for Stemcell`
* It's possible to verify OS/Stemcell changes without making a deployment using
the stemcell. For a vSphere-specific Ubuntu stemcell, the filesytem is
the stemcell. For a vSphere-specific Ubuntu stemcell, the filesystem is
available at `/mnt/stemcells/vsphere/esxi/ubuntu/work/work/chroot`

## External Assets

The ovftool installer from VMWare can be found at
[my.vmware.com](https://my.vmware.com/group/vmware/details?downloadGroup=OVFTOOL410&productId=489).

The ovftool installer must be copied into the [ci/docker/os-image-stemcell-builder-noble](https://github.com/cloudfoundry/bosh-linux-stemcell-builder/tree/master/ci/docker/os-image-stemcell-builder) next to the Dockerfile or you will receive the error
The OVF Tool is only required for building **vSphere** stemcells. Download
"OVF Tool for Linux Zip" from
[Broadcom's developer portal](https://developer.broadcom.com/tools/open-virtualization-format-ovf-tool/latest).

Step 24/30 : ADD ${OVF_TOOL_INSTALLER} /tmp/ovftool_installer.bundle
ADD failed: stat /var/lib/docker/tmp/docker-builder389354746/VMware-ovftool-4.1.0-2459827-lin.x86_64.bundle: no such file or directory

## Rebuilding the Docker Image
Extract the zip and place the resulting `ovftool/` directory inside the Docker
build context so that the Dockerfile's `COPY ovftool/ /usr/lib/vmware-ovftool/`
can find it:

The Docker image is published to
[`bosh/os-image-stemcell-builder`](https://hub.docker.com/r/bosh/os-image-stemcell-builder/).
You will need the ovftool installer present on your filesystem.
```bash
cd ci/docker/os-image-stemcell-builder-resolute/
unzip ~/Downloads/VMware-ovftool-*.zip # creates ovftool/ in the current directory
```

Rebuild the container with the `build` script...
The `ovftool/` directory is already in `.gitignore` and will not be committed.

./build os-image-stemcell-builder
## Rebuilding the Docker Image

When ready, `push` to DockerHub and use the credentials from LastPass...
You will need the `ovftool/` directory present in
`ci/docker/os-image-stemcell-builder-resolute/` (see [External Assets](#external-assets)
above). Then build the image:

cd os-image-stemcell-builder
./push
```bash
docker build -t bosh/os-image-stemcell-builder:resolute \
ci/docker/os-image-stemcell-builder-resolute/
```
8 changes: 5 additions & 3 deletions Rakefile
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,12 +12,13 @@ namespace :stemcell do
require 'bosh/stemcell/stage_collection'
require 'bosh/stemcell/stage_runner'

os_image_path = File.expand_path(args.os_image_path)
definition = Bosh::Stemcell::Definition.for('null', 'null', args.operating_system_name, args.operating_system_version)
environment = Bosh::Stemcell::BuildEnvironment.new(
ENV.to_hash,
definition,
'',
args.os_image_path,
os_image_path,
)
collection = Bosh::Stemcell::StageCollection.new(definition)
runner = Bosh::Stemcell::StageRunner.new(
Expand All @@ -34,7 +35,7 @@ namespace :stemcell do
runner: runner,
archive_handler: archive_handler,
)
builder.build(args.os_image_path)
builder.build(os_image_path)

sh(environment.os_image_rspec_command)
rescue RuntimeError => e
Expand Down Expand Up @@ -105,12 +106,13 @@ namespace :stemcell do

args.with_defaults(build_number: '0000')

os_image_path = File.expand_path(args.os_image_path)
definition = Bosh::Stemcell::Definition.for(args.infrastructure_name, args.hypervisor_name, args.operating_system_name, args.operating_system_version)
environment = Bosh::Stemcell::BuildEnvironment.new(
ENV.to_hash,
definition,
args.build_number,
args.os_image_path,
os_image_path,
)

sh(environment.os_image_rspec_command)
Expand Down
19 changes: 19 additions & 0 deletions bosh-stemcell/image-metalinks/ubuntu-resolute.meta4
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
<metalink xmlns="urn:ietf:params:xml:ns:metalink">
<file name="ubuntu-resolute.tgz">
<hash type="sha-512">placeholder-update-when-resolute-os-image-is-published</hash>
<hash type="sha-256">placeholder</hash>
<hash type="sha-1">placeholder</hash>
<size>0</size>
<url>https://storage.googleapis.com/bosh-os-images/ubuntu-resolute/ubuntu-resolute.tgz</url>
<version>0.0.0</version>
</file>
<file name="usn-log.json">
<hash type="sha-512">placeholder</hash>
<hash type="sha-256">placeholder</hash>
<size>1</size>
<url>https://storage.googleapis.com/bosh-os-images/ubuntu-resolute/usn-log.json</url>
<version>0.0.0</version>
</file>
<generator>metalink-repository-resource/0.0.0</generator>
<published>1970-01-01T00:00:00Z</published>
</metalink>
2 changes: 1 addition & 1 deletion bosh-stemcell/lib/bosh/stemcell/build_environment.rb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -141,7 +141,7 @@ def build_time_settings
end

def operating_system_spec_name
"#{operating_system.name}"
operating_system.name
end

def prepare_build_path
Expand Down
10 changes: 5 additions & 5 deletions bosh-stemcell/spec/assets/dpkg-list-ubuntu-kernel.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
linux-generic
linux-headers-6.8
linux-headers-6.8-generic
linux-headers-7.0
linux-headers-7.0-generic
linux-headers-generic
linux-image-6.8-generic
linux-image-7.0-generic
linux-image-generic
linux-modules-6.8-generic
linux-modules-extra-6.8-generic
linux-main-modules-zfs-7.0-generic
linux-modules-7.0-generic
Loading
Loading