Cert-Manager на Kubernetes: Пълно ръководство за настройка на автоматизирано управление на TLS сертификати

Cert-Manager е контролер с отворен код за Kubernetes, който напълно автоматизира жизнения цикъл на TLS сертификатите — от първоначалното издаване през валидирането до подновяването — чрез директна интеграция с удостоверителни органи като Let’s Encrypt, HashiCorp Vault и частни PKI системи. Той елиминира ръчните работни процеси за сертификати, като третира сертификатите като собствени ресурси на Kubernetes, управлявани декларативно чрез Custom Resource Definitions (CRDs).

За всеки производствен Kubernetes клъстер, изтеклите или неправилно конфигурирани TLS сертификати са една от най-честите причини за непланиран престой. Cert-Manager решава това, като непрекъснато съгласува състоянието на сертификатите, автоматично подновява идентификационните данни преди изтичане и съхранява получения ключов материал в Kubernetes Secrets, които Ingress контролерите и работните натоварвания могат да използват незабавно.

Защо Cert-Manager е стандартът за TLS автоматизация в Kubernetes

Преди Cert-Manager да се превърне в де факто решение, екипите или скриптираха certbot подновявания на отделни възли, ръчно ротираха сертификати в пространствата от имена, или разчитаха на специфични за облачни доставчици интеграции, които създаваха зависимост от доставчика. Cert-Manager обединява всички тези подходи под единна, Kubernetes-native контролна равнина.

Ключови предимства пред ad-hoc подходите:

• Декларативно управление: Намерението за сертификат се изразява като YAML манифест, контролиран по версии заедно с кода на приложението.
• Автоматично съгласуване: Контролният цикъл открива отклонения между желаното и действителното състояние на сертификата и ги коригира без човешка намеса.
• Поддръжка на множество издатели: Един клъстер може едновременно да използва Let’s Encrypt за публично достъпни услуги, вътрешен CA за service-mesh mTLS и HashiCorp Vault за работни натоварвания, чувствителни към тайни.
• Одитна следа: Всеки CertificateRequest обект се запазва в Kubernetes API, давайки ви пълна история на издаванията.

Работата с Kubernetes на платформа за VPS Хостинг с NVMe-базирано съхранение и пълен root достъп ви дава необходимия контрол за конфигуриране на персонализирани DNS резолвери, управление на правила на защитната стена за ACME HTTP-01 предизвикателства и инсталиране на CRDs на ниво клъстер без ограничения — всички предпоставки за производствено внедряване на Cert-Manager.

Основна архитектура: Как работи Cert-Manager вътрешно

Разбирането на вътрешната архитектура на Cert-Manager предотвратява неправилни конфигурации и ви помага бързо да отстранявате грешки при издаване.

Машината на състоянията на жизнения цикъл на сертификата

Cert-Manager управлява сертификатите чрез детерминистична машина на състоянията. Всеки Certificate ресурс преминава през следните състояния:

1. Pending (Изчакване) — Обектът Certificate съществува, но нито едно валидно CertificateRequest не е изпълнено.
2. Issuing (Издаване) — Създаден е CertificateRequest и е изпратен до конфигурирания издател.
3. Ready (Готов) — Валиден, неизтекъл сертификат е съхранен в референтния Kubernetes Secret.
4. Renewal Pending (Подновяване в изчакване) — Сертификатът е в рамките на прозореца renewBefore (по подразбиране: 30 дни преди изтичане) и се обработва нов CertificateRequest.

Контролерът наблюдава всички Certificate обекти в целия клъстер и непрекъснато съгласува тяхното състояние. Ако Secret бъде изтрит ръчно, Cert-Manager открива липсващия ресурс и незабавно задейства повторно издаване — критично поведение за самовъзстановяване, което предотвратява случайни прекъсвания.

Основни CRD компоненти

Ресурсите Order и Challenge се създават автоматично от ACME издателя — рядко взаимодействате с тях директно, но инспектирането им е основният път за отстраняване на грешки, когато издаването спре.

Съхранение на сертификати и формат на Secret

След издаване, Cert-Manager записва три ключа с данни в целевия Kubernetes Secret:

• tls.crt — Пълната верига от сертификати (листов + междинни), кодирана в PEM.
• tls.key — Частният ключ, кодиран в PEM.
• ca.crt — Сертификатът на издаващия CA (попълва се за вътрешни CA; може да е празен за ACME издатели).

