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). 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.
• Obnoviť sa dajú certifikáty v stave issued, renewed a failed — pri ostatných vznikne CertificateException pre nepovolený prechod stavu.
• Záznam prejde do stavu renewing a 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ý, alebo úplne ten istý certifikát (rovnaký odtlačok, napríklad importovaný materiál, ktorý nikto nevymenil), 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, kým platnosť pôvodného certifikátu neuplynie.

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. 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é.