Стадия жизненного цикла модуля: General Availability
Какие виды сертификатов поддерживаются?
На данный момент модуль устанавливает следующие ClusterIssuer:
letsencryptletsencrypt-stagingselfsignedselfsigned-no-trust
Если требуется поддержка других типов сертификатов, вы можете добавить их самостоятельно.
Как добавить дополнительный ClusterIssuer?
В каких случаях требуется дополнительный ClusterIssuer?
В стандартной поставке присутствуют ClusterIssuer, издающие либо сертификаты из доверенного публичного удостоверяющего центра Let’s Encrypt, либо самоподписанные сертификаты.
Чтобы издать сертификаты на доменное имя через Let’s Encrypt, сервис требует осуществить подтверждение владения доменом.
Cert-manager поддерживает несколько методов для такого подтверждения при использовании ACME(Automated Certificate Management Environment):
HTTP-01—cert-managerсоздаст временный Pod в кластере, который будет слушать на определенном URL для подтверждения владения доменом. Для его работы необходимо иметь возможность направлять внешний трафик на этот Pod, обычно черезIngress.DNS-01—cert-managerделает TXT-запись в DNS для подтверждения владения доменом. Уcert-managerесть встроенная поддержка популярных провайдеров DNS: AWS Route53, Google Cloud DNS, Cloudflare и т.д. Полный перечень доступен в документации cert-manager.
Метод HTTP-01 не поддерживает выпуск wildcard-сертификатов.
Поставляемые ClusterIssuers, издающие сертификаты через Let’s Encrypt, делятся на два типа:
ClusterIssuer,специфичные для используемого облачного провайдера.
Добавляются автоматически, при заполнении настроек модуля связанных с облачным провайдером. Поддерживают методDNS-01.clouddnscloudflaredigitaloceanroute53
ClusterIssuerиспользующие методHTTP-01.
Добавляются автоматически, если их создание не отключено в настройках модуля.letsencryptletsencrypt-staging
Таким образом, дополнительный ClusterIssuer может потребоваться в случаях издания сертификатов:
- В удостоверяющем центре (УЦ), отличном от Let’s Encrypt (в т.ч. в приватном). Поддерживаемые УЦ доступны в документации
cert-manager - Через Let’s Encrypt с помощью метода
DNS-01через сторонний провайдер.
Как добавить дополнительный ClusterIssuer, использующий Let’s Encrypt и метод подтверждения DNS-01?
Для подтверждения владения доменом через Let’s Encrypt с помощью метода DNS-01 требуется настроить возможность создания TXT-записей в публичном DNS.
У cert-manager есть поддержка механизмов для создания TXT-записей в некоторых популярных DNS: AzureDNS, Cloudflare, Google Cloud DNS и т.д.
Полный перечень доступен в документации cert-manager.
Модуль автоматически создает ClusterIssuer поддерживаемых облачных провайдеров, при заполнении настроек модуля связанных с используемым облаком.
При необходимости можно создать такие ClusterIssuer самостоятельно.
Пример использования AWS Route53 доступен в разделе Как защитить учетные данные cert-manager.
Актуальный перечень всех возможных для создания ClusterIssuer доступен в шаблонах модуля.
Встроенные провайдеры, настраиваемые через параметры модуля: Cloudflare, Amazon Route53, DigitalOcean, Google Cloud DNS и Yandex Cloud DNS. Порядок настройки Yandex Cloud DNS описан в разделе Заказ wildcard-сертификата с DNS в Yandex Cloud DNS.
Использование других сторонних DNS-провайдеров реализуется через метод webhook.
Когда cert-manager выполняет вызов ACME DNS-01, он отправляет запрос на вебхук-сервер, который затем выполняет нужные операции для обновления записи DNS.
При использовании данного метода требуется разместить сервис, который будет обрабатывать хук и осуществлять создание TXT-записи в DNS-провайдере, а затем создать ClusterIssuer с настройками dns01.webhook согласно документации вебхука.
Как добавить дополнительный Issuer и ClusterIssuer, использующий HashiCorp Vault для выпуска сертификатов?
Для выпуска сертификатов с помощью HashiCorp Vault, можете использовать инструкцию.
После конфигурации PKI и включения авторизации в Kubernetes выполните следующие шаги:
-
Создайте
ServiceAccount:d8 k create serviceaccount issuer -
Создайте
Secretс токеном для этой учётной записи. Начиная с Kubernetes 1.24, секрет дляServiceAccountне создаётся автоматически:d8 k apply -f - <<EOF apiVersion: v1 kind: Secret metadata: name: issuer annotations: kubernetes.io/service-account.name: issuer type: kubernetes.io/service-account-token EOF -
Создайте
Issuer:d8 k apply -f - <<EOF apiVersion: cert-manager.io/v1 kind: Issuer metadata: name: vault-issuer namespace: default spec: vault: # Если Vault разворачивался по вышеуказанной инструкции, в этом месте в инструкции опечатка. server: http://vault.default.svc.cluster.local:8200 # Указывается на этапе конфигурации PKI. path: pki/sign/example-dot-com auth: kubernetes: mountPath: /v1/auth/kubernetes role: issuer secretRef: name: issuer key: token EOF -
Создать ресурс
Certificateдля получения TLS-сертификата, подписанного CA Vault:d8 k apply -f - <<EOF apiVersion: cert-manager.io/v1 kind: Certificate metadata: name: example-com namespace: default spec: secretName: example-com-tls issuerRef: name: vault-issuer # Домены указываются на этапе конфигурации PKI в Vault. commonName: www.example.com dnsNames: - www.example.com EOF
Как добавить ClusterIssuer, использующий свой или промежуточный CA для заказа сертификатов?
Для использования собственного или промежуточного CA:
-
Сгенерируйте сертификат (при необходимости):
openssl ecparam -name prime256v1 -genkey -out rootCAKey.pem openssl req -x509 -sha256 -new -nodes -key rootCAKey.pem -days 3650 -out rootCACert.pem -
В пространстве имён
d8-cert-managerсоздайте секрет, содержащий данные файлов сертификатов. Пример создания секрета с помощью команды d8 k:d8 k create secret tls internal-ca-key-pair -n d8-cert-manager --key="rootCAKey.pem" --cert="rootCACert.pem"Пример создания секрета из YAML-файла (содержимое файлов сертификатов должно быть закодировано в Base64):
apiVersion: v1 data: tls.crt: <результат команды `cat rootCACert.pem | base64 -w0`> tls.key: <результат команды `cat rootCAKey.pem | base64 -w0`> kind: Secret metadata: name: internal-ca-key-pair namespace: d8-cert-manager type: OpaqueИмя секрета может быть любым.
-
Создайте
ClusterIssuerиз созданного секрета:apiVersion: cert-manager.io/v1 kind: ClusterIssuer metadata: name: inter-ca spec: ca: secretName: internal-ca-key-pair # Имя созданного секрета.Имя
ClusterIssuerтакже может быть любым.
Теперь можно использовать созданный ClusterIssuer для получения сертификатов для всех компонентов Deckhouse или конкретного компонента.
Например, чтобы использовать ClusterIssuer для получения сертификатов для всех компонентов Deckhouse, укажите его имя в глобальном параметре clusterIssuerName (d8 k edit mc global):
spec:
settings:
modules:
https:
certManager:
clusterIssuerName: inter-ca
mode: CertManager
publicDomainTemplate: '%s.<public_domain_template>'
version: 1
Как cert-manager работает через прокси-сервер?
cert-manager использует прокси-сервер кластера,
заданный в параметре proxy
ресурса ClusterConfiguration.
Настройки прокси передаются контроллеру cert-manager и вебхуку Yandex Cloud DNS.
Запросы к ACME-серверу, HashiCorp Vault и HTTP API DNS-провайдеров идут через прокси-сервер.
Напрямую идут следующие запросы:
- запросы к домену кластера, подсетям подов и сервисов;
- запросы контроллера к именам сервисов вида
<SERVICE>.<NAMESPACE>.svc; - запросы к адресам из
noProxy.
Адреса узлов и короткие имена сервисов вида <SERVICE>.<NAMESPACE> в этот список не входят.
Чтобы обращаться к Issuer в кластере напрямую, указывайте полное имя <SERVICE>.<NAMESPACE>.svc.
Чтобы обращаться напрямую к удостоверяющему центру во внутренней сети, добавьте его адрес в noProxy.
Учитывайте, что noProxy действует также на остальные компоненты кластера и на узлы.
Перед проверкой DNS-01 контроллер проверяет TXT-запись по протоколу DNS,
который прокси-сервер не передаёт.
Если у кластера нет прямого доступа к внешним DNS-серверам,
задайте DNS через HTTPS в параметре recursiveSettings:
apiVersion: deckhouse.io/v1alpha1
kind: ModuleConfig
metadata:
name: cert-manager
spec:
version: 1
settings:
recursiveSettings:
nameservers: ["https://1.1.1.1/dns-query"]
useOnlyRecursive: true
С параметром useOnlyRecursive: true контроллер отправляет проверки только на указанные серверы,
а запросы DNS через HTTPS идут через прокси-сервер.
Подойдёт и DNS-сервер внутренней сети, который разрешает внешние имена: укажите его в формате IP:port.
Перед проверкой HTTP-01 контроллер также запрашивает адрес проверки домена через прокси-сервер.
Если прокси-сервер не может обратиться к публичному адресу кластера, добавьте домен в noProxy.
Как защитить учетные данные cert-manager?
Если вы не хотите хранить учетные данные конфигурации Deckhouse (например, по соображениям безопасности), можете создать
свой собственный ClusterIssuer / Issuer.
Пример создания собственного ClusterIssuer для сервиса route53:
-
Создайте Secret с учетными данными:
d8 k apply -f - <<EOF apiVersion: v1 kind: Secret type: Opaque metadata: name: route53 namespace: default data: secret-access-key: MY-AWS-ACCESS-KEY-TOKEN EOF -
Создайте простой
ClusterIssuerсо ссылкой на этот Secret:d8 k apply -f - <<EOF apiVersion: cert-manager.io/v1 kind: ClusterIssuer metadata: name: route53 namespace: default spec: acme: server: https://acme-v02.api.letsencrypt.org/directory privateKeySecretRef: name: route53-tls-key solvers: - dns01: route53: region: us-east-1 accessKeyID: MY-AWS-ACCESS-KEY-ID secretAccessKeySecretRef: name: route53 key: secret-access-key EOF -
Закажите сертификаты как обычно, используя созданный
ClusterIssuer:d8 k apply -f - <<EOF apiVersion: cert-manager.io/v1 kind: Certificate metadata: name: example-com namespace: default spec: secretName: example-com-tls issuerRef: name: route53 commonName: www.example.com dnsNames: - www.example.com EOF
Работает ли аннотация TLS-acme?
Да, работает. Специальный компонент cert-manager-ingress-shim видит эти аннотации и на их основании автоматически создает ресурсы Certificate (в тех же namespaces, что и Ingress-ресурсы с аннотациями).
При использовании аннотации ресурс Certificate создаётся «прилинкованным» к существующему Ingress-ресурсу, и для прохождения Challenge не создаётся отдельный Ingress, а вносятся дополнительные записи в существующий. Это означает, что если на основном Ingress’е настроена аутентификация или whitelist — ничего не выйдет. Лучше не использовать аннотацию и переходить на ресурс Certificate.
При переходе с аннотации на ресурс Certificate удалите ресурс Certificate, который был создан по аннотации. Иначе по обоим ресурсам Certificate будет обновляться один Secret, и это может привести к достижению лимита запросов Let’s Encrypt.
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
annotations:
kubernetes.io/tls-acme: "true" # Аннотация.
name: example-com
namespace: default
spec:
ingressClassName: nginx
rules:
- host: example.com
http:
paths:
- backend:
service:
name: site
port:
number: 80
path: /
pathType: ImplementationSpecific
- host: www.example.com # Дополнительный домен.
http:
paths:
- backend:
service:
name: site
port:
number: 80
path: /
pathType: ImplementationSpecific
- host: admin.example.com # Еще один дополнительный домен.
http:
paths:
- backend:
service:
name: site
port:
number: 80
path: /
pathType: ImplementationSpecific
tls:
- hosts:
- example.com
- www.example.com # Дополнительный домен.
- admin.example.com # Еще один дополнительный домен.
secretName: example-com-tls # Имя для Certificate и Secret.
Как посмотреть состояние сертификата?
d8 k -n default describe certificate example-com
...
Status:
Acme:
Authorizations:
Account: https://acme-v01.api.letsencrypt.org/acme/reg/22442061
Domain: example.com
Uri: https://acme-v01.api.letsencrypt.org/acme/challenge/qJA9MGCZnUnVjAgxhoxONvDnKAsPatRILJ4n0lJ7MMY/4062050823
Account: https://acme-v01.api.letsencrypt.org/acme/reg/22442061
Domain: admin.example.com
Uri: https://acme-v01.api.letsencrypt.org/acme/challenge/pW2tFKLBDTll2Gx8UBqmEl846x5W-YpBs8a4HqstJK8/4062050808
Account: https://acme-v01.api.letsencrypt.org/acme/reg/22442061
Domain: www.example.com
Uri: https://acme-v01.api.letsencrypt.org/acme/challenge/LaZJMM9_OKcTYbEThjT3oLtwgpkNfbHVdl8Dz-yypx8/4062050792
Conditions:
Last Transition Time: 2018-04-02T18:01:04Z
Message: Certificate issued successfully
Reason: CertIssueSuccess
Status: True
Type: Ready
Events:
Type Reason Age From Message
---- ------ ---- ---- -------
Normal PrepareCertificate 1m cert-manager-controller Preparing certificate with issuer
Normal PresentChallenge 1m cert-manager-controller Presenting http-01 challenge for domain example.com
Normal PresentChallenge 1m cert-manager-controller Presenting http-01 challenge for domain www.example.com
Normal PresentChallenge 1m cert-manager-controller Presenting http-01 challenge for domain admin.example.com
Normal SelfCheck 1m cert-manager-controller Performing self-check for domain admin.example.com
Normal SelfCheck 1m cert-manager-controller Performing self-check for domain example.com
Normal SelfCheck 1m cert-manager-controller Performing self-check for domain www.example.com
Normal ObtainAuthorization 55s cert-manager-controller Obtained authorization for domain example.com
Normal ObtainAuthorization 54s cert-manager-controller Obtained authorization for domain admin.example.com
Normal ObtainAuthorization 53s cert-manager-controller Obtained authorization for domain www.example.com
Как получить список сертификатов?
d8 k get certificate --all-namespaces
NAMESPACE NAME AGE
default example-com 13m
Что делать, если появляется ошибка: CAA record does not match issuer?
Если cert-manager не может заказать сертификаты с ошибкой:
CAA record does not match issuer
то необходимо проверить CAA (Certificate Authority Authorization) DNS-запись у домена, для которого заказывается сертификат.
Если вы хотите использовать Let’s Encrypt-сертификаты, у домена должна быть CAA-запись: issue "letsencrypt.org".
Подробнее про CAA можно почитать в документации Let’s Encrypt.
Что делать, если самопроверка HTTP-01 не завершается?
Перед тем как попросить Let’s Encrypt проверить Challenge HTTP-01,
cert-manager запрашивает URL проверки для домена изнутри кластера.
Если кластер не может обратиться к своему публичному адресу, эта самопроверка не проходит,
и Challenge остаётся в ожидании, хотя Let’s Encrypt смог бы его проверить.
Так бывает, например, из-за NAT без hairpinning (когда изнутри кластера нельзя обратиться к своему внешнему IP) или при split-horizon DNS (когда один и тот же домен резолвится в разные IP-адреса в зависимости от того, откуда пришёл DNS-запрос: изнутри кластера или снаружи).
В этом случае Challenge сообщает об ошибке самопроверки. Чтобы её посмотреть, выполните команду:
d8 k -n <NAMESPACE> describe challenges.acme.cert-manager.io
Чтобы пропустить самопроверку для ClusterIssuer letsencrypt и letsencrypt-staging,
задайте параметр http01WaitInsteadOfSelfCheck.
Следующий ModuleConfig заставляет cert-manager ждать 30 секунд вместо самопроверки:
apiVersion: deckhouse.io/v1alpha1
kind: ModuleConfig
metadata:
name: cert-manager
spec:
version: 1
settings:
http01WaitInsteadOfSelfCheck: 30s
После обновления ClusterIssuer новый Challenge больше не ждёт успешного завершения самопроверки. cert-manager просит Let’s Encrypt проверить его через 30 секунд после публикации.
Используйте параметр, только если домен доступен из интернета. Иначе каждая попытка проверки завершится ошибкой на стороне Let’s Encrypt и будет учитываться в его ограничениях на количество запросов.