Cert-Manager и Let's Encrypt в Kubernetes

Графика с логотипом Cert-Manager

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

Установка Cert-Manager
Добавление плагина kubectl
Создание Issuer
Получение сертификата
Использование Let’s Encrypt в продакшене
Обновление Cert-Manager
Руководство по эксплуатации и устранению проблем
Резюме

Cert-Manager автоматизирует выдачу сертификатов в кластере Kubernetes. Он предоставляет набор CRD (custom resources), с помощью которых можно запрашивать сертификаты и привязывать их к сервисам и Ingress.

Одно из самых частых применений — защита веб-приложений и API с помощью сертификатов Let’s Encrypt. В этом руководстве описаны шаги: установка Cert-Manager, создание ClusterIssuer для Let’s Encrypt, получение сертификата для приложения, доступного через Ingress, а также рекомендации для production и варианты обхода проблем.

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

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

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

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

Обновите кэш репозиториев:

helm repo update

Установите Cert-Manager в отдельное пространство имён:

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

Замените версию v1.5.3 на ту, что рекомендована в официальной документации для вашей среды.

Параметр installCRDs=true добавит CRD Cert-Manager автоматически. Эта опция поддерживается в Helm 3.2+. Если вы используете более старую версию Helm, примените CRD вручную:

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

Важно: Cert-Manager будет установлен в namespace cert-manager. Убедитесь, что у вас есть права для создания namespace и установки ресурсов кластера.

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

Cert-Manager предоставляет плагин для kubectl, который упрощает проверку состояния и некоторые операции управления.

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

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

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

kubectl cert-manager check api

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

The cert-manager API is ready

Этот плагин полезен для быстрой диагностики и проверки готовности API Cert-Manager.

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

Issuer и ClusterIssuer — это ресурсы Cert-Manager, которые отвечают за получение сертификатов. ClusterIssuer действует на уровне кластера и доступен во всех namespace, в то время как Issuer привязан к конкретному namespace.

Рекомендуется сначала настраивать staging-сервер Let’s Encrypt, чтобы избежать ограничения скорости в production. Создайте файл issuer.yml в рабочем каталоге с содержимым:

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

Замените example@example.com на ваш реальный контактный email. Let’s Encrypt может использовать этот адрес для оповещений по сертификатам.

Примените ClusterIssuer:

kubectl create -f issuer.yml

Если вы используете другой контроллер Ingress (не nginx), укажите соответствующий класс в поле ingress.class.

Важно: используйте staging на этапе настройки. Он не выдаёт доверенные браузерам сертификаты, но не попадает под строгие ограничения производства.

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

Cert-Manager следит за ресурсами Ingress и создаёт сертификаты на основе поля tls и аннотаций. Ниже приведён пример YAML, который разворачивает Deployment, Service и Ingress. Он подразумевает, что в кластере работает nginx-ingress.

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
---
apiVersion: networking.k8s.io/v1beta1
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: /
        backend:
          serviceName: my-service
          servicePort: 80
  tls:
  - hosts:
    - example.com

После применения этого манифеста Cert-Manager обнаружит аннотацию cert-manager.io/cluster-issuer и запустит процесс валидации через HTTP-01 (создаст временный путь .well-known на Ingress). Если Let’s Encrypt сможет достучаться до example.com/.well-known, будет выдан сертификат и он сохранится в секрете Kubernetes.

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

kubectl describe certificate -n

Проверьте также события в namespace cert-manager и логи контроллера Cert-Manager, если операция не удалась.

Использование Let’s Encrypt в продакшене

Когда staging-процесс отработал успешно, создайте отдельный ClusterIssuer для production и переключите Ingress-аннотации.

Файл issuer-production.yml (копировать issuer.yml и изменить поля):

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

Создайте production-issuer:

kubectl create -f issuer-production.yml

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

kubectl apply -f my-ingress.yaml

Cert-Manager автоматически заменит staging-сертификат на production. После этого HTTPS будет предоставлен браузерам как доверенный.

Советы для продакшена:

Держите отдельные issuer для staging и production.
Включите мониторинг секретов и оповещения о завершении срока действия сертификатов (Cert-Manager сам обновляет ресурсы, но мониторинг лишним не будет).
Рассмотрите использование DNS-01 для wildcard-сертификатов.

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

Обычно Cert-Manager поддерживает in-place обновления через Helm.

Обновите репозиторий Helm:

helm repo update

Выполните upgrade (замените на целевую версию):

helm upgrade --version  cert-manager jetstack/cert-manager

Во время обновления сертификаты остаются доступными, но процессы автоматического обновления могут остановиться на время обновления контроллеров.

Рекомендации по обновлению:

Всегда читайте релиз-ноты перед обновлением. Там часто указывают изменения API, поведения solvers и требования к Kubernetes.
Если вы обновляетесь через несколько мажорных версий, делайте поэтапные обновления и проверяйте состояние после каждого шага.
Для старых кластеров Kubernetes проверьте совместимость Cert-Manager с вашей версией API.

Руководство по эксплуатации и устранению проблем

Ниже — набор практических сценариев, чеклистов и плейбуков для DevOps/SRE, чтобы ускорить диагностику и восстановление.

Быстрая проверка состояния

kubectl get pods -n cert-manager
kubectl get clusterissuer
kubectl describe certificate -n
kubectl logs -n cert-manager deployment/cert-manager -c cert-manager
kubectl cert-manager check api

Типичные ошибки и как их исправлять

Ошибка валидации HTTP-01
- Проверьте, что Ingress действительно проксирует запросы на /.well-known/acme-challenge.
- Убедитесь, что DNS для домена указывает на IP балансировщика Ingress.
- Проверьте аннотацию ingress.class и соответствие контроллера.
Rate limit от Let’s Encrypt
- Используйте staging при тестировании.
- Проверьте, не запрашивали ли вы много разных сертификатов для одинаковых имён.
- Если упёрлись в лимиты, дождитесь сброса лимитов или используйте другой набор имён.
Нет доступа к API Cert-Manager
- Проверьте pod’ы в namespace cert-manager и их логи.
- Убедитесь, что CRD установлены корректно.
Секрет с сертификатом пустой или неправильный
- Откройте событие Certificate и Order: kubectl describe certificate/Order/Challenge.
- Проверьте, создан ли Secret и содержит ли ключи tls.crt и tls.key.

Плейбук при инциденте: сертификат истёк у живого сервиса

Быстрая проверка: kubectl describe certificate -n my-cert
Просмотрите логи cert-manager на предмет ошибок обновления.
Если автоматическое обновление не сработало, временно включите HTTP (если закрыт) или примените ручной сертификат в Secret.
Проверьте сетевые ACL, firewall и маршруты, которые могут блокировать HTTP-01 запросы.
Если проблема в Let’s Encrypt (rate limit), используйте временный доверенный сертификат от другого CA.
После восстановления повторно включите автоматическое управление и наблюдайте обновления.

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

Cert-Manager установлен и все pod’ы в состоянии Running в namespace cert-manager.
Создан ClusterIssuer для staging и production.
Для тестового домена успешно выдан сертификат от staging и затем от production.
TLS завершён и браузер показывает доверенный сертификат для production-домена.
Настроен мониторинг секретов и оповещения о проблемах с renew.

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

DNS-01 challenge
- Подойдёт, если HTTP-01 невозможен (например, внутренние сервисы или firewall).
- Позволяет получать wildcard-сертификаты.
- Требует управления DNS-записями через провайдера (DNS-провайдеры: Cloudflare, Route53, Gandi, и т.д.).
Внешние решения и интеграции
- External-DNS для автоматического создания DNS-записей.
- Ingress-контроллеры с поддержкой TLS и автоматическими интеграциями.
Управление секретами
- Для дополнительной безопасности храните приватные ключи в внешнем хранилище (например, HashiCorp Vault) и интегрируйте с Cert-Manager.

Ментальные модели и рекомендации

Cert-Manager — контроллер: он наблюдает за ресурсами (Ingress, Certificate) и действует по декларации.
Issuer/ClusterIssuer — «поставщик» сертификатов. ClusterIssuer — глобален, Issuer — локален.
Solvers — способы прохождения проверки (http01, dns01). Выбирайте по условиям сети и безопасности.

