Cert-Manager и Let's Encrypt в Kubernetes

Логотип Cert-Manager на иллюстрации

Cert-Manager упрощает автоматическое получение и продление TLS-сертификатов в кластере Kubernetes. Установите Cert-Manager через Helm, добавьте ClusterIssuer для Let’s Encrypt (сначала staging, затем production), аннотируйте Ingress и получите HTTPS для приложений. В статье есть пошаговый плейбук, чеклисты для ролей, типичные ошибки и варианты с DNS-челленджем.

Быстрые ссылки

Установка Cert-Manager
Добавление плагина kubectl
Создание ClusterIssuer
Получение сертификата через Ingress
Перевод в production с Let’s Encrypt
Обновление Cert-Manager
Плейбук и чек-листы
Устранение неполадок и сценарии отказа
Критерии приёмки
Словарь терминов
Резюме

Введение

Cert-Manager автоматизирует выдачу и продление TLS-сертификатов внутри Kubernetes. Он добавляет CRD (custom resources), которые позволяют запрашивать сертификаты у ACME-провайдеров, например Let’s Encrypt, и автоматически привязывать их к Ingress или другим ресурсам.

Краткое определение: Cert-Manager — контроллер Kubernetes, который управляет жизненным циклом TLS-сертификатов и интегрируется с ACME-провайдерами.

Важно: перед установкой убедитесь, что у вас есть подключённый kubectl и доступ к кластеру с правами создания namespace и CRD.

Установка Cert-Manager

Cert-Manager проще всего устанавливать через Helm. Helm — менеджер пакетов для Kubernetes, который использует репозитории с chart’ами.

Добавьте репозиторий Jetstack (разработчик Cert-Manager):

helm repo add jetstack https://charts.jetstack.io

Обновите локальную информацию о репозиториях Helm:

helm repo update

Установите Cert-Manager и CRD (пример с версией). Замените номер версии на актуальный из официальной документации:

helm install cert-manager jetstack/cert-manager --namespace cert-manager --create-namespace --version v1.5.3 --set installCRDs=true

Важно: флаг installCRDs автоматически создаёт CRD при установке. Для Helm версии ниже 3.2 нужно вручную применить CRD:

kubectl apply -f https://github.com/jetstack/cert-manager/releases/download/v1.5.3/cert-manager.crds.yaml

Проверка статуса:

kubectl get pods -n cert-manager

Ожидайте статуса Ready для основных компонентов: cert-manager, cert-manager-cainjector, cert-manager-webhook.

Добавление плагина kubectl

Плагин kubectl-cert-manager упрощает проверку состояния Cert-Manager и выполнение некоторых задач.

Скачайте архив плагина:

curl -L -o kubectl-cert-manager.tar.gz https://github.com/jetstack/cert-manager/releases/latest/download/kubectl-cert_manager-linux-amd64.tar.gz

Распакуйте и установите:

tar xzf kubectl-cert-manager.tar.gz
sudo mv kubectl-cert_manager /usr/local/bin

Проверьте API Cert-Manager:

kubectl cert-manager check api

Ожидаемый вывод:

The cert-manager API is ready

Если видите ошибку, проверьте логи webhook и status CRD.

Создание ClusterIssuer для Let’s Encrypt

Issuer и ClusterIssuer — ресурсы, которые выдают сертификаты. ClusterIssuer доступен во всём кластере, а Issuer ограничен namespace.

Пример конфигурации для staging-сервера Let’s Encrypt. Сохраните в файл issuer.yml и замените email на ваш контакт:

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

Примените:

kubectl create -f issuer.yml

Примечание: staging используется для проверки интеграции и не имеет ограничений production, поэтому не засчитывает в лимиты. Замените server и name для production, когда будете готовы.

Важно: убедитесь, что Ingress controller (например nginx-ingress) правильно маршрутизирует HTTP запросы к /.well-known/acme-challenge/

Получение сертификата через Ingress

Cert-Manager наблюдает за Ingress и создаёт Certificate при наличии аннотаций. Пример простого деплоя, сервиса и Ingress, который запросит сертификат у letsencrypt-staging:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app
spec:
  replicas: 1
  selector:
    matchLabels:
      app: my-app
  template:
    metadata:
      labels:
        app: my-app
    spec:
      containers:
      - name: my-app
        image: wordpress:latest
        ports:
        - containerPort: 80
