Pull-through-cacher

En pull-through-cache er en speiling av ett offentlig register, plassert i din egen tenant og fylt ved behov. Du henter et bilde via den i stedet for fra det offentlige registeret; den første hentingen henter bildet fra oppstrøms og beholder en kopi, og senere hentinger av det samme bildet betjenes fra den kopien.

Det er nyttig når et offentlig register begynner å begrense deg, når en byggepipeline henter de samme grunnbildene hele dagen, eller når du vil at arbeidslastene dine skal nå én adresse — registry.sweden.frostmoln.cloud — for både dine egne bilder og de offentlige du er avhengig av.

Én cache speiler ett oppstrømsregister. Henter du fra GitHub Container Registry, Docker Hub og Quay, er det tre cacher, hver med sitt eget navnerom og sin egen pull-sti. Det er ingenting å konfigurere utover valget av oppstrømsregister.

Registeret ditt må være aktivert først

En cache ligger i registeret ditt, så aktiver registeret før du oppretter en. Har du ikke gjort det, avvises forsøket på å opprette en cache.

Hvilke oppstrømsregistre du kan speile

Frostmoln tilbyr en fast liste over offentlige registre — du velger ett fra den listen, ikke en URL du bestemmer selv. Da dette ble skrevet omfatter den Docker Hub, GitHub Container Registry, Quay, Kubernetes-registeret, Microsoft Container Registry og Amazon ECR Public.

Les den gjeldende listen i portalen eller i CLI-et, ikke her

Listen leveres av API-et, så portalens velger og fm registry cache list viser alltid nøyaktig hva som tilbys i dag, og fm registry cache create fullfører nøklene fra den samme serverlisten — så du trenger aldri å huske dem eller holde en egen kopi. Gå ut fra dem; navnene over er eksempler og kan bli utdaterte. Et oppstrømsregister som trekkes tilbake, slutter å bli tilbudt for nye cacher — en cache du allerede har, fortsetter å virke og kan fortsatt slettes.

Docker Hub krever din egen Docker Hub-legitimasjon

En Docker Hub-cache avvises med mindre du oppgir et brukernavn og et passord for Docker Hub (et personlig tilgangstoken virker, og er det bedre valget).

Dette er ingen vilkårlig regel. En cache som henter anonymt fra Docker Hub, tærer på en anonym kvote som deles med andre Frostmoln-kunder på den samme utgående adressen. Én travel anonym speiling bruker den opp, og alle andre kunder bak den adressen begynner å bli hastighetsbegrenset — for hentinger som ikke har noe med cachen din å gjøre. Å oppgi din egen legitimasjon legger hentingene på din Docker Hub-konto og din egen kvote, som også er den eneste måten cachen din får grensene du betaler Docker for.

Andre oppstrømsregistre krever ingen legitimasjon i dag, men du kan likevel oppgi den — for eksempel for å nå et privat repository du har tilgang til.

Hvilke oppstrømsregistre som krever legitimasjon vises der du oppretter cachen

Portalen merker dem, og CLI-et sier fra hvis du utelater dem. Regelen håndheves av API-et, så CLI-et og Terraform møter det samme avslaget som portalen.

Opprett en cache

I portalen: åpne Containerregister og finn seksjonen Pull-through-cacher der, og velg så Legg til cache. Velg oppstrømsregister, oppgi legitimasjon hvis den etterspørres, og opprett den. Et oppstrømsregister du allerede har en cache for, vises nedtonet i stedet for skjult — én cache per oppstrømsregister. Den nye cachens pull-sti vises på raden sin; velg den, eller kopiikonet ved siden av den, for å kopiere den.

Fra CLI-et:

fm registry cache list          # hva du har, og hva som tilbys
fm registry cache create ghcr
fm registry cache delete ghcr   # --force hopper over bekreftelsen

Et oppstrømsregister som krever legitimasjon, tar imot den på én av to trygge måter. Ved en terminal: oppgi brukernavnet og la kommandoen spørre etter passordet — det ekkoes ikke, og det havner aldri i skallhistorikken din:

fm registry cache create dockerhub --username acme

I CI, der det ikke finnes noe spørsmål, mater du passordet inn på stdin:

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

Bruk printf '%s' og ikke echo, av grunnen som er forklart under Innlogging — echo forvrenger enkelte verdier stille, og et forvrengt oppstrømstoken feiler som en ødelagt henting snarere enn som et feil passord.

Det finnes også et --password-flagg. Se på det som en siste utvei: verdien er synlig i ps på en delt maskin og blir liggende i skallhistorikken din, så foretrekk én av de to måtene over. Å kjøre ikke-interaktivt helt uten passord er ingen felle — kommandoen feiler og nevner --password-stdin i stedet for å henge.

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 # sensitivt — se advarselen nedenfor

  depends_on = [frostmoln_container_registry.this]
}

Oppstrømspassordet skrives til Terraform-staten

Terraform lagrer hver verdi du sender inn, så Docker Hub-tokenet ditt havner i staten — som JSON i klartekst i arbeidskatalogen din hvis du ikke har konfigurert en fjernbackend. Advarselen på registersiden gjelder her fullt ut: bruk en kryptert fjernbackend, hold terraform.tfstate* utenfor git, og hent verdien fra en variabel i stedet for å skrive den inn i .tf-filen.

Uansett hvilken flate du bruker, får du tilbake cachens pull-sti. Det er det eneste du trenger etterpå.

Legitimasjonen kontrolleres ikke når du oppretter cachen

Frostmoln tester den ikke mot oppstrømsregisteret, så en skrivefeil feiler ikke her — den feiler senere, som en henting som ikke får tak i bildet. Betjener en cache aldri noe, mistenk legitimasjonen først.

Hent via cachen

Sett cachens pull-sti i stedet for oppstrømsverten foran bildet, og behold resten av referansen nøyaktig som den var.

Et bilde du normalt ville hentet som:

ghcr.io/acme/widget:1.2.3

blir:

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

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

Bruk den samme legitimasjonen som du allerede bruker for dine egne bilder.docker login gjelder per vert, og en cache ligger på samme vert som navnerommet ditt, så én innlogging dekker begge. Du oppretter ingenting nytt for en cache — legitimasjonen du allerede har, utvides automatisk til den når den opprettes.

# Logg inn én gang (enkeltfnutt rundt brukernavnet — det inneholder en $)
docker login registry.sweden.frostmoln.cloud -u 'robot$t-...-a1b2c3d4'

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

En pull-legitimasjon holder. podman tar de samme kommandoene.

Offisielle Docker Hub-bilder beholder library/-prefikset sitt

docker pull nginx virker fordi Docker-klienten utvider det til docker.io/library/nginx. Ingenting utvider det for deg her, så via en Docker Hub-cache er referansen registry.sweden.frostmoln.cloud/<cache-navnerommet-ditt>/library/nginx:1.27. Utelater du library/, får du et «not found» som ser ut som en ødelagt cache.

Fra en administrert Kubernetes-klynge

Ingenting nytt trengs. Cachen ligger på samme vert som registeret ditt, så image pull secreten du allerede har, dekker den — du endrer bare bildereferansen:

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 Secreten ennå, bygg den nøyaktig som for dine egne bilder — se Hent bilder fra en administrert Kubernetes-klynge, inkludert merknaden om at klyngens VPC trenger en gateway for utgående trafikk.

Tagger, :latest og hvor oppdatert en cache er

En henting med tagg spør oppstrømsregisteret hver gang cachen kan nå det. Hver gang du henter acme/widget:1.2.3 eller acme/widget:latest via en cache, spør cachen først oppstrømsregisteret hvilket bilde taggen peker på akkurat nå, og gir deg det — kopien den allerede har hvis ingenting er endret, ellers det nye bildet, som den deretter beholder. Det finnes ingen levetid for cachen å vente ut: :latest via en cache følger oppstrømsregisteret i det øyeblikket du henter.

Når oppstrømsregisteret sier at en tagg ikke lenger finnes, feiler en henting med den taggen, selv om cachen fortsatt har en kopi. Fjernes en tagg oppstrøms, forsvinner den også for hentinger via cachen.

Når cachen ikke får svar fra oppstrømsregisteret — det er utilgjengelig, eller avviser sjekken med et svar om hastighetsbegrensning — avhenger det av bildet hva du får:

• Et bilde for én plattform som hentes med tagg, betjenes fra cachen — selv om taggen har flyttet seg oppstrøms siden. Hentingen lykkes, og ingenting forteller deg at bildet kan være utdatert.
• En henting med tagg av et flerplattformsbilde med Docker feiler. De fleste offentlige bilder er flerplattformsbilder (én tagg som dekker linux/amd64, linux/arm64 og så videre), og cachen lagrer dem ikke under taggen — se Flerplattformsbilder nedenfor — så det finnes ingenting under taggen å falle tilbake på.
• En henting med digesten til et bilde cachen har — et bilde for én plattform, eller én plattform av et flerplattformsbilde — betjenes fra cachen, med eller uten oppstrømsregisteret.

Fest en plattformdigest for at hentinger skal virke gjennom et avbrudd oppstrøms

Digesten docker pull skriver ut for et flerplattformsbilde, og den i RepoDigests fra docker inspect, er digesten til indeksen — listen over plattformer. Cachen tar ikke vare på den indeksen slik den er, så en henting med den digesten krever at oppstrømsregisteret svarer. Fest i stedet digesten til plattformbildet du kjører:

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

Du finner den ved å liste plattformene til bildet oppstrøms — plattformdigestene er de samme oppstrøms 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

Hopp over oppføringer med plattformen unknown/unknown — det er byggattesteringer, ikke bilder. Hent den festede referansen via cachen én gang, så cachen har den, og fortsett å hente den: som alle andre bilder fjernes et bilde ingen henter på 7 dager.

Bilder ingen henter, fjernes. Et bilde som ikke er hentet via cachen på 7 dager, fjernes fra den ved neste daglige sjekk. Neste henting henter det fra oppstrømsregisteret igjen, så lenge oppstrømsregisteret svarer — og det hindrer en cache i å holde på lagringsplass for bilder du har sluttet å bruke.

Flerplattformsbilder

Når du henter et flerplattformsbilde via en cache med Docker, henter Docker først indeksen med taggen, og deretter det ene plattformbildet det trenger, med digesten til det bildet. Cachen lagrer det den ble bedt om:

• Plattformbildet du hentet — for eksempel linux/amd64 — under sin egen digest, uten tagg, fordi det ble hentet med digest.
• Kort etter cachens egen indeks, som lister plattformene som er hentet via cachen så langt. Den har heller ingen tagg, og digesten dens er aldri oppstrømsregisterets: cachen bygger denne indeksen selv, så digesten er en annen selv når alle plattformene er hentet.

Når du blar gjennom cachen, er det dette du ser: først plattformbildet, og når cachens egen indeks finnes, den indeksen i stedet — uten tagg, med en digest som verken samsvarer med oppstrømsregisterets eller med RepoDigests. Det er ingenting galt med bildet, og hentinger med tagg fortsetter å virke mens oppstrømsregisteret svarer: cachen spør oppstrømsregisteret om den gjeldende indeksen hver gang, som beskrevet ovenfor.

Digesten som vises når du blar, er cachens, ikke en du skal feste. For å feste et plattformbilde tar du digesten fra oppstrømsregisteret, som vist i tipset ovenfor.

Se hva en cache inneholder

I portalen: velg Bla gjennom på raden til en cache i seksjonen Pull-through-cacher. Du får repositoriene cachen inneholder og, for hvert av dem, bildene: tagger, digest, størrelse, når cachen hentet bildet og når det sist ble hentet. Velg en tagg, eller kopiikonet ved siden av den, for å kopiere hele referansen som henter bildet via cachen. Et flerplattformsbilde hentet med Docker vises uten tagg og under en egen digest — se Flerplattformsbilder.

Fra CLI-et angir du cachen med nøkkelen til oppstrømsregisteret, som overalt ellers:

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 oppstrømsregisterets egne — acme/widget, eller library/nginx via en Docker Hub-cache — uten cachens navnerom foran.

Fjern bilder fra en cache

Du kan fjerne ett bilde fra en cache uten å slette cachen. I portalen: trykk Fjern på raden til bildet. 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 tar en digest, aldri en tagg, av samme grunn som når du sletter dine egne bilder: en tagg kan flytte seg mellom listingen og slettingen. Alle taggene på bildet følger med, og et bilde for flere arkitekturer fjernes via indeksen sin, ikke via delene per plattform.

Det er ikke varig. Alt i en cache er en kopi av noe som fortsatt finnes oppstrøms, så neste henting av bildet henter det rett og slett på nytt. Fjern et bilde for å frigjøre plass nå i stedet for å vente på at det eldes ut. Det hindrer ingen i å hente bildet — for å stoppe hentinger via en cache, slett cachen.

Å fjerne gir deg ikke et ferskere bilde

En henting med tagg spør allerede oppstrømsregisteret hver gang, så det finnes ingen utdatert kopi å rydde bort mens oppstrømsregisteret svarer. Og mens oppstrømsregisteret ikke kan nås eller begrenser deg, er den cachede kopien av et bilde for én plattform eller av en festet plattformdigest det eneste en henting kan få — fjerner du den da, feiler hentinger av bildet til oppstrømsregisteret svarer igjen.

Cachede bilder teller mot lagringsgrensen din

Én grense, delt med dine egne bilder — og en cache fyller seg selv

Alt en cache lagrer, teller mot den samme lagringsgrensen som ditt eget navnerom. Det er ett tall og én grense for hele registeret ditt: bildene dine pluss hver cache du eier.

En cache fylles ved henting, ikke ved push. Den kan altså bruke opp grensen din uten at du noen gang pusher noe — og den gjør det som en bivirkning av en helt vanlig docker pull fra en pipeline, en klynge eller en kollega. Selv en forespørsel som bare ber om et manifest, utløser en full henting av bildet.

Den praktiske følgen: en cache foran et travelt offentlig register kan fylle grensen din på egen hånd, og det første tegnet er at en push av dine egne bilder avvises fordi det ikke er plass igjen.

Følg med på lagringstallet i portalen under Lagring i bruk, eller med fm registry status, etter at du har lagt til en cache — det er summen, så det beveger seg når en cache fylles. Hver caches eget tall står i kolonnen Lagring i seksjonen Pull-through-cacher. Det teller hvert lagrede lag én gang innenfor den cachen, så det forteller deg hvilken cache som holder på å fylles, ikke summen av størrelsene på bildene du har hentet.

Holder plassen på å ta slutt, er det som regel raskest å slette en cache du ikke lenger henter via — se Slett en cache — eller å fjerne bildene du ikke lenger trenger fra en cache du beholder. Ingen av delene koster deg noe varig. Å slette dine egne bilder er beskrevet under Frigjøre plass.

Bytte oppstrømslegitimasjonen

Den kan ikke oppdateres. Legitimasjonen er skrivebeskyttet i den forstand at ingenting leser den tilbake, og det finnes ikke noe felt å endre. For å rotere et Docker Hub-token, eller rette ett du skrev feil, sletter du cachen og oppretter den på nytt med de nye verdiene.

Det er ikke så tungt som det høres ut — du mister de cachede kopiene, og neste henting henter dem på nytt. Pull-stien utledes av tenanten din og oppstrømsregisteret, så den blir identisk, og ingenting som viser til den, må endres.

Slett en cache

I portalen: fjern raden i seksjonen Pull-through-cacher på siden Containerregister. Fra CLI-et:

fm registry cache delete ghcr
fm registry cache delete ghcr --force   # det samme, uten bekreftelse

Slettingen tar oppstrømsregisterets nøkkel — det samme korte navnet du opprettet den med — og det er det portalraden og fm registry cache list viser.

Å slette en cache sletter bildene den hadde cachet, og spør ikke to ganger. Det er trygt på en måte sletting av dine egne bilder ikke er: alt i en cache er en kopi av noe som fortsatt finnes oppstrøms, så ingenting du har laget, går tapt. Opprett cachen igjen, hent igjen, og innholdet kommer tilbake.

To ting endrer seg umiddelbart:

• Tallet for lagrede byte faller etter hvert som det cachede innholdet forsvinner. Det er hele poenget hvis du slettet for å frigjøre plass.
• Alt som fortsatt henter via den stien, begynner å feile. Søk gjennom manifestene, Helm-verdiene og pipelinefilene dine etter pull-stien før du sletter en cache som er i bruk.

Den lagrede oppstrømslegitimasjonen følger med. Sletter du cachen for å bytte den, ha det nye brukernavnet og det nye tokenet klart før du begynner.

Hvor mange cacher du kan ha

Tenanten din kan ha et begrenset antall cacher om gangen. Å opprette en til utover grensen avvises, og løsningen er å slette en cache du ikke lenger henter via.

Les tallet der du oppretter cachen

Portalen viser grensen og slutter å tilby Legg til cache når du har nådd den, og fm registry cache list rapporterer den sammen med det du har. Det tallet kommer fra API-et og er det som gjelder — denne siden skriver bevisst ikke ut noe tall, slik at det ikke stille kan bli utdatert.

Når en cache ikke kan opprettes

Det du ser	Hva det betyr
Oppstrømsregisteret kan ikke speiles	Det står ikke på den tilbudte listen, eller er trukket tilbake siden du skrev skriptet ditt. Les den gjeldende listen og velg derfra.
Legitimasjon kreves for dette oppstrømsregisteret	Docker Hub, i dag. Oppgi eget brukernavn og token — se over.
Du har allerede en cache for det oppstrømsregisteret	Én cache per oppstrømsregister, og det er ingenting å oppdatere. Slett den og opprett den på nytt hvis du skal bytte legitimasjon.
Du har nådd grensen	Slett en cache du ikke lenger henter via.
Registeret ditt er ikke aktivert	Aktiver det først.

Et suspendert register nekter også å opprette en cache, slik det nekter enhver annen skriving. Hentinger via cacher du allerede har, fortsetter å virke, med pull-legitimasjonen du allerede innehar — akkurat som for dine egne bilder. Se Hvis registeret ditt er suspendert.