Роль‑ориентированные чеклисты

Для DevOps

Установить Cert-Manager через Helm.
Создать staging ClusterIssuer.
Протестировать выдачу сертификата через Ingress.
Настроить мониторинг и уведомления о сроках действия.

Для SRE

Подготовить план отката обновлений Cert-Manager.
Проверять совместимость мажорных версий с текущим Kubernetes.
Настроить runbooks для инцидентов с выдачей сертификатов.

Для разработчиков

Проверьте, что приложение слушает нужные пути и отвечает 200 на /.well-known/acme-challenge при необходимости.
Уточните у инфраструктуры требования к ingress.class.

Безопасность и конфиденциальность

Приватные ключи сертификатов хранятся в Kubernetes Secret. Ограничьте доступ к namespace и RBAC.
Для повышенной безопасности используйте внешнее хранилище секретов (Vault, KMS).
Убедитесь, что email в ACME-конфиге — контролируемый адрес, чтобы получать уведомления от CA.
При обработке личных данных убедитесь, что выбранный DNS-провайдер и способ хранения соответствуют требованиям конфиденциальности (GDPR/локальное законодательство).

Совместимость и миграция

Проверяйте таблицу совместимости Cert-Manager в релиз-нотах при обновлении Kubernetes.
Для крупных миграций делайте поэтапные обновления и тестируйте выдачу сертификатов в staging.

Факто-бокс: ключевые понятия

Helm — менеджер пакетов для Kubernetes.
Issuer/ClusterIssuer — ресурсы Cert-Manager для выдачи сертификатов.
HTTP-01 и DNS-01 — два основных способа проверки владения доменом.
Staging — тестовый ACME-сервер Let’s Encrypt; не доверяется браузерами.

Тестовые сценарии и критерии приёмки

Интеграция staging
- Применить issuer.yml.
- Применить тестовый Ingress.
- Ожидать создание Secret с tls.crt и tls.key.
Переход в production
- Создать production ClusterIssuer.
- Обновить Ingress на production-issuer.
- Проверить доверенный сертификат в браузере.
Повторное обновление Cert-Manager
- Обновить Helm chart на тестовом кластере.
- Проверить работу renew после обновления.

Глоссарий (в одну строку)

ACME — протокол для автоматического получения сертификатов от CA.
CRD — расширение API Kubernetes (Custom Resource Definition).
Issuer — namespaced поставщик сертификатов.
ClusterIssuer — глобальный поставщик сертификатов.
HTTP-01/DNS-01 — типы ACME-проверок владения доменом.

Социальный превью и анонс

OG title: Cert-Manager и Let’s Encrypt в Kubernetes OG description: Установка, настройка ClusterIssuer, выпуск сертификатов через Ingress и лучшие практики для production.

Короткий анонс (100–200 слов): Cert-Manager упрощает выпуск и управление TLS-сертификатами в Kubernetes. В этом пошаговом руководстве показано, как установить Cert-Manager через Helm, добавить kubectl-плагин, создать ClusterIssuer для Let’s Encrypt staging и production, а также привязать сертификаты к Ingress. Приведены готовые YAML-файлы, чеклисты для DevOps и SRE, рекомендации по безопасности, варианты DNS-01 для wildcard и подробный плейбук для восстановления в продакшене.

Краткое резюме

Устанавливайте Cert-Manager через Helm и используйте staging для тестов.
Создайте отдельные issuer для staging и production.
Для wildcard и внутренних зон рассмотрите DNS-01.
Настройте мониторинг секретов и оповещения.
Имея готовый плейбук и чеклисты, вы ускорите восстановление в инцидентах.

Важно: описанная конфигурация предполагает наличие работающего Ingress-контроллера (например, nginx-ingress) и корректно настроенного DNS. Если ваш сетевой маршрут или политика безопасности не позволяют публиковать HTTP-01 проверки, используйте DNS-01 или проконсультируйтесь с сетевой командой.