Siirry suoraan sisältöön.
Suomi.fi-palveluväylä

Palveluväylän X-Road Toolkit – liityntäpalvelimen automaattiset hallintaskriptit

Palveluväylän automaattisilla hallintaskripteillä (X-Road Toolkit) automatisoit yhden tai useamman liityntäpalvelimen määrittelyn. Automaattisilla skripteillä liityntäpalvelimen määrittely on sujuvampaa ja mahdollisuudet virheiden tekemiseen ovat vähäisemmät.

Mikä on X-Road Toolkit?

X-Road Toolkit on Python-pohjainen työkalu liityntäpalvelimen automaattiseen asentamiseen ja hallinnointiin. Sitä voi käyttää kaikkien Palveluväylän liityntäpalvelinvaihtoehtojen (RHEL, Ubuntu, Docker) määrittelyyn. X-Road Toolkitin avulla voit määritellä yhden tai useamman liityntäpalvelimen kerrallaan.

Automaattiset skriptit sopivat ainoastaan Suomi.fi-palveluväylän käyttöön. Tämä tarkoittaa, että esimerkiksi skripteillä luodut varmenteet ovat Suomen käyttöön tarkoitettuja.

X-Road Toolkit on julkaistu Python Package Index (PyPI) -pakettina.

Katso demovideo liityntäpalvelimen määrittelemisestä X-Road Toolkitilla (Youtube, englanniksi)Avautuu uuteen ikkunaan..

Mitä X-Road Toolkit mahdollistaa?

X-Road Toolkit mahdollistaa yhden tai useamman liityntäpalvelimen perusmäärittelyn. Liityntäpalvelimen määrittely X-Road Toolkitilla on helpompaa ja nopeampaa kuin manuaalinen konfigurointi. Määrittelyn automatisoiminen säästää aikaa ja vähentää virheiden tekemisen mahdollisuutta. Automaattiset skriptit helpottavat myös X-Road versiossa 6.24.0 julkaistun liityntäpalvelimen hallintarajapinnan käyttöä eli mahdollistavat liityntäpalvelimen etähallinnan.

X-Road Toolkit mahdollistaa myös asennuspakettien luomisen. YAML-konfiguraatiotiedostoon voi määritellä esimerkiksi sopivia palveluita valmiiksi, jolloin tiedostoon tarvitsee muokata erikseen ainoastaan organisaatiokohtaiset perustiedot, kuten organisaation nimi.

Liityntäpalvelimen perusmäärittely tarkoittaa muun muassa seuraavia komentoja:

  • Liityntäpalvelimen alustaminen ja konfiguraatioankkurin lisääminen
  • Tunnukset (Tokenit). Token kirjautumiseen, tokenien listaus
  • Liityntäpalvelimen aikaleimapalvelun asettaminen
  • Varmenteet: Allekirjoitus- ja autentikointivarmenteet sekä sisäiset TLS-varmenteet. Allekirjoitus- ja autentikointiavaimen sekä varmennepyyntöjen luominen, vastaanotettujen varmenteiden asentaminen liityntäpalvelimelle, autentikointivarmenteen rekisteröinti ja aktivointi ja sisäisten TLS-varmenteiden luonti ja lataaminen
  • Alijärjestelmät. Yhden tai useamman alijärjestelmän luominen ja rekisteröinti.
  • Palvelut. Yhden tai useamman palvelun luominen. Palvelun tyyppi: REST API Base Path, REST OpenAPI 3 tai WSDL. Palvelun parametrien ja pääsyoikeuksien asettaminen.

Perusmäärittelyn lisäksi voit:

Lue lisää komennoista Githubissa (englanniksi)Avautuu uuteen ikkunaan..

X-Road Toolkitin käyttöönotto

Löydät ohjeet Toolkitin asentamiseen Githubista (englanniksi)Avautuu uuteen ikkunaan..

Huomioi, että sinun täytyy avata tarvittavat portit palvelimeltasi, ennen liityntäpalvelimen määrittelyä. Lue palomuuriavauksista käyttöönoton ohjeista kohdasta 2.

