Obnova certifikátov

Certifikát sa považuje za expirujúci, keď je vystavený, obnovený alebo zlyhaný a jeho platný certifikát vyprší do renewal.threshold_days dní (predvolene 21) — alebo už vypršal. Certificates::renewDue() obnoví všetky takéto certifikáty — alebo každý zaradí do fronty — a vráti RenewalReport:

use RoundlyConsulting\Certificates\Facades\Certificates;

$report = Certificates::renewDue();          // everything inside renewal.threshold_days → RenewalReport
Certificates::renewDue(7, queue: true);      // a 7-day window, one queued job per certificate

if ($report->hasFailures()) {
    foreach ($report->failed as $failure) {
        logger()->warning("Renewal failed for {$failure->certificate->domain}: {$failure->reason()}");
    }
}

$report->renewedDomains();   // ['a.example.com', …]; also queuedDomains(), failedDomains(), count(), isEmpty()

Každý certifikát na rade sa spracuje samostatne: jedno zlyhanie nezastaví ostatné. Report uvádza renewed, queued (pri queue: true) a failed — každé zlyhanie je RenewalFailure s certifikátom a výnimkou a metódou reason() pre jej správu. Každé zlyhanie dostane aj váš exception handler. Neúspešná priama obnova nechá záznam v stave failed so spustenou udalosťou CertificateFailed; neúspešné odoslanie do fronty záznam nezmení, takže ho ďalší beh skúsi znova.

Jeden certifikát

renew() a renewLater() prijímajú Certificate z registra alebo doménu (jej najnovší záznam), priamo aj cez rukoväť for(). Neznáma doména alebo stav, z ktorého obnova nie je možná (napríklad odvolaný certifikát), vyhodí CertificateException — renewLater() stav overí skôr, než čokoľvek zaradí do fronty:

use RoundlyConsulting\Certificates\Facades\Certificates;

Certificates::renew('app.example.com');        // now, through the certificate's own driver
Certificates::renewLater('app.example.com');   // queue RenewCertificateJob (renewal.queue)
Certificates::renew($certificate);             // a registry row works as well as a domain

Certificates::for('app.example.com')->renew();                // same verbs on the domain handle
Certificates::for('app.example.com')->using('acme')->renewLater(); // only the acme row is touched

Certificates::expiring(14);   // Collection<int, Certificate> expiring within 14 days, soonest first

Z konzoly

certificates:renew spustí Certificates::renewDue() — alebo pri zadanej doméne Certificates::renew() pre jej najnovší záznam (s --queue renewLater()). Vypíše výsledok každého certifikátu a skončí nenulovým kódom, ak zlyhala ktorákoľvek obnova alebo odoslanie do fronty, takže sa spustia chybové hooky plánovača:

# everything expiring within renewal.threshold_days
php artisan certificates:renew

# one domain, whatever its expiry
php artisan certificates:renew shop.example.com

# a wider window, renewed through the queue
php artisan certificates:renew --threshold=30 --queue

Plánovanie

Balík neregistruje žiadny plán — ten patrí do vašej aplikácie, napríklad do routes/console.php:

use Illuminate\Support\Facades\Schedule;
use RoundlyConsulting\Certificates\Facades\Certificates;

Schedule::command('certificates:renew')->daily()->emailOutputOnFailure('[email protected]');

// or, without the command:
Schedule::call(fn () => Certificates::renewDue(queue: true))->daily();

emailOutputOnFailure() pošle výstup príkazu e-mailom vždy, keď certificates:renew skončí nenulovým kódom — keď zlyhala niektorá priama obnova alebo odoslanie do fronty — preto potrebuje funkčný mailer. S --queue obnova, ktorá zlyhá až v RenewCertificateJob, výstupný kód nezmení: záznam prejde do stavu failed a spustí sa CertificateFailed, ktorá pri zapnutom alerts.enabled vytvorí upozornenie.

Životný cyklus obnovy

• renewDue() spustí CertificateExpiring pre každý certifikát, ktorý spracúva — po expirácii je daysUntilExpiry záporné.
• Obnoviť sa dajú certifikáty v stave issued, renewed a failed, ako aj uviaznutý záznam v stave renewing (nižšie) — pri ostatných vznikne CertificateException pre nepovolený prechod stavu.
• Obnova drží zámok vystavenia certifikátu — ten istý, ktorý berie issue() — a záznam presunie do stavu renewing, len ak má stále stav, ktorý tento proces načítal. Súbežná obnova, obnova súperiaca s issue() alebo zastaraný model vyhodia ProvisioningInProgressException namiesto dvojitej obnovy.
• Vlastný driver certifikátu znovu vystaví všetky domény, ktoré pokrýva — SAN certifikát si ponechá všetkých hostiteľov.
• Obnovu dokazuje report samotného poskytovateľa: stav, ktorý nie je platný, úplne ten istý certifikát (rovnaký odtlačok, napríklad importovaný materiál, ktorý nikto nevymenil) alebo — pri driveri, ktorý odtlačok nehlási, ako kubernetes — expirácia, ktorá sa neposunula neskôr, znamená neúspešnú obnovu.
• Inak záznam prejde do stavu renewed s nahlásenou expiráciou (o 90 dní, ak ju driver neuvádza), vydavateľom, sériovým číslom a odtlačkom, vyplní sa last_renewed_at a spustí sa CertificateRenewed. Cachovaný report stavu certifikátu sa zahodí.
• Neúspešná obnova presunie záznam do stavu failed, spustí CertificateFailed a výnimku pošle ďalej — záznam nikdy neuviazne v stave renewing, takže namiesto toho vyvolá upozornenie. Failed nie je slepá ulička: expiring(), renewDue() aj certificates:renew ho skúšajú znova pred uplynutím platnosti pôvodného certifikátu aj po ňom.
• Prerušená obnova — timeout fronty počas kontrol ACME, nasadenie — nechá záznam v stave renewing. Keď ho nikto nezmenil dlhšie ako lock.locked_for_seconds, považuje sa znova za obnoviteľný: expiring() a renewDue() ho zahrnú, renew() a renewLater() ho prijmú a prevezme ho len jeden proces.

Podľa drivera

acme vytvorí novú objednávku s novým kľúčom certifikátu a prepíše uložený materiál. kubernetes nájde TLS záznam v Ingresse už na mieste a nechá ho tak — secret obnovuje sám cert-manager — a zaznamená notAfter, ktoré hlási; ak sa notAfter neposunulo neskôr, obnova zlyhá ako neobnovená, pretože cert-manager hlási Ready, aj keď jeho vlastná obnova zlyháva. filesystem so self_signed vytvorí nový materiál; bez neho PEM súbory pred obnovou nahraďte, inak obnova zlyhá ako neobnovená.

Obnova cez frontu

renewLater(), renewDue(queue: true) aj certificates:renew --queue namiesto priamej obnovy odošlú pre každý certifikát RenewCertificateJob. Job ide do fronty z renewal.queue (CERTIFICATES_RENEW_QUEUE), záznam znovu načíta na databázovom pripojení, z ktorého bol odoslaný, a preskočí certifikáty, ktoré boli medzitým zmazané. Job zaradený cez renewDue(queue: true) navyše nič neurobí, ak certifikát už nie je na rade, takže prekrývajúce sa behy nikdy znova neobnovia práve obnovený certifikát; job z renewLater() obnoví vždy.

Timeout jobu je lock.locked_for_seconds (predvolene 600 sekúnd), takže worker ACME obnovu počas kontrol nepreruší. retry_after pripojenia fronty nastavte nad túto hodnotu.