Cert-manager#

Cert-manager - менеджер сертификатов DropApp. Cert-manager добавляет сертификаты и эмитенты сертификатов в качестве типов ресурсов в кластеры DropApp и упрощает процесс получения, обновления и использования этих сертификатов.

Cert-manager настраивается на выдачу сертификатов из различных поддерживаемых источников, включая Let’s Encrypt, HashiCorp Vault и Venafi, а также частные PKI.

Cert-manager поддерживает сертификаты в действительном и актуальном состоянии, выполняет обновление сертификатов в настроенное время до истечения срока их действия.

Источники сертификатов определяют, как Cert-manager будет запрашивать сертификаты TLS 1.2. По умолчанию источники сертификатов специфичны для каждого namespace DropApp. Добавьте флаг -n my-namespace к командам kubectl create, чтобы указать namespace, в котором должны быть созданы ресурсы. Также возможно заменить Issuers на ClusterIssuers. Ресурсы ClusterIssuer применяются ко всем ресурсам Ingress в кластере DropApp. Обновите аннотацию Ingress cert-manager.io/issuer до cert-manager.io/cluster-issuer.

Cert-manager предоставляет следующие инструменты:

  • cert-manager-acmesolver - компонент, который взаимодействует с ACME-серверами для автоматического получения сертификатов. Использует протокол ACME для связи с серверами, такими как Let’s Encrypt;

  • cert-manager-cainjector - компонент, который автоматически добавляет сертификаты в контейнеры приложений. Внедряет их, чтобы использовать HTTPS для связи друг с другом;

  • cert-manager-controller - компонент, который управляет жизненным циклом сертификатов в DropApp. Отслеживает состояние и автоматически обновляет их;

  • cert-manager-ctl - утилита командной строки, которая позволяет управлять сертификатами и компонентами Cert-manager из командной строки. Предоставляет различные команды для создания, обновления и удаления сертификатов;

  • cert-manager-webhook - компонент, который обрабатывает запросы на создание и обновление сертификатов. Проверяет запросы на соответствие правилам и политикам, установленным для сертификатов.

Эти компоненты работают вместе, чтобы обеспечить автоматическое управление сертификатами в DropApp с помощью Cert-manager.

Установка Cert-manager#

Для выполнения данного сценария необходимы права администратора.

  1. Установите все компоненты Cert-manager:

    kubectl apply -f https://<repoexample.ru>/cert-manager/cert-manager/releases/download/v1.14.4/cert-manager.yaml
# Укажите актуальный путь до локального репозитория

    По умолчанию Cert-manager будет установлен в namespace cert-manager.

    Можно запустить Cert-manager в другом namespace, для этого потребуется внести изменения в манифесты развертывания.

  2. Убедитесь, что Cert-manager развернут правильно. Проверьте список запущенных pods в namespace:

    kubectl get pods --namespace cert-manager

    В namespace cert-manager будут созданы следующие ресурсы:

    NAME                                       READY   STATUS    RESTARTS   AGE
cert-manager-5c6866597-zw7kh               1/1     Running   0          2m
cert-manager-cainjector-577f6d9fd7-tr77l   1/1     Running   0          2m
cert-manager-webhook-787858fcdb-nlzsq      1/1     Running   0          2m

Сценарий использования Cert-manager#

Настройка эмитента Let’s Encrypt#

В сценарии приведены настройки двух эмитентов для Let’s Encrypt: промежуточный и рабочий.

Примечание

Промежуточный эмитент приведен для целей тестирования. Сертификат промежуточного издателя не надежен.

  1. Создайте локально файл staging-issuer.yaml следующего содержания:

    apiVersion: cert-manager.io/v1
kind: Issuer
metadata:
  name: letsencrypt-staging
spec:
  acme:
    # URL-адрес сервера ACME
    server: https://acme-staging-v02.api.letsencrypt.org/directory
    # Адрес электронной почты, используемый для регистрации ACME
    email: user@example.com
    # Имя secret, используемого для хранения закрытого ключа учетной записи ACME
    privateKeySecretRef:
      name: letsencrypt-staging
    # Включить поставщика вызовов HTTP-01
    solvers:
      - http01:
          ingress:
            ingressClassName: nginx

  2. Примените пользовательский ресурс:

    kubectl create --edit -f https://<repoexample.ru>/cert-manager/website/master/content/docs/tutorials/acme/example/staging-issuer.yaml
# Укажите актуальный путь до локального репозитория

    В результате будет создан ресурс letsencrypt-staging.

  3. Создайте локальный файл production-issuer.yaml следующего содержания:

    apiVersion: cert-manager.io/v1
    kind: Issuer
metadata:
    name: letsencrypt-prod
    spec:
    acme:
        # URL-адрес сервера ACME
        server: https://acme-v02.api.letsencrypt.org/directory
    # Адрес электронной почты, используемый для регистрации ACME
    email: user@example.com
    email: user@example.com
    # Имя secret, используемого для хранения закрытого ключа учетной записи ACME
    privateKeySecretRef:
        name: letsencrypt-prod
# Включить поставщика вызовов HTTP-01
solvers:
    - http01:
ingress:
    ingressClassName: nginx

  4. Примените пользовательский ресурс:

    kubectl create --edit -f https://<repoexample.ru>/cert-manager/website/master/content/docs/tutorials/acme/example/staging-issuer.yaml
# Укажите актуальный путь до локального репозитория

    В результате будет создан ресурс letsencrypt-prod.

  5. Проверьте статус эмитента после его создания:

    kubectl describe issuer letsencrypt-staging
Name:         letsencrypt-staging
Namespace:    default
Labels:       <none>
Annotations:  kubectl.kubernetes.io/last-applied-configuration={"apiVersion":"cert-manager.io/v1","kind":"Issuer","metadata":{"annotations":{},"name":"letsencrypt-staging","namespace":"default"},(...)}
API Version:  cert-manager.io/v1
Kind:         Issuer
Metadata:
  Cluster Name:
  Creation Timestamp:  2018-11-17T18:03:54Z
  Generation:          0
  Resource Version:    9092
  Self Link:           /apis/cert-manager.io/v1/namespaces/default/issuers/letsencrypt-staging
  UID:                 <UID>
Spec:
  Acme:
    Email:  email@example.com
    Private Key Secret Ref:
      Key:
      Name:  letsencrypt-staging
    Server:  https://acme-staging-v02.api.letsencrypt.org/directory
    Solvers:
      Http 01:
        Ingress:
          Class:  nginx
Status:
  Acme:
    Uri:  https://acme-staging-v02.api.letsencrypt.org/acme/acct/7374163
  Conditions:
    Last Transition Time:  2018-11-17T18:04:00Z
    Message:               The ACME account was registered with the ACME server
    Reason:                ACMEAccountRegistered
    Status:                True
    Type:                  Ready
Events:                    <none>

  6. Добавьте аннотации, которые были закомментированы в шагах 1 и 3:

    apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: kuard
  annotations:
    cert-manager.io/issuer: "letsencrypt-staging"
spec:
  ingressClassName: nginx
  tls:
  - hosts:
    - example.example.com
    secretName: quickstart-example-tls
  rules:
  - host: example.example.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: kuard
            port:
              number: 80

  7. Разверните аннотацию, введите команду:

    kubectl create --edit -f https://<repoexample.ru>/cert-manager/website/master/content/docs/tutorials/acme/example/ingress-tls.yaml
# Укажите актуальный путь до локального репозитория

    Cert-manager прочитает аннотации и использует их для создания сертификата.

  8. Введите команду, чтобы запросить сертификат:

    kubectl get certificate
NAME                     READY   SECRET                   AGE
quickstart-example-tls   True    quickstart-example-tls   16m

  9. Запросите информацию о сертификате, введите команду:

    kubectl describe certificate quickstart-example-tls

    Вывод отобразит следующее:

    Name:         quickstart-example-tls
Namespace:    default
Labels:       <none>
Annotations:  <none>
API Version:  cert-manager.io/v1
Kind:         Certificate
Metadata:
  Cluster Name:
  Creation Timestamp:  2023-11-17T17:58:37Z
  Generation:          0
  Owner References:
    API Version:           networking.k8s.io/v1
    Block Owner Deletion:  true
    Controller:            true
    Kind:                  Ingress
    Name:                  kuard
    UID:                   <UID>
  Resource Version:        9295
  Self Link:               /apis/cert-manager.io/v1/namespaces/default/certificates/quickstart-example-tls
  UID:                     <UID>
Spec:
  Dns Names:
    www.example.com
  Issuer Ref:
    Kind:       Issuer
    Name:       letsencrypt-staging
  Secret Name:  quickstart-example-tls
Status:
  Acme:
    Order:
      URL:  https://acme-staging-v02.api.letsencrypt.org/acme/order/7374163/1333676
  Conditions:
    Last Transition Time:  2023-11-17T18:05:57Z
    Message:               Certificate issued successfully
    Reason:                CertIssued
    Status:                True
    Type:                  Ready
Events:

  Type     Reason          Age                From          Message
  ----     ------          ----               ----          -------
  Normal   CreateOrder     9m                 cert-manager  Created new ACME order, attempting validation...
  Normal   DomainVerified  8m                 cert-manager  Domain "www.example.com" verified with "http-01" validation
  Normal   IssueCert       8m                 cert-manager  Issuing certificate...
  Normal   CertObtained    7m                 cert-manager  Obtained certificate from ACME server
  Normal   CertIssued      7m                 cert-manager  Certificate issued Successfully

    События, связанные с этим ресурсом и перечисленные в нижней части результатов describe, показывают состояние запроса. В приведенном примере сертификат был проверен и выдан в течение нескольких минут.

    После завершения Cert-manager создаст secret с деталями сертификата, используемого в ресурсе Ingress.

  10. Введите флаг desckribe в инструменте kubectl для получения детальной информации:

    kubectl describe secret quickstart-example-tls

    Вывод отобразит следующее:

    Name:         quickstart-example-tls
