Latest revision as of 17:53, 12 September 2024

Distributing Kickstart Files as OCI Artifacts

This is a proposed Change for Fedora Linux.
This document represents a proposed Change. As part of the Changes process, proposals are publicly announced in order to receive community feedback. This proposal will only be implemented if approved by the Fedora Engineering Steering Committee.

Summary

Fedora distributed as bootable container ships via OCI registry. Installation is typically done by conversion into a VM image or ISO installer via osbuild (image builder), however, booting from network is a useful workflow for bare-metal fleet deployments. Required files to perform such installation are not available in the OCI repository that could be fetched from registry in a similar manner as the bootable container.

As of today, files are only available in the Fedora RPM repository and the installation workflow would be cumbersome to find appropriate RPM repo version and extract needed files instead of fetching all the needed assets from the registry only. The change introduces a new OCI repository with the files in question for each Fedora stable version.

The change is complementary to the current distribution of kickstart, we are not proposing to stop distributing these files in dnf repositories.

Owner

Name: Ina Panova, Lukáš Zapletal
Email: <ipanova@redhat.com>, <lzap@redhat.com>

Current status

Targeted release: Fedora Linux 42
Last updated: 2024-09-12
Announced
Discussion thread
FESCo issue: <will be assigned by the Wrangler>
Tracker bug: <will be assigned by the Wrangler>
Release notes tracker: <will be assigned by the Wrangler>

Detailed Description

Fedora bootable container is shipped via OCI registries without any supplementary files for automated kickstart installations. The files needed for this workflow are typically: bootloader, anaconda kernel, initramdisk and anaconda main image. These files can be found in regular Fedora RPM repository, for example in case of x86_64 architecture:

Some files are distributed unsigned in the images/ directory, others are signed and need to be extracted from RPM packages. A complete ISO "netboot" image is also available for network installations, the image can be customized using mkksiso tool found in Fedora.

The main goal of this change is to start publishing the mentioned files as OCI artifacts for each Fedora version and architecture. Buildah/Podman will be used for creating such manifest and pushing it to OCI registry and the process will be integrated into current or upcoming (Konflux) release processes.

There is currently no support for downloading OCI artifacts with podman but the feature is currently being discussed and worked on upstream. However, Fedora contains golang-oras tool which understands the OCI artifact format. This tool can already be used by Fedora users to consume the content:

$ oras pull quay.io/pulp/fedora-kickstart-artifacts:40-amd64
Downloading 8ea1dd040e97 initrd.img
Downloading 80c3fe2ae106 boot.iso
Downloading a3b7052d7b2f grubx64.efi
Downloaded  a3b7052d7b2f grubx64.efi
Downloading fff4b2feeef3 pxelinux.0
Downloaded  fff4b2feeef3 pxelinux.0
Downloading 4773d74d87c2 shimx64.efi
Downloaded  4773d74d87c2 shimx64.efi
Downloading 09cf5df01619 vmlinuz
Downloaded  80c3fe2ae106 boot.iso
Downloaded  09cf5df01619 vmlinuz
Downloaded  8ea1dd040e97 initrd.img
Restored    80c3fe2ae106 install.img
Pulled quay.io/pulp/fedora-kickstart-artifacts:40-amd64
Digest: sha256:0306e10fd556e12ce8c3674150bceb88c0917b74b63c37eecc17070b3b30003b

Alternatively, the content can be downloaded via skopeo tool with some scripting involving file renaming.

The proposed repository for the content is: quay.io/fedora/kickstart-artifacts and tag convention will be N where N is Fedora version with manifest index for all supported architectures pointing to tags in the form of N-arch. Only stable and N-1 Fedora versions will be kept for storage reasons and old artifacts will be regularly removed and garbage collected. For more info, read manifest specification.

Files are currently being published at a temporary space: quay.io/pulp/fedora-kickstart-artifacts and can be consumed from there. The pipeline currently lives on Fedora's gitlab.

Benefit to Fedora

The change solves the situation for Fedora bootable containers users who currently need to find matching Fedora RPM repositories and use various tools like curl or rpm2cpio and cpio to download required files. This will significantly simplify provisioning workflows of Fedora systems en-masse via automation tools like Ansible or Foreman. All files will be also signed by Fedora GPG keys for increased security.

Users of regular (RPM) Fedora spin will benefit as well since bare-metal provisioning workflows, scripts or tools can be further simplified. Additionally, many provisioning systems (Beaker, Foreman) use one shim/grub for installing all OS versions which does not work reliably when SecureBoot is turned on. Published files can be easily downloaded for each OS version.