Ingress контролерите, service mesh-овете и приложните подове монтират директно този Secret. Форматът е съвместим с NGINX, Traefik, Istio, Linkerd и повечето други Kubernetes-native TLS потребители.

Поддържани издатели и кога да използвате всеки

ACME (Let’s Encrypt и алтернативи)

ACME протоколът е най-честият път за издаване. Cert-Manager имплементира пълния RFC 8555 ACME клиент, поддържайки както staging, така и production крайни точки.

HTTP-01 предизвикателство: Cert-Manager временно обслужва токен на http://<domain>/.well-known/acme-challenge/<token>. Това изисква домейнът да се разрешава до публично достъпен IP на порт 80. Работи за сертификати с единичен домейн и SAN, но не може да издава wildcard сертификати.

DNS-01 предизвикателство: Cert-Manager създава _acme-challenge.<domain> TXT запис чрез API на DNS доставчик. Работи зад защитни стени, поддържа wildcard сертификати (*.example.com) и се изисква за всеки клъстер, който не е директно изложен в интернет. Поддържаните DNS доставчици включват Cloudflare, Route53, Google Cloud DNS, Azure DNS и много други чрез webhook решители.

HashiCorp Vault

Vault издателят се интегрира с PKI secrets engine на Vault. Той е предпочитаният избор за:

• Вътрешен mTLS на микроуслуги, където сертификатите трябва да бъдат краткотрайни (часове, не месеци).
• Среди със строги изисквания за съхранение на ключове, където частните ключове никога не трябва да напускат Vault.
• Автоматизирана ротация на сертификати, свързана със системата за подновяване на наем на Vault.

Self-Signed и CA издатели

Издателят SelfSigned генерира сертификати, подписани от собствения частен ключ на сертификата — полезен за начално зареждане на root CA в клъстера. Издателят CA използва Kubernetes Secret, съдържащ двойка CA ключове за подписване на сертификати, което го прави подходящ за вътрешни среди за разработка и service mesh PKI.

Venafi

Интеграцията с Venafi е насочена към корпоративни среди с централизирано прилагане на политики за сертификати, одит на съответствие и интеграция с хардуерни модули за сигурност (HSMs).

Cert-Manager срещу алтернативни подходи за TLS автоматизация

За екипи, работещи с Kubernetes на Dedicated Server или VPS, Cert-Manager е единственият подход, който едновременно е Kubernetes-native, поддържа всички основни CA и изисква нулева продължаваща ръчна намеса.

Инсталиране на Cert-Manager: Настройка, готова за производство

Предпоставки

• Kubernetes 1.22+ (препоръчва се 1.26+ за пълна стабилност на CRD)
• kubectl конфигуриран с привилегии на cluster-admin
• Инсталиран Helm 3.x
• Регистриран домейн с достъп до управление на DNS (за DNS-01) или публично достъпен ingress IP (за HTTP-01)

Ако управлявате собствен домейн, силно се препоръчва Регистрация на домейн чрез доставчик, който предоставя API — това позволява напълно автоматизирано решаване на DNS-01 предизвикателства без ръчна намеса.

Стъпка 1: Инсталиране на CRDs и Cert-Manager контролера

Препоръчителният метод за производствена инсталация използва Helm с CRDs, управлявани отделно, за да се избегнат конфликти при надграждане на Helm:

# Add the Jetstack Helm repository
helm repo add jetstack https://charts.jetstack.io
helm repo update

# Install Cert-Manager with CRDs included
helm install cert-manager jetstack/cert-manager 
  --namespace cert-manager 
  --create-namespace 
  --version v1.14.5 
  --set installCRDs=true 
  --set global.leaderElection.namespace=cert-manager

Проверете дали всичките три основни пода работят, преди да продължите:

kubectl get pods --namespace cert-manager

Очакван изход:

NAME                                       READY   STATUS    RESTARTS   AGE
cert-manager-xxxxxxxxx-xxxxx              1/1     Running   0          60s
cert-manager-cainjector-xxxxxxxxx-xxxxx   1/1     Running   0          60s
cert-manager-webhook-xxxxxxxxx-xxxxx      1/1     Running   0          60s

cainjector инжектира данни за CA bundle в конфигурациите на webhook. webhook валидира и мутира CRD обектите на Cert-Manager — ако не работи, всички kubectl apply операции върху ресурси на Cert-Manager ще се провалят.

Стъпка 2: Конфигуриране на ClusterIssuer за Let’s Encrypt

Винаги започвайте с staging средата на Let’s Encrypt, за да избегнете достигане на производствените ограничения за скорост (50 сертификата на регистриран домейн на седмица):

apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: letsencrypt-staging
spec:
  acme:
    server: https://acme-staging-v02.api.letsencrypt.org/directory
    email: ops@example.com
    privateKeySecretRef:
      name: letsencrypt-staging-account-key
    solvers:
      - http01:
          ingress:
            class: nginx

След като staging сертификатите се издадат успешно, създайте производствения издател:

apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: letsencrypt-prod
spec:
  acme:
    server: https://acme-v02.api.letsencrypt.org/directory
    email: ops@example.com
    privateKeySecretRef:
      name: letsencrypt-prod-account-key
    solvers:
      - http01:
          ingress:
            class: nginx

Приложете двата манифеста:

kubectl apply -f clusterissuer-staging.yaml
kubectl apply -f clusterissuer-prod.yaml

Проверете готовността на издателя:

kubectl describe clusterissuer letsencrypt-prod

Полето Status.Conditions трябва да показва Ready: True. Ако показва False, регистрацията на ACME акаунта е неуспешна — проверете имейл адреса и мрежовата свързаност от пода cert-manager.

Стъпка 3: Изрично заявяване на сертификат

Можете да заявявате сертификати или чрез директно създаване на ресурс Certificate, или чрез анотиране на ресурс Ingress. Явният подход с Certificate ви дава повече контрол:

apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: example-com-tls
  namespace: production
spec:
  secretName: example-com-tls-secret
  issuerRef:
    name: letsencrypt-prod
    kind: ClusterIssuer
  commonName: example.com
  dnsNames:
    - example.com
    - www.example.com
  duration: 2160h    # 90 days (Let's Encrypt default)
  renewBefore: 720h  # Renew 30 days before expiry

Приложете и наблюдавайте издаването:

kubectl apply -f certificate.yaml
kubectl describe certificate example-com-tls -n production

Наблюдавайте обектите CertificateRequest и Order за подробен статус:

kubectl get certificaterequest -n production
kubectl describe order -n production

Стъпка 4: Метод с анотация на Ingress (опростен)

За екипи, използващи NGINX Ingress Controller, Cert-Manager може да бъде задействан автоматично чрез анотация — не се изисква отделен манифест Certificate:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: example-ingress
  namespace: production
  annotations:
    cert-manager.io/cluster-issuer: "letsencrypt-prod"
spec:
  ingressClassName: nginx
  tls:
    - hosts:
        - example.com
        - www.example.com
      secretName: example-com-tls-secret
  rules:
    - host: example.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: example-service
                port:
                  number: 80

Cert-Manager открива анотацията и автоматично създава съответния ресурс Certificate. Това е най-честият модел в GitOps работните процеси.

Разширени модели на конфигурация

Wildcard сертификати с DNS-01 (пример с Cloudflare)

Wildcard сертификатите изискват DNS-01 валидиране. Първо, създайте Secret, съдържащ вашия Cloudflare API токен:

kubectl create secret generic cloudflare-api-token 
  --from-literal=api-token=<YOUR_CLOUDFLARE_API_TOKEN> 
  --namespace cert-manager

Конфигурирайте ClusterIssuer с DNS-01 решител:

apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: letsencrypt-prod-dns
spec:
  acme:
    server: https://acme-v02.api.letsencrypt.org/directory
    email: ops@example.com
    privateKeySecretRef:
      name: letsencrypt-prod-dns-account-key
    solvers:
      - dns01:
          cloudflare:
            apiTokenSecretRef:
              name: cloudflare-api-token
              key: api-token

Заявете wildcard сертификата:

apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: wildcard-example-com
  namespace: production
spec:
  secretName: wildcard-example-com-tls
  issuerRef:
    name: letsencrypt-prod-dns
    kind: ClusterIssuer
  dnsNames:
    - "*.example.com"
    - example.com

Критичен проблем: Secret, съдържащ идентификационните данни на DNS доставчика, трябва да се намира в пространството от имена cert-manager, когато е референциран от ClusterIssuer. Ако го поставите в друго пространство от имена, контролерът не може да го прочете и издаването ще се провали безшумно. Проверете логовете на cert-manager контролера с kubectl logs -n cert-manager deploy/cert-manager, ако предизвикателствата спрат.

Вътрешна PKI с CA издател

За mTLS между услуги в рамките на клъстер, издател CA, подкрепен от самоподписан root, е по-подходящ от ACME:

# Step 1: Create a self-signed root CA certificate
apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: selfsigned-root
spec:
  selfSigned: {}
