Ansible-keräilyn pakkausohjeet

Seuraava

Ansible-kokoelmat ovat pakattuja Ansible-sisällön yksiköitä, mukaan lukien moduulit ja muut lisäosat. Suurin osa Ansible-lisäosista on kirjoitettu Pythonilla tai Powershellillä.

Jotkin kokoelmat sisältyvät myös Ansible Communityn %ansible% kokoelmapakettiin, joka on pakattu Fedoraan. Kaikki kokoelmat, riippumatta siitä, sisältyvätkö ne %ansible% -pakettiin vai eivät, VOIDAAN pakata Fedoraan.

%ansible% riippuu %ansible-core%, joka sisältää ydinmoottorin ja CLI-ohjelmat (esim. %ansible%, %ansible-playbook%). %ansible% -paketilla on erilainen julkaisusykli kuin yksittäisillä kokoelmilla, ja se saattaa sisältää vanhempia versioita yksittäisistä komponenteista. %ansible% asentaa kokoelmia eri nimiavaruuteen ja on rinnakkain asennettavissa yksittäisten kokoelmien kanssa. Ansible-moottori etsii kokoelmia ensin itsenäisestä kokoelmahakemistosta.

Katso Changes/Ansible5 lisätietoja jaosta %ansible% ja %ansible-core%.

Nimeäminen

Kokoelmapakettien ON nimettävä %ansible-collection-NAMESPACE-NAME%. Esimerkiksi %community.general% kokoelmapaketti on nimeltään %ansible-collection-community-general%.

Kokoelman lähde

Kokoelman lähdekoodi TÄYTYY ladata kokoelman vastaavasta Git-forgesta tai muusta SCM-varastosta. Vaikka Ansible Galaxylle julkaistut tarballit sisältävät koko kokoelman Python/Powershell-lähdekoodin sekä joitakin kehitystiedostoja, ne eivät sisällä %galaxy.yml% build-konfiguraatio- ja kehitystiedostoja (esim. yksikkötestejä), jotka tekijä voi halutessa poistaa. Huomaa, että Ansible-yhteisön kokoelmavaatimukset edellyttävät, että kokoelmien tagivapautukset tulee julkaista julkisessa SCM-arkistossa.

Kokoelmapakettien TULISI käyttää %%{ansible_collection_url NAMESPACE NAME}% paketin %URL:% arvosanana. Tämä viittaa kokoelman kotisivuun Ansible Galaxyssa.

Riippuvuudet

Koostamisaika

Kokoelmissa TÄYTYY olla %BuildVaatii: ansible-packaging%. %ansible-packaging% tarjoaa makrot ja riippuvuusgeneraattorin Ansible-kokoelmien pakkaamiseen. Se hakee myös %ansible-core%, joten %BuildVaatii: ansible-core% EI SAISI lisätä manuaalisesti.

Ajonaikainen

Riippuvuusgeneraattori luo sopivan riippuvuuden Ansible-moottorista. Tämä varmistaa yhteensopivuuden Fedora 35:n kanssa, joka sisältää klassisen %ansible% 2.9 -paketin (kokoelmapaketin sijaan) ja %ansible-core%. Molemmat Ansible-moottorin versiot tukevat kokoelmia, mutta niitä ei voi asentaa rinnakkain. Paketit EIVÄT SAA manuaalisesti %Require% %ansible-core% tai %ansible%, ellei niiden tiedetä vaativan tiettyä versiota, jolloin asianmukaisia versiorajoituksia tulisi käyttää.

Riippuvuusgeneraattori käsittelee myös kokoelmien välisiä riippuvuuksia.

Lisäosien ulkoiset riippuvuudet

Ansible-kokoelmat voivat sisältää erilaisia lisäosia, joilla on erilaisia ulkoisia riippuvuuksia. Ansible-kehitysopas vaatii, että lisäosat epäonnistuvat puhtaasti, jos näitä riippuvuuksia ei ole asennettu. Monesti ulkoisia riippuvuuksia tarvitaan vain pienelle osalle kokoelmasta, jota käytetään laajasti tai ei. Siksi kokoelmapakettien PITÄISI heikosti riippua näistä ulkoisista kirjastoista, eli käyttää Recommends-toimintoa vaatimusten sijaan.