The newly published content is planned to be integrated with other open source projects: Foreman, Pulp and Ansible. This is out of scope for this change.

Scope

Proposal owners: prepare CI/CD pipeline for fully automated build and push of kickstart artifacts, integrate the published repositories with related open-source project workflows Foreman and Pulp

Release engineering: create new repository in fedora namespace #12152 and assistance with integrating the new pipeline into the Fedora workflow

Documentation

The newly created repository will be features in documentation of several upstream projects that will make use of it:

osbuild
foreman
pulp

Release Notes

TBD

@@ Line 4: / Line 4: @@
 == Summary ==
-Fedora distributed as bootable container ships via [https://quay.io/repository/fedora/fedora-bootc?tab=tags OCI registry]. Installation is typically done by conversion into a VM image or ISO installer via [https://osbuild.org/ osbuild] (image builder), however, booting from network is a useful workflow for bare-metal fleet deployments. Required files to perform such installation are not available in the OCI repository.
+Fedora distributed as bootable container ships via [https://quay.io/repository/fedora/fedora-bootc?tab=tags OCI registry]. Installation is typically done by conversion into a VM image or ISO installer via [https://osbuild.org/ osbuild] (image builder), however, booting from network is a useful workflow for bare-metal fleet deployments. Required files to perform such installation are not available in the OCI repository that could be fetched from registry in a similar manner as the bootable container.
+As of today, files are only available in the Fedora RPM repository and the installation workflow would be cumbersome to find appropriate RPM repo version and extract needed files instead of fetching all the needed assets from the registry only. The change introduces a new OCI repository with the files in question for each Fedora stable version.
+The change is complementary to the current distribution of kickstart, we are not proposing to stop distributing these files in dnf repositories.
 == Owner ==
@@ Line 14: / Line 19: @@
 == Current status ==
-[[Category:ChangePageIncomplete]]
+[[Category:ChangeAnnounced]]
-<!-- When your change proposal page is completed and ready for review and announcement -->
-<!-- remove Category:ChangePageIncomplete and change it to Category:ChangeReadyForWrangler -->
-<!-- The Wrangler announces the Change to the devel-announce list and changes the category to Category:ChangeAnnounced (no action required) -->
-<!-- After review, the Wrangler will move your page to Category:ChangeReadyForFesco... if it still needs more work it will move back to Category:ChangePageIncomplete-->
 [[Category:SelfContainedChange]]
 * Targeted release: [https://docs.fedoraproject.org/en-US/releases/f42/ Fedora Linux 42]
 * Last updated: {{REVISIONYEAR}}-{{REVISIONMONTH}}-{{REVISIONDAY2}}
-* [Announced]
+* [https://lists.fedoraproject.org/archives/list/devel-announce@lists.fedoraproject.org/thread/IN4SB5QANHIN3GVV5VCSES5OFTCCRHZR/ Announced]
-* [<will be assigned by the Wrangler> Discussion thread]
+* [https://discussion.fedoraproject.org/t/f42-change-proposal-distributing-kickstart-files-as-oci-artifacts-self-contained/131150 Discussion thread]
 * FESCo issue: <will be assigned by the Wrangler>
 * Tracker bug: <will be assigned by the Wrangler>
@@ Line 44: / Line 44: @@
 Some files are distributed unsigned in the `images/` directory, others are signed and need to be extracted from RPM packages. A complete ISO "netboot" image is also available for network installations, the image can be customized using `mkksiso` tool found in Fedora.
-The main goal of this change is to start publishing the mentioned file as OCI commits or also known [https://oras.land/docs/concepts/artifact/ OCI artifacts] for each Fedora version and architecture. Buildah/Podman will be used for creating such manifest and [https://gitlab.com/fedora/bootc/netboot/netboot/-/blob/main/push.sh?ref_type=heads pushing it] to OCI registry.
+The main goal of this change is to start publishing the mentioned files as [https://oras.land/docs/concepts/artifact/ OCI artifacts] for each Fedora version and architecture. Buildah/Podman will be used for creating such manifest and [https://gitlab.com/fedora/bootc/netboot/netboot/-/blob/main/push.sh?ref_type=heads pushing it] to OCI registry and the process will be integrated into current or upcoming (Konflux) release processes.
-There are currently no support for downloading OCI artifacts with podman and the feature is being discussed upstream, however, Fedora contains `golang-oras` tool which understands the OCI artifact format. This tool can be used by Fedora users to consume the content:
+There is currently no support for downloading OCI artifacts with podman but the feature is currently being discussed and worked on upstream. However, Fedora contains `golang-oras` tool which understands the OCI artifact format. This tool can already be used by Fedora users to consume the content:
-```
+<pre>
-$ oras pull quay.io/lzapletal/fedora-bootfiles:40-amd64
+$ oras pull quay.io/pulp/fedora-kickstart-artifacts:40-amd64
 Downloading 8ea1dd040e97 initrd.img
 Downloading 80c3fe2ae106 boot.iso
 Downloading a3b7052d7b2f grubx64.efi
-Downloaded  80c3fe2ae106 boot.iso
+Downloaded  a3b7052d7b2f grubx64.efi
 Downloading fff4b2feeef3 pxelinux.0
-Downloaded  a3b7052d7b2f grubx64.efi
+Downloaded  fff4b2feeef3 pxelinux.0
 Downloading 4773d74d87c2 shimx64.efi
-Downloaded  fff4b2feeef3 pxelinux.0
+Downloaded  4773d74d87c2 shimx64.efi
 Downloading 09cf5df01619 vmlinuz
-Downloaded  4773d74d87c2 shimx64.efi
+Downloaded  80c3fe2ae106 boot.iso
 Downloaded  09cf5df01619 vmlinuz
 Downloaded  8ea1dd040e97 initrd.img
 Restored    80c3fe2ae106 install.img
-Pulled quay.io/lzapletal/fedora-bootfiles:40-amd64
+Pulled quay.io/pulp/fedora-kickstart-artifacts:40-amd64
 Digest: sha256:0306e10fd556e12ce8c3674150bceb88c0917b74b63c37eecc17070b3b30003b
-```
+</pre>
-There is a [https://github.com/pulp/netboot-oci-specs/blob/main/netboot-oci-artifacts.md manifest specification] of such content describing required annotations.
+Alternatively, the content can be downloaded via `skopeo` tool with [https://github.com/theforeman/nboci-files/blob/main/artifact-pull.py some scripting] involving file renaming.
-== Feedback ==
+The proposed repository for the content is: `quay.io/fedora/kickstart-artifacts` and tag convention will be `N` where N is Fedora version with manifest index for all supported architectures pointing to tags in the form of `N-arch`. Only stable and N-1 Fedora versions will be kept for storage reasons and old artifacts will be regularly removed and garbage collected. For more info, read [https://github.com/pulp/netboot-oci-specs/blob/main/netboot-oci-artifacts.md manifest specification].
-<!-- Summarize the feedback from the community and address why you chose not to accept proposed alternatives. This section is optional for all change proposals but is strongly suggested. Incorporating feedback here as it is raised gives FESCo a clearer view of your proposal and leaves a good record for the future. If you get no feedback, that is useful to note in this section as well. For innovative or possibly controversial ideas, consider collecting feedback before you file the change proposal. -->
+Files are currently being published at a temporary space: [https://quay.io/repository/pulp/fedora-kickstart-artifacts?tab=tags&tag=latest quay.io/pulp/fedora-kickstart-artifacts] and can be consumed from there. The pipeline currently lives on Fedora's gitlab.
 == Benefit to Fedora ==
-<!-- What is the benefit to the distribution?  Will the software we generate be improved? How will the process of creating Fedora releases be improved?
-      Be sure to include the following areas if relevant:
-      If this is a major capability update, what has changed?
-           For example: This change introduces Python 5 that runs without the Global Interpreter Lock and is fully multithreaded.
-      If this is a new functionality, what capabilities does it bring?
-           For example: This change allows package upgrades to be performed automatically and rolled-back at will.
-      Does this improve some specific package or set of packages?
-           For example: This change modifies a package to use a different language stack that reduces install size by removing dependencies.
-      Does this improve specific Spins or Editions?
-           For example: This change modifies the default install of Fedora Workstation to be more in line with the base install of Fedora Server.
-      Does this make the distribution more efficient?
-           For example: This change replaces thousands of individual %post scriptlets in packages with one script that runs at the end.
-      Is this an improvement to maintainer processes?
-           For example: Gating Fedora packages on automatic QA tests will make rawhide more stable and allow changes to be implemented more smoothly.
-      Is this an improvement targeted as specific contributors?
-           For example: Ensuring that a minimal set of tools required for contribution to Fedora are installed by default eases the onboarding of new contributors.
-     When a Change has multiple benefits, it's better to list them all.
+The change solves the situation for Fedora bootable containers users who currently need to find matching Fedora RPM repositories and use various tools like `curl` or `rpm2cpio` and `cpio` to download required files. This will significantly simplify provisioning workflows of Fedora systems en-masse via automation tools like Ansible or Foreman. All files will be also signed by Fedora GPG keys for increased security.
-     Consider these Change pages from previous editions as inspiration:
+Users of regular (RPM) Fedora spin will benefit as well since bare-metal provisioning workflows, scripts or tools can be further simplified. Additionally, many provisioning systems (Beaker, Foreman) use one shim/grub for installing all OS versions which does not work reliably when SecureBoot is turned on. Published files can be easily downloaded for each OS version.
-     https://fedoraproject.org/wiki/Changes/Annobin (low-level and technical, invisible to users)
-     https://fedoraproject.org/wiki/Changes/ParallelInstallableDebuginfo (low-level, but visible to advanced users)
+The newly published content is planned to be integrated with other open source projects: Foreman, Pulp and Ansible. This is out of scope for this change.
-     https://fedoraproject.org/wiki/Changes/VirtualBox_Guest_Integration (primarily a UX change)
-     https://fedoraproject.org/wiki/Changes/NoMoreAlpha (an improvement to distro processes)
-     https://fedoraproject.org/wiki/Changes/perl5.26 (major upgrade to a popular software stack, visible to users of that stack)
--->
 == Scope ==
-* Proposal owners:
-<!-- What work do the feature owners have to accomplish to complete the feature in time for release?  Is it a large change affecting many parts of the distribution or is it a very isolated change? What are those changes?-->
-* Other developers: <!-- REQUIRED FOR SYSTEM WIDE CHANGES -->
+* Proposal owners: prepare CI/CD pipeline for fully automated build and push of kickstart artifacts, integrate the published repositories with related open-source project workflows [https://theforeman.org/ Foreman] and [https://pulpproject.org/ Pulp]
-<!-- What work do other developers have to accomplish to complete the feature in time for release?  Is it a large change affecting many parts of the distribution or is it a very isolated change? What are those changes?-->
-* Release engineering: [https://pagure.io/releng/issues #Releng issue number] <!-- REQUIRED FOR SYSTEM WIDE CHANGES -->
+* Release engineering: create new repository in fedora namespace [https://pagure.io/fedora-infrastructure/issue/12152 #12152] and assistance with integrating the new pipeline into the Fedora workflow
-<!-- Does this feature require coordination with release engineering (e.g. changes to installer image generation or update package delivery)?  Is a mass rebuild required?  include a link to the releng issue.
-The issue is required to be filed prior to feature submission, to ensure that someone is on board to do any process development work and testing and that all changes make it into the pipeline; a bullet point in a change is not sufficient communication -->
-* Policies and guidelines: N/A (not needed for this Change) <!-- REQUIRED FOR SYSTEM WIDE CHANGES -->
+== Documentation ==
-<!-- Do the packaging guidelines or other documents need to be updated for this feature?  If so, does it need to happen before or after the implementation is done?  If a FPC ticket exists, add a link here. Please submit a pull request with the proposed changes before submitting your Change proposal. -->
-* Trademark approval: N/A (not needed for this Change)
-<!-- If your Change may require trademark approval (for example, if it is a new Spin), file a ticket ( https://pagure.io/Fedora-Council/tickets/issues ) requesting trademark approval from the Fedora Council. This approval will be done via the Council's consensus-based process. -->
-* Alignment with the Fedora Strategy:
-<!-- Does your proposal align with the current Fedora Strategy: https://discussion.fedoraproject.org/t/fedora-strategy-2028-february-march-planning-work-and-roadmap-til-flock/43618 ? It's okay if it doesn't, but it's something to consider -->
-== Upgrade/compatibility impact ==
-<!-- What happens to systems that have had a previous versions of Fedora installed and are updated to the version containing this change? Will anything require manual configuration or data migration? Will any existing functionality be no longer supported? -->
-<!-- REQUIRED FOR SYSTEM WIDE CHANGES -->
-== Early Testing (Optional) ==
-<!-- This is an optional step for system-wide changes to avail of. If you would like to build an initial proof of concept of your change and have a member of Fedora QA help you write and/or run some initial basic tests on your code, please email tests@fedoraproject.org and include the link to your change proposal. This step is *optional*. -->
-Do you require 'QA Blueprint' support? Y/N <!-- Optional Step for System-Wide Changes only -->
-== How To Test ==
-<!-- This does not need to be a full-fledged document. Describe the dimensions of tests that this change implementation is expected to pass when it is done.  This can be based off of the above section if early testing has been completed. If it needs to be tested with different hardware or software configurations, indicate them.  The more specific you can be, the better the community testing can be.
-Remember that you are writing this how to for interested testers to use to check out your change implementation - documenting what you do for testing is OK, but it's much better to document what *I* can do to test your change.
-A good "how to test" should answer these four questions:
-. What special hardware / data / etc. is needed (if any)?
-. How do I prepare my system to test this change? What packages
-need to be installed, config files edited, etc.?
-. What specific actions do I perform to check that the change is
-working like it's supposed to?
-. What are the expected results of those actions?
--->
-<!-- REQUIRED FOR SYSTEM WIDE CHANGES -->
-== User Experience ==
-<!-- If this change proposal is noticeable by users, how will their experiences change as a result?
- This section partially overlaps with the Benefit to Fedora section above. This section should be primarily about the User Experience, written in a way that does not assume deep technical knowledge. More detailed technical description should be left for the Benefit to Fedora section.
- Describe what Users will see or notice, for example:
-  - Packages are compressed more efficiently, making downloads and upgrades faster by 10%.
-  - Kerberos tickets can be renewed automatically. Users will now have to authenticate less and become more productive. Credential management improvements mean a user can start their work day with a single sign on and not have to pause for reauthentication during their entire day.
- - Libreoffice is one of the most commonly installed applications on Fedora and it is now available by default to help users "hit the ground running".
- - Green has been scientifically proven to be the most relaxing color. The move to a default background color of green with green text will result in Fedora users being the most relaxed users of any operating system.
--->
-== Dependencies ==
-<!-- What other packages (RPMs) depend on this package?  Are there changes outside the developers' control on which completion of this change depends?  In other words, completion of another change owned by someone else and might cause you to not be able to finish on time or that you would need to coordinate?  Other upstream projects like the kernel (if this is not a kernel change)? -->
-<!-- REQUIRED FOR SYSTEM WIDE CHANGES -->
-== Contingency Plan ==
-<!-- If you cannot complete your feature by the final development freeze, what is the backup plan?  This might be as simple as "Revert the shipped configuration".  Or it might not (e.g. rebuilding a number of dependent packages).  If you feature is not completed in time we want to assure others that other parts of Fedora will not be in jeopardy.  -->
+The newly created repository will be features in documentation of several upstream projects that will make use of it:
-* Contingency mechanism: (What to do?  Who will do it?) N/A (not a System Wide Change)  <!-- REQUIRED FOR SYSTEM WIDE CHANGES -->
-<!-- When is the last time the contingency mechanism can be put in place?  This will typically be the beta freeze. -->
-* Contingency deadline: N/A (not a System Wide Change)  <!-- REQUIRED FOR SYSTEM WIDE CHANGES -->
-<!-- Does finishing this feature block the release, or can we ship with the feature in incomplete state? -->
-* Blocks release? N/A (not a System Wide Change), Yes/No <!-- REQUIRED FOR SYSTEM WIDE CHANGES -->
+* osbuild
-== Documentation ==
+* foreman
-<!-- Is there upstream documentation on this change, or notes you have written yourself?  Link to that material here so other interested developers can get involved. -->
+* pulp
-<!-- REQUIRED FOR SYSTEM WIDE CHANGES -->
-N/A (not a System Wide Change)
 == Release Notes ==
-<!-- The Fedora Release Notes inform end-users about what is new in the release.  Examples of past release notes are at https://docs.fedoraproject.org/en-US/fedora/latest/release-notes/ -->
-<!-- The release notes also help users know how to deal with platform changes such as ABIs/APIs, configuration or data file formats, or upgrade concerns.  If there are any such changes involved in this change, indicate them here.  A link to upstream documentation will often satisfy this need.  This information forms the basis of the release notes edited by the documentation team and shipped with the release.
-Release Notes are not required for initial draft of the Change Proposal but has to be completed by the Change Freeze.
+TBD
--->

Search

Changes/KickstartOciArtifacts: Difference between revisions