---
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: internal-root-ca
  namespace: cert-manager
spec:
  isCA: true
  commonName: internal-root-ca
  secretName: internal-root-ca-secret
  issuerRef:
    name: selfsigned-root
    kind: ClusterIssuer
---
# Step 2: Create a CA issuer backed by the root certificate
apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: internal-ca-issuer
spec:
  ca:
    secretName: internal-root-ca-secret

Услугите вече могат да заявяват краткотрайни сертификати от internal-ca-issuer за mTLS без никаква зависимост от външен CA.

Конфигуриране на renewBefore за среди с висока сигурност

Стойността по подразбиране renewBefore от 30 дни е подходяща за 90-дневни Let’s Encrypt сертификати. За краткотрайни вътрешни сертификати (напр. 24-часова валидност), задайте renewBefore като дробна част от общата продължителност:

spec:
  duration: 24h
  renewBefore: 8h

Cert-Manager ще започне подновяване 8 часа преди изтичане, давайки на контролера три прозореца за подновяване в рамките на 24-часов живот на сертификата — критичен предпазен марж, ако клъстерът изпита временна недостъпност на API сървъра.

Отстраняване на чести грешки в Cert-Manager

Сертификат, заседнал в състояние „Issuing”

# Check the Certificate status
kubectl describe certificate <name> -n <namespace>

# Check the associated CertificateRequest
kubectl describe certificaterequest -n <namespace>

# Check the ACME Order
kubectl describe order -n <namespace>

# Check the Challenge
kubectl describe challenge -n <namespace>

# Check controller logs
kubectl logs -n cert-manager deploy/cert-manager --tail=100

Чести основни причини:

• Неуспех на HTTP-01: Ingress контролерът не маршрутизира правилно трафика /.well-known/acme-challenge/. Проверете дали обектът Ingress на предизвикателството е създаден и дали порт 80 е достъпен от интернет. Защитните стени на хоста трябва да позволяват входящ TCP/80.
• Неуспех на DNS-01: API токенът на DNS доставчика има недостатъчни разрешения или DNS разпространението не е завършило. Валидиращите сървъри на Let’s Encrypt могат да заявяват различни резолвери от вашия локален DNS — закъснения при разпространение от 60–120 секунди са нормални.
• Надвишено ограничение за скорост: Let’s Encrypt налага 5 неуспешни опита за валидиране на домейн на час. След достигане на това ограничение трябва да изчакате преди повторен опит. Винаги тествайте първо с staging крайната точка.
• Webhook не е готов: Ако подът на cert-manager webhook не работи, всички CRD операции ще се провалят с грешка за отказана връзка. Уверете се, че webhook услугата има валидна крайна точка.

Проверка на внедрен сертификат

# Check the Secret contents
kubectl get secret example-com-tls-secret -n production -o jsonpath='{.data.tls.crt}' | base64 -d | openssl x509 -noout -text

# Check expiry date specifically
kubectl get secret example-com-tls-secret -n production -o jsonpath='{.data.tls.crt}' | base64 -d | openssl x509 -noout -enddate

Контролен списък за втвърдяване на производствената среда

Внедряването на Cert-Manager в производствена среда изисква повече от стандартна Helm инсталация. Приложете тези мерки за втвърдяване преди пускане в производство:

• Ограничения на ресурсите: Задайте requests и limits за CPU и памет на всичките три пода на Cert-Manager, за да предотвратите конкуренция за ресурси на споделени възли.
• RBAC одит: Cert-Manager изисква широки RBAC разрешения. Прегледайте инсталираните ClusterRole обекти и ги ограничете до минимално необходимото за вашите типове издатели.
• Отделно пространство от имена: Винаги внедрявайте Cert-Manager в собственото му пространство от имена cert-manager, изолирано от работните натоварвания на приложенията.
• Мониторинг: Изложете крайната точка за Prometheus метрики на Cert-Manager (--metrics-listen-address) и задайте предупреждения за certmanager_certificate_expiration_timestamp_seconds, за да улавяте неуспехи при подновяване преди да засегнат услугите.
• Архивиране на CRD състоянието: Включете обектите Certificate, ClusterIssuer и Issuer в стратегията си за архивиране на клъстера. Загубата на тези манифести след събитие за възстановяване при бедствие означава ръчно пресъздаване на всички конфигурации на сертификати.
• Staging валидиране: Никога не издавайте първия си сертификат срещу производствена ACME крайна точка. Нарушенията на ограниченията за скорост могат да блокират вашия домейн за до една седмица.