Moduuliriippuvuuksia tarvitaan vain kohdesolmussa, ei ohjainsolmussa. Siksi kokoelmapakettien EI PITÄISI riippua näistä riippuvuuksista lainkaan, heikosti tai voimakkaasti. Käyttäjät ovat vastuussa näiden riippuvuuksien asentamisesta kohdepalvelimelle. Moduulit, jotka on tarkoitettu käytettäväksi yhdessä %delegate_to: localhost%, ovat poikkeus tähän sääntöön.

Tilanne on hieman erilainen ohjainlaajennuksissa, kuten suodatinplugineissa, hakuplugineissa, yhteysplugineissa tai inventaarioliitännöissä. Kokoelmat VOIVAT lisätä %Recommends% ohjainlaajennusten riippuvuuksiin. Pakkaajien tulisi kuitenkin käyttää harkintaa lisätessään minkä tahansa riippuvuuden tyyppiä ja tehdä se vain, kun se on tarpeen kokoelman keskeisen toiminnallisuuden vuoksi. Esimerkiksi on järkevää, että %ansible-collection-community-docker% suosittelee %python3-docker%, mutta ei ole järkevää, että laajempi, yleisempi ansible-collection-community-general -kokoelma suosittelee %python3-redis% %redis% hakupluginille. Tämä ohjeistus pyrkii estämään keräyspakettien paisumisen. %ansible-core% ja %ansible% noudattavat samaa periaatetta.

Rakentaminen ja asennus

Kokoelmaartefaktin rakentamiseksi pakettien ON käytettävä %%ansible_collection_build% %%build%. %%ansible_collection_install% täytyy käyttää %%install% artefaktin asentamiseen.

Paketoijien TULISI käyttää %%files -f %{ansible_collection_filelist}% kokoelman asentamiseen. %%{ansible_collection_filelist}% on %%ansible_collection_install%.

Yksikkötestit

Xref:index.adoc#_test_suites[yleiset Fedora-pakkausohjeet] mukaan kokoelmapakettien TULISI suorittaa ylävirran yksikkötestit %%check% -muodossa, jos se on mahdollista. Integraatiotestit ovat mahdottomia suorittaa RPM-rakennusympäristössä. Yksikkötestien suorittamiseksi kokoelmien TÄYTYY %BuildRequire% %ansible-packaging-tests%, mikä hakee tarvittavat riippuvuudet. Joillakin kokoelmilla on muita testausriippuvuuksia, jotka yleensä määritellään %tests/unit/requirements.txt%. Nämä täytyy lisätä käsin. %%ansible_test_unit% -makroa TÄYTYY käyttää testien suorittamiseen.

EPEL-yhteensopivuus

EPEL 8:lla ja 9:llä on tällä hetkellä mahdotonta suorittaa yksikkötestejä.

ansible-core RHEL 8:ssa ja 9:ssä on rakennettu vaihtoehtoisia python-pinoja vastaan, joille tarvittavia testiriippuvuuksia ei ole saatavilla.

Muut ohjeet koskevat EPEL 8:aa ja 9:ää, ja %ansible-packaging% on saatavilla siellä.

Tarpeettomat tiedostot

Oletuksena kokoelmat toimitetaan kaikkien tiedostojen mukana arkiston juuressa, ellei niitä ole manuaalisesti poissuljettu. Siksi monet kokoelmat sisältävät kehitystiedostoja, joita käyttäjät eivät halua.

Paketoijien TULISI sulkea nämä tiedostot pois, mikä PITÄISI tehdä korjaamalla kokoelman %galaxy.yml% ja lisäämällä nämä tiedostot %build_ignore%-konfiguraatioon. Näitä tiedostoja EI PIDÄ poistaa %rm% -menetelmällä. Katso Ansible-dokumentaatio lisätietoja %galaxy.yml% syntaksista.

Yleisiä kehitystiedostoja ovat:

  • %tests% -hakemisto, joka sisältää yksikkö- ja integraatiotestit

  • SCM-asetukset, kuten %.gitignore% ja %.keep% -tiedostot

  • %.azure-pipelines% ja %.github% -hakemistot, jotka sisältävät CI-konfiguraatiota

Nämä tiedostot joudutaan usein poistamaan myöhemmin, sillä muutosten siirtämisessä ylävirran yhteisökokoelmiin on joitakin ratkaisemattomia ongelmia. Nämä kysymykset ovat merkityksettömiä Fedora-kontekstissa.

Shebangs

Ansible-pluginit eivät ole suoritettavissa. Monissa niistä on kuitenkin %#!/usr/bin/python% shebangit perinteisistä syistä. Nämä shebangit ON poistettava seuraavista syistä:

  1. Ei-suoritettavissa tiedostoissa ei pitäisi olla shebangeja

  2. Shebangien pitäminen johtaa tarpeettomaan riippuvuuteen %python-unversioned-command%.

%%py3_shebang_fix% EI SAA käyttää, sillä se rikkoo yhteensopivuuden tiettyjen Ansible-kohdesolmujen kanssa. Se ei myöskään korjaa ei-suoritettavien tiedostojen ongelmaa.

Shebangit voidaan poistaa:

find -type f ! -executable -name '*.py' -print -exec sed -i -e '1{\@^#!.*@d}' '{}' +

Dokumentaatio ja lisenssitiedostot

Lisenssitiedostot ja kokoelmien dokumentaatio asennetaan kokoelman hakemistoon oletuksena %/usr/share/ansible%. Paketoijat VOIVAT joko merkitä lisenssi- ja dokumentaatiotiedostot tässä hakemistossa %%license% ja %%doc% tai lisätä oikeat polut %build_ignore%:iin %galaxy.yml%:ssa ja asentaa ne standardihakemistoihin. Vältä näiden tiedostojen päällekkäisyyttä molemmissa kohdissa.

Huomaa, että jotkut monilisensoidut kokoelmat tallentavat lisenssit %LICENSES% -hakemistoon. Tämä koko hakemisto TÄYTYY merkitä %%license%.

Katso Legal docs saadaksesi säännöt sallituista lisensseistä, ja %License:% -kentän määrittämisestä.

Esimerkki Specfile

# suorita testejä vain, kun riippuvuudet ovat saatavilla
%if %{defined fedora}
%bcond_without tests
%else
%bcond_with tests
%endif

Nimi: ansible-collection-community-rabbitmq
Versio: 1.2.2
Julkaisu: 1%{?dist}
Yhteenveto: RabbitMQ-kokoelma Ansiblelle

# plugins/module_utils/_version.py: Python Software Foundation License versio 2
Lisenssi: GPL-3.0-or-later ja PSF-2.0
URL: %{ansible_collection_url community rabbitmq}
%global forgeurl https://github.com/ansible-collections/community.rabbitmq
Source0: %{forgeurl}/archive/%{version}/%{name}-%{version}.tar.gz
# Korjaus galaxy.yml tarpeettomien tiedostojen poissulkemiseksi rakennetusta kokoelmasta.
# Tämä on vain alavirran alue.
Patch0: build_ignore.patch

BuildVaatii: ansible-packaging
%if %{with tests}
BuildRebbes: ansible-packaging-tests
# Kokoelmakohtainen testiriippuvuus
BuildRequires: glibc-all-langpacks
%endif

BuildArch:      noarch

%description
%{summary}.


%prep
%autosetup -n community.rabbitmq-%{version} -p1
find -type f ! -executable -name '*.py' -print -exec sed -i -e '1{\@^#!.*@d}' '{}' +


%build
%ansible_collection_build


%install
%ansible_collection_install


%if %{with tests}
%check
%ansible_test_unit
%endif


%files -f %{ansible_collection_filelist}
%license COPYING PSF-license.txt
%doc README.md CHANGELOG.rst

%changelog

build_ignore.patch:

diff --git a/galaxy.yml b/galaxy.yml
index 0b37162.. acd029a 100644
--- a/galaxy.yml
+++ b/galaxy.yml
@@ -13,3 +13,13 @@ repository: https://github.com/ansible-collections/community.rabbitmq
dokumentaatio: https://docs.ansible.com/ansible/latest/collections/community/rabbitmq/
kotisivu: https://github.com/ansible-collections/community.rabbitmq
ongelmat: https://github.com/ansible-collections/community.rabbitmq/issues
+build_ignore:
+ # Poista tarpeettomat kehitystiedostot Rakennettu paketti.
+ - tests
+ - .azure-pipelines
+ - .gitignore
+ # Lisenssit ja dokumentit asennetaan %%doc ja %%license
+ - PSF-license.txt
+ - COPYING
+ - README.md
+ - CHANGELOG.rst

Macro Breakdown

Tässä on lyhyt erittely siitä, mitä kukin %ansible-packaging% -makro tekee.

%ansible_collection_url

Usage:

URL:            %{ansible_collection_url NAMESPACE NAME}

Tämä makro viittaa kokoelman Ansible Galaxy -sivuun. Sitä on tarkoitettu käytettäväksi %URL:% -tunnisteelle specfikatiedoston johdannossa. Se ottaa kokoelman nimiavaruuden ja kokoelman nimen argumentteina.

Jos tälle makrolle ei siirretä argumentteja, se palautuu arvoihin %%{collection_namespace}% ja %%{collection_name}%, jos ne on asetettu specfileen. Uusien pakettien PITÄISI nimenomaisesti välittää nimiavaruus ja nimi argumentteina. Varasuunnitelma voidaan poistaa tulevaisuudessa. Katso lisätietoja linkistä:#legacy_macros[Legacy Macros] -osio.

%ansible_collection_build

Usage:

%build
%ansible_collection_build

Tämä makro suorittaa yksinkertaisesti %ansible-galaxy collection build%.

%ansible_collection_install

Usage:

%install
%ansible_collection_install

Tämä makro hakee kokoelman nimiavaruuden, nimen ja version %galaxy.yml%:sta ja käyttää sitä ajaakseen %ansible-galaxy collection install%. Tämän jälkeen se kirjoittaa %%{ansible_collection_filelist}% aiemmin poimimaansa metadatan perusteella

%ansible_test_unit

Usage:

%check
%ansible_test_unit

Tämä makro jäsentää galaxy.yml määrittääkseen kokoelman nimiavaruuden ja nimen, joka tarvitaan ansible-testin odottaman hakemistorakenteen luomiseen. Kun väliaikainen rakennushakemisto tarvittavalla rakenteella on luotu, skripti suorittaa ansible-testiyksiköt annetuilla argumenteilla.

%{ansible_collection_filelist}

Usage:

%files -f %{ansible_collection_filelist}
%doc ...
%license ...

Tämä makro osoittaa tiedostolistaan, joka on kirjoitettu %%ansible_collection_install%. Tällä hetkellä se sisältää vain yhden merkinnän, joka omistaa koko kokoelman hakemiston %%{ansible_collections_dir}%

Tämä makro laajenee %%{_datadir}/ansible/collections/ansible_collections%. Sitä käyttävät sisäisesti muut makrot. Pakkaajien odotetaan käyttävän %%ansible_collection_install% ja %%ansible_collection_filelist% sen sijaan, että viittaisivat suoraan tähän hakemistoon.

Perintömakrot

%{collection_namepsace}

Usage:

%global collection_namespace NAMESPACE

Ansible-packaging -makrot vaativat aiemmin pakkaajilta %%collection_namespace%:n manuaalista asettamista specfileissa. Makrot poimivat kokoelman nimiavaruuden %galaxy.yml %:sta.

%{collection_name}

Usage:

%global collection_name NAME

Ansible-pakkausmakrot vaativat aiemmin pakkaajien asettamaan %%collection_name% manuaalisesti specfileissa. Nyt makrot poimivat kokoelman nimen %galaxy.yml %:sta.

%{ansible_collection_files}

Usage:

%files
%doc ...
%license ...
%{ansible_collection_files}

Uusien specfikatiedostojen tulisi käyttää %%files -f %{ansible_collection_filelist}% tämän makron sijaan. %%{ansible_collection_files}% vaatii asetuksen %%collection_namespace% ja %%collection_name%.

Want to help? Learn how to contribute to Fedora Docs ›