---
apiVersion: v1
kind: Service
metadata:
  name: my-service
spec:
  selector:
    app: my-app
  ports:
  - port: 80
    targetPort: 80
---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: my-ingress
  annotations:
    kubernetes.io/ingress.class: nginx
    cert-manager.io/cluster-issuer: letsencrypt-staging
spec:
  rules:
  - host: example.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: my-service
            port:
              number: 80
  tls:
  - hosts:
    - example.com
    secretName: my-ingress-tls

После применения kubectl apply -f my-ingress.yaml Cert-Manager создаст ресурс Certificate и попытается пройти HTTP-01 челлендж. Если всё успешно — сертификат будет сохранён в Secret my-ingress-tls и автоматически применён к Ingress.

Важно: в поле tls.secretName укажите секрет, который Cert-Manager заполнит. Если не указать — Cert-Manager создаст имя автоматически.

Использование Let’s Encrypt в production

Когда staging проверен, создайте отдельный ClusterIssuer для production:

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

Примените:

kubectl create -f issuer-production.yml

Затем обновите аннотацию Ingress на cert-manager.io/cluster-issuer: letsencrypt-production и примените изменения.

Совет: не переводите всё в production одномоментно. Держите оба ClusterIssuer и поэтапно меняйте аннотации для проверенных сервисов.

Обновление Cert-Manager

Обычно Cert-Manager поддерживает in-place upgrade через Helm. Шаги общие:

helm repo update
helm upgrade --version  cert-manager jetstack/cert-manager --namespace cert-manager

Перед обновлением:

Внимательно прочитайте release notes каждой промежуточной версии.
Выполните резервную копию секретов и сертификатов (Secrets с типом kubernetes.io/tls).
Для крупных переходов протестируйте upgrade на тестовом кластере.

Важно: во время апгрейда процесс автоматического обновления сертификатов может временно приостанавливаться.

Плейбук для DevOps инженера: шаги от A до Z

Проверить доступ к кластеру и версии kubectl/helm.
Установить Helm chart Jetstack и CRD.
Проверить Pods cert-manager, webhook и cainjector.
Установить kubectl плагин и проверить API.
Создать letsencrypt-staging ClusterIssuer и протестировать HTTP-01.
Развернуть тестовый Ingress и дождаться создания Certificate.
Проверить содержимое Secret и ответ HTTPS.
Создать letsencrypt-production ClusterIssuer и поэтапно переключать рабочие Ingress.
Настроить мониторинг: alerts на expiring certificates и состояния cert-manager.
Документировать процедуру отката и периодичность обновлений.

Ролевые чек-листы

Платформенный инженер:

Установить и поддерживать Cert-Manager в namespace cert-manager.
Обеспечить доступность Ingress controller и корректную маршрутизацию HTTP.
Вести версионность Helm release и release notes.

SRE:

Настроить SLIs/SLOs: percentage успешных выпусков, время на решение инцидента.
Настроить alerts на expiring certificates за 30 дней и 7 дней до истечения.

Разработчик приложения:

Добавлять аннотации cert-manager.io/cluster-issuer в Ingress.
Указывать tls.secretName и проверять, что сервис отвечает на HTTP.

Устранение неполадок и типичные ошибки

Cert-Manager не создаёт Certificate:
- Проверьте аннотации Ingress и правильность имени ClusterIssuer.
- Посмотрите логи cert-manager: kubectl logs -n cert-manager deploy/cert-manager.
HTTP-01 челлендж провалился:
- Проверьте, что Ingress отвечает по HTTP на /.well-known/acme-challenge/.
- Убедитесь, что DNS A/AAAA записи указывают на ваш Ingress controller.
Webhook недоступен после обновления:
- Проверьте Mutating/ValidatingWebhookConfiguration и сертификаты вебхуков.
Ошибки rate limit от Let’s Encrypt:
- Переключитесь на staging для тестов. Избегайте частых запросов и тестовых перезапросов.

Когда подход с HTTP-01 не подходит

Если ваша инфраструктура блокирует публичный HTTP или вы не можете настроить Ingress для ACME — используйте DNS-01 челлендж. DNS-01 проверяет владение доменом через TXT-запись и подходит для wildcard-сертификатов.

