Jak opravit Kubernetes CrashLoopBackOff v lokálním Minikube

Cílem není pouze nechat CrashLoopBackOff na několik sekund zmizet. Dobrá oprava nechá kontejner běžet, udrží Pod v stavu Ready, pokud má přijímat provoz, zastaví nárůst počtu restartů a vytvoří logy, které ukazují na normální spuštění aplikace. V lokálním Minikube byste také měli před přestavbou ověřit, že je samotný Minikube klastr zdravý.

Aktuální dokumentace Kubernetes popisuje CrashLoopBackOff jako podmínku zpětného odpočtu, která se objeví, když kontejner opakovaně startuje, selhává a je restartován. Kubernetes postupně oddaluje další restarty, aby se vyhnul těsné smyčce selhání. Štítek je tedy příznakem opakovaného selhání kontejneru, nikoli samotnou příčinou. Viz dokumentace životního cyklu Podu v Kubernetes.

Tato příručka používá čtyři diagnostické fáze. Postupujte v pořadí a zastavte, jakmile identifikujete a opravíte skutečnou příčinu. Minikube je určen pro lokální učení a vývoj, takže stejná diagnostika na úrovni aplikace se přenáší na jiné klastry Kubernetes, zatímco kroky obnovy specifické pro Minikube se nutně nevztahují na produkční prostředí. Viz aktuální dokumentace ke spuštění Minikube.

Jak vypadá úspěšná oprava?

Používejte pozorovatelné znaky spíše než jeden zelený stavový řádek:

• Dotčený kontejner zůstává ve stavu running dostatečně dlouho na dokončení normálního spuštění.
• Pod se stane Ready, pokud má obsluhovat provoz.
• Počet restartů přestane během vašeho pozorovacího období růst.
• kubectl logs ukazuje normální cestu spuštění, nikoli opakující se stejnou fatální chybu.
• Sondy pro liveness a startup, pokud jsou nakonfigurovány, přestanou selhávat.
• Aplikace může dosáhnout služeb nebo závislostí, které skutečně potřebuje.
• minikube status ukazuje zdravý lokální klastr, pokud byla zpochybněna zdraví klastru.

Nepožadujte, aby se počítadlo restartů existujícího Podu vrátilo na nulu. Kubernetes zaznamenává, kolikrát byl kontejner v tomto Podu restartován; úspěšná oprava může zanechat nenulovou historickou hodnotu. Důležité je, že počet přestane růst. Pokud rollout Deploymentu vytvoří nový Pod, tento nový Pod obvykle začíná s vlastním novým počtem restartů.

Fáze 1: Dokažte, který kontejner padá

Začněte seznamem Podů:

kubectl get pods -A

Pokud již znáte namespace, zúžte příkaz:

kubectl get pods -n my-namespace

Poté popište dotčený Pod:

kubectl describe pod <pod-name> -n <namespace>

V sekci kontejneru se podívejte na čtyři pole:

• State — kontejner může být aktuálně ve stavu Waiting s důvodem CrashLoopBackOff.
• Last State — často Terminated, což vám řekne, co se stalo při předchozím běhu.
• Reason and Exit Code — užitečné stopy jako Error nebo OOMKilled.
• Restart Count a Events — důkazy, že se selhání opakuje, a zda jsou zapojeny sondy nebo akce kubeletu.

Jemný, ale užitečný rozdíl: celková fáze Podu může být stále Running, zatímco jeden z jeho kontejnerů čeká ve stavu CrashLoopBackOff. Sloupec STATUS vypsáný příkazem kubectl get pods je pohodlné lidsky čitelné shrnutí, nikoli kompletní diagnostika stavu životního cyklu Podu.

Kontrola kvality: na konci této fáze byste měli znát přesný Pod, namespace a kontejner, který se restartuje. Pokud má Pod více kontejnerů, identifikujte, který selhává, než začnete číst logy.

Pokud selhání ve skutečnosti není CrashLoopBackOff

Nenutěte každý problém se spuštěním do této příručky. ImagePullBackOff, ErrImagePull, Pending a ContainerCreating ukazují na různé fáze selhání. Například problém s načtením obrazu nastane před spuštěním procesu vaší aplikace, takže logy aplikace ještě nemusí existovat.

