Konfigurácia

Publikovaný config/certificates.php celý, bez komentárov:

return [
    'default' => env('CERTIFICATES_DRIVER', 'kubernetes'),
    'connection' => env('CERTIFICATES_DB_CONNECTION'),

    'model' => RoundlyConsulting\Certificates\Models\Certificate::class,
    'table' => 'certificates',
    'key_type' => env('CERTIFICATES_KEY_TYPE', 'bigint'),

    'renewal' => [
        'threshold_days' => env('CERTIFICATES_RENEW_THRESHOLD_DAYS', 21),
        'queue' => env('CERTIFICATES_RENEW_QUEUE'),
    ],

    'name_prefix' => env('CERTIFICATES_NAME_PREFIX', 'generated-tls-'),

    'lock' => [
        'name' => env('CERTIFICATES_LOCK_NAME', 'certificates:generate'),
        'locked_for_seconds' => env('CERTIFICATES_LOCK_SECONDS', 5),
    ],

    'status_cache' => [
        'enabled' => env('CERTIFICATES_STATUS_CACHE', true),
        'store' => env('CERTIFICATES_STATUS_CACHE_STORE'),
        'ttl' => env('CERTIFICATES_STATUS_CACHE_TTL', 300),
    ],

    'alerts' => [
        'enabled' => env('CERTIFICATES_ALERTS', false),
        'notifiable' => env('CERTIFICATES_ALERTS_NOTIFIABLE'),
        'thresholds' => [
            'warning_days' => env('CERTIFICATES_ALERTS_WARNING_DAYS', 30),
            'critical_days' => env('CERTIFICATES_ALERTS_CRITICAL_DAYS', 7),
        ],
        'channels' => ['mail'],
        'register_check' => env('CERTIFICATES_ALERTS_REGISTER_CHECK', false),
    ],

    'drivers' => [
        'kubernetes' => [
            'base_url' => env('CERTIFICATES_K8S_BASE_URL', 'https://kubernetes.default.svc'),
            'token' => env('CERTIFICATES_K8S_TOKEN'),
            'token_path' => env('CERTIFICATES_K8S_TOKEN_PATH', '/var/run/secrets/kubernetes.io/serviceaccount/token'),
            'ca_path' => env('CERTIFICATES_K8S_CA_PATH', '/var/run/secrets/kubernetes.io/serviceaccount/ca.crt'),
            'namespace' => env('CERTIFICATES_K8S_NAMESPACE', 'default'),
            'issuer' => env('CERTIFICATES_K8S_ISSUER', 'letsencrypt'),
            'issuer_kind' => env('CERTIFICATES_K8S_ISSUER_KIND', 'ClusterIssuer'),
            'ingress' => [
                'name' => env('CERTIFICATES_K8S_INGRESS_NAME'),
                'class' => env('CERTIFICATES_K8S_INGRESS_CLASS', 'nginx'),
            ],
            'service' => [
                'name' => env('CERTIFICATES_K8S_SERVICE_NAME'),
                'port' => env('CERTIFICATES_K8S_SERVICE_PORT', 80),
            ],
        ],

        'acme' => [
            'directory' => env('CERTIFICATES_ACME_DIRECTORY', 'https://acme-v02.api.letsencrypt.org/directory'),
            // Staging: https://acme-staging-v02.api.letsencrypt.org/directory
            'contact' => env('CERTIFICATES_ACME_CONTACT'),
            'account' => [
                'key_type' => env('CERTIFICATES_ACME_KEY_TYPE', 'EC'),
                'disk' => env('CERTIFICATES_ACME_ACCOUNT_DISK', 'local'),
                'key_path' => env('CERTIFICATES_ACME_ACCOUNT_KEY', 'acme/account.pem'),
                'auto_register' => env('CERTIFICATES_ACME_AUTO_REGISTER', true),
            ],
            'solver' => env('CERTIFICATES_ACME_SOLVER'),
            'http' => [
                'disk' => env('CERTIFICATES_ACME_HTTP_DISK', 'local'),
                'path' => env('CERTIFICATES_ACME_HTTP_PATH', 'acme-challenge'),
            ],
            'store' => [
                'disk' => env('CERTIFICATES_ACME_STORE_DISK', 'local'),
                'path' => env('CERTIFICATES_ACME_STORE_PATH', 'certificates'),
            ],
            'poll' => [
                'attempts' => env('CERTIFICATES_ACME_POLL_ATTEMPTS', 30),
                'seconds' => env('CERTIFICATES_ACME_POLL_SECONDS', 2),
            ],
            'verify' => env('CERTIFICATES_ACME_VERIFY', true),
        ],

        'filesystem' => [
            'disk' => env('CERTIFICATES_FS_DISK', 'local'),
            'path' => env('CERTIFICATES_FS_PATH', 'certificates'),
            'self_signed' => env('CERTIFICATES_FS_SELF_SIGNED', false),
            'self_signed_days' => env('CERTIFICATES_FS_SELF_SIGNED_DAYS', 90),
        ],

        'null' => [],
        'array' => [],
    ],
];

