From f39c5305a20f18ccde1306bd568a5986c88d0d10 Mon Sep 17 00:00:00 2001 From: Petr Stodulka Date: Wed, 5 Feb 2025 09:37:58 +0100 Subject: [PATCH] DOC: tutorial: custom content Add tutorial to add custom custom content (leapp repositories, actors, etc.) on the system to be used during the IPU process. --- docs/source/tutorials/custom-content.md | 118 ++++++++++++++++++++++++ docs/source/tutorials/index.rst | 6 +- 2 files changed, 123 insertions(+), 1 deletion(-) create mode 100644 docs/source/tutorials/custom-content.md diff --git a/docs/source/tutorials/custom-content.md b/docs/source/tutorials/custom-content.md new file mode 100644 index 0000000000..9bad96af95 --- /dev/null +++ b/docs/source/tutorials/custom-content.md @@ -0,0 +1,118 @@ +# Creating custom content for IPU + +The official leapp repositories for in-place upgrade cover usually only RPM packages +signed by official distribution's GPG keys. Other content (third-party RPMs - +including EPEL, custom installed content, ..) needs to be covered separately. +In some cases there is not a better (or other) way than creating additional actors +to customize the IPU process. + +To simplify troubleshooting for us and others (and prevent other possible problems) +we request custom actors to be installed into own leapp repositories +on the system which should be located inside the `/usr/share/leapp-repository/custom-repositories/` +directory. + +This guide explains how to create custom leapp actors and repositories on the system and +how to ensure they are discovered and processed by Leapp. For the simplification +consider that custom content includes third-party content as well. + +For the purpose of this guide install the `snactor` utility. + +## Create custom repository + +To keep it simple, instructions covers the creation of the custom leapp repository +on the system with installed `leapp` and `leapp-upgrade-*` (and `snactor`) packages. +For in-place upgrade of RHEL systems see also [official instructions](https://access.redhat.com/articles/4977891#create-custom-actor). + +```{note} +If you want to create new leapp repository in your develpment environment without +installing `leapp-upgrade-*` packages, you will need clone the leapp-repository +git repo and register related leapp repositories using `snactor` manually. See +`snactor repo find --help` for more info. +``` + + +1. Go to the directory where a new Leapp repository should be created: +```shell +cd /usr/share/leapp-repository/custom-repositories/ +``` + +2. Create a new Leapp repository: +```shell +snactor repo new +``` + +Read carefully [Naming Convention](#naming-convention) section to choose a right +name to prevent possible conflicts with other content. + +```{note} +Note that snactor does not have to create automatically whole directory structure +inside the repository (directories like `tools`, `libraries`, etc...). Create +any needed directories manually. See [Repository directory layout](https://leapp.readthedocs.io/en/latest/repository-dir-layout.html) for more info. +``` + +3. Go to the newly created leapp repository: +```shell +cd /usr/share/leapp-repository/custom-repositories/ +``` + +4. [Link other needed repositories](https://leapp.readthedocs.io/en/latest/repo-linking.html) +into the newly created custom repository. You should always link following repositories: +```shell +snactor repo link --path /usr/share/leapp-repository/repositories/system_upgrade/common +snactor repo link --path /usr/share/leapp-repository/repositories/common +``` +In case you need any content present in particular `.../system_upgrade/elXtoelY` +repository, link it too. + +```{note} +All defined links are understood as requirements for the correct functioning +of the custom leapp repository. E.g. adding dependency on `system_upgrade_el8toel9` +repository means that the custom repository can bee installed and used only on +RHEL 8 (inluding RHEL-like) system as the `system_upgrade_el8toel9` is present +only there. +``` + +5. Create a symlink in `/etc/leapp/repos.d/` to register your repository for leapp: +```shell +ln -s /usr/share/leapp-repository/custom-repositories/ /etc/leapp/repos.d/ +``` + +```{note} +This step is required to be done just on the system where the custom repository +is installed so leapp will discover the repository. +``` + +Note that such a created leapp repository can be installed to other systems as it is, +just the symlink needs to be always created as well (step `5`). + +## Create custom actor + +To create custom actors inside the newly created custom leapp repository follow +the tutorial [Writing an Actor for Leapp Upgrade](howto-first-actor-upgrade) +and read the **Naming convention** section below. + + +## Naming convention + +The system can contain number of leapp repositories and actors. Also, the leapp framework +is focused on making lives of developers as simple as possible, but it is +paid by missing namespacing. So developers are responsible to choose wisely +names of their leapp repositories, actors, models, and libraries to ensure +they do not conflict with others. To help you to prevent possible conflicts +we propose following conventions: + +1. If you create solutions for your personal use that will not be shared with +others, use e.g. the `my_custom_` prefix for the repository name. Similar can be applied +for all other leapp entities (actors, models, libraries, ...). +2. If you are SW vendor and want to create solution for your customers, +make the name of your company or product part of the leapp repository name. +3. Do not use generic names for leapp actors, models, and repositories. E.g. +creating actor that checks MySQL configuration with the `check_config` or `check_database` names +are really bad. `check_config_mysql` or `check_config_mysql_vX` is better but if multiple +products on market use the same MySQL version X and can be present on the same system, +it's still not ideal. So e.g. `check_config_mysql_` +or `check_config_mysql_`, where product is your unique product you deliver, +is much better option. +4. Similar applies for libraries. Creating library `databases` or `mysql` is too much +generic. + diff --git a/docs/source/tutorials/index.rst b/docs/source/tutorials/index.rst index 0fba46a27b..046c81f623 100644 --- a/docs/source/tutorials/index.rst +++ b/docs/source/tutorials/index.rst @@ -1,13 +1,17 @@ Tutorials ========= +Tutorials here are focused on In-Place Upgrades with leapp repositories +covered by the `leapp-repository `_ project. + .. toctree:: :maxdepth: 4 :caption: Contents: :glob: - templates/index howto-first-actor-upgrade + custom-content + templates/index troubleshooting-debugging .. Indices and tables