Namespace:    default
Labels:       cert-manager.io/certificate-name=quickstart-example-tls
Annotations:  cert-manager.io/alt-names=www.example.com
              cert-manager.io/common-name=www.example.com
              cert-manager.io/issuer-kind=Issuer
              cert-manager.io/issuer-name=letsencrypt-staging

Type:  DropApp.io/tls

Data
====
tls.crt:  3566 bytes
tls.key:  1675 bytes

  11. Обновите аннотации Ingress для указания эмитента letsencrypt-prod:

    apiVersion: networking.k8s.io/v1 
kind: Ingress
metadata:
  name: kuard
  annotations:
    cert-manager.io/issuer: "letsencrypt-prod"

spec:
  ingressClassName: nginx
  tls:
  - hosts:
    - example.example.com
    secretName: quickstart-example-tls
  rules:
  - host: example.example.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: kuard
            port:
              number: 80

  12. Примените аннотацию Ingress:

    kubectl create --edit -f https://<repoexample.ru>/cert-manager/website/master/content/docs/tutorials/acme/example/ingress-tls-final.yaml
ingress.networking.k8s.io/kuard configured
# Укажите актуальный путь до локального репозитория

  13. Удалите существующий secret, который отслеживается Cert-manager,

    kubectl delete secret quickstart-example-tls
secret "quickstart-example-tls" deleted

    В результате запрос будет обработан с обновленным эмитентом.

  14. Проверьте статус процесса получения нового сертификата:

    kubectl describe certificate quickstart-example-tls
Name:         quickstart-example-tls
Namespace:    default
Labels:       <none>
Annotations:  <none>
API Version:  cert-manager.io/v1
Kind:         Certificate
Metadata:
  Cluster Name:
  Creation Timestamp:  2018-11-17T18:36:48Z
  Generation:          0
  Owner References:
    API Version:           networking.k8s.io/v1
    Block Owner Deletion:  true
    Controller:            true
    Kind:                  Ingress
    Name:                  kuard
    UID:                   <UID>
  Resource Version:        283686
  Self Link:               /apis/cert-manager.io/v1/namespaces/default/certificates/quickstart-example-tls
  UID:                     <UID>
Spec:
  Dns Names:
    www.example.com
  Issuer Ref:
    Kind:       Issuer
    Name:       letsencrypt-prod
  Secret Name:  quickstart-example-tls
Status:
  Conditions:
    Last Transition Time:  2019-01-09T13:52:05Z
    Message:               Certificate does not exist
    Reason:                NotFound
    Status:                False
    Type:                  Ready
Events:
  Type    Reason        Age   From          Message
  ----    ------        ----  ----          -------
  Normal  Generated     18s   cert-manager  Generated new private key
  Normal  OrderCreated  18s   cert-manager  Created Order resource "quickstart-example-tls-889745041"

    Вывод должен содержать KUARD, работающий в домене с подписанным сертификатом TLS 1.2.

  15. Запросите текущее состояние ACME, запустите команду kubectl describe Cert-manager:

    kubectl describe order quickstart-example-tls-889745041
...
Events:
Type    Reason      Age   From          Message
----    ------      ----  ----          -------
Normal  Created     90s   cert-manager  Created Challenge resource "quickstart-example-tls-889745041-0" for domain "www.example.com"

    В приведенном примере Cert-manager успешно создал ресурс.

  16. Изучите состояние текущей задачи ACME, запустите команду:

    kubectl describe challenge quickstart-example-tls-889745041-0
...
Status:
  Presented:   false
  Processing:  false
  Reason:      Successfully authorized domain
  State:       valid
Events:
  Type    Reason          Age   From          Message
  ----    ------          ----  ----          -------
  Normal  Started         71s   cert-manager  Challenge scheduled for processing
  Normal  Presented       70s   cert-manager  Presented challenge using http-01 challenge mechanism
  Normal  DomainVerified  2s    cert-manager  Domain "www.example.com" verified with "http-01" validation

    В результате выполнения команды в приведенном примере соответствующие ресурсы удалены, а ресурс order был обновлен.

  17. Отследите состояние order:

    kubectl describe order quickstart-example-tls-889745041
...
Events:
  Type    Reason      Age   From          Message
  ----    ------      ----  ----          -------
  Normal  Created     90s   cert-manager  Created Challenge resource "quickstart-example-tls-889745041-0" for domain "www.example.com"
  Normal  OrderValid  16s   cert-manager  Order completed successfully

  18. Убедитесь в обновлении сертификата, введите команду:

    kubectl describe certificate quickstart-example-tls
Status:
  Conditions:
    Last Transition Time:  2023-01-09T13:57:52Z
    Message:               Certificate is up to date and has not expired
    Reason:                Ready
    Status:                True
    Type:                  Ready
  Not After:               2023-04-09T12:57:50Z
Events:
  Type    Reason         Age                  From          Message
  ----    ------         ----                 ----          -------
  Normal  Generated      11m                  cert-manager  Generated new private key
  Normal  OrderCreated   11m                  cert-manager  Created Order resource "quickstart-example-tls-889745041"
  Normal  OrderComplete  10m                  cert-manager  Order "quickstart-example-tls-889745041" completed successfull

    В приведенном примере сертификат был успешно обновлен.