Všeobecné kľúče

Kľúč	Env	Predvolené	Účel
`default`	`CERTIFICATES_DRIVER`	kubernetes	Driver použitý, keď nijaký neuvediete — kľúč z drivers alebo driver registrovaný cez extend().
`connection`	`CERTIFICATES_DB_CONNECTION`	null	DB pripojenie registra; null použije predvolené pripojenie modelu. Pre jedno volanie ho prepíše on().
`model`	—	Models\Certificate::class	Model registra; podtrieda ho nahradí všade, iná trieda vyhodí výnimku.
`table`	—	certificates	Názov tabuľky registra.
`key_type`	`CERTIFICATES_KEY_TYPE`	bigint	Typ kľúča morphu vlastníka certifiable: bigint, uuid alebo ulid (bez ohľadu na veľkosť písmen; iná hodnota vyhodí výnimku).
`renewal.threshold_days`	`CERTIFICATES_RENEW_THRESHOLD_DAYS`	21	Počet dní pred expiráciou, od ktorého je certifikát expirujúci.
`renewal.queue`	`CERTIFICATES_RENEW_QUEUE`	null	Fronta, do ktorej ide RenewCertificateJob.
`name_prefix`	`CERTIFICATES_NAME_PREFIX`	generated-tls-	Prefix odvodeného názvu certifikátu — malé písmená, formát DNS-1123. '' je platný prefix — názvy sú potom samotný hostiteľ.
`lock.name`	`CERTIFICATES_LOCK_NAME`	certificates:generate	Prefix zámku vystavenia pre každý certifikát zvlášť ({lock.name}:{názov certifikátu}).
`lock.locked_for_seconds`	`CERTIFICATES_LOCK_SECONDS`	5	Bezpečnostná expirácia zámku v sekundách — nastavte ju nad najpomalšie vystavenie.
`status_cache.enabled`	`CERTIFICATES_STATUS_CACHE`	true	Cachovať živé reporty stavu od poskytovateľa.
`status_cache.store`	`CERTIFICATES_STATUS_CACHE_STORE`	null	Cache store; null použije predvolený.
`status_cache.ttl`	`CERTIFICATES_STATUS_CACHE_TTL`	300	Platnosť cache stavu v sekundách.
`alerts.enabled`	`CERTIFICATES_ALERTS`	false	Upozornenia z certificates:check a pri zlyhaniach životného cyklu.
`alerts.notifiable`	`CERTIFICATES_ALERTS_NOTIFIABLE`	null	FQCN príjemcu z kontajnera — musí sa vyriešiť na uložený Eloquent model, preto triedu naviažte na jej záznam (nenaviazaná trieda vytvorí neuložený model, čo vyhodí výnimku); má prednosť pred vlastníkom certifikátu.
`alerts.thresholds.warning_days`	`CERTIFICATES_ALERTS_WARNING_DAYS`	30	Varovné pásmo kontroly expirácie.
`alerts.thresholds.critical_days`	`CERTIFICATES_ALERTS_CRITICAL_DAYS`	7	Kritické pásmo — kontrola v ňom zlyhá.
`alerts.channels`	—	['mail']	Kanály kontroly za celý register.
`alerts.register_check`	`CERTIFICATES_ALERTS_REGISTER_CHECK`	false	Pri štarte zaregistrovať jednu kontrolu expirácie za celý register.

Kľúče driverov nájdete na stránkach ACME a Let’s Encrypt, Kubernetes a cert-manager a Súborový driver. Drivery null a array nemajú žiadne nastavenia.

Prostredie (env)

Bežné prepínače sú riadené cez env, takže konfiguráciu publikujete len zriedka:

CERTIFICATES_DRIVER=acme
CERTIFICATES_RENEW_THRESHOLD_DAYS=21
CERTIFICATES_RENEW_QUEUE=certificates
CERTIFICATES_STATUS_CACHE_TTL=300
CERTIFICATES_ALERTS=true
CERTIFICATES_ALERTS_WARNING_DAYS=30
CERTIFICATES_ALERTS_CRITICAL_DAYS=7

Každý logický prepínač prijíma bežné zápisy z env — true/false, 1/0, on/off, yes/no — takže CERTIFICATES_ALERTS=1 zapne upozornenia a CERTIFICATES_STATUS_CACHE=off vypne cache. Nenastavená hodnota — chýbajúca, null alebo prázdna ('', čo dá KEY= v .env) — sa číta ako predvolená; čokoľvek iné (preklep ako disabled) vyhodí InvalidConfigurationException s názvom kľúča, namiesto toho, aby sa potichu použila predvolená hodnota.

