News, tips, partners, and perspectives for the Oracle Solaris operating system
-
Technologies / Oracle Solaris 11
May 27, 2020
Building Custom Solaris Images for Oracle Cloud Infrastructure
With this month's release of Oracle Solaris 11.4.21, we're making it easy for Solaris users of Oracle Cloud Infrastructure (OCI) to build custom images for use in your tenancies by releasing the tooling we have used to build the Solaris 11.4 images that are available in the Oracle Cloud Marketplace. We build these images using the Solaris Distribution Constructor tool, distro_const(8), which we use to build all of the Solaris 11 media images for distribution. Some of you may even remember that back in the OpenSolaris days of the late 2000's, distro_const could be used to create Solaris images for import into VirtualBox. That was removed before we integrated the tooling into Solaris 11 as it relied on a very complex and slow process of driving a VirtualBox guest to produce a VDI or VMDK image. This time, we're building the images directly so it's fast and reliable. The new feature largely re-uses existing code that's used for building installation images, we just had to add a couple of new distro_const checkpoints to create a labeled lofi(4d) device for building the disk image, and to convert the image to a format that's importable to OCI. distro_const can produce either QCOW2 or VMDK images (it can also produce a raw disk image file if that's desired, though that should be very uncommon; you'd need to convert it to one of the other formats for import to OCI). QCOW2 is the default, and relies on the qemu-img(1) tool, which we now provide as part of Solaris (we are not providing all of QEMU, just the qemu-img tool). qemu-img will be automatically installed as a required dependency of the distribution-constructor package. To produce a VMDK file, you must install VirtualBox for Solaris, as distro_const uses the VBoxManage convertfromraw command to generate the VMDK file.
There are a several prerequisites to prepare for before you set out to build your own custom images.
- A reminder that that OCI is x86 only, so building SPARC images isn't possible.
- Decide whether you're building a custom image to run on a VM or on bare metal, as one Solaris image can't run both ways at present. If you're building a VM image, you need to build it either on an OCI VM, or on a system that's set up to use old-style BIOS for booting. If you're building a bare metal image, then you'll need either an OCI bare metal system or your own system (any x86 hardware that's supported with Oracle Solaris is expected to work) that's configured to boot using UEFI firmware. An appropriately configured VirtualBox guest can be used for either case.
- You'll need a ZFS pool with at least 60 GB free to build a standard-size OCI image that has a 50 GB root volume. If you're wanting to make your root pool larger (remember that OCI limits custom images at this writing to 400 GB) then you'll need even more space.
- Of course, you must install or upgrade to Solaris 11.4.21.
- Ensure you have the Distribution Constructor tool installed, you can check with pkg info distribution-constructor.
- You'll need access to the Solaris 11 support package repository, either your own clone or the master from pkg.oracle.com. If using the pkg.oracle.com repository directly, then you will need your key and certificate for access to the repository.
Once you've sorted all of that, make a copy of /usr/share/distro_const/dc_diskimage_x86.xml. This is the sample manifest that drives the image build process. There are several edits you'll need to make to the manifest before using it:
- At line 83, specify the name of the ZFS pool where you'll be building the image. If your root pool is named rpool and has enough space as noted above, then you can leave the default.
- At line 137, specify the URL for your Solaris support repository. If you're using the pkg.oracle.com repository, you'll also need to add a credential element inside the publisher to configure your key and certificate for use, for example:
<publisher name="solaris">
<origin name="https://pkg.oracle.com/solaris/support">
<credentials>
<key src="/export/home/opc/pkg.oracle.com.key.pem"/>
<cert src="/export/home/opc/pkg.oracle.com.certificate.pem"/>
</credentials>
</origin>
</publisher>
- At line 165, you can customize the list of packages that should be installed. The default solaris-cloud-guest group package provides a minimal system with some additional software that's either required or useful for running in the cloud, especially cloudbase-init, which is used to perform configuration of the image at boot time.
- At line 177, you likely will want to customize the package publisher to be used by the image after it's deployed. Providing the support repository credentials here will usually be a good idea.
- At line 210, if you need to modify the default root pool size, this is where you'll do it. OCI allows resize of deployed boot volumes, but at this time you can only do so for boot volumes that aren't attached to a compute instance.
- If you want to produce a VMDK image, modify line 283 to select that image type as output.
- Finally, around line 293, you can specify additional SMF profiles to be applied to the image for configuration. If you're building a VM image, you'll need to uncomment the configuration element for the emulated_oci.xml profile so that the guest will use DHCP to configure its network interface. Bare metal images boot over iSCSI with DHCP automatically and don't require this profile.
At this point you can save the manifest, then build an image with the command (this must be done as root, or preferably with an account that has the Distribution Constructor RBAC profile assigned):
# distro_const build dc_diskimage_x86.xml
The construction process will run for a while and, assuming it was successful, will print out a path to the resulting QCOW2 image file. Here's output from a sample run:
# distro_const build dc_diskimage_x86.xml 18:43:31 Build datasets successfully setup 18:43:31 Simple log: /rpool1/dc/diskimage/logs/simple-log.2020-05-22.18:43 18:43:31 Detail Log: /rpool1/dc/diskimage/logs/detail-log.2020-05-22.18:43 18:43:31 Saving credential file pkg.oracle.com.key.pem 18:43:31 Saving credential file pkg.oracle.com.certificate.pem 18:43:31 === Executing Setup Image Target Checkpoint === 18:43:40 Saving credential file pkg.oracle.com.key.pem 18:43:40 Saving credential file pkg.oracle.com.certificate.pem 18:43:40 Creating IPS image 18:46:00 Installing packages from: 18:46:00 solaris 18:46:00 origin: https://pkg.oracle.com/solaris/support/ 18:47:50 The following licenses have been accepted and not displayed. 18:47:50 Please review the licenses for the following packages post-install: 18:47:50 release/notices 18:47:50 Package licenses may be viewed using the command: 18:47:50 pkg info --licenseDOWNLOAD PKGS FILES XFER (MB) SPEED Completed 508/508 76878/76878 511.1/511.1 954k/s PHASE ITEMS Installing new actions 102574/102574 Updating package state database Done Updating package cache 0/0 Updating image state Done Creating fast lookup database Done Updating package cache 1/1 19:01:06 Setting post-install publishers to: 19:01:06 solaris 19:01:06 origin: http://pkg.oracle.com/solaris/release 19:01:20 === Executing Disk Image Pre-Package Image Modification Checkpoint === 19:01:20 Preloading SMF repository 19:01:47 Applying SMF profile: /usr/share/distro_const/profile/oci.xml to layer system 19:02:23 === Executing Create Disk Image Checkpoint === 19:02:25 Converting to qcow2 19:10:46 Disk image successfully created: /rpool1/dc/diskimage/media/solaris_diskimage.qcow2
Now, to use the image, you'll need to upload it to OCI's object store and then import the object as a custom image to your tenancy. The OCI documentation on importing Linux images generally applies to Solaris images, but since we do not currently provide drivers needed for Paravirtualized mode, there are a few import points to understand:
- If you've built a bare metal image, it must be imported in Native mode.
- If you've build a VM image, it must be imported in Emulated mode.
- Solaris bare metal images are currently compatible with all of OCI's Intel CPU shapes, but not AMD shapes. It's usually a good idea to edit the image details to remove shapes that aren't supported so users don't try to launch an image on shapes that can't work.
We've covered the basics of building your own image here, but you can do much more complex customization of the image contents using your own checkpoints, including installing your own applications. The custom script documentation for distro_const is also applicable to building cloud images, and that's how we recommend adding software that's not part of Solaris. If you decide to use that capability, you'll usually want to place the script checkpoint after the set-ips-attributes checkpoint, as is shown in the documentation, as this is the point when the image will have the operating system installed and prepared for configuration, before it's processed into a bootable state. Good luck!
I had already given up on Solaris x86/64 in the cloud and in general. I still used the old VM and BM images from 2018 to avoid the OCI marketplace restrictions. But I can already feel the passion return after reading your article :-)
Ralf