Změňte přístup, když: sekce Events ukazuje na stahování obrazu, připojování svazků, plánování nebo chyby přijetí (admission), nikoli na kontejner, který se spustí a ukončí.

Fáze 2: Přečtěte si aktuální a předchozí logy padlého kontejneru

Pro Pod s jedním kontejnerem začněte s:

kubectl logs <pod-name> -n <namespace>

Když se kontejner restartuje rychle, nejužitečnějším příkazem je často:

kubectl logs <pod-name> -n <namespace> --previous

Kubernetes dokumentuje --previous jako možnost, která vypíše logy z předchozí instance kontejneru v Podu. Pokud Pod obsahuje více než jeden kontejner, zadejte ten selhávající:

kubectl logs <pod-name> -n <namespace> -c <container-name> --previous

Viz oficiální reference kubectl logs.

Klasifikujte první smysluplnou fatální chybu, místo abyste se soustředili na poslední řádek „process exited“. Typické vzory zahrnují:

Kontrola kvality: měli byste být schopni formulovat vyvratitelnou hypotézu, jako je „aplikace končí, protože DATABASE_HOST ukazuje na neexistující Service“, nikoli pouze „Kubernetes je rozbitý“.

Nepovažujte exit code 137 samotný za důkaz OOM

Exit code 137 se běžně objevuje, když proces obdrží SIGKILL, ale silnější signál specifický pro Kubernetes je Last State: Terminated s Reason: OOMKilled. Dokumentace správy zdrojů Kubernetes ukazuje tuto kombinaci, když kontejner překročí svůj limit paměti. Viz dokumentace správy zdrojů Kubernetes.

Užitečná akce: založte diagnostiku na důvodu ukončení a okolních Events, nikoli na čísle 137 samotném.

Fáze 3: Opravte příčinu, ne časovač zpětného odpočtu

Jakmile víte, proč kontejner končí, změňte nejmenší věc, která řeší tuto příčinu. Opakované restartování Podu neopraví špatný příkaz, chybějící konfiguraci, selhávající kontrolu zdraví nebo nedostatečnou paměť.

Případ A: Aplikace se snaží dosáhnout jiné služby na localhostu

Uvnitř normálního Podu Kubernetes sdílejí kontejnery ve stejném Podu síťový namespace a mohou spolu komunikovat přes localhost. Databáze běžící v jiném Podu není dosažitelná přes localhost vaší aplikace. Kubernetes vytváří DNS názvy pro Služby, aby workloads mohly být objevovány podle názvu služby. Viz koncepty sítě v Kubernetes a DNS pro Služby a Pody.

Pokud je vaše Service pojmenována postgres ve stejném namespace, vaše aplikace může být schopna použít:

DATABASE_HOST=postgres

Napříč namespacey použijte název kvalifikovaný namespace, jako je postgres.data, nebo plně kvalifikovaný název služby vhodný pro doménu vašeho klastru.

Ověřte Service před úpravou aplikace:

kubectl get svc -A
kubectl get endpointslices -n <namespace>

Změňte přístup, když: Service existuje, ale nemá žádné použitelné backendové endpointy. V takovém případě oprava hostnameu klienta nestačí; diagnostikujte serverový Deployment nebo selektor Service.

Případ B: Hodnoty ConfigMap nebo Secret jsou špatné

Zkontrolujte odkazy v manifestu workloadu:

kubectl get deployment <name> -n <namespace> -o yaml
kubectl get configmap -n <namespace>
kubectl get secret -n <namespace>

Kubernetes podporuje proměnné prostředí z env, ConfigMaps a Secrets. Užitečným detailem je, že hodnoty ConfigMap spotřebované jako proměnné prostředí se neaktualizují v již běžícím procesu, když se ConfigMap změní; Pod musí být nahrazen. To samé platí pro hodnoty Secret spotřebované jako proměnné prostředí. Viz dokumentace ConfigMap v Kubernetes a dokumentace vstřikování Secret v Kubernetes.

Pro Deployment je po opravě konfigurace rollout restart jedním ze způsobů, jak vytvořit nové Pody:

kubectl rollout restart deployment/<name> -n <namespace>
kubectl rollout status deployment/<name> -n <namespace>

Kontrola kvality: ověřte, že nový Pod skutečně používá zamýšlenou hodnotu. Nepředpokládejte, že úprava ConfigMap okamžitě změní proměnnou prostředí uvnitř existujícího kontejneru.

Případ C: Sonda liveness nebo startup zabíjí pomalou aplikaci

Kubernetes definuje tři typy sond s různými účely:

• Startup probe: určuje, zda bylo spuštění aplikace dokončeno. Zatímco je aktivní, sondy liveness a readiness čekají.
• Liveness probe: určuje, kdy by měl Kubernetes restartovat zaseknutý nebo nezdravý kontejner.
• Readiness probe: určuje, zda by měl Pod přijímat provoz prostřednictvím Služeb.

Běžným nedorozuměním je, že selhávající readiness probe způsobuje restart. Nezpůsobuje. Selhání readiness činí Pod nepřipraveným; opakovaná selhání sond liveness nebo startup mohou způsobit restarty kontejneru. Viz koncepty sond v Kubernetes a oficiální příručka konfigurace sond.

Pokud aplikace legitimně potřebuje dlouhé spuštění, zvažte startup probe s dostatečným časem failureThreshold × periodSeconds na pokrytí realistického spuštění. Jednoduše nevypínejte všechny sondy, aby stav vypadal zeleně; tím odstraníte užitečnou ochranu zdraví.

Kontrola kvality: sonda by měla testovat podmínku, která odráží její účel, a aplikace by měla přežít normální spuštění, aniž by byla předčasně zabita.

Případ D: Kontejner je OOMKilled

Nejprve porovnejte limit paměti kontejneru s jeho skutečnými potřebami při spuštění. Malý příklad:

resources:
  requests:
    memory: "256Mi"
  limits:
    memory: "512Mi"

Pokud se objeví Reason: OOMKilled a aplikace legitimně vyžaduje více než nakonfigurovaný limit, opatrně zvyšte limit nebo snižte využití paměti aplikací. Pokud Minikube sám trpí nedostatkem paměti, zvýšení pouze limitu kontejneru může jednoduše přesunout problém na uzel.

Aktuální dokumentace Minikube uvádí, že standardní lokální nastavení očekává alespoň 2 CPU, 2 GB volné paměti a 20 GB volného diskového prostoru. Minikube také podporuje změnu nakonfigurované paměti klastru, což vyžaduje restart. Viz aktuální požadavky na spuštění Minikube.

Změňte přístup, když: několik nesouvisejících Podů selhává nebo je evikováno, nebo je Minikube sám nezdravý. To ukazuje za limit paměti jednoho Deploymentu.

Fáze 4: Ověřte stabilitu a rozhodněte, zda je problém na úrovni klastru

Po aplikaci opravy sledujte workload, místo abyste ho kontrolovali jednou:

kubectl get pods -n <namespace> -w

Pro Deployment:

kubectl rollout status deployment/<name> -n <namespace>

Poté přečtěte nové logy:

kubectl logs <new-pod-name> -n <namespace>

Silným signálem úspěchu není jednoduše STATUS=Running. Potvrďte všechny následující body, pokud jsou aplikovatelné:

• READY dosáhne očekávané hodnoty, jako je 1/1.
• Počet restartů zůstává nezměněn, zatímco pozorujete normální spuštění a provoz.
• Neobjevují se žádné nové události BackOff, selhání sondy nebo OOM.
• Logy aplikace ukazují úspěšnou inicializaci.
• Service nebo lokální přístupová cesta skutečně dosáhne aplikace.

Pokud aplikace stále selhává, zkontrolujte, zda je Minikube sám zdravý

Spusťte:

minikube status
kubectl get pods -A

Příkaz status v Minikube hlásí stav lokálního klastru, včetně stavu hostitele, kubeletu, API serveru a kubeconfigu. Viz oficiální reference minikube status.

Pokud jsou kontrolní rovina nebo jádrové systémové Pody nezdravé, shromážděte diagnostiku klastru:

minikube logs --problems
minikube logs

