Pull-through-cacher

En pull-through-cache er en spejling af ét offentligt register, som ligger i din egen tenant og fyldes efter behov. Du puller et image gennem den i stedet for fra det offentlige register; det første pull henter imaget fra upstream og beholder en kopi, og senere pull af det samme image betjenes fra den kopi.

Den er nyttig, når et offentligt register begynder at ratebegrænse dig, når en byggepipeline puller de samme baseimages hele dagen, eller når du vil have, at dine arbejdslaster kun skal nå ét endpoint — registry.sweden.frostmoln.cloud — både for dine egne images og for de offentlige, du afhænger af.

Én cache spejler ét upstream-register. Puller du fra GitHub Container Registry, Docker Hub og Quay, er det tre cacher, hver med sit eget navnerum og sin egen pull-sti. Der er ikke andet at konfigurere end valget af upstream-register.

Dit register skal være aktiveret først

En cache ligger i dit register, så aktivér registret, før du opretter en. Har du ikke gjort det, afvises oprettelsen af en cache.

Hvilke upstream-registre du kan spejle

Frostmoln tilbyder en fast liste over offentlige registre — du vælger ét fra den liste, ikke en URL, du selv bestemmer. Da dette blev skrevet, omfatter den Docker Hub, GitHub Container Registry, Quay, Kubernetes-registret, Microsoft Container Registry og Amazon ECR Public.

Læs den aktuelle liste i portalen eller i CLI'et, ikke her

Listen leveres af API'et, så portalens vælger og fm registry cache list viser altid præcis det, der tilbydes i dag, og fm registry cache create udfylder nøglerne fra den samme serverside-liste — så du behøver aldrig at huske dem eller holde din egen kopi. Behandl dem som svaret; navnene ovenfor er eksempler og kan blive forældede. Et upstream-register, der trækkes tilbage, holder op med at blive tilbudt til nye cacher — en cache, du allerede har, bliver ved med at virke og kan stadig slettes.

Docker Hub kræver dine egne Docker Hub-legitimationsoplysninger

En Docker Hub-cache afvises, medmindre du angiver et brugernavn og en adgangskode til Docker Hub (et personligt adgangstoken virker og er det bedre valg).

Det er ikke en vilkårlig regel. En cache, der puller anonymt fra Docker Hub, trækker på en anonym kvote, der deles med andre Frostmoln-kunder på den samme udgående adresse. Én travl anonym spejling bruger den op, og alle andre kunder bag den adresse begynder at blive ratebegrænset — for pull, der intet har med din cache at gøre. At angive dine egne legitimationsoplysninger lægger de pull på din Docker Hub-konto og din egen kvote, hvilket også er den eneste måde, din cache får de grænser, du betaler Docker for.

Andre upstream-registre kræver ikke legitimationsoplysninger i dag, men du kan stadig angive dem — for eksempel for at nå et privat repository, du har adgang til.

Hvilke upstream-registre der kræver legitimationsoplysninger, vises der, hvor du opretter cachen

Portalen markerer dem, og CLI'et siger til, hvis du udelader dem. Reglen håndhæves af API'et, så CLI'et og Terraform møder den samme afvisning som portalen.

Opret en cache

I portalen: åbn Containerregister, find afsnittet Pull-through-cacher der, og vælg så Tilføj cache. Vælg upstream-registret, angiv legitimationsoplysninger, hvis der bliver bedt om dem, og opret den. Et upstream-register, du allerede har en cache til, vises nedtonet frem for skjult — én cache pr. upstream-register. Den nye caches pull-sti vises på dens række; vælg den, eller kopiikonet ved siden af den, for at kopiere den.

Fra CLI'et:

fm registry cache list          # hvad du har, og hvad der tilbydes
fm registry cache create ghcr
fm registry cache delete ghcr   # --force springer bekræftelsen over

Et upstream-register, der kræver legitimationsoplysninger, tager imod dem på én af to sikre måder. I en terminal: angiv brugernavnet, og lad kommandoen spørge efter adgangskoden — den ekkoes ikke, og den havner aldrig i din shell-historik:

fm registry cache create dockerhub --username acme

I CI, hvor der ikke kan spørges om noget, sender du adgangskoden på stdin:

printf '%s' "$DOCKERHUB_TOKEN" | fm registry cache create dockerhub \
  --username acme --password-stdin

Brug printf '%s' frem for echo, af den grund, der er forklaret under Log ind — echo forvansker nogle værdier i stilhed, og et forvansket upstream-token fejler som et ødelagt pull frem for som en forkert adgangskode.

Der findes også et --password-flag. Betragt det som en sidste udvej: værdien er synlig i ps på en delt maskin og bliver liggende i din shell-historik, så foretræk en af de to måder ovenfor. At køre ikke-interaktivt helt uden adgangskode er ingen fælde — kommandoen fejler og nævner --password-stdin i stedet for at hænge.

Med Terraform:

resource "frostmoln_container_registry_cache" "ghcr" {
  upstream = "ghcr"

  depends_on = [frostmoln_container_registry.this]
}

resource "frostmoln_container_registry_cache" "dockerhub" {
  upstream = "dockerhub"
  username = var.dockerhub_username
  password = var.dockerhub_token # følsom — se advarslen nedenfor

  depends_on = [frostmoln_container_registry.this]
}

Upstream-adgangskoden skrives til Terraform-state

Terraform gemmer hver værdi, du sender ind, så dit Docker Hub-token ender i state — JSON i klartekst i din arbejdsmappe, hvis du ikke har konfigureret en fjernbackend. Advarslen på registersiden gælder her fuldt ud: brug en krypteret fjernbackend, hold terraform.tfstate* uden for git, og hent værdien fra en variabel frem for at skrive den ind i .tf-filen.

Uanset hvilken flade du bruger, får du caches pull-sti tilbage. Det er det eneste, du har brug for bagefter.

Legitimationsoplysningerne kontrolleres ikke, når du opretter cachen

Frostmoln tester dem ikke mod upstream-registret, så en tastefejl fejler ikke her — den fejler senere, som et pull, der ikke kan hente imaget. Betjener en cache aldrig noget, så mistænk legitimationsoplysningerne først.

Pull gennem cachen

Sæt caches pull-sti foran imaget i stedet for upstream-værten, og behold resten af referencen nøjagtigt, som den var.

Et image, du normalt ville pulle som:

ghcr.io/acme/widget:1.2.3

bliver til:

registry.sweden.frostmoln.cloud/t-3f2a9c1e4b7d4a2f8e1c5d6b7a8f9e0d-cache-ghcr/acme/widget:1.2.3

Din egen pull-sti vises i portalen og af fm registry cache list; delen t-...-cache-ghcr ovenfor er et eksempel.

Brug det samme sæt legitimationsoplysninger, som du allerede bruger til dine egne images. docker login gælder pr. vært, og en cache ligger på samme vært som dit navnerum, så ét login dækker begge dele. Du udsteder ikke noget nyt til en cache — de legitimationsoplysninger, du allerede har, udvides automatisk til den, når den oprettes.

# Log ind én gang (sæt brugernavnet i enkelte anførselstegn — det indeholder et $)
docker login registry.sweden.frostmoln.cloud -u 'robot$t-...-a1b2c3d4'

# Pull gennem cachen
docker pull \
  registry.sweden.frostmoln.cloud/t-3f2a9c1e4b7d4a2f8e1c5d6b7a8f9e0d-cache-ghcr/acme/widget:1.2.3

Et sæt pull-legitimationsoplysninger er nok. podman tager de samme kommandoer.

Officielle Docker Hub-images beholder deres library/-præfiks

docker pull nginx virker, fordi Docker-klienten udvider det til docker.io/library/nginx. Intet udvider det for dig her, så gennem en Docker Hub-cache er referencen registry.sweden.frostmoln.cloud/<dit-cache-navnerum>/library/nginx:1.27. Udelader du library/, får du en "not found", der ligner en ødelagt cache.

Fra en administreret Kubernetes-klynge

Der er ikke brug for noget nyt. Cachen ligger på samme vært som dit register, så den image pull secret, du allerede har, dækker den — du ændrer kun image-referencen:

spec:
  imagePullSecrets:
    - name: frostmoln-registry
  containers:
    - name: my-app
      image: registry.sweden.frostmoln.cloud/t-3f2a9c1e4b7d4a2f8e1c5d6b7a8f9e0d-cache-ghcr/acme/widget:1.2.3

Har du ikke den Secret endnu, så byg den nøjagtigt som til dine egne images — se Pull fra en administreret Kubernetes-klynge, inklusive bemærkningen om, at klyngens VPC skal have en gateway for at få udgående adgang.

Tags, :latest og hvor aktuel en cache er

Et pull via tag spørger upstream hver gang, cachen kan nå den. Hver gang du puller acme/widget:1.2.3 eller acme/widget:latest gennem en cache, spørger cachen først upstream, hvilket image taggen peger på lige nu, og giver dig det — den kopi, den allerede har, hvis intet har ændret sig, ellers det nye image, som den derefter beholder. Der er ingen cache-levetid at vente ud: :latest gennem en cache følger upstream i det øjeblik, du puller.

Når upstream siger, at en tag ikke længere findes, fejler et pull via den tag, selv hvis cachen stadig har en kopi. Fjernes en tag hos upstream, forsvinder den også for pull gennem cachen.

Når cachen ikke kan få svar fra upstream — den er utilgængelig eller afviser tjekket med et ratebegrænsningssvar — afhænger det af imaget, hvad du får:

• Et pull via tag af et image til én platform betjenes fra cachen — også selvom taggen siden har flyttet sig upstream. Pullet lykkes, og intet fortæller dig, at imaget kan være forældet.
• Et pull via tag af et multiplatform-image med Docker fejler. De fleste offentlige images er multiplatform-images (én tag, der dækker linux/amd64, linux/arm64 og så videre), og cachen gemmer dem ikke under taggen — se Multiplatform-images nedenfor — så der er intet under taggen at falde tilbage på.
• Et pull via digesten for et image, som cachen har — et image til én platform eller én platform af et multiplatform-image — betjenes fra cachen, med eller uden upstream.

Lås fast på en platform-digest, så pulls virker gennem et nedbrud hos upstream

Den digest, docker pull udskriver for et multiplatform-image, og den i RepoDigests fra docker inspect, er digesten for indexet — listen over platforme. Cachen gemmer ikke indexet, som det er, så et pull via den digest kræver, at upstream svarer. Lås i stedet fast på digesten for det platform-image, du kører:

image: <pull-sti>/acme/widget@sha256:<digest for linux/amd64>

Du finder den ved at vise platformene for upstream-imaget — platform-digesterne er de samme hos upstream og i cachen:

docker buildx imagetools inspect ghcr.io/acme/widget:1.2.3
docker manifest inspect ghcr.io/acme/widget:1.2.3   # det samme, som JSON

Spring over poster, hvis platform er unknown/unknown — det er build-attesteringer, ikke images. Pull den fastlåste reference gennem cachen én gang, så cachen har den, og bliv ved med at pulle den: som ethvert andet image fjernes et image, som ingen puller i 7 dage.

Images, som ingen puller, fjernes. Et image, der ikke er blevet pullet gennem cachen i 7 dage, fjernes fra den ved næste daglige tjek. Det næste pull henter det fra upstream igen, så længe upstream svarer — og det forhindrer en cache i at holde fast i lagringsplads til images, du er holdt op med at bruge.

Multiplatform-images

Når du puller et multiplatform-image gennem en cache med Docker, henter Docker først indexet via dets tag og derefter det ene platform-image, det har brug for, via det images digest. Cachen gemmer det, den blev bedt om:

• Det platform-image, du pullede — for eksempel linux/amd64 — under sin egen digest, uden tag, fordi det blev hentet via digest.
• Kort efter cachens eget index, som viser de platforme, der indtil videre er blevet pullet gennem cachen. Det har heller ingen tag, og dets digest er aldrig upstreams: cachen bygger selv dette index, så dets digest er anderledes, selv når alle platforme er blevet pullet.

Når du gennemser cachen, er det dette, du ser: først platform-imaget, og når cachens eget index findes, det index i stedet — uden tag, med en digest, der hverken matcher upstreams eller RepoDigests. Der er intet galt med imaget, og pulls via tag bliver ved med at virke, mens upstream svarer: cachen spørger upstream om det aktuelle index hver gang, som beskrevet ovenfor.

Den digest, der vises, når du gennemser, er cachens, ikke en at låse fast på. For at låse fast på et platform-image skal du tage dets digest fra upstream som vist i tippet ovenfor.

Se hvad en cache indeholder

I portalen: vælg Gennemse på en caches række i afsnittet Pull-through-cacher. Du får de repositories, cachen indeholder, og for hvert af dem dets images: tags, digest, størrelse, hvornår cachen hentede imaget, og hvornår det sidst blev pullet. Vælg en tag, eller kopiikonet ved siden af den, for at kopiere den fulde reference, der puller imaget gennem cachen. Et multiplatform-image, der er pullet med Docker, vises uden tag og under sin egen digest — se Multiplatform-images.

Fra CLI'et angiver du cachen med upstream-registrets nøgle, ligesom alle andre steder:

fm registry cache repository list ghcr
fm registry cache image list ghcr acme/widget
fm registry cache image list ghcr acme/widget --all -o json

Repository-navnene er upstreams egne — acme/widget, eller library/nginx gennem en Docker Hub-cache — uden cachens navnerum foran.

Fjern images fra en cache

Du kan fjerne ét image fra en cache uden at slette cachen. I portalen: tryk Fjern på imagets række. Fra CLI'et:

fm registry cache image delete ghcr acme/widget sha256:1b0c8dd1...
fm registry cache image delete ghcr acme/widget sha256:1b0c8dd1... --force

Den tager en digest, aldrig en tag, af samme grund som ved sletning af dine egne images: en tag kan flytte sig mellem listningen og sletningen. Alle tags på imaget følger med, og et multiarkitektur-image fjernes via sit index, ikke via sine dele pr. platform.

Det er ikke permanent. Alt i en cache er en kopi af noget, der stadig findes hos upstream, så det næste pull af imaget henter det blot igen. Fjern et image for at frigøre plads nu i stedet for at vente på, at det ældes ud. Det forhindrer ikke nogen i at pulle imaget — for at stoppe pull gennem en cache skal du slette cachen.

At fjerne giver dig ikke et friskere image

Et pull via tag spørger allerede upstream hver gang, så der er ingen forældet kopi at rydde væk, mens upstream svarer. Og mens upstream ikke kan nås eller begrænser dig, er den cachede kopi af et image til én platform eller af en fastlåst platform-digest det eneste, et pull kan få — fjerner du den da, fejler pulls af imaget, indtil upstream svarer igen.

Cachede images tæller mod din lagringsgrænse

Én grænse, delt med dine egne images — og en cache fylder sig selv

Alt, hvad en cache gemmer, tæller mod den samme lagringsgrænse som dit eget navnerum. Der er ét tal og én grænse for hele dit register: dine images plus hver eneste cache, du ejer.

En cache fyldes ved pull, ikke ved push. Den kan altså bruge af din grænse, uden at du nogensinde pusher noget — og den gør det som en sidevirkning af et helt almindeligt docker pull fra en pipeline, en klynge eller en kollega. Selv en forespørgsel, der kun beder om et manifest, udløser en fuld hentning af imaget.

Den praktiske konsekvens: en cache foran et travlt offentligt register kan fylde din grænse helt på egen hånd, og det første tegn er, at et push af dine egne images afvises, fordi der ikke er plads tilbage.

Hold øje med lagringstallet i portalen under Anvendt lagring, eller med fm registry status, efter at du har tilføjet en cache — det er summen, så det flytter sig, når en cache fyldes. Hver caches eget tal står i kolonnen Lagring i afsnittet Pull-through-cacher. Det tæller hvert lagret lag én gang inden for den cache, så det fortæller dig, hvilken cache der er ved at blive fyldt, ikke summen af størrelserne på de images, du har pullet.

Er du ved at løbe tør for plads, er den hurtigste måde at få plads igen som regel at slette en cache, du ikke længere puller gennem — se Slet en cache — eller at fjerne de images, du ikke længere har brug for, fra en cache, du beholder. Ingen af delene koster dig noget varigt. At slette dine egne images er beskrevet under Frigør plads.

Ændring af upstream-legitimationsoplysningerne

Der findes ingen opdatering. Legitimationsoplysningerne er skrivebeskyttede i den forstand, at intet læser dem tilbage, og der er intet felt at ændre. For at rotere et Docker Hub-token, eller for at rette et, du har skrevet forkert, sletter du cachen og opretter den igen med de nye værdier.

Det er ikke så tungt, som det lyder — du mister de cachede kopier, og det næste pull henter dem igen. Pull-stien udledes af din tenant og upstream-registret, så den kommer tilbage identisk, og intet, der refererer til den, skal ændres.

Slet en cache

I portalen: fjern rækken i afsnittet Pull-through-cacher på siden Containerregister. Fra CLI'et:

fm registry cache delete ghcr
fm registry cache delete ghcr --force   # samme, uden spørgsmål

Sletningen tager upstream-registrets nøgle — det samme korte navn, du oprettede den med — og det er det, portalrækken og fm registry cache list viser.

At slette en cache sletter de images, den havde cachet, og den spørger ikke to gange. Det er sikkert på en måde, som sletning af dine egne images ikke er: alt i en cache er en kopi af noget, der stadig findes hos upstream, så intet, du selv har lavet, går tabt. Opret cachen igen, pull igen, og indholdet kommer tilbage.

To ting ændrer sig med det samme:

• Dit tal for lagrede byte falder, efterhånden som det cachede indhold forsvinder. Det er netop pointen, hvis du slettede for at frigøre plads.
• Alt, der stadig puller gennem den sti, begynder at fejle. Søg i dine manifester, Helm-værdier og pipelinefiler efter pull-stien, før du sletter en cache, der har været i brug.

De gemte upstream-legitimationsoplysninger følger med. Sletter du en cache for at ændre dem, så hav det nye brugernavn og token klar, før du går i gang.

Hvor mange cacher du kan have

Din tenant må have et begrænset antal cacher ad gangen. At oprette en ud over grænsen afvises, og løsningen er at slette en cache, du ikke længere puller gennem.

Læs tallet der, hvor du opretter cachen

Portalen viser grænsen og holder op med at tilbyde Tilføj cache, når du når den, og fm registry cache list rapporterer den sammen med det, du har. Det tal kommer fra API'et og er det, der gælder — denne side skriver bevidst ikke noget tal, så det ikke stille og roligt kan blive forældet.

Når oprettelse af en cache afvises

Det, du ser	Hvad det betyder
Upstream-registret kan ikke spejles	Det står ikke på den tilbudte liste, eller det er trukket tilbage, siden du skrev dit script. Læs den aktuelle liste, og vælg derfra.
Der kræves legitimationsoplysninger til dette upstream-register	Docker Hub, i dag. Angiv dit eget brugernavn og token — se ovenfor.
Du har allerede en cache til dette upstream-register	Én cache pr. upstream-register, og der er intet at opdatere. Slet den, og opret den igen, hvis du skal ændre legitimationsoplysningerne.
Du har nået grænsen	Slet en cache, du ikke længere puller gennem.
Dit register er ikke aktiveret	Aktivér det først.

Et suspenderet register nægter også at oprette en cache, ligesom det nægter enhver anden skrivning. Pull gennem cacher, du allerede har, bliver ved med at virke med de pull-legitimationsoplysninger, du allerede har — præcis som for dine egne images. Se Hvis dit register er suspenderet.