Ако управлявате множество Kubernetes клъстери — например разделяне на staging и производствени работни натоварвания — VPS Контролни панели могат да опростят управлението на жизнения цикъл на клъстера и да ви дадат унифициран интерфейс за осигуряване на базовата инфраструктура, върху която работи всеки клъстер.

За работни натоварвания, изискващи GPU-ускорено извеждане или ML обслужване зад TLS-терминирани крайни точки, същите модели на Cert-Manager се прилагат на инфраструктура за GPU Хостинг, където автоматизираното управление на сертификати е еднакво критично за защита на крайните точки на API на модели.

Практическа матрица за вземане на решения: Избор на правилния издател

Основни изводи

• Инсталирайте Cert-Manager с Helm с installCRDs=true и винаги валидирайте срещу staging ACME крайната точка преди преминаване към производство.
• Използвайте ClusterIssuer за клъстери с множество пространства от имена; използвайте Issuer с обхват на пространство от имена само когато се нуждаете от изолация на CA на ниво екип.
• DNS-01 е строго задължителен за wildcard сертификати и за клъстери, недостъпни директно от интернет на порт 80.
• Полето renewBefore не е незадължително в производство — задайте го на поне една трета от общия duration на сертификата.
• Когато издаването спре, пътят за отстраняване на грешки винаги е: Certificate → CertificateRequest → Order → Challenge → логове на контролера.
• Идентификационните данни на DNS доставчика, референцирани от ClusterIssuer, трябва да се намират в пространството от имена cert-manager, а не в пространствата от имена на приложенията.
• Наблюдавайте certmanager_certificate_expiration_timestamp_seconds в Prometheus и задайте предупреждение за него — безшумните неуспехи при подновяване са най-опасният режим на повреда.
• Архивирайте манифестите Certificate и ClusterIssuer като част от плана си за възстановяване при бедствие.

Често задавани въпроси

Каква е разликата между Issuer и ClusterIssuer в Cert-Manager?

Issuer е с обхват на пространство от имена и може да издава сертификати само в пространството от имена, където е дефиниран. ClusterIssuer е за целия клъстер и може да бъде референциран от ресурси Certificate във всяко пространство от имена. За повечето производствени клъстери ClusterIssuer е правилният избор, освен ако не се нуждаете от строга изолация на CA на ниво пространство от имена.

Защо моят Cert-Manager сертификат е заседнал в състояние „Issuing”?

Инспектирайте обектите Order и Challenge в същото пространство от имена с kubectl describe. Най-честите причини са: порт 80, блокиран от защитна стена (HTTP-01), неправилни API идентификационни данни на DNS или закъснение при разпространение (DNS-01), надвишени ограничения за скорост на Let’s Encrypt или неработещ под на cert-manager webhook. Винаги проверявайте логовете на контролера с kubectl logs -n cert-manager deploy/cert-manager.

Може ли Cert-Manager да издава wildcard сертификати от Let’s Encrypt?

Да, но само с типа предизвикателство DNS-01. HTTP-01 не може да валидира wildcard домейни. Трябва да конфигурирате интеграция с DNS доставчик (Cloudflare, Route53 и др.) в конфигурацията на решителя ClusterIssuer и да се уверите, че API идентификационните данни имат разрешение да създават TXT записи за целевия домейн.

Как Cert-Manager обработва автоматичното подновяване на сертификати?

Контролерът на Cert-Manager непрекъснато сравнява изтичането на всеки обект Certificate с текущото време. Когато оставащата валидност падне под прага renewBefore (по подразбиране: 30 дни), контролерът създава нов CertificateRequest, завършва ACME предизвикателството и атомарно заменя съдържанието на целевия Secret — всичко това без рестартиране на подовете, използващи сертификата. Подовете, монтиращи Secret като том, ще видят актуализирания сертификат при следващия цикъл на синхронизация на kubelet.

Подходящ ли е Cert-Manager за защита на вътрешна комуникация между услуги, не само за публичен HTTPS?

Да. Използвайки издателя CA или издателя HashiCorp Vault, Cert-Manager може да издава краткотрайни сертификати за вътрешен mTLS между микроуслуги. Това е често срещан модел в внедрявания на service mesh, където всяко работно натоварване се нуждае от уникален сертификат за идентичност. Полетата duration и renewBefore позволяват сертификатите да бъдат толкова краткотрайни, колкото минути, с напълно автоматизирана ротация.