Prísne čítanie konfigurácie

Rovnako prísne sa číta každá ďalšia hodnota. Nenastavená hodnota (chýbajúca, null alebo prázdna) sa číta ako predvolená; zadaná hodnota nesprávneho tvaru vyhodí InvalidConfigurationException s názvom kľúča:

Celé čísla prijímajú int alebo kanonické celé číslo v reťazci (hodnoty z env prichádzajú ako reťazce), takže CERTIFICATES_RENEW_THRESHOLD_DAYS=five, '1.5' či hodnota mimo rozsahu vyhodí výnimku — nikdy sa potichu nezmení na 0. Hranice: renewal.threshold_days, lock.locked_for_seconds, status_cache.ttl, drivers.acme.poll.* a drivers.filesystem.self_signed_days ≥ 1; alerts.thresholds.* ≥ 0; drivers.kubernetes.service.port 1–65535.
Reťazcové nastavenia (default, table, lock.name, disky, cesty, namespace, issuer, …) musia byť reťazce a prázdna hodnota sa považuje za nenastavenú, takže platí predvolená. Voliteľné (connection, fronty, cache store, tokeny, contact, solver, notifiable) musia byť reťazcom, ak sú nastavené, a prázdna hodnota sa považuje za nenastavenú, takže zostanú nenastavené. name_prefix smie byť '' — nečíta sa ako nenastavený, takže názvy sú samotný hostiteľ.
drivers.acme.account.key_type je EC alebo RSA; alerts.channels je zoznam názvov kanálov; alerts.notifiable sa musí vyriešiť na uložený Eloquent model (naviažte triedu v kontajneri: $this->app->bind(OpsTeam::class, fn () => OpsTeam::query()->firstOrFail())) a drivers.acme.solver na AcmeChallengeSolver.
key_type je bigint, uuid alebo ulid bez ohľadu na veľkosť písmen — nenastavená alebo prázdna hodnota sa číta ako bigint, iná vyhodí výnimku. Číta ho migrácia, preto ho nastavte pred migrovaním.

Zámok a overovanie TLS

lock.* nastavuje cache zámok, ktorý sa počas vystavenia berie pre každý certifikát zvlášť ({lock.name}:{názov certifikátu}) — ostatné certifikáty nikdy neblokuje. Kým je obsadený, issue() vyhodí ProvisioningInProgressException (záznam v registri zostane nedotknutý) a generate() vráti false. lock.locked_for_seconds nastavte nad najpomalšie vystavenie: ACME objednávka sa kontroluje až poll.attempts × poll.seconds.

drivers.kubernetes.ca_path a drivers.acme.verify sa čítajú rovnako: cesta k CA balíku, null alebo prázdna hodnota (či true, 1, on, yes) pre systémový CA balík a overovanie TLS vypne len hodnota false (false, 0, off, no) — neodporúčame. Akýkoľvek iný reťazec je cesta k balíku (preklep zlyhá pri TLS handshaku — overovanie nikdy nevypne) a hodnota, ktorá nie je reťazcom ani booleanom (pole, float), vyhodí InvalidConfigurationException.

Odvodené názvy certifikátov

Každý certifikát dostane deterministický názov: name_prefix a primárnu doménu prevedené na malé písmená a do tvaru DNS-1123 subdomény — len a–z, 0–9 a pomlčky, úvodné *. sa zmení na wildcard- a príliš dlhý názov sa skráti na 253 znakov s hashom na konci. Pri doménach nezáleží na veľkosti písmen, takže App.Example.com a app.example.com zdieľajú jeden názov aj jeden záznam v registri. Názov je zároveň názvom secretu v Kubernetes, názvom adresára na úložnom disku a polovicou unikátneho kľúča (driver, name) v registri:

Certificates::certificateName('app.example.com'); // "generated-tls-app-example-com"
Certificates::certificateName('App.Example.com'); // "generated-tls-app-example-com" — the same certificate
Certificates::certificateName('*.Example.com');   // "generated-tls-wildcard-example-com"

Prejavte lásku k open source

Tento balík je zadarmo pod licenciou MIT. Ak vám šetrí čas, jednorazový príspevok alebo členstvo na Patreone nám pomôže ho ďalej udržiavať, testovať a dokumentovať.

Ďalšie spôsoby podpory vrátane kryptomien

Odoslaním daru súhlasíte s našimi podmienkami prijímania darov.

Podporte našu open-source prácu Pridajte sa k nám na Patreone

Chcete to zabudovať do svojho produktu?

Naše balíky integrujeme do zákazkových Laravel a AI riešení. Napíšte nám, na čom pracujete, a ozveme sa do 48 hodín.

Ponuka do 48 hodín Prezrieť všetky balíky