1) Quick Checklist

1. Ensure the new release is available on https://shoemaker.cc.gatech.edu/cobbler_web under Distros
2. Copy a previous Kickstart Template for the new release (e.g., copy coc-ubuntu-focal.seed to coc-ubuntu-hirsute.seed)
3. Copy a previous Repo for the new release and update the repo configuration (e.g., copy Ubuntu-20-x86_64 to Ubuntu-21-x86_64)
4. Copy a previous unmanaged Profile for the new release and update the profile config (e.g., copy Ubuntu-20-x86_64 to Ubuntu-21-x86_64)
5. Copy a previous managed Profile for the new release and create a development profile (e.g., copy Ubuntu-20-x86_64-coc-base to Ubuntu-21-x86_64-coc-base-devel)
6. Create a new System with the development profile for the new release
7. Create new base Simon streams (e.g., coc-sw-base and coc-config-base) for the new release
8. PXE boot the development system and begin developing/debugging/testing the automated deployment

2) Adding New Distro

The first step involves adding the new distribution to Shoemaker (e.g., importing a disk). This part is somewhat complicated and is best left to someone who knows what they're doing.

Click into the Distros tab and see if the desired distro is listed. If it isn't, you will need to import the image yourself. First check to make sure Shoemaker has enough space to accommodate the .iso image you need to upload. Then transfer the .iso to Shoemaker and mount it under the /mnt tree for the machine. Lastly, from the Cobbler web interface, use the "Import DVD" action and direct Cobbler to the location the .iso is mounted.

It is possible for relatively new releases that our Cobbler instance does not have updated signatures for your OS. If this is the case, log into Shoemaker and run the following command to update from Cobbler's Github:

$> cobbler signature update

As of 4/30/2024, it seems likely that the production version of Cobbler will lag behind where we want to be in terms of signatures. In this case, it is possible to manually edit /var/lib/cobbler/distro_signatures.json but, as always, you need to make sure you know what you're doing. Cobbler version 2.8.5 claims there is a cobbler signature reload command that one would expect to update the available signatures, but it does not work and you will instead need to restart the entire Cobbler daemon if you manually edit the signatures JSON file.

$> systemctl restart cobblerd

Note: It is useful to keep the .iso files available even after they have been successfully imported. Most freely available  images are stored in /var/www on Shoemaker.

3) Kickstart Template

The kickstart template/preseed provides the commands to run as the machine is kickstarted. For Ubuntu, these are all debian-based kickstarts.

Since there is not much that changes between versions of Ubuntu, start off by copying the previous known-working kickstart and work from there. Make sure to note what you name the new kickstart, as you'll need to reference that in the new profiles.

It is possible you will need to edit this kickstart once you try kickstarting a system, but worry about that later and adjust commands/directives/recipes/snippets/etc. based on your testing later on unless you really know something needs to be changed.

Once you create a golden "base kickstart" that definitely works for the main TSO deployment profiles, try to leverage Snippets instead of new kickstarts to facilitate easier code re-use and modularity.

4) Repository

Similar to the kickstarts, the repository for the distribution stays relatively the same between Ubuntu versions, so make a copy of the previous known-working version and start from there. Some things to check:

• Keep updated: It doesn't hurt to set this flag, so make sure it's set
• (Don't) Mirror Locally: We've run into issues with mirroring the repositories locally, so we usually leave this unchecked
• Apt Dist Names: This will likely start as the code for the previous iteration of Ubuntu (e.g., focal), so make sure to update all of the version codes to the new distribution name.

5) Profiles

We generally have three main profiles for an Ubuntu release: Ubuntu-##-x86_64, Ubuntu-##-x86_64-coc-base, and Ubuntu-##-x86_64-coc-base-devel. The plain profile does not apply any CoC management/configuration items and is mainly there in case we want to deploy a box with a "fresh" load of this distribution. The coc-base and coc-base-devel use our custom kickstarts and apply Simon streams to deploy systems in a TSO fashion.

As with everything else, our life is easier if we start from a known working base, so copy the plain profile over, then create the coc-base and coc-base-devel profiles as sub-profiles of the main one for the new release. The profile, however, is the first place we're going to need to do some real changes to the copied base, so make sure to update the following fields.

5.1) Fields to Update

Unmanaged Profile

• Distribution: set this to the appropriate distribution from the Distros tab
• Kickstart: leave as sample.seed
• Repos: Select and use the arrows to "add" the repository for this distribution you created

Managed Profile

Managed profiles should both be created by using "Create New Sub-profile"

• Parent Profile for both the coc-base and coc-base-devel profiles should be the main profile (so we don't have to worry too much about which distribution/repos/etc. are used).
• Management Classes: Under "Management" tab, select and use the arrows to add coc-config-base and coc-sw-base for the coc-base profile
  • Use coc-config-base::test and coc-sw-base::test for the coc-base-devel profile
• Template Files: Under "Management" tab, ensure the following line is present so that Cobbler adds the Simon configuration file on load
  /var/lib/cobbler/snippets/streams.template=/var/gtswd/etc/streams.conf

6) Systems

You'll obviously need to set up a machine to test everything on, so go ahead and spin up a VM (or set up hardware) and create a definition in the Systems tab for that machine which uses the Ubuntu-##-x86_64-coc-base-devel profile (since we're going to be developing/deploying!)

7) Streams

This document will not cover Simon streams too deeply (see the Stream Best Practices page instead), but it is worth emphasizing that you should focus on creating appropriate Simon streams for coc-config-base and coc-sw-base when you're generating the new Ubuntu release profile.

My personal preference is to create a new definition in GTSWD (e.g., mkdir x86-ubuntu-21.04) as well as empty streams for both coc-config-base and coc-sw-base in that definition (e.g., mkdir x86-Ubuntu-21.04/coc-sw-base). I then create empty devel and test flows within each of those streams (e.g., mkdir x86-Ubuntu-21.04/coc-sw-base/devel). Finally, I make a hard copy of all patches/patch directories from the release flow of the previous Ubuntu version into devel to begin development/testing. (e.g., cp -r x86-Ubuntu-20.04/coc-sw-base/release/* x86-Ubuntu-21.04/coc-sw-base/devel).

If you choose to copy and base you work off of previous versions, please note that some things may not work and some things definitely won't work. A good example is in coc-sw-base/1.dir with the template sources list for apt. Even though Cobbler knows to look into the repositories for the current release code, the base management streams from Simon overwrite the system's repository configuration. When you first copy the stream over, Simon will tell the system to look for packages in the repositories for the previous version of Ubuntu, which will obviously break things. Don't ask me how I know this. Just make sure to check everything to make sure it's working as expected when you develop streams for the new version.