diff --git a/doc/source/developer_resources/starlingx_patching.rst b/doc/source/developer_resources/starlingx_patching.rst
index 3f7d92bf4..e06c3fb3c 100644
--- a/doc/source/developer_resources/starlingx_patching.rst
+++ b/doc/source/developer_resources/starlingx_patching.rst
@@ -21,7 +21,7 @@ vulnerabilities, feature enhancements, etc.
StarlingX patching supports two kinds of patches:
-* *In-service* patches, which don’t require a reboot for those hosts to be
+* *In-service* patches, which do not require a reboot for those hosts to be
patched. Only affected processes need to be restarted.
* *Reboot-required* patches, which require a host reboot operation to make the
@@ -42,8 +42,13 @@ A StarlingX patch includes one or more rpms that contain some updates to the
system. Before starting to generate a patch, you must identify rpms to be
installed against the deployed system.
+Starting at StarlingX 10.0, the patches will now be built and applied using
+|USM|, which means the patch process will be simplified as there is no need to
+deliver ostree deltas anymore and just debian packages (.deb's). Legacy
+patching will no longer be supported.
+
*****************************
-Identify rpms to be installed
+Identify debs to be Installed
*****************************
First, figure out the software version of the deployed system, using either
@@ -58,7 +63,7 @@ Use Horizon GUI
Discover your OAM floating IP address with the :command:`system oam-show` command.
-#. Log in to Horizon with an admin/<sysadmin-password>.
+#. Log in to Horizon with an ``admin/<sysadmin-password>``.
#. Identify the software version of the deployed system by clicking
:menuselection:`Admin > Platform > System Configuration` and clicking the
@@ -72,7 +77,7 @@ Use StarlingX CLI
node to show the software version. In the example below, the software version
is "19.09".
- ::
+ .. code-block::
controller-0:~$ . /etc/platform/openrc
[sysadmin@controller-0 ~(keystone_admin)]$ system show
@@ -99,121 +104,199 @@ Use StarlingX CLI
+----------------------+--------------------------------------+
-After you figure out the software version, check the latest StarlingX
-build to identify updated rpms against that version. Select one or
-more rpms for patch generation and continue to the next section.
+After you figure out the software version, check the latest StarlingX build to
+identify updated debs against that version. Select one or more debs for patch
+generation and continue to the next section.
*************
-Build patches
+Build Patches
*************
-After you determine the rpms to be installed, set up an environment for
+After you determine the debs to be installed, set up an environment for
patch build. As a StarlingX developer, the easiest way to set up this type of
environment is to use a StarlingX build container, with a few changes.
-#############
-Prerequisites
-#############
+.. rubric:: |prereq|
-* Set up a StarlingX build container following `the
- build guide <https://docs.starlingx.io/developer_resources/build_guide.html>`_.
+#. Set up a StarlingX build container following `the
+ build guide <https://docs.starlingx.io/developer_resources/build_guide.html>`_.
-* Download StarlingX source code.
+#. Download StarlingX source code.
-* Be sure that the rpms to be installed are already available in the build
- container filesystem.
+#. Populate your build using ``build-pkgs --reuse`` or ``build-pkgs --all``.
+ Using the reuse flag should be faster if you already have the running env.
-Set up the patch build environment using the steps below. Note that
-this environment is intended for developers working on this feature
-and is not intended to be used for a StarlingX-based product.
+#. Make your changes, usually by cherry picking some commit.
-#. Install two python packages ``crypto`` and ``pycrypto``, which are the
- python dependencies of the ``cgcs-patch`` package.
+#. Apply the changes to the necessary files and than build the packages
+ related to these files with:
- ::
+ .. code-block:: none
- $ sudo pip install crypto pycrypto
+ $ build-pkgs -p <package name>
-#. Use the script ``$MY_REPO/stx/stx-update/extras/scripts/patch_build.sh``
- to build patches. This script sources the **PLATFORM_RELEASE**
- variable from the **release-info.inc** file, and sets up the PYTHONPATH to
- point to cgcs-patch package in the repo. This avoids the need to install
- cgcs-patch or manually set the PLATFORM_RELEASE variable.
+#. Build all necessary packages. To find out the package name, look for a
+ debian ``meta_data.yaml`` file.
- View the details of the patch build command using the command:
- ``$MY_REPO/stx/stx-update/extras/scripts/patch_build.sh -h``
+.. rubric:: |proc|
- ::
+Set up the patch build environment using the procedure below.
- $ $MY_REPO/stx/stx-update/cgcs-patch/bin/patch_build --help
- Usage: patch_build [ <args> ] ... <rpm list>
- Options:
- --id <id> Patch ID
- --release <version> Platform release version
- --status <status> Patch Status Code (ie. O, R, V)
- --unremovable Marks patch as unremovable
- --reboot-required <Y|N> Marks patch as reboot-required (default=Y)
- --summary <summary> Patch Summary
- --desc <description> Patch Description
- --warn <warnings> Patch Warnings
- --inst <instructions> Patch Install Instructions
- --req <patch_id> Required Patch
- --controller <rpm> New package for controller
- --worker <rpm> New package for worker node
- --worker-lowlatency <rpm> New package for worker-lowlatency node
- --storage <rpm> New package for storage node
- --controller-worker <rpm> New package for combined node
- --controller-worker-lowlatency <rpm> New package for lowlatency
- combined node
- --all-nodes <rpm> New package for all node types
+.. note::
- You must specify the patch id, whether a reboot is required or not, any
- dependent patches, the file path of rpms, etc. For new rpm packages, you
- must specify which hosts require them using options, for example
- ``--controller``.
+ This environment is intended for developers working on this feature
+ and is not intended to be used for a StarlingX-based product.
- When the command is finished, you get a patch file with the name
- ``<patch-id>.patch``.
+.. note::
-Let’s dive a little deeper into the generated patch.
+ Patch requirements are automatically installed when containers are created.
-#. The patch file is a gzip compressed package. Check it
- using the :command:`file` command. Below is an example, including command output.
- ::
+#. Create your patch recipe. The recipe file is used as input and it has all
+ the patch metadata. Packages that will be included in the patch need to be
+ added to the `packages` object ("stx" are packages we build, "binary" are
+ packages we download).
- $ file 001.patch
- 001.patch: gzip compressed data, was "001.patch", last modified:
- Fri Aug 16 05:56:59 2019, max compression
+ .. code-block:: none
-#. Unzip the patch file to discover four files, ``software.tar``,
- ``metadata.tar``, ``signature``, and ``signature.v2``.
+ <patch_recipe>
+ <!-- Software Version -->
+ <sw_version>1.0.0</sw_version>
+ <!-- Component -->
+ <component>starlingx</component>
+ <!-- Summary: Short text to give a summary about the patch -->
+ <summary>sample patch test</summary>
+ <!-- Description: Patch description. Usually it has a list of fixes -->
+ <description>Sample description</description>
+ <!-- Install Instructions: Any instructions to be done before the patch installation -->
+ <install_instructions>Sample instructions</install_instructions>
+ <!-- Warnings: Any warnings that this patch can trigger -->
+ <warnings>Sample warning</warnings>
+ <!-- Reboot required: Y (Yes) or N (No) for in service patch -->
+ <reboot_required>Y</reboot_required>
+ <!-- Unremovable: Y (Yes)/ N (No), specifices if the patch can be removed -->
+ <unremovable>N</unremovable>
+ <!-- Patch Status: Supported values are DEV (development) and REL (released) -->
+ <status>DEV</status>
+ <!-- Requires: List of patches that are required by this patch -->
+ <requires>
+ <!--
+ <id>PATCH_XYZ_01</id>
+ <id>PATCH_XYZ_02</id>
+ -->
+ </requires>
+ <semantics></semantics>
+ <!--
+ Pre and Post install hook scripts that are executed before/after patch installation.
+ Leave if blank if no scripts are required.
+ -->
+ <pre_install>scripts/pre-install.sh</pre_install>
+ <post_install>scripts/post-install.sh</post_install>
+ <!-- List Packages to be included in the patch -->
+ <stx_packages>
+ <!-- Starlingx packages list -->
+ <package>sysvinv</package>
+ <package>linux</package>
+ <package>linux-rt</package>
+ </stx_packages>
+ <!-- Binary packages list to be included in the patch (Packages that we download from 3rd party sources) -->
+ <binary_packages>
+ <!-- 3rd party packages list -->
+ <package>curl</package>
+ </binary_packages>
+ </patch_recipe>
- ::
+**Patch build**
- $ tar -xf 001.patch
- $ tree
- ├── 001.patch
- ├── metadata.tar
- ├── signature
- ├── signature.v2
- └── software.tar
+#. Create the patch.
- * Unzip ``software.tar`` to find that it contains all rpms to be
- installed. Note that all rpms have been signed during patch
- build using the key
- ``$MY_REPO/build-tools/signing/ima_signing_key.priv``.
+ .. code-block:: none
- * ``metadata.tar`` contains only one file ``metadata.xml``, which
- includes all the information provided by the patch build command. It is
- used by the StarlingX patching runtime system.
+ $ patch-builder --recipe EXAMPLES/patch-recipe-sample.xml
+ ...
+ 2024-06-12 13:12:49,566 - patch_builder - DEBUG: Copying pre-install script: /localdisk/designer/USER/master-env/cgcs-root/build-tools/stx/patch/scripts/pre-install.sh
+ 2024-06-12 13:12:49,567 - patch_builder - INFO: Renaming /localdisk/designer/USER/master-env/cgcs-root/build-tools/stx/patch/scripts/pre-install.sh to pre-install.sh
+ 2024-06-12 13:12:49,567 - patch_builder - DEBUG: Copying post-install script: /localdisk/designer/USER/master-env/cgcs-root/build-tools/stx/patch/scripts/post-install.sh
+ 2024-06-12 13:12:49,567 - patch_builder - INFO: Renaming /localdisk/designer/USER/master-env/cgcs-root/build-tools/stx/patch/scripts/post-install.sh to post-install.sh
+ 2024-06-12 13:12:49,567 - patch_builder - DEBUG: Generating metadata file
+ 2024-06-12 13:12:49,569 - patch_builder - DEBUG: Generating signature for patch files ['metadata.tar', 'software.tar', 'pre-install.sh', 'post-install.sh']
+ 2024-06-12 13:12:49,888 - patch_builder - INFO: Formal signing status: False
+ 2024-06-12 13:12:49,888 - patch_builder - INFO: Saving file software.tar
+ 2024-06-12 13:12:51,441 - patch_builder - INFO: Saving file post-install.sh
+ 2024-06-12 13:12:51,441 - patch_builder - INFO: Saving file metadata.tar
+ 2024-06-12 13:12:51,442 - patch_builder - INFO: Saving file signature
+ 2024-06-12 13:12:51,442 - patch_builder - INFO: Saving file signature.v2
+ 2024-06-12 13:12:51,442 - patch_builder - INFO: Saving file pre-install.sh
+ 2024-06-12 13:12:51,442 - patch_builder - INFO: Patch file created /localdisk/loadbuild/USER/master-env/patch_output/starlingx-1.0.0.patch
- * ``signature`` is a combination of the md5 values of ``software.tar`` and
- ``metadata.tar``.
+#. Verify patch content.
+
+ .. code-block:: none
+
+ $ tar -tvf /localdisk/loadbuild/USER/master-env/patch_output/starlingx-1.0.0.patch
+ USER/cgts 74772480 2024-06-12 13:12 software.tar
+ USER/cgts 440 2024-06-12 13:12 post-install.sh
+ USER/cgts 10240 2024-06-12 13:12 metadata.tar
+ USER/cgts 32 2024-06-12 13:12 signature
+ USER/cgts 256 2024-06-12 13:12 signature.v2
+ USER/cgts 433 2024-06-12 13:12 pre-install.sh
+
+#. Verify patch metadata.
+
+ .. code-block:: none
+
+ $ tar xf /localdisk/loadbuild/USER/stx-master/patch_output/sample_patch.patch -O metadata.tar | tar x -O
+ <?xml version="1.0" ?>
+ <patch>
+ <id>starlingx-1.0.0</id>
+ <sw_version>1.0.0</sw_version>
+ <component>starlingx</component>
+ <summary>sample patch test</summary>
+ <install_instructions>Sample instructions</install_instructions>
+ <warnings>Sample warning</warnings>
+ <status>DEV</status>
+ <unremovable>N</unremovable>
+ <reboot_required>Y</reboot_required>
+ <semantics/>
+ <requires/>
+ <pre_install>pre-install.sh</pre_install>
+ <post_install>post-install.sh</post_install>
+ <packages>
+ <deb>curl_7.74.0-1.3+deb11u11_amd64.deb</deb>
+ <deb>linux-compiler-gcc-10-x86_5.10.205-1.stx.79_amd64.deb</deb>
+ <deb>linux-headers-5.10.0-6-amd64_5.10.205-1.stx.84_amd64.deb</deb>
+ <deb>linux-headers-5.10.0-6-common_5.10.205-1.stx.84_all.deb</deb>
+ <deb>linux-image-5.10.0-6-amd64-unsigned_5.10.205-1.stx.84_amd64.deb</deb>
+ <deb>linux-kbuild-5.10_5.10.205-1.stx.84_amd64.deb</deb>
+ <deb>linux-libc-dev_5.10.205-1.stx.84_amd64.deb</deb>
+ <deb>linux-perf-5.10_5.10.205-1.stx.84_amd64.deb</deb>
+ <deb>linux-rt-headers-5.10.0-6-rt-amd64_5.10.205-1.stx.79_amd64.deb</deb>
+ <deb>linux-rt-headers-5.10.0-6-rt-common_5.10.205-1.stx.79_all.deb</deb>
+ <deb>linux-rt-image-5.10.0-6-rt-amd64-unsigned_5.10.205-1.stx.79_amd64.deb</deb>
+ <deb>linux-rt-kbuild-5.10_5.10.205-1.stx.79_amd64.deb</deb>
+ </packages>
+ </patch>
+
+
+#. Verify patch content (``software.tar``).
+
+ .. code-block:: none
+
+ $ tar xf /localdisk/loadbuild/USER/stx-master/patch_output/sample_patch.patch -O software.tar | tar t
+
+ linux-kbuild-5.10_5.10.205-1.stx.84_amd64.deb
+ linux-compiler-gcc-10-x86_5.10.205-1.stx.79_amd64.deb
+ linux-rt-image-5.10.0-6-rt-amd64-unsigned_5.10.205-1.stx.79_amd64.deb
+ linux-rt-kbuild-5.10_5.10.205-1.stx.79_amd64.deb
+ linux-perf-5.10_5.10.205-1.stx.84_amd64.deb
+ linux-rt-headers-5.10.0-6-rt-common_5.10.205-1.stx.79_all.deb
+ linux-rt-headers-5.10.0-6-rt-amd64_5.10.205-1.stx.79_amd64.deb
+ linux-headers-5.10.0-6-amd64_5.10.205-1.stx.84_amd64.deb
+ linux-image-5.10.0-6-amd64-unsigned_5.10.205-1.stx.84_amd64.deb
+ linux-libc-dev_5.10.205-1.stx.84_amd64.deb
+ curl_7.74.0-1.3+deb11u11_amd64.deb
+ linux-headers-5.10.0-6-common_5.10.205-1.stx.84_all.deb
- * ``signature.v2`` is a signature file for ``software.tar`` and
- ``metadata.tar``. In this case, it is generated using the key file
- ``$MY_REPO/build-tools/signing/dev-private-key.pem``.
-------------
Apply a patch
diff --git a/doc/source/shared/abbrevs.txt b/doc/source/shared/abbrevs.txt
index 68307a082..7355472c3 100755
--- a/doc/source/shared/abbrevs.txt
+++ b/doc/source/shared/abbrevs.txt
@@ -208,6 +208,7 @@
.. |UDS| replace:: :abbr:`UDS (Unix Domain Socket)`
.. |UEFI| replace:: :abbr:`UEFI (Unified Extensible Firmware Interface)`
.. |UFT| replace:: :abbr:`UFT (Unified Flow Tool)`
+.. |USM| replace:: :abbr:`USM (Unified Software Management)`
.. |UUID| replace:: :abbr:`UUID (Universally Unique Identifier)`
.. |UUIDs| replace:: :abbr:`UUIDs (Universally Unique Identifiers)`
.. |VF| replace:: :abbr:`VF (Virtual Function)`