ProHoster > Blog > Administrazioa > Docker irudien muntaketa eta hedapena dinamikoa werf-arekin bertsiotutako dokumentazio gune baten adibidea erabiliz
Docker irudien muntaketa eta hedapena dinamikoa werf-arekin bertsiotutako dokumentazio gune baten adibidea erabiliz
Dagoeneko behin baino gehiagotan hitz egin dugu gure GitOps tresnari buruz. werf, eta oraingoan proiektuaren beraren dokumentazioarekin gunea muntatzen dugun esperientzia partekatu nahi dugu - werf.io (bere errusierazko bertsioa da en.werf.io). Gune estatiko arrunta da, baina bere muntaia interesgarria da artefaktu kopuru dinamiko bat erabiliz eraikitzen baita.
Sartu gunearen egituraren ñabarduretan: bertsio guztietarako menu komun bat sortzea, bertsioei buruzko informazioa duten orrialdeak, etab. - ez dugu egingo. Horren ordez, zentratu gaitezen muntaketa dinamikoaren gai eta ezaugarrietan eta apur bat dakarten CI/CD prozesuetan.
Sarrera: gunearen funtzionamendua
Hasteko, werf dokumentazioa bere kodearekin batera gordetzen da. Honek, oro har, artikulu honen esparrutik kanpo geratzen diren garapen-baldintza batzuk ezartzen ditu, baina gutxienez zera esan daiteke:
Ez dira werf funtzio berriak kaleratu behar dokumentazioa eguneratu gabe eta, alderantziz, dokumentazioan egindako aldaketak werf-en bertsio berri bat kaleratzea dakar;
Proiektuak nahiko garapen intentsiboa du: egunean hainbat aldiz kaleratu daitezke bertsio berriak;
Dokumentazio bertsio berri bat duen gune bat zabaltzeko eskuzko eragiketak gutxienez neketsuak dira;
Proiektuak ikuspegi semantiko bat hartzen du bertsioa egitea, 5 egonkortasun kanalekin. Askapen-prozesuak bertsioak kanaletan zehar sekuentzialki igarotzea dakar, gero eta egonkortasun handiagoaren arabera: alfatik harri solidora;
Guneak errusierazko bertsioa du, "bizi eta garatzen" dena (hau da, edukia eguneratzen dena) bertsio nagusiarekin batera (hau da, ingelesezkoa).
“Barruko sukalde” hori guztia erabiltzaileari ezkutatzeko, “funtzionatzen duen” zerbait eskainiz, egin genuen werf instalatzeko eta eguneratzeko tresna bereizi - Is multiwerf. Erabiltzeko prest zauden bertsio-zenbakia eta egonkortasun-kanala zehaztu besterik ez duzu behar, eta multiwerf-ek kanalean bertsio berririk dagoen egiaztatuko du eta behar izanez gero deskargatuko du.
Webguneko bertsioak aukeratzeko menuan, kanal bakoitzean werf-en azken bertsioak daude eskuragarri. Berez, helbidearen arabera werf.io/documentation azken bertsiorako kanal egonkorrenaren bertsioa irekitzen da - bilatzaileek ere indexatzen dute. Kanalaren dokumentazioa helbide ezberdinetan dago eskuragarri (adibidez, werf.io/v1.0-beta/documentation 1.0 beta bertsiorako).
Guztira, webguneak bertsio hauek ditu eskuragarri:
root (lehenespenez irekitzen da),
bertsio bakoitzeko eguneratze-kanal aktibo bakoitzeko (adibidez, werf.io/v1.0-beta).
Gune baten bertsio zehatz bat sortzeko, oro har, nahikoa da hura erabiliz konpilatzea Jekylldirektorioa exekutatuz /docs werf biltegia dagokion komandoa (jekyll build), beharrezko bertsioaren Git etiketara aldatu ondoren.
Hau gehitzea besterik ez da geratzen:
erabilgarritasuna bera (werf) erabiltzen da muntatzeko;
CI/CD prozesuak GitLab CI-n oinarrituta eraikitzen dira;
eta hori guztia, noski, Kubernetesen exekutatzen da.
zereginak
Orain formula ditzagun deskribatutako berezitasun guztiak kontuan hartzen dituzten zereginak:
Edozein eguneratze kanaletan werf bertsioa aldatu ondoren webguneko dokumentazioa automatikoki eguneratu behar da.
Garapenerako gai izan behar duzu batzuetan ikusi webgunearen aurrebista bertsioak.
Gunea birkonpilatu behar da edozein kanaletan dagozkion Git etiketatatik bertsioa aldatu ondoren, baina irudia eraikitzeko prozesuan ezaugarri hauek lortuko ditugu:
Kanalen bertsioen zerrenda aldatzen denez, bertsioa aldatu den kanalen dokumentazioa berreraikitzea baino ez da beharrezkoa. Azken finean, dena berriro berreraikitzea ez da oso polita.
Argitalpenetarako kanalen multzoa alda daiteke. Uneren batean, adibidez, baliteke kanaletan sarbide goiztiarra 1.1 bertsioa baino bertsio egonkorragorik egotea, baina denborarekin agertuko dira; kasu honetan, ez al zenuke muntaia eskuz aldatu behar?
Izarrekin bihurtzen da muntaia kanpoko datuak aldatzearen araberakoa da.
Inplementazioa
Ikuspegi bat aukeratzea
Bestela, beharrezkoa den bertsio bakoitza kubernetes-en ontzi bereizi gisa exekutatu dezakezu. Aukera honek klusterrean objektu-kopuru handiagoa suposatzen du, werf-en kaleratze egonkorren kopurua handitu ahala haziko dena. Eta horrek, aldi berean, mantentze konplexuagoa dakar: bertsio bakoitzak bere HTTP zerbitzaria du, eta karga txikiarekin. Jakina, horrek baliabide kostu handiagoak ere dakartza.
Bide bera hartu genuen beharrezko bertsio guztiak irudi bakarrean biltzea. Gunearen bertsio guztien konpilatutako estatika NGINX duen edukiontzi batean dago, eta dagokion Inplementaziorako trafikoa NGINX Ingress-en bidez dator. Egitura sinple batek (aberririk gabeko aplikazio bat) Kubernetes bera erabiliz Inplementazioa erraz eskalatu dezakezu (kargaren arabera).
Zehatzago esateko, bi irudi biltzen ari gara: bata produkzio-zirkuiturako, bigarrena gehigarri bat garatzeko zirkuiturako. Irudi gehigarria dev zirkuituan bakarrik erabiltzen da (abian) nagusiarekin batera eta webgunearen bertsioa berrikuspen-konpromisoa dauka, eta haien arteko bideratzea Ingress baliabideak erabiliz egiten da.
werf vs git klona eta artefaktuak
Esan bezala, dokumentazioaren bertsio zehatz baterako gune estatikoak sortzeko, biltegi-etiketa egokira aldatuz eraiki behar duzu. Hau ere egin dezakezu biltegia eraikitzen duzun bakoitzean klonatuz, zerrenda batetik etiketa egokiak hautatuz. Dena den, baliabideak asko behar dituen eragiketa da eta, gainera, argibide ez-hutsak idaztea eskatzen du... Beste desabantaila larri bat da ikuspegi honekin ez dagoela modurik muntaian zehar zerbait cachean gordetzeko.
Hemen werf utility bera datorkigu laguntza, inplementatzen cache adimenduna eta erabiltzeko aukera ematen dizu kanpoko biltegiak. Biltegiko kodea gehitzeko werf erabiltzeak nabarmen azkartuko du eraikuntza, zeren werf funtsean biltegia behin klonatzen du eta gero exekutatzen du bakarrikfetch Beharrezkoa bada. Gainera, biltegiko datuak gehitzean, beharrezkoak diren direktorioak soilik hauta ditzakegu (gure kasuan hau direktorioa da. docs), gehitutako datu kopurua nabarmen murriztuko duena.
Jekyll datu estatikoak biltzeko diseinatutako tresna bat denez eta azken irudian beharrezkoa ez denez, logikoa litzateke hemen biltzea. werf artefaktua, eta azken irudian inportatu konpilazioaren emaitza soilik.
Werf.yaml idazten dugu
Beraz, bertsio bakoitza werf artefaktu batean bilduko genuela erabaki genuen. Hala ere guk ez dakigu zenbat artefaktu hauek izango diren muntatzean, beraz, ezin dugu eraikitze konfigurazio finkorik idatzi (zorrotz esanda, oraindik egin dezakegu, baina ez da guztiz eraginkorra izango).
werf-ek erabiltzeko aukera ematen dizu Joan txantiloiak zure konfigurazio fitxategian (werf.yaml), eta honek posible egiten du konfigurazioa sortu hegan kanpoko datuen arabera (behar duzuna!). Gure kasuan kanpoko datuak bertsioei eta kaleratzeei buruzko informazioa dira, eta horren arabera behar diren artefaktu kopurua biltzen dugu eta, ondorioz, bi irudi lortzen ditugu: werf-doc и werf-dev zirkuitu ezberdinetan ibiltzeko.
Kanpoko datuak ingurune-aldagaietatik pasatzen dira. Hona hemen haien osaera:
RELEASES - kaleratzeen zerrenda eta dagokion werf-en uneko bertsioa dituen lerroa, formatuan espazioz bereizitako balioen zerrenda moduan <НОМЕР_РЕЛИЗА>%<НОМЕР_ВЕРСИИ>... Adibidea: 1.0%v1.0.4-beta.20
CHANNELS - kanalen zerrenda eta dagokion werf-en uneko bertsioa dituen lerroa, formatuan espazioz bereizitako balioen zerrenda moduan <КАНАЛ>%<НОМЕР_ВЕРСИИ>... Adibidea: 1.0-beta%v1.0.4-beta.20 1.0-alpha%v1.0.5-alpha.22
ROOT_VERSION — werf bertsioa lehenespenez bistaratzeko gunean (ez da beti beharrezkoa dokumentazioa kaleratze-zenbaki handienarekin bistaratzea). Adibidea: v1.0.4-beta.20
REVIEW_SHA — Berrikuspen-konpromisoaren hash, bertatik probaren begiztarako bertsioa eraiki behar duzun.
Aldagai hauek GitLab CI kanalizazioan beteko dira, eta behean nola idazten den zehazki.
Lehenik eta behin, erosotasunerako, in definitzen dugu werf.yaml Joan txantiloi-aldagaiak, ingurune-aldagaietatik balioak esleitu:
Gunearen bertsio estatikoa konpilatzeko artefaktuaren deskribapena, oro har, berdina da behar ditugun kasu guztietan (rootaren bertsioa sortzea barne, baita garatzeko zirkuituaren bertsioa ere). Hori dela eta, beste bloke batera eramango dugu funtzioa erabiliz define - gero berrerabiltzeko include. Argumentu hauek pasatuko dizkiogu txantiloiari:
Version — sortutako bertsioa (etiketa izena);
Channel — artefaktua sortzen den eguneratze-kanalaren izena;
Commit — konprometitu hash, artefaktua berrikuspen-konpromiso baterako sortzen bada;
Artefaktuaren izenak bakarra izan behar du. Hori lor dezakegu, adibidez, kanalaren izena gehituz (aldagaiaren balioa .Channel) artefaktuaren izenaren atzizki gisa: artifact: doc-{{ .Channel }}. Baina ulertu behar duzu artefaktuetatik inportatzean, izen berdinak aipatu beharko dituzula.
Artefaktu bat deskribatzean, werf ezaugarri hau erabiltzen da: muntatzea. Zerbitzu-direktorioa adierazten duen muntaketa build_dir kanalizazioen artean Jekyll cachea gordetzeko aukera ematen du, hau da nabarmen bizkortzen du berriro muntatzea.
Baliteke fitxategiaren erabileraz ere nabaritzea releases.yml YAML fitxategi bat da, bertatik eskatutako kaleratze-datuak dituena github.com (tubide bat exekutatzen denean lortutako artefaktua). Beharrezkoa da gunea osatzerakoan, baina artikuluaren testuinguruan interesgarria da guretzat, bere egoeraren araberakoa delako artefaktu bakarra birmuntatzea — gunearen erro bertsioaren artefaktua (ez da beharrezkoa beste artefaktu batzuetan).
Hau baldintzapeko adierazpena erabiliz gauzatzen da if Joan txantiloiak eta diseinuak {{ $Root.Files.Get "releases.yml" | sha256sum }} eszenatokian etapak. Honela funtzionatzen du: root bertsiorako artefaktu bat eraikitzean (aldagaia .Channel berdina da root) fitxategi hash releases.yml etapa osoaren sinadurari eragiten dio, Ansible zereginaren izenaren parte baita (parametroa name). Horrela, aldatzean edukia fitxategia releases.yml dagokion artefaktua berriro muntatuko da.
Mesedez, arreta jarri kanpoko biltegi batekin lan egiteari. Artefaktu baten irudian werf biltegia, direktorioa bakarrik gehitzen da /docs, eta gainditutako parametroen arabera, beharrezkoa den etiketaren edo berrikuspen-konpromisoaren datuak berehala gehitzen dira.
Artefaktu txantiloia kanalen eta bertsio transferituen artefaktuaren deskribapena sortzeko erabiltzeko, aldagaiaren begizta bat antolatu dugu. .WerfVersions в werf.yaml:
{{ range .WerfVersions -}}
{{ $VersionsDict := splitn "%" 2 . -}}
{{ dict "Version" $VersionsDict._1 "Channel" $VersionsDict._0 "Root" $Root | include "doc_artifact" }}
---
{{ end -}}
Zeren begiztak hainbat artefaktu sortuko ditu (espero dugu), haien arteko bereizlea kontuan hartu behar da - sekuentzia --- (Konfigurazio-fitxategiaren sintaxiari buruzko informazio gehiago lortzeko, ikus dokumentazioa). Lehenago definitu den bezala, txantiloi bati begizta batean deitzean, bertsio-parametroak, URLa eta root testuingurua pasatzen ditugu.
Era berean, baina begiztarik gabe, artefaktuaren txantiloiari "kasu berezietarako" deitzen diogu: erroko bertsiorako, baita berrikuspen-konpromisorako bertsiorako ere:
{{ dict "Version" .WerfRootVersion "Channel" "root" "Root" $Root | include "doc_artifact" }}
---
{{- if .WerfReviewCommit }}
{{ dict "Version" "review" "Channel" "review" "Commit" .WerfReviewCommit "Root" $Root | include "doc_artifact" }}
{{- end }}
Kontuan izan berrikuspen-konpromisorako artefaktua aldagaia ezarrita badago soilik eraikiko dela .WerfReviewCommit.
Artefaktuak prest daude - inportatzen hasteko ordua da!
Azken irudia, Kubernetesen exekutatzeko diseinatuta, NGINX arrunta da, zerbitzariaren konfigurazio fitxategia gehituta nginx.conf eta artefaktuetatik estatikoa. Gunearen erro bertsioaren artefaktuaz gain, aldagaiaren begizta errepikatu behar dugu .WerfVersions kanaleko eta kaleratzeko bertsioen artefaktuak inportatzeko + jarraitu lehenago onartu genuen artefaktuak izendatzeko araua. Artefaktu bakoitzak bi hizkuntzatarako webgunearen bertsioak gordetzen dituenez, konfigurazioak eskaintzen dituen tokietara inportatzen ditugu.
Irudi gehigarriak, nagusiarekin batera, garapen-zirkuituan abiarazten dena, webgunearen bi bertsio baino ez ditu: berrikuspen-konpromisoaren bertsioa eta gunearen root bertsioa (aktibo orokorrak daude eta, gogoratzen baduzu, , kaleratu datuak). Horrela, irudi gehigarria inportazio atalean (eta, noski, izenean) bakarrik desberdina izango da nagusiarekiko:
image: werf-dev
...
import:
- artifact: doc-root
add: /app/_main_site
to: /app/main_site
before: setup
- artifact: doc-root
add: /app/_ru_site
to: /app/ru_site
before: setup
{{- if .WerfReviewCommit }}
- artifact: doc-review
add: /app/_main_site
to: /app/main_site/review
before: setup
- artifact: doc-review
add: /app/_ru_site
to: /app/ru_site/review
before: setup
{{- end }}
Goian adierazi bezala, berrikuspen-konpromisorako artefaktua ezarriko ingurune-aldagaia exekutatzen denean bakarrik sortuko da REVIEW_SHA. Posible litzateke werf-dev irudia batere ez sortzea ingurune-aldagairik ez badago REVIEW_SHA, baina ahal izateko garbiketa politikak Docker-en werf-eko irudiek werf-dev irudirako funtzionatu zuten, root bertsioaren artefaktuarekin soilik eraikitzeko utziko dugu (hala ere eraikita dago), kanalizazio-egitura sinplifikatzeko.
Batzarra prest dago! Joan gaitezen CI/CDra eta ñabardura garrantzitsuetara.
Pipeline GitLab CI-n eta eraikuntza dinamikoaren ezaugarriak
Eraikuntza exekutatzen denean erabilitako ingurune-aldagaiak ezarri behar ditugu werf.yaml. Hau ez zaio aplikatzen REVIEW_SHA aldagaiari, GitHub kakotik kanalizazioa deitzean ezarriko duguna.
Beharrezko kanpoko datuak Bash script batean sortuko ditugu generate_artifacts, GitLab kanalizazio bi artefaktu sortuko dituena:
fitxategia releases.yml kaleratze datuekin,
fitxategia common_envs.sh, esportatu beharreko ingurune-aldagaiak dituena.
Fitxategien edukia generate_artifacts gurean aurkituko duzu adibideak dituzten biltegiak. Datuak jasotzea bera ez da artikuluaren gaia, fitxategia baizik common_envs.sh garrantzitsua da guretzat, zeren werf-en lana horren menpe dago. Bere edukiaren adibide bat:
Horrelako script baten irteera erabil dezakezu, adibidez, Bash funtzioa erabiliz source.
Orain parte dibertigarria dator. Aplikazioaren eraikuntza eta hedapena behar bezala funtzionatzeko, beharrezkoa da hori ziurtatzea werf.yaml It zen berdina behintzat hodi baten barruan. Baldintza hori betetzen ez bada, werf-ek muntaian eta, adibidez, zabaltzean kalkulatzen dituen etapen sinadurak desberdinak izango dira. Horrek inplementazio-errore bat ekarriko du, zeren... zabaltzeko behar den irudia faltako da.
Beste era batera esanda, gunearen irudia muntatzean kaleratzeei eta bertsioei buruzko informazioa berdina bada, eta zabaltzeko unean bertsio berri bat askatzen bada eta ingurune-aldagaiek balio desberdinak badituzte, orduan inplementazioak huts egingo du errore batekin: azken finean, bertsio berriaren artefaktua oraindik ez da eraiki.
Belaunaldia bada werf.yaml kanpoko datuen araberakoa da (adibidez, egungo bertsioen zerrenda, gure kasuan bezala), orduan datu horien konposizioa eta balioak kanalizazioan erregistratu behar dira. Hau bereziki garrantzitsua da kanpoko parametroak sarritan aldatzen badira.
egingo dugu kanpoko datuak jaso eta erregistratu GitLab-en kanalizazioaren lehen fasean (Aurrez eraikitzea) eta gehiago transmititu forman GitLab CI artefaktua. Honek kanalizazio lanak (eraiki, zabaldu, garbitu) exekutatu eta berrabiarazi ahal izango dituzu konfigurazio berarekin werf.yaml.
Artifaktuan kanpoko datuak jaso ondoren, GitLab CI kanalizazio fase estandarrak erabiliz eraiki eta zabaldu dezakezu: Eraiki eta zabaldu. Pipelinea bera abiarazten dugu werf GitHub biltegiko kakoak erabiliz (hau da, GitHub biltegian aldaketak daudenean). Horien datuak ataleko GitLab proiektuaren propietateetan aurki daitezke CI/CD ezarpenak -> Pipeline abiarazleak, eta gero sortu dagokion Webhook GitHub-en (Ezarpenak -> Webhooks).
GitLab-ek bi artefaktu gehituko ditu eszenatokitik eraikitze fasera Aurrez eraikitzea, beraz, prestatutako sarrerako datuekin aldagaiak esportatzen ditugu eraikuntza erabiliz source common_envs.sh. Eraikuntza-etapa hasten dugu kasu guztietan, hoditeria programazio baten arabera abiarazteko izan ezik. Egitarauaren arabera, garbiketarako hodi bat egingo dugu; kasu honetan, ez da muntaketa egin beharrik.
Inplementazio-etapan, bi zeregin deskribatuko ditugu - bereizita ekoizpen- eta garapen-zirkuituetara hedatzeko, YAML txantiloi bat erabiliz:
Zereginak, funtsean, werf-ek hedapena egin behar duen kluster-testuingurua adieraztean baino ez dira (WERF_KUBE_CONTEXT), eta begizta inguruneko aldagaiak ezarri (environment.name и environment.url), Helm diagramen txantiloietan erabiltzen direnak. Ez dugu txantiloien edukia emango, zeren... ez dago ezer interesgarririk gaiari dagokionez, baina bertan aurki ditzakezu artikuluaren biltegiak.
Azken ukitua
Werf bertsioak sarritan kaleratzen direnez, irudi berriak maiz eraikiko dira eta Docker Erregistroa etengabe haziko da. Hori dela eta, ezinbestekoa da politiken arabera irudien garbiketa automatikoa konfiguratzea. Oso erraza da egitea.
Ezartzeko:
Gehitu garbiketa-urrats bat .gitlab-ci.yml;
Gehitu garbiketa-lan baten aldizkako exekuzioa;
Konfiguratu ingurune-aldagai bat idazteko sarbide-token batekin.
Dagoeneko ia hori guztia apur bat gorago ikusi dugu - garbitzeko bakarrik Docker Erregistroan saioa hasi behar duzu Docker Erregistroko irudiak ezabatzeko eskubideak dituen token batekin (automatikoki jaulkitako GitLab CI zereginaren tokenak ez du eskubide horiek izan). Tokena aldez aurretik GitLab-en sortu behar da eta bere balioa ingurune-aldagaian zehaztu behar da WERF_IMAGES_CLEANUP_PASSWORD proiektua (CI/CD ezarpenak -> Aldagaiak).
Beharrezko ordutegiarekin garbiketa-zeregin bat gehitzen da CI/CD ->
ordutegiak.
Hori da: Docker Erregistroko proiektu bat ez da etengabe haziko erabili gabeko irudietatik.
Zati praktikoaren amaieran, gogorarazten dizut artikuluaren zerrenda osoa eskuragarri dagoela hemen Git:
Batzar-egitura logiko bat jaso genuen: bertsio bakoitzeko artefaktu bat.
Muntaia unibertsala da eta ez du eskuzko aldaketarik behar werf-en bertsio berriak kaleratzen direnean: webguneko dokumentazioa automatikoki eguneratzen da.
Bi irudi muntatzen dira ingerada ezberdinetarako.
Azkar funtzionatzen du, zeren Cachea ahalik eta gehien erabiltzen da - werf-en bertsio berri bat askatzen denean edo GitHub-en kako bat berrikusteko konpromisoa deitzen denean, aldatutako bertsioarekin dagokion artefaktua soilik berreraikitzen da.
Ez da pentsatu behar erabili gabeko irudiak ezabatzean: werf politiken arabera garbitzeak Docker Erregistroa ordenatuta mantenduko du.
Findings
Werf erabiltzeak muntaia azkar funtzionatzea ahalbidetzen du, bai muntaia bera eta kanpoko biltegiekin lan egitean cachean gordeta dagoelako.
Kanpoko Git biltegiekin lan egiteak biltegi osoa klonatu edo gurpila berrasmatu beharra ezabatzen du optimizazio-logika zailarekin. werf-ek cache bat erabiltzen du eta behin bakarrik egiten du klonazioa, eta gero erabiltzen du fetch eta beharrezkoa denean bakarrik.
Eraikitzeko konfigurazio fitxategian Go txantiloiak erabiltzeko gaitasuna werf.yaml emaitza kanpoko datuen araberakoa den muntaia deskribatzeko aukera ematen du.
Muntatzea werf-en erabiltzeak artefaktuen bilduma nabarmen bizkortzen du - hodi guztietan ohikoa den cachearen ondorioz.
werf-ek garbiketa konfiguratzea errazten du, eta hori bereziki garrantzitsua da dinamikoki eraikitzen denean.