Kubernetes-clusters kunnen verschillende problemen ondervinden bij het ophalen van uw container-images. Als er een fout optreedt, gaan uw pods naar een ImagePullBackOff-status. Hier leest u hoe u dit veelvoorkomende maar cryptische bericht kunt debuggen, zodat u uw services online kunt krijgen.
Hoe Image Pulls werkt
Kubernetes moet een afbeelding ophalen wanneer u een nieuwe implementatie maakt of een bestaande bijwerkt met een andere tagverwijzing. De verantwoordelijkheid voor het ophalen van afbeeldingen ligt bij het Kubelet-proces op elk werkknooppunt. Elke afbeelding waarnaar wordt verwezen door het manifest van een Pod moet toegankelijk zijn voor alle knooppunten in het cluster, zodat elk van hen kan voldoen aan een containerplanningsverzoek.
De download kan mislukken als het afbeeldingspad onjuist is, u niet correct bent geverifieerd of het netwerk uitvalt. Wanneer dit gebeurt, trekt Kubernetes “terug” en plant een nieuwe downloadpoging. De vertraging voor de volgende pull neemt exponentieel toe elke keer dat een poging mislukt, tot een limiet van vijf minuten.
Als uw Pod de ImagePullBackOff-status vertoont, heeft Kubernetes meerdere opeenvolgende mislukte image pull-fouten gehad en wacht nu voordat het probeert het opnieuw. De container kan pas starten als de afbeelding beschikbaar is.
U kunt de Pod in deze staat laten als u weet dat het probleem te wijten is aan netwerkomstandigheden of een andere tijdelijke fout. Kubernetes zal uiteindelijk nog een nieuwe poging voltooien en de afbeelding met succes verkrijgen. Als dat niet het geval is, kunt u als volgt beginnen met debuggen zodat u uw Pod kunt openen.
Controleer de basis
Eerst en vooral is het de moeite waard om de basisprincipes te controleren. Verwijst uw resourcemanifest naar een geldige afbeelding die daadwerkelijk bestaat? Controleer het registerpad en de afbeeldingstag op eenvoudige typefouten.
Advertentie
U kunt de interne Kubernetes-status inspecteren met de opdracht description pod in Kubectl. Dit geeft u meer informatie dan de pod en het Kubernetes-dashboard bieden.
kubectl description pod my-pod –namespace my-namespace
Wijzigingen in de levenscyclus van de Pod worden weergegeven onder de “Evenementen” rubriek. Het eerste evenement wordt gepland; het moet worden gevolgd door een Pulling-evenement voor de eerste pull-poging. Hierna ziet u een Failed of BackOff-gebeurtenis als de pull niet kon slagen. Deze worden later in de lijst herhaald als Kubernetes zich nog steeds in een cyclus van terugtrekken en opnieuw proberen bevindt.
Het lezen van het bericht dat bij deze gebeurtenissen hoort, levert vaak de hoofdoorzaak van het probleem op. Een manifest voor image:tag not found-bericht betekent dat de afbeelding geldig is, maar dat u een ongeldige tag hebt opgegeven. Als u ziet dat het niet bestaat of geen pull-toegang heeft, controleert u of de register- en afbeeldingspaden correct zijn. Als u zeker weet dat ze gelijk hebben, heeft het probleem te maken met onjuiste authenticatie.
Registeraanmeldingen beheren
U moet ingelogd zijn voordat u privé-afbeeldingen kunt ophalen. In Kubernetes is het een mechanisme in twee stappen: maak een geheim met inloggegevens en verwijs vervolgens naar dat geheim in uw Pod-definities.
Het veld Pod heet imagePullSecrets. Het moet een Kubernetes-geheim aangeven dat een aanmeldingstoken voor het register biedt. Dit geheim zou een Docker-compatibele JSON-waarde moeten opslaan.
apiVersion: v1 soort: Geheim type: kubernetes.io/dockerconfigjson metadata: naam: image-pull-secret data: .dockerconfigjson: {{ "{"auths": {"registry.example.com": {"gebruikersnaam": "demo-gebruiker", "wachtwoord" : "mijn-wachtwoord"}}}" | b64enc }} apiVersion: v1 soort: Pod-metadata: naam: my-pod spec: containers: – naam: mijn-container image: registry.example.com/my-image:latest imagePullSecrets: – name: image-pull-secret
Dit manifest laat zien hoe u een geheim maakt waarmee u zich als demogebruiker bij registry.example.com aanmeldt met het wachtwoord mijn-wachtwoord. De Pod verwijst naar het geheim bij zijn naam. Kubelet-processen op de knooppunten van uw cluster bevatten het Docker config.json-fragment wanneer ze afbeeldingen uit het register halen.
Advertentie
Het fragment moet Base64-gecodeerd zijn om een geldige geheime waarde van Kubernetes zijn. U kunt een vooraf gecodeerde waarde gebruiken of platte tekst doorsluizen via YAML’s b64enc, zoals weergegeven in het bovenstaande manifest.
Het type referenties dat u gebruikt, is afhankelijk van uw register. In veel gevallen is het wachtwoord eigenlijk een persoonlijke toegangstoken of API-sleutel. Docker Hub vereist een toegangstoken die is gegenereerd in uw accountinstellingen als u tweefactorauthenticatie hebt ingeschakeld voor uw account.
Registry Rate Limits
Als u uw register-URL, de naam van de afbeeldingstag en inloggegevens hebt gecontroleerd, ziet u mogelijk ImagePullBackOff vanwege de limieten voor de registersnelheid. Docker Hub beperkt u nu tot 100 containertrekkingen om de zes uur. Dit loopt op tot 200 pulls per zes uur als u uw inloggegevens opgeeft. Die limiet kan snel worden bereikt in een actief cluster met veel veelgebruikte Pods.
Een pull-fout vanwege een snelheidslimiet zal zich op dezelfde manier manifesteren als een authenticatieprobleem. U moet wachten tot er voldoende tijd is verstreken om de limiet te laten verlopen. Kubernetes zou dan met succes de afbeelding moeten trekken en uw pods omhoog moeten brengen.
Voor beperking op langere termijn kunt u overwegen uw eigen in-cluster register of proxy te gebruiken om uw afbeeldingen in de cache op te slaan. Dit kan de frequentie waarmee u de servers van Docker bereikt aanzienlijk verminderen, waardoor u binnen de snelheidslimieten blijft.
Samenvatting
Kubernetes-pods gaan een ImagePullBackOff-status in wanneer een knooppunt slaagt er niet in om een afbeelding te trekken. Kubelet zal de pull periodiek opnieuw proberen, zodat tijdelijke fouten geen handmatige tussenkomst vereisen om aan te pakken.
Advertentie
Als u zeker weet dat een ImagePullBackOff niet slechts een tijdelijke blip is , begin met ervoor te zorgen dat het afbeeldingspad van de Pod geldig is. Als dat klopt, vermoed dan onjuiste inloggegevens of een uitgeputte snelheidsbeperkende vergoeding. Het gebruik van kubectl description zal de reeks gebeurtenissen blootleggen die tot de storing hebben geleid.
Als laatste optie kunt u proberen de afbeelding zelf van een andere machine te halen om er zeker van te zijn dat de externe registerserver daadwerkelijk actief is. Als u de afbeelding kunt ophalen, maar uw cluster niet, heeft u mogelijk meer algemene netwerkproblemen waardoor uw knooppunten het register niet kunnen bereiken.