Если вам нужен автоматический выпуск и продление TLS-сертификатов в кластере Kubernetes, cert-manager — стандарт де-факто. На уровне CRD он добавляет в кластер ресурсы для работы по протоколу ACME (включая Let’s Encrypt), умеет решать проверки HTTP-01 и DNS-01, интегрируется с Ingress-контроллерами и поддерживает wildcard. В этой статье мы сфокусируемся на грамотной настройке Issuer/ClusterIssuer и практиках DNS-01, от безопасности секретов до типовых ошибок с делегированием и TTL.
Зачем DNS-01 и когда он действительно нужен
Проверка DNS-01 подтверждает владение доменом через размещение временной TXT-записи в зоне _acme-challenge. В отличие от HTTP-01 ей не нужен доступ к веб-серверу и неважно, где и как маршрутизируется трафик. Именно DNS-01 позволяет выпускать wildcard-сертификаты (*.example.com), а также подходит, когда:
- у вас сложная схема с несколькими балансировщиками, CDN, приватными сетями или mTLS на входе;
- сервисы не доступны извне на 80/443 в момент проверки;
- нужен единый сертификат для множества поддоменов (wildcard).
Минусы DNS-01 — необходимость API-доступа к DNS-провайдеру или настройка делегирования/прокси для TXT-записей, а также зависимость от времени распространения изменений (TTL, консистентность авторитативных NS).
Issuer vs ClusterIssuer: область видимости и модель управления
В cert-manager есть два схожих CRD-ресурса для регистрации ACME-аккаунта и описания способов решения проверок:
- Issuer — namespaced-ресурс. Подходит, когда команды или приложения изолированы по неймспейсам. Секреты и настройки провайдеров хранятся в том же пространстве имен, где и сертификаты.
- ClusterIssuer — кластерный ресурс. Удобен для централизованного управления выпуском в масштабах всего кластера. Используйте, если у вас единая команда SRE/Platform и единый ACME-аккаунт. Секреты, на которые он ссылается, обычно размещают в неймспейсе cert-manager.
Практика: для продуктивных кластеров чаще создают пару из двух ClusterIssuer — «staging» (для тестов и отладки) и «production» (боевой выпуск), чтобы не упереться в лимиты Let’s Encrypt и быстрее ловить ошибки конфигурации.
Компоненты cert-manager, которые важно понимать
Выпуск и продление строятся вокруг нескольких CRD:
Certificate— желаемый сертификат: домены (SAN), срок, алгоритм ключа, секрет, куда положить результат.OrderиChallenge— промежуточные объекты, отражающие состояние ACME-взаимодействия и шаги валидации.Secret— для приватного ключа ACME-аккаунта, токенов DNS-провайдера и для результата (tls.crt/tls.key).
cert-manager по умолчанию инициирует продление примерно за треть срока до истечения (например, около 30 дней для 90-дневных сертификатов). Это дает запас на ретраи и на случай временных проблем с DNS.
Планирование DNS-01: провайдер, доступы, безопасность
Чтобы cert-manager смог создать и удалить TXT-запись, нужен провайдерский solver. Поддерживаются популярные API (например, Cloudflare, Route53, Google Cloud DNS, PowerDNS) и внешние webhook-решения. Ключевые моменты:
- Создайте отдельный API-токен с минимальными правами: только управление DNS в нужной зоне. Не используйте глобальные ключи администратора.
- Храните токен в
Secret, а не вConfigMapили аннотациях. Доступ к секрету должен быть только уServiceAccountcert-manager. - Если зона делегирована, убедитесь, что авторитативные NS для поддомена действительно обслуживают записи
_acme-challenge(проверяйте трассировкой DNS). - Если провайдер не поддерживается из коробки, разверните совместимый webhook-solver и опишите его в
Issuer/ClusterIssuer.
Если доменная зона еще не заведена или планируете отдельные поддомены под делегирование, заранее продумайте зонирование и сроки обновления. При необходимости воспользуйтесь сервисом регистрация доменов, чтобы быстро оформить нужные имена и настроить NS.
Установка cert-manager и базовые параметры
В проде разворачивайте cert-manager с минимум двумя репликами контроллера, включенной leader election и ограничениями ресурсов. CRD устанавливаются один раз на кластер. Важно, чтобы версия чарта/манифестов соответствовала версии Kubernetes API у вас в кластере.
Полезная привычка — сразу создать два ClusterIssuer: le-staging и le-production. Сначала проверяйте выпуск через «staging», затем переключайтесь на «production».
Пример: ClusterIssuer с DNS-01 через Cloudflare
Предположим, у вас есть зона example.com в Cloudflare и API Token со Scope «DNS:Edit» только для этой зоны. Секрет с токеном размещаем в неймспейсе cert-manager (важно для ClusterIssuer):
apiVersion: v1
kind: Secret
metadata:
name: cloudflare-api-token
namespace: cert-manager
type: Opaque
stringData:
token: YOUR_CLOUDFLARE_TOKEN
Создадим staging ClusterIssuer. Секцию server указываем на тестовую среду ACME, чтобы не упереться в лимиты:
apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
name: le-staging
spec:
acme:
email: ops@example.com
server: https://acme-staging-v02.api.letsencrypt.org/directory
privateKeySecretRef:
name: le-staging-account-key
solvers:
- selector:
dnsZones:
- example.com
dns01:
cloudflare:
apiTokenSecretRef:
name: cloudflare-api-token
key: token
Аналогично создайте le-production с боевым ACME-эндпоинтом. Для гибридных зон можно добавить несколько solvers и маршрутизировать их по dnsZones или другим селекторам.
Выпуск сертификата: Certificate и wildcard
Для wildcard указываем и сам подстановочный домен, и базовый домен (часто это нужно приложениям и для SNI):
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
name: wildcard-example-com
namespace: apps
spec:
secretName: wildcard-example-com-tls
duration: 2160h
renewBefore: 720h
privateKey:
algorithm: ECDSA
size: 256
dnsNames:
- example.com
- "*.example.com"
issuerRef:
name: le-staging
kind: ClusterIssuer
После применения проверьте Order/Challenge: cert-manager создаст TXT-запись, дождется самопроверки (self-check), затем завершит валидацию. Готовый сертификат попадет в секрет wildcard-example-com-tls. Про нюансы wildcard и автоматизацию DNS-01 мы писали отдельно — смотрите материал Подробно про wildcard и DNS-01 автоматизацию.
Интеграция с Ingress: автоматическое подключение TLS
Есть два варианта: создавать Certificate явно, как выше, или поручить это «ingress-shim» через аннотации/поля Ingress. В простых кейсах достаточно прописать tls.secretName и указать, каким Issuer пользоваться.
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: app
namespace: apps
annotations:
cert-manager.io/cluster-issuer: le-production
spec:
ingressClassName: nginx
tls:
- hosts:
- app.example.com
secretName: app-example-com-tls
rules:
- host: app.example.com
http:
paths:
- path: /
pathType: Prefix
backend:
service:
name: app-svc
port:
number: 80
ingress-shim создаст ресурс Certificate автоматически и будет поддерживать его в актуальном состоянии. Если нужен wildcard, удобнее описать Certificate вручную, а в нескольких Ingress ссылаться на один секрет.
Namespace Issuer для изоляции команд
В мультикомандных кластерах безопасно выдавать каждой команде отдельный Issuer в их namespace и свой токен DNS с ограничениями. В этом случае секрет токена храните также в namespace команды, и указывайте в issuerRef именно Issuer, а не ClusterIssuer. Плюс — явная изоляция и простая передача ответственности за сертификаты команде.
Делегирование и ACME-DNS: когда не хочется выдавать токен DNS
Иногда дать приложению доступ к API-записям всей зоны невозможно по требованиям безопасности. Тогда используют два подхода:
- Субделегирование
_acme-challenge.example.comна отдельные NS, управляемые безопасным сервисом. cert-manager пишет TXT в делегированный поддомен. - acme-dns: постоянная CNAME-запись указывает на внешний сервис, где cert-manager обновляет короткоживущие TXT. В спеке solvers включают
cnameStrategy: Follow, чтобы самопроверка шла по CNAME.
Оба подхода сокращают blast radius доступа, но требуют аккуратной начальной настройки зоны и документации для команд.
Типовые ошибки и как их диагностировать
Сборка частых проблем:
- TXT не виден снаружи. Причины: высокие TTL, кэш резолвера, записи применены в другом профиле/аккаунте провайдера, или правки не в той зоне (apex vs подзона). Проверяйте авторитативные NS, а не локальный резолвер.
- Неверные права токена. Минимум нужен доступ на изменение TXT в нужной зоне. Проверьте, что токен ограничен именно этой зоной и не просрочен.
- Selector solver не сработал. Если используете несколько solvers и маршрутизируете по
dnsZones, удостоверьтесь, что домен подпадает под правило. - Ingress без аннотации. Если рассчитываете на ingress-shim, но не указали
cert-manager.io/issuerилиcert-manager.io/cluster-issuer,Certificateможет не создаться.
Диагностика в кластере:
# Состояние сертификатов во всех неймспейсах
kubectl get certificates -A
# Детали конкретного сертификата и событий
kubectl describe certificate wildcard-example-com -n apps
# Текущие challenge и order
kubectl get challenges -A
kubectl get orders -A
# Логи контроллера cert-manager
kubectl logs -n cert-manager deploy/cert-manager -f
# Проверьте TXT с трассировкой к авторитативным NS
dig +trace _acme-challenge.example.com TXT
Если выпускаете много SAN в одном сертификате, учитывайте лимиты CA и частоту запросов. Детали и практики мы разбирали в материале Лимиты SAN и автоматизация выпуска сертификатов.
Продление, алгоритмы ключей и ротация
По умолчанию cert-manager начнет продление заранее, чтобы уложиться в дедлайн даже при временных сбоях DNS или недоступности ACME. Хорошей практикой является ECDSA P-256 (короче ключи, быстрее TLS-рукопожатия). Если у вас есть клиенты, не поддерживающие ECDSA, используйте RSA 2048+, но лучше постепенно переводить трафик на ECDSA. Ротацию ключей можно контролировать полем privateKey.rotationPolicy в Certificate.
Если планируете миграцию между staging и production, держите одинаковый secretName, но меняйте issuerRef. На выпуске из staging проверьте цепочку до тестового корня, затем переключайтесь на production и перезапускайте поды Ingress-контроллера (если он не видит обновление секрета автоматически).
Взаимодействие с ExternalDNS и контроллерами Ingress
ExternalDNS обычно управляет A/AAAA/CNAME, но TXT для ACME лучше оставлять cert-manager. Избегайте ситуаций, когда ExternalDNS «прибирает» к рукам _acme-challenge. Это достигается фильтрами в его настройках или разделением зон. Для Ingress-контроллеров (nginx, Traefik, Istio Gateway, Contour) важно, чтобы они корректно перечитывали обновленные секреты TLS — проверьте флаги контроллера или включите reload по событию.
Производственная надежность cert-manager
Несколько практических пунктов:
- Минимум две реплики deployment контроллера cert-manager и webhook, включите анти-аффинити и probe.
- Ограничьте RBAC: только необходимые кластерам разрешения на чтение/запись CRD cert-manager, доступ к секретам — по принципу наименьших привилегий.
- Следите за метриками: количество проваленных валидаций, ретраи, время выпуска. Настройте алерты на «сертификат истекает через X дней» по лейблам секретов или через экспортер.
- Не забывайте о бэкапах: секреты с приватными ключами ACME-аккаунтов и выпущенными сертификатами должны попадать в регулярные снапшоты etcd/манифестов.
Когда Issuer вместо ClusterIssuer
Если у вас многопользовательский кластер, и команды полностью самостоятельны, используйте Issuer в их namespaces. Это упрощает разграничение доступа: токены DNS каждой команды хранятся в ее пространстве имен, а cluster-admin не обязан масштабировать сложные селекторы в одном глобальном ClusterIssuer. Минус — больше повторяющегося кода и сложнее поддерживать стандарты, если десятки namespaces.
ACME EAB и корпоративные CA
В некоторых организациях применяют ACME с обязательной External Account Binding (EAB). cert-manager поддерживает EAB через параметры в секции acme Issuer/ClusterIssuer. Это полезно, если вы используете недефолтный ACME-сервер (внутренний CA или коммерческий ACME-провайдер) с политиками доступа на уровне аккаунта. Для публичных сайтов, где требуется OV/EV, подойдут коммерческие SSL-сертификаты: их можно использовать вместе с cert-manager через Issuer для корпоративных CA.
Контроль качества DNS и TTL
Для стабильного прохождения DNS-01 держите TTL TXT-записей невысоким (например, 60–120 секунд) и проверяйте, что авторитативные NS отвечают одинаково. При использовании нескольких провайдеров DNS обеспечьте консистентное обновление везде, куда указывает NS-запись домена. Для split-horizon DNS избегайте ситуации, когда внутренние NS не отражают состояние внешних авторитативных серверов — cert-manager ориентируется на публичную зону.
Чек-лист перед продом
- Есть
le-stagingиle-production, выпуск протестирован на staging. - API-токены DNS выданы с минимальными правами и лежат в Secrets правильных namespaces.
- Для wildcard есть явный
Certificateи общий секрет для всех Ingress, кому нужен домен из этого wildcard. - Ingress-контроллер перечитывает секреты без ручных рестартов.
- Алерты настроены на окончание срока действия сертификатов и на ошибки в логах cert-manager.
Итоги
Связка cert-manager + DNS-01 закрывает подавляющее большинство сценариев выпуска и продления TLS в Kubernetes, включая wildcard и сложные периметры. Выбор между Issuer и ClusterIssuer определяется моделью владения и безопасностью: централизованный контроль против изоляции команд. Практика показывает, что главный источник проблем — DNS (делегирование, TTL, недостаточные права токена), поэтому уделите ему особое внимание, а выпуск сертификатов через staging помогает поймать ошибки раньше, чем это повлияет на прод.