Dokumentace Minikube je explicitní v tom, že minikube logs slouží k ladění lokálního klastru Kubernetes, nikoli k vašemu uživatelskému aplikačnímu kódu. Použijte kubectl logs pro aplikační kontejner a minikube logs, když je podezřelý samotný klastr nebo uzel. Viz aktuální reference minikube logs a pokyny k řešení problémů s Minikube.

Změňte přístup, když: jádrové komponenty Kubernetes selhávají, API server je nedostupný, stav Minikube je nezdravý nebo mnoho nesouvisejících workloadů selhává najednou. V takovém případě je nepravděpodobné, že by další úpravy jednoho Deploymentu vyřešily základní problém.

Měli byste smazat a znovu vytvořit klastr Minikube?

Pouze poté, co jste oddělili problém aplikace od problému klastru. Znovuvytvoření lokálního vývojového klastru může být rozumné, když je klastr jednorázový, vaše manifesty jsou reprodukovatelné a Minikube je sám poškozen nebo špatně nakonfigurován. Je to špatná první reakce na aplikaci, která končí s jasným stack trace.

Příkazy jako minikube delete odstraní lokální klastr. To může také odstranit lokální stav Kubernetes a data, o kterých jste očekávali, že zůstanou. Nepoužívejte mazání jako diagnostickou zkratku, když trvalý svazek, lokální databáze nebo ručně vytvořený zdroj obsahuje jedinou kopii něčeho důležitého.

Prahová hodnota kvality pro přechod na znovuvytvoření klastru: potvrdili jste, že selhání není vysvětleno příkazem workloadu, konfigurací, závislostí, sondami nebo limity zdrojů; zdraví Minikube je abnormální; a lokální stav je buď zálohován, nebo bezpečně reprodukovatelný.

Kompaktní rozhodovací strom

Co tento pracovní postup nemůže zaručit

Lokální CrashLoopBackOff může odhalit chybu aplikace, selhání závislosti, chybu sondy, limit zdrojů, neshodu architektury, chybějící soubor, problém s oprávněními nebo mnoho dalších selhání při spuštění. Žádná pevná sekvence příkazů nemůže identifikovat každou příčinu bez přečtení skutečného důvodu ukončení, Events a logů.

Dále oprava, která funguje v Minikube, automaticky nedokazuje připravenost na produkci. Produkční klastry mohou používat různé třídy úložiště, bezpečnostní politiky, ingress controllery, architektury uzlů, síťové politiky, kvóty zdrojů, systémy secretů nebo externí služby. Minikube je cenný pro reprodukci a pochopení selhání na úrovni kontejneru, ale chování specifické pro prostředí musí být stále testováno tam, kde bude aplikace skutečně běžet.

Závěrečný kontrolní seznam

• Identifikujte přesný selhávající kontejner a namespace.
• Přečtěte si Last State, důvod ukončení, exit code, počet restartů a Events.
• Použijte kubectl logs --previous pro rychle se restartující kontejnery.
• Přeměňte důkazy na jednu konkrétní hypotézu o příčině.
• Opravte konfiguraci, adresování závislostí, sondy nebo zdroje na základě těchto důkazů.
• Restartujte nebo nasadte nové Pody, když se změní hodnoty ConfigMap nebo Secret založené na prostředí.
• Ověřte stav Ready a potvrďte, že počet restartů přestává růst.
• Použijte minikube status a minikube logs pouze tehdy, když je podezřelé i zdraví klastru.
• Znovuvytvořte Minikube pouze tehdy, když je samotný klastr pravděpodobným problémem a jednorázový stav je chráněn.

Nejspolehlivějším způsobem, jak opravit CrashLoopBackOff, je brát ho jako signál k vyšetření, nikoli jako diagnózu. Ve zdravém procesu řešení problémů každý příkaz zúží příčinu: stav Podu vám řekne, co se restartuje, předchozí logy vám řeknou, proč poslední běh selhal, manifest a Events ukazují, co Kubernetes od kontejneru požadoval, a diagnostika Minikube vám řekne, zda je zapojen samotný lokální klastr. Jakmile se tyto vrstvy shodnou, oprava je obvykle mnohem menší – a mnohem snáze ověřitelná – než smazání a přestavění všeho.