Skip to content

Commit 600836d

Browse files
pirat89pirat89
committed
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.
1 parent ed72611 commit 600836d

File tree

2 files changed

+123
-1
lines changed

2 files changed

+123
-1
lines changed

Diff for: ‎docs/source/tutorials/custom-content.md

+118
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,118 @@
1+
# Creating custom content for IPU
2+
3+
The official leapp repositories for in-place upgrade cover usually only RPM packages
4+
signed by official distribution's GPG keys. Other content (third-party RPMs -
5+
including EPEL, custom installed content, ..) needs to be covered separately.
6+
In some cases there is not a better (or other) way than creating additional actors
7+
to customize the IPU process.
8+
9+
To simplify troubleshooting for us and others (and prevent other possible problems)
10+
we request custom actors to be installed into own leapp repositories
11+
on the system which should be located inside the `/usr/share/leapp-repository/custom-repositories/`
12+
directory.
13+
14+
This guide explains how to create custom leapp actors and repositories on the system and
15+
how to ensure they are discovered and processed by Leapp. For the simplification
16+
consider that custom content includes third-party content as well.
17+
18+
For the purpose of this guide install the `snactor` utility.
19+
20+
## Create custom repository
21+
22+
To keep it simple, instructions covers the creation of the custom leapp repository
23+
on the system with installed `leapp` and `leapp-upgrade-*` (and `snactor`) packages.
24+
For in-place upgrade of RHEL systems see also [official instructions](https://access.redhat.com/articles/4977891#create-custom-actor).
25+
26+
```{note}
27+
If you want to create new leapp repository in your develpment environment without
28+
installing `leapp-upgrade-*` packages, you will need clone the leapp-repository
29+
git repo and register related leapp repositories using `snactor` manually. See
30+
`snactor repo find --help` for more info.
31+
```
32+
33+
34+
1. Go to the directory where a new Leapp repository should be created:
35+
```shell
36+
cd /usr/share/leapp-repository/custom-repositories/
37+
```
38+
39+
2. Create a new Leapp repository:
40+
```shell
41+
snactor repo new <repository_name>
42+
```
43+
44+
Read carefully [Naming Convention](#naming-convention) section to choose a right
45+
name to prevent possible conflicts with other content.
46+
47+
```{note}
48+
Note that snactor does not have to create automatically whole directory structure
49+
inside the repository (directories like `tools`, `libraries`, etc...). Create
50+
any needed directories manually. See [Repository directory layout](https://leapp.readthedocs.io/en/latest/repository-dir-layout.html) for more info.
51+
```
52+
53+
3. Go to the newly created leapp repository:
54+
```shell
55+
cd /usr/share/leapp-repository/custom-repositories/<repository_name>
56+
```
57+
58+
4. [Link other needed repositories](https://leapp.readthedocs.io/en/latest/repo-linking.html)
59+
into the newly created custom repository. You should always link following repositories:
60+
```shell
61+
snactor repo link --path /usr/share/leapp-repository/repositories/system_upgrade/common
62+
snactor repo link --path /usr/share/leapp-repository/repositories/common
63+
```
64+
In case you need any content present in particular `.../system_upgrade/elXtoelY`
65+
repository, link it too.
66+
67+
```{note}
68+
All defined links are understood as requirements for the correct functioning
69+
of the custom leapp repository. E.g. adding dependency on `system_upgrade_el8toel9`
70+
repository means that the custom repository can bee installed and used only on
71+
RHEL 8 (inluding RHEL-like) system as the `system_upgrade_el8toel9` is present
72+
only there.
73+
```
74+
75+
5. Create a symlink in `/etc/leapp/repos.d/` to register your repository for leapp:
76+
```shell
77+
ln -s /usr/share/leapp-repository/custom-repositories/<repository_name> /etc/leapp/repos.d/
78+
```
79+
80+
```{note}
81+
This step is required to be done just on the system where the custom repository
82+
is installed so leapp will discover the repository.
83+
```
84+
85+
Note that such a created leapp repository can be installed to other systems as it is,
86+
just the symlink needs to be always created as well (step `5`).
87+
88+
## Create custom actor
89+
90+
To create custom actors inside the newly created custom leapp repository follow
91+
the tutorial [Writing an Actor for Leapp Upgrade](howto-first-actor-upgrade)
92+
and read the **Naming convention** section below.
93+
94+
95+
## Naming convention
96+
97+
The system can contain number of leapp repositories and actors. Also, the leapp framework
98+
is focused on making lives of developers as simple as possible, but it is
99+
paid by missing namespacing. So developers are responsible to choose wisely
100+
names of their leapp repositories, actors, models, and libraries to ensure
101+
they do not conflict with others. To help you to prevent possible conflicts
102+
we propose following conventions:
103+
104+
1. If you create solutions for your personal use that will not be shared with
105+
others, use e.g. the `my_custom_` prefix for the repository name. Similar can be applied
106+
for all other leapp entities (actors, models, libraries, ...).
107+
2. If you are SW vendor and want to create solution for your customers,
108+
make the name of your company or product part of the leapp repository name.
109+
3. Do not use generic names for leapp actors, models, and repositories. E.g.
110+
creating actor that checks MySQL configuration with the `check_config` or `check_database` names
111+
are really bad. `check_config_mysql` or `check_config_mysql_vX` is better but if multiple
112+
products on market use the same MySQL version X and can be present on the same system,
113+
it's still not ideal. So e.g. `check_config_mysql_<company>`
114+
or `check_config_mysql_<product>`, where product is your unique product you deliver,
115+
is much better option.
116+
4. Similar applies for libraries. Creating library `databases` or `mysql` is too much
117+
generic.
118+

Diff for: ‎docs/source/tutorials/index.rst

+5-1
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,17 @@
11
Tutorials
22
=========
33

4+
Tutorials here are focused on In-Place Upgrades with leapp repositories
5+
covered by the `leapp-repository <https://github.com/oamg/leapp-repository>`_ project.
6+
47
.. toctree::
58
:maxdepth: 4
69
:caption: Contents:
710
:glob:
811

9-
templates/index
1012
howto-first-actor-upgrade
13+
custom-content
14+
templates/index
1115
troubleshooting-debugging
1216

1317
.. Indices and tables

0 commit comments

Comments
 (0)