How do I check the certificate status?

Как посмотреть состояние сертификата?

How do I get a list of certificates?

Как получить список сертификатов?

What types of certificates are supported?

Какие виды сертификатов поддерживаются?

Currently, the module supports the following two ClusterIssuers:

• letsencrypt
• letsencrypt-staging

На данный момент модуль устанавливает два ClusterIssuer’а:

• letsencrypt;
• letsencrypt-staging.

Does the legacy tls-acme annotation work?

Работает ли старая аннотация TLS-acme?

Yes, it works! The dedicated component (cert-manager-ingress-shim) automatically creates Certificate resources based on these annotations (in the same namespaces as those of Ingress resources with annotations).

Да, работает! Специальный компонент (cert-manager-ingress-shim) видит эти аннотации и на их основании автоматически создает ресурсы Certificate (в тех же namespace, что и Ingress-ресурсы с аннотациями).

Caution! The Certificate for a particular annotation is linked to the existing Ingress resource. The additional records are put into the existing Ingress resource instead of creating a separate one. Thus, the process will fail if authentication or whitelist is set for the primary Ingress. In this case, you shouldn’t use the annotation; use the Certificate instead.

Caution! If you switched to the Certificate instead of annotation, then you need to delete the annotation-based Certificate. Otherwise, the same Secret will be updated for both Certificates (this may lead to exceeding the Let’s Encrypt limits).

Важно! При использовании аннотации Certificate создается «прилинкованным» к существующему Ingress-ресурсу, и для прохождения Challenge НЕ создается отдельный Ingress, а вносятся дополнительные записи в существующий. Это означает, что если на основном Ingress’е настроена аутентификация или whitelist — ничего не выйдет. Лучше не использовать аннотацию и переходить на Certificate.

Важно! При переходе с аннотации на Certificate нужно удалить Certificate, который был создан по аннотации. Иначе по обоим Certificate будет обновляться один Secret, и это может привести к достижению лимита запросов Let’s Encrypt.

yaml apiVersion: networking.k8s.io/v1 kind: Ingress metadata: annotations: kubernetes.io/tls-acme: “true” # here is the annotation! 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 # the additional domain http: paths:
• backend: service: name: site port: number: 80 path: / pathType: ImplementationSpecific
• host: admin.example.com # another additional domain http: paths:
• backend: service: name: site port: number: 80 path: / pathType: ImplementationSpecific tls:
• hosts:
• example.com
• www.example.com # the additional domain
• admin.example.com # another additional domain secretName: example-com-tls # the name of the certificate & secret

yaml 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.

The “CAA record does not match issuer” error

Ошибка: CAA record does not match issuer

Suppose cert-manager gets the following error when trying to provide a certificate:

Если cert-manager не может заказать сертификаты с ошибкой:

In this case, you have to check the CAA (Certificate Authority Authorization) DNS record of the domain for which the certificate is intended. For Let’s Encrypt certificates, the domain must have the issue "letsencrypt.org" CAA record. You can read more about CAA here and here.

то необходимо проверить CAA (Certificate Authority Authorization) DNS-запись у домена, для которого заказывается сертификат. Если вы хотите использовать Let’s Encrypt-сертификаты, у домена должна быть CAA-запись: issue "letsencrypt.org". Подробнее про CAA можно почитать тут и тут.

Vault integration

Интеграция с Vault

You can use this manual for configuring certificate issuance using Vault.

Вы можете использовать данную инструкцию для выпуска сертификатов с помощью Vault.

After configuring PKI and enabling Kubernetes authorization, you have to:

• Create a service account and copy its secret reference:

После конфигурации PKI и включения авторизации в Kubernetes, вам нужно:

• Создать ServiceAccount и скопировать ссылку на его Secret:

• Create an Issuer:

• Создать Issuer:

shell kubectl apply -f - «EOF apiVersion: cert-manager.io/v1 kind: Issuer metadata: name: vault-issuer namespace: default spec: vault: HashiCorp instruction has mistype here server: http://vault.default.svc.cluster.local:8200 path: pki/sign/example-dot-com # configure in pki setup step auth: kubernetes: mountPath: /v1/auth/kubernetes role: issuer secretRef: name: $ISSUER_SECRET_REF key: token EOF

shell kubectl 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_SECRET_REF key: token EOF

• Create a Certificate resource, to get a TLS certificate, which is issued by Vault CA:

• Создать ресурс Certificate для получения TLS-сертификата подписанного Vault CA:

shell kubectl 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 domains are set on PKI setup commonName: www.example.com dnsNames:

• www.example.com EOF

shell kubectl 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

How do I use a custom or interim CA to issue certificates?

Как использовать свой или промежуточный CA для заказа сертификатов?

Follow the steps below to use a custom or interim CA:

Для использования собственного или промежуточного CA:

• Generate a certificate (if necessary):

• Сгенерируйте сертификат (при необходимости):

• In the d8-cert-manager namespace, create a secret containing certificate file data.

• В пространстве имён d8-cert-manager создайте секрет, содержащий данные файлов сертификатов.

An example of creating a secret with kubectl:

Пример создания секрета с помощью команды kubectl:

An example of creating a secret from a YAML file (the contents of the certificate files must be Base64-encoded):

Пример создания секрета из YAML-файла (содержимое файлов сертификатов должно быть закодировано в Base64):

yaml apiVersion: v1 data: tls.crt: <OUTPUT OF cat rootCACert.pem | base64 -w0> tls.key: <OUTPUT OF cat rootCAKey.pem | base64 -w0> kind: Secret metadata: name: internal-ca-key-pair namespace: d8-cert-manager type: Opaque

yaml 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

You can use any name you like for the secret.

Имя секрета может быть любым.

• Create a ClusterIssuer using the secret you created earlier:

• Создайте ClusterIssuer из созданного секрета:

yaml apiVersion: cert-manager.io/v1 kind: ClusterIssuer metadata: name: inter-ca spec: ca: secretName: internal-ca-key-pair # Name of the secret you created earlier.

yaml apiVersion: cert-manager.io/v1 kind: ClusterIssuer metadata: name: inter-ca spec: ca: secretName: internal-ca-key-pair # Имя созданного секрета.

You can use any name as your ClusterIssuer name.

Имя ClusterIssuer также может быть любым.

You can now use the created ClusterIssuer to issue certificates for all Deckhouse components or a particular component.

Теперь можно использовать созданный ClusterIssuer для получения сертификатов для всех компонентов Deckhouse или конкретного компонента.

For example, to issue certificates for all Deckhouse components, specify the ClusterIssuer name in the clusterIssuerName global parameter (kubectl edit mc global):

Например, чтобы использовать ClusterIssuer для получения сертификатов для всех компонентов Deckhouse, укажите его имя в глобальном параметре clusterIssuerName (kubectl edit mc global):

How to secure cert-manager credentials?

Как защитить учетные данные cert-manager?

If you don’t want to store credentials in the Deckhouse configuration (security reasons, for example), feel free to create your own ClusterIssuer / Issuer. For example, you can create your own ClusterIssuer for a route53 service in this way:

• Create a Secret with credentials:

Если вы не хотите хранить учетные данные конфигурации Deckhouse (например, по соображениям безопасности), можете создать свой собственный ClusterIssuer / Issuer. Например, вы можете создать свой ClusterIssuer для сервиса route53 следующим образом:

• Создайте Secret с учетными данными:

• Create a simple ClusterIssuer with reference to that secret:

• Создайте простой ClusterIssuer со ссылкой на этот Secret:

• Order certificates as usual, using created ClusterIssuer:

• Закажите сертификаты как обычно, используя созданный ClusterIssuer: