Pull-through-cacher

En pull-through-cache är en spegling av ett publikt register, placerad i din egen tenant och fylld vid behov. Du hämtar en avbild via den i stället för från det publika registret; den första hämtningen hämtar avbilden uppströms och behåller en kopia, och senare hämtningar av samma avbild serveras från den kopian.

Den är användbar när ett publikt register börjar begränsa dig, när en byggpipeline hämtar samma basavbilder hela dagen, eller när du vill att dina arbetslaster ska nå en enda adress — registry.sweden.frostmoln.cloud — för både dina egna avbilder och de publika du är beroende av.

En cache speglar ett uppströmsregister. Om du hämtar från GitHub Container Registry, Docker Hub och Quay är det tre cacher, var och en med sin egen namnrymd och sin egen pull-sökväg. Det finns inget att konfigurera utöver valet av uppströmsregister.

Ditt register måste vara aktiverat först

En cache ligger i ditt register, så aktivera registret innan du skapar en. Har du inte gjort det avvisas försöket att skapa en cache.

Vilka uppströmsregister du kan spegla

Frostmoln erbjuder en fast lista över publika register — du väljer ett ur den listan, inte en egen URL. När detta skrivs omfattar den Docker Hub, GitHub Container Registry, Quay, Kubernetes-registret, Microsoft Container Registry och Amazon ECR Public.

Läs den aktuella listan i portalen eller i CLI:et, inte här

Listan levereras av API:et, så portalens väljare och fm registry cache list visar alltid exakt vad som erbjuds i dag, och fm registry cache create kompletterar nycklarna från samma serverlista — så du behöver aldrig memorera dem eller hålla en egen kopia. Utgå från dem; namnen ovan är exempel och kan bli inaktuella. Ett uppströmsregister som dras tillbaka slutar erbjudas för nya cacher — en cache du redan har fortsätter fungera och går fortfarande att ta bort.

Docker Hub kräver dina egna Docker Hub-uppgifter

En Docker Hub-cache avvisas om du inte anger ett användarnamn och ett lösenord för Docker Hub (en personlig åtkomsttoken fungerar och är det bättre valet).

Det är ingen godtycklig regel. En cache som hämtar anonymt från Docker Hub förbrukar en anonym kvot som delas med andra Frostmoln-kunder på samma utgående adress. En enda flitig anonym spegling gör slut på den, och alla andra kunder bakom den adressen börjar bli hastighetsbegränsade — för hämtningar som inte har något med din cache att göra. Att ange egna uppgifter lägger hämtningarna på ditt Docker Hub-konto och din egen kvot, vilket också är det enda sättet att få de gränser du betalar Docker för.

Övriga uppströmsregister kräver inga uppgifter i dag, men du kan ändå ange dem — till exempel för att nå ett privat repository du har tillgång till.

Vilka uppströmsregister som kräver uppgifter visas där du skapar cachen

Portalen märker ut dem, och CLI:et säger till om du utelämnar dem. Regeln upprätthålls av API:et, så CLI:et och Terraform möts av samma avslag som portalen.

Skapa en cache

I portalen: öppna Containerregister och leta upp avsnittet Pull-through-cacher där, och välj sedan Lägg till cache. Välj uppströmsregister, ange uppgifter om det efterfrågas, och skapa den. Ett uppströmsregister du redan har en cache för visas nedtonat i stället för dolt — en cache per uppströmsregister. Den nya cachens pull-sökväg visas på dess rad; välj den, eller kopieringsikonen bredvid den, för att kopiera den.

Från CLI:et:

fm registry cache list          # vad du har, och vad som erbjuds
fm registry cache create ghcr
fm registry cache delete ghcr   # --force hoppar över bekräftelsen

Ett uppströmsregister som kräver uppgifter tar emot dem på ett av två säkra sätt. Vid en terminal: ange användarnamnet och låt kommandot fråga efter lösenordet — det ekas inte, och det når aldrig din skalhistorik:

fm registry cache create dockerhub --username acme

I CI, där det inte finns någon fråga, matar du lösenordet via stdin:

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

Använd printf '%s' och inte echo, av skälet som beskrivs under Logga in — echo förvanskar vissa värden tyst, och en förvanskad uppströmstoken misslyckas som en trasig hämtning snarare än som ett felaktigt lösenord.

Det finns också en flagga --password. Betrakta den som en sista utväg: värdet syns i ps på en delad maskin och sparas i din skalhistorik, så föredra något av de två sätten ovan. Att köra icke-interaktivt helt utan lösenord är ingen fälla — kommandot misslyckas och nämner --password-stdin i stället för att hänga sig.

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 # känsligt — se varningen nedan

  depends_on = [frostmoln_container_registry.this]
}

Uppströmslösenordet skrivs till Terraforms state

Terraform sparar varje värde du skickar in, så din Docker Hub-token hamnar i state — som JSON i klartext i din arbetskatalog om du inte har konfigurerat en fjärrbackend. Varningen på registersidan gäller här fullt ut: använd en krypterad fjärrbackend, håll terraform.tfstate* utanför git, och ta värdet från en variabel i stället för att skriva in det i .tf-filen.

Oavsett vilket gränssnitt du använder får du tillbaka cachens pull-sökväg. Det är det enda du behöver därefter.

Uppgifterna kontrolleras inte när du skapar cachen

Frostmoln testar dem inte mot uppströmsregistret, så ett skrivfel misslyckas inte här — det misslyckas senare, som en hämtning som inte kan få tag i avbilden. Serverar en cache aldrig något, misstänk uppgifterna först.

Hämta via cachen

Sätt cachens pull-sökväg i stället för uppströmsvärden framför avbilden, och behåll resten av referensen precis som den var.

En avbild du normalt skulle hämta 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-sökväg visas i portalen och av fm registry cache list; delen t-...-cache-ghcr ovan är ett exempel.

Använd samma behörighet som du redan använder för dina egna avbilder.docker login gäller per värd, och en cache ligger på samma värd som din namnrymd, så en inloggning täcker båda. Du skapar inget nytt för en cache — de behörigheter du redan har utökas automatiskt till den när den skapas.

# Logga in en gång (enkelcitera användarnamnet — det innehåller ett $)
docker login registry.sweden.frostmoln.cloud -u 'robot$t-...-a1b2c3d4'

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

En pull-behörighet räcker. podman tar samma kommandon.

Officiella Docker Hub-avbilder behåller sitt library/-prefix

docker pull nginx fungerar för att Docker-klienten expanderar det till docker.io/library/nginx. Ingenting expanderar det åt dig här, så via en Docker Hub-cache är referensen registry.sweden.frostmoln.cloud/<din-cache-namnrymd>/library/nginx:1.27. Utelämnar du library/ får du ett "not found" som ser ut som en trasig cache.

Från ett hanterat Kubernetes-kluster

Inget nytt behövs. Cachen ligger på samma värd som ditt register, så den image pull secret du redan har täcker den — du ändrar bara avbildsreferensen:

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 inte den hemligheten ännu, bygg den precis som för dina egna avbilder — se Hämta avbilder från ett hanterat Kubernetes-kluster, inklusive noteringen om att klustrets VPC behöver en gateway för utgående trafik.

Taggar, :latest och hur aktuell en cache är

En hämtning med tagg frågar uppströmsregistret varje gång cachen kan nå det. När du hämtar acme/widget:1.2.3 eller acme/widget:latest via en cache frågar cachen först uppströmsregistret vilken avbild taggen pekar på just nu, och ger dig den — kopian den redan har om inget har ändrats, annars den nya avbilden, som den sedan behåller. Det finns ingen cachetid att vänta ut: :latest via en cache följer uppströmsregistret i det ögonblick du hämtar.

När uppströmsregistret säger att en tagg inte längre finns misslyckas en hämtning med den taggen, även om cachen fortfarande har en kopia. Tas en tagg bort uppströms försvinner den även för hämtningar via cachen.

När cachen inte kan få något svar från uppströmsregistret — det är onåbart, eller vägrar kontrollen med ett svar om hastighetsbegränsning — beror det på avbilden vad du får:

• En avbild för en plattform som hämtas med tagg serveras från cachen — även om taggen har flyttats uppströms sedan dess. Hämtningen lyckas och ingenting talar om för dig att avbilden kan vara inaktuell.
• En hämtning med tagg av en flerplattformsavbild med Docker misslyckas. De flesta publika avbilder är flerplattformsavbilder (en tagg som täcker linux/amd64, linux/arm64 och så vidare), och cachen sparar dem inte under taggen — se Flerplattformsavbilder nedan — så det finns inget under taggen att falla tillbaka på.
• En hämtning med digesten för en avbild som cachen har — en avbild för en plattform, eller en plattform av en flerplattformsavbild — serveras från cachen, med eller utan uppströmsregistret.

Fäst en plattformsdigest för att hämtningar ska fungera under ett avbrott uppströms

Digesten som docker pull skriver ut för en flerplattformsavbild, och den i RepoDigests från docker inspect, är digesten för indexet — listan över plattformar. Cachen sparar inte indexet som det är, så en hämtning med den digesten kräver att uppströmsregistret svarar. Fäst i stället digesten för den plattformsavbild du kör:

image: <pull-sökväg>/acme/widget@sha256:<digest för linux/amd64>

Du hittar den genom att lista plattformarna för avbilden uppströms — plattformsdigesterna är desamma uppströms och i cachen:

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

Hoppa över poster vars plattform är unknown/unknown — det är byggattesteringar, inte avbilder. Hämta den fästa referensen via cachen en gång så att cachen har den, och fortsätt att hämta den: precis som alla andra avbilder tas en avbild som ingen hämtar på 7 dagar bort.

Avbilder som ingen hämtar tas bort. En avbild som inte har hämtats via cachen på 7 dagar tas bort ur den vid nästa dagliga kontroll. Nästa hämtning hämtar den från uppströmsregistret igen, så länge uppströmsregistret svarar — och det hindrar en cache från att hålla fast vid lagringsutrymme för avbilder du slutat använda.

Flerplattformsavbilder

När du hämtar en flerplattformsavbild via en cache med Docker hämtar Docker först indexet med dess tagg och sedan den enda plattformsavbild den behöver med den avbildens digest. Cachen sparar det den ombads om:

• Plattformsavbilden du hämtade — till exempel linux/amd64 — under sin egen digest, utan tagg, eftersom den hämtades med digest.
• Strax därefter cachens eget index, som listar de plattformar som hittills har hämtats via cachen. Det har inte heller någon tagg, och dess digest är aldrig uppströmsregistrets: cachen bygger det här indexet själv, så dess digest skiljer sig även när alla plattformar har hämtats.

När du bläddrar i cachen är det här du ser: först plattformsavbilden, och när cachens eget index finns, det indexet i dess ställe — utan tagg, med en digest som varken stämmer med uppströmsregistrets eller med RepoDigests. Det är inget fel på avbilden, och hämtningar med tagg fortsätter att fungera medan uppströmsregistret svarar: cachen frågar uppströmsregistret om det aktuella indexet varje gång, som beskrivs ovan.

Digesten som visas när du bläddrar är cachens, inte en att fästa. För att fästa en plattformsavbild tar du dess digest från uppströmsregistret, som visas i tipset ovan.

Se vad en cache innehåller

I portalen: välj Bläddra på en caches rad i avsnittet Pull-through-cacher. Du får de repositorier cachen innehåller och, för vart och ett, dess avbilder: taggar, digest, storlek, när cachen hämtade avbilden och när den senast hämtades. Välj en tagg, eller kopieringsikonen bredvid den, för att kopiera hela referensen som hämtar avbilden via cachen. En flerplattformsavbild som hämtats med Docker visas utan tagg och under en egen digest — se Flerplattformsavbilder.

Från CLI:et anger du cachen med uppströmsregistrets nyckel, precis som överallt annars:

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-namnen är uppströmsregistrets egna — acme/widget, eller library/nginx via en Docker Hub-cache — utan cachens namnrymd framför.

Ta bort avbilder från en cache

Du kan ta bort en enskild avbild ur en cache utan att ta bort cachen. I portalen: tryck Ta bort på avbildens rad. Från 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, aldrig en tagg, av samma skäl som när du tar bort dina egna avbilder: en tagg kan flytta sig mellan listningen och borttagningen. Alla taggar på avbilden följer med, och en avbild för flera arkitekturer tas bort via sitt index, inte via sina delar per plattform.

Det är inte bestående. Allt i en cache är en kopia av något som fortfarande finns uppströms, så nästa hämtning av avbilden hämtar den helt enkelt igen. Ta bort en avbild för att frigöra utrymme nu i stället för att vänta på att den åldras ut. Det hindrar ingen från att hämta avbilden — för att stoppa hämtningar via en cache, ta bort cachen.

Att ta bort ger dig inte en färskare avbild

En hämtning med tagg frågar redan uppströmsregistret varje gång, så det finns ingen inaktuell kopia att rensa bort medan uppströmsregistret svarar. Och medan uppströmsregistret är onåbart eller hastighetsbegränsar dig är den cachade kopian av en avbild för en plattform eller av en fäst plattformsdigest det enda en hämtning kan få — tar du bort den då misslyckas hämtningar av avbilden tills uppströmsregistret svarar igen.

Cachade avbilder räknas mot din lagringsgräns

En gräns, delad med dina egna avbilder — och en cache fyller sig själv

Allt en cache lagrar räknas mot samma lagringsgräns som din egen namnrymd. Det finns en siffra och en gräns för hela ditt register: dina avbilder plus varje cache du äger.

En cache fylls vid hämtning, inte vid push. Den kan alltså förbruka din gräns utan att du någonsin pushar något — och den gör det som en bieffekt av en vanlig docker pull från en pipeline, ett kluster eller en kollega. Även en förfrågan som bara efterfrågar ett manifest utlöser en fullständig hämtning av avbilden.

Den praktiska följden: en cache framför ett hårt belastat publikt register kan fylla din gräns på egen hand, och första tecknet är att en push av dina egna avbilder avvisas för att utrymmet är slut.

Håll ögonen på lagringssiffran i portalen under Använt lagringsutrymme, eller med fm registry status, efter att du lagt till en cache — den är sammanlagd, så den rör sig när en cache fylls. Varje caches egen siffra finns i kolumnen Lagring i avsnittet Pull-through-cacher. Den räknar varje lagrat lager en gång inom den cachen, så den visar vilken cache som håller på att fyllas, inte summan av storlekarna på de avbilder du hämtat.

Om utrymmet håller på att ta slut är det oftast snabbast att ta bort en cache du inte längre hämtar via — se Ta bort en cache — eller att ta bort de avbilder du inte längre behöver ur en cache du behåller. Inget av det kostar dig något bestående. Att ta bort dina egna avbilder beskrivs under Frigöra utrymme.

Byta uppströmsuppgifter

Det går inte att uppdatera dem. Uppgifterna är skrivskyddade i den meningen att ingenting läser tillbaka dem, och det finns inget fält att ändra. För att rotera en Docker Hub-token, eller rätta en du skrev fel, tar du bort cachen och skapar den på nytt med de nya värdena.

Det är inte så tungt som det låter — du förlorar de cachade kopiorna, och nästa hämtning hämtar dem igen. Pull-sökvägen härleds ur din tenant och uppströmsregistret, så den blir identisk och ingenting som refererar till den behöver ändras.

Ta bort en cache

I portalen: ta bort raden i avsnittet Pull-through-cacher på sidan Containerregister. Från CLI:et:

fm registry cache delete ghcr
fm registry cache delete ghcr --force   # samma, utan bekräftelse

Borttagningen tar uppströmsregistrets nyckel — samma korta namn som du skapade den med — och det är den som visas på portalraden och av fm registry cache list.

Att ta bort en cache tar bort de avbilder den cachat, och frågar inte två gånger. Det är ofarligt på ett sätt som borttagning av dina egna avbilder inte är: allt i en cache är en kopia av något som fortfarande finns uppströms, så ingenting du själv skapat går förlorat. Skapa cachen igen, hämta igen, och innehållet kommer tillbaka.

Två saker ändras omedelbart:

• Din siffra för lagrade byte sjunker när det cachade innehållet försvinner. Det är hela poängen om du tog bort cachen för att frigöra utrymme.
• Allt som fortfarande hämtar via den sökvägen börjar misslyckas. Sök igenom dina manifest, Helm-värden och pipelinefiler efter pull-sökvägen innan du tar bort en cache som är i bruk.

De sparade uppströmsuppgifterna följer med. Tar du bort cachen för att byta dem, ha det nya användarnamnet och den nya token till hands innan du börjar.

Hur många cacher du kan ha

Din tenant får ha ett begränsat antal cacher samtidigt. Att skapa en till utöver gränsen avvisas, och lösningen är att ta bort en cache du inte längre hämtar via.

Läs antalet där du skapar cachen

Portalen visar gränsen och slutar erbjuda Lägg till cache när du nått den, och fm registry cache list rapporterar den tillsammans med det du har. Den siffran kommer från API:et och är den som gäller — den här sidan skriver medvetet inte ut något tal, så att det inte tyst kan bli inaktuellt.

När en cache inte kan skapas

Vad du ser	Vad det betyder
Uppströmsregistret kan inte speglas	Det finns inte på den erbjudna listan, eller har dragits tillbaka sedan du skrev ditt skript. Läs den aktuella listan och välj därifrån.
Uppgifter krävs för det här uppströmsregistret	Docker Hub, i dag. Ange eget användarnamn och token — se ovan.
Du har redan en cache för det uppströmsregistret	En cache per uppströmsregister, och det finns inget att uppdatera. Ta bort den och skapa den på nytt om du ska byta uppgifter.
Du har nått gränsen	Ta bort en cache du inte längre hämtar via.
Ditt register är inte aktiverat	Aktivera det först.

Ett pausat register vägrar också skapa en cache, precis som det vägrar varje annan skrivning. Hämtningar via cacher du redan har fortsätter fungera, med de pull-behörigheter du redan innehar — precis som för dina egna avbilder. Se Om ditt register är pausat.