Пример схемы DNS-01: провайдер DNS с API + cert-manager DNS01 solver (Cloudflare, Route53 и т.д.).

Альтернативные подходы

Использовать облачные управляющиеся сертификационные сервисы (например, ACM в AWS) — если вы работаете в одном облаке и хотите избавиться от управления ACME.
Генерация и управление сертификатами вручную — подходит для специальных сценариев, но требует операционной дисциплины.
Использовать external-dns вместе с DNS-01 для автоматизации записи TXT-записей.

Модели зрелости использования Cert-Manager

Начальная: ручная установка, staging, единичные сервисы.
Базовая: автоматическое обновление для большинства Ingress, мониторинг.
Продвинутая: DNS-01 для wildcard, интеграция с CD/CI, автоматические тесты и аудит.

Критерии приёмки

Cert-Manager установлен в namespace cert-manager и все Pods Ready.
ClusterIssuer letsencrypt-staging создан и показывает статус Ready.
Тестовый Ingress успешно получает секрет TLS и HTTPS отвечает корректно.
Мониторинг оповещает о сертификатах за 30 и 7 дней до истечения.
Документация по процедурам обновления и отката доступна в репозитории конфигураций.

Примеры конфигураций и шаблоны

ClusterIssuer staging (шаблон выше) — используйте как основу.

Ingress с аннотацией ClusterIssuer:

metadata:
  annotations:
    kubernetes.io/ingress.class: nginx
    cert-manager.io/cluster-issuer: letsencrypt-production

Secret для ключей создаётся автоматически и имеет тип kubernetes.io/tls.

Безопасность и соответствие требованиям приватности

Секреты с приватными ключами хранятся в Kubernetes Secrets. По возможности включите шифрование etcd в Kubernetes для защиты данных на диске.
Ограничьте доступ к namespace cert-manager через RBAC и убедитесь, что только доверенные роли могут изменять ClusterIssuer.
Для соответствия GDPR: контактный email указывается в ACME запросах; убедитесь, что вы контролируете почтовый ящик и корректно обрабатываете уведомления.

Когда это не сработает или нужно осторожно

Приватные сети без публичного доступа к Ingress: HTTP-01 не пройдёт, используйте DNS-01.
Ограничения хостинга/провайдера, где изменение DNS автоматизировано сложно — потребуется интеграция с API провайдера или ручное управление.
Legacy Kubernetes версии могут требовать специальных патчей при апгрейде Cert-Manager.

Сценарий отката при проблемах после обновления

Откатить Helm release на предыдущую версию:

helm rollback cert-manager  -n cert-manager

Восстановить бэкап Secret’ов, если были изменения форматов.
Проверить состояние webhook и cainjector.
Если проблема в CRD, следовать инструкциям релиз-нотов на предмет миграций CRD.

Краткий словарь терминов

ACME: протокол автоматического получения сертификатов.
Issuer / ClusterIssuer: ресурсы Cert-Manager для запроса сертификатов.
HTTP-01 / DNS-01: типы проверок владения доменом.
CRD: Custom Resource Definition, расширение API Kubernetes.

Вопросы часто задаваемые (короткие ответы)

Q: Зачем staging сервер Let’s Encrypt? A: Чтобы тестировать интеграцию без риска получить rate limit или недействительные сертификаты в production.

Q: Могу ли я получить wildcard сертификат? A: Да, через DNS-01 челлендж, если ваш DNS-провайдер поддерживает автоматическое управление TXT-записями.

Резюме

Cert-Manager делает выдачу и обновление TLS-сертификатов в Kubernetes повторяемой и автоматической. Основные шаги: установка через Helm, создание ClusterIssuer для staging и production, аннотирование Ingress и проверка создания Certificate. Для продвинутых сценариев используйте DNS-01, интеграцию с external-dns и настройку мониторинга.

Важно: всегда тестируйте на staging перед переводом в production и заранее планируйте процедуру отката.

Ключевые действия для старта:

Установить Cert-Manager и CRD
Создать letsencrypt-staging ClusterIssuer
Развернуть тестовый Ingress и проверить TLS
Настроить мониторинг и перейти в production пошагово

Установка и использование Cert-Manager с Let's Encrypt в Kubernetes