Toolkitin käytön edellytykset:

1. Alustapalvelimella, jolle liityntäpalvelinohjelmisto asennetaan, on valmiina

  • RHEL-käyttöjärjestelmä (8) tai Ubuntu-käyttöjärjestelmä (24.04LTS)
  • tai Docker asennettuna mille tahansa Linux-jakelulle

2. Alustapalvelimelle on asennettu

  • alustapalvelimeen (RHEL, Ubuntu) pohjautuvan liityntäpalvelimen asennuspaketit
  • tai kontitetun liityntäpalvelimen (Docker) asennuspaketit

3. Käytössä on Python-versio 3.6 tai uudempi

Lue lisää käyttöönoton edellytyksistä (englanniksi)Avautuu uuteen ikkunaan..

Toolkitin haluttu toiminta ja tiedot määritellään YAML-konfiguraatioon. Määriteltäviä tietoja ovat esimerkiksi:

  • liityntäpalvelimen tiedot, kuten sen FQDN-nimi sekä
  • liityntäpalvelimen omistajan tiedot, kuten organisaation tyyppi.

Lue lisää YAML-konfiguraatiotiedoston muokkaamisesta (englanniksi)Avautuu uuteen ikkunaan..

Toolkitin konfiguraatioon määritellyt toimenpiteet voidaan ajaa joko kaikki kerralla tai yksitellen

  • Koko konfiguraation voi ajaa kerralla xrdsst apply -komennolla
  • Osia konfiguraatiosta voidaan ajaa yksitellen alikomennoilla. Esimerkiksi xrdsst init lataa konfiguraatioankkurin ja alustaa liityntäpalvelimen tiedot

Palveluväylässä alijärjestelmät rekisteröityvät automaattisesti, joten koko prosessin voi ajaa kahdessa osassa.

  1. Ensimmäinen konfigurointiajo xrdsst apply -komennolla loppuu ilmoitukseen siitä, että varmenteet täytyy allekirjoittaa.
  2. Lataa varmennepyynnöt xrdsst cert download-csrs -komennolla ja lähetä ne allekirjoitettavaksi osoitteeseen palveluvayla@palveluvayla.fi.
  3. Kun olet saanut allekirjoitetut varmenteet Palveluväylän tuelta, lisää konfiguraatiotiedostoon polku allekirjoitettuihin varmenteisiin ja jatka tämän jälkeen koko konfiguraation ajamista xrdsst apply -komennolla.

Jos liityntäpalvelimen määrittelyn aikana ilmenee virheitä, konfigurointi pysähtyy virheilmoitukseen. Virheilmoituksessa kerrotaan, missä virhe ilmeni ja miten sen voi korjata. Jos virheilmoituksesta ei ole apua tai et pysty korjaamaan virhettä, ota yhteyttä Palveluväylän tukeen palveluvayla@palveluvayla.fi.

HUOM! Jos määrittelet kontitetun Sidecar Slim liityntäpalvelimen X-Road Toolkitilla, saat konfiguroinnissa virheilmoituksen siitä, että aikaleimapalvelun konfiguroiminen ei onnistunut. Tämä johtuu siitä, että Sidecar Slim ei sisällä lokitusta eikä aikaleimapalvelua, jolloin niitä ei voi myöskään määritellä. Tämän virheen voi ohittaa ja liityntäpalvelimen määrittely onnistuu ja liityntäpalvelin toimii virheilmoituksesta huolimatta.

Lue lisää virhetilanteista (englanniksi)Avautuu uuteen ikkunaan..

Haluatko tietää lisää?

Tutustu X-Road Toolkitin tekniseen dokumentaatioon Githubissa (englanniksi)Avautuu uuteen ikkunaan..

Jos sinulla on kysyttävää automaattisista skripteistä, ota yhteyttä ylläpitoomme palveluvayla@palveluvayla.fiAvautuu uuteen ikkunaan..

Päivitetty: 29.8.2025

Oletko tyytyväinen tämän sivun sisältöön?