Certificats TLS avec cert-manager et Let's Encrypt

cert-manager obtient et renouvelle automatiquement les certificats TLS Let’s Encrypt pour toutes les applications du cluster Kaeyros. Cette page explique les deux ClusterIssuers disponibles, les cas d’usage de chacun, le mécanisme de validation, et comment diagnostiquer puis débloquer un certificat en attente.

Les deux émetteurs

ClusterIssuer	Type de validation	Quand l’utiliser
`letsencrypt-dns`	HTTP-01 via l’ingress Traefik	Cas courant : domaine accessible directement depuis Internet.
`letsencrypt-cloudflare`	DNS-01 via jeton d’API Cloudflare	Certificats génériques (wildcard), ou domaines dont la validation HTTP n’aboutit pas.

Le nom letsencrypt-dns est trompeur : il s’agit bien d’une validation HTTP-01, pas DNS-01. L’acme-challenge transite par l’ingress Traefik, pas par un enregistrement DNS.

Comment ça fonctionne

Le diagramme ci-dessous montre le déroulement d’une validation HTTP-01, le cas le plus fréquent sur la plateforme. Lorsque vous déployez un Ingress avec l’annotation cert-manager.io/cluster-issuer: letsencrypt-dns, cert-manager crée automatiquement un objet Order puis un Challenge. Un pod temporaire cm-acme-http-solver-* est lancé pour répondre au challenge sur le chemin /.well-known/acme-challenge/…. Une fois la validation réussie, Let’s Encrypt émet le certificat et cert-manager le stocke dans le secret Kubernetes référencé par spec.tls[].secretName.

Quand HTTP-01 échoue

La validation HTTP-01 exige que Let’s Encrypt puisse atteindre http://<votre-domaine>/.well-known/acme-challenge/… directement sur le serveur d’origine. Si le domaine est proxifié par Cloudflare (orange cloud activé), la validation échoue et le certificat n’est jamais émis. Dans ce cas, basculer sur letsencrypt-cloudflare.

Les cas typiques de blocage HTTP-01 incluent :

Domaine derrière le proxy Cloudflare avec l’orange cloud activé.
Redirection forcée qui empêche l’accès au chemin ACME.
Certificat générique (wildcard) de type *.exemple.com, qui nécessite obligatoirement une validation DNS-01.

Reconnaître un certificat en attente

Un certificat en attente se reconnaît à la présence durable de pods cm-acme-http-solver-* dans le namespace. Ces pods ne devraient exister que quelques minutes. S’ils persistent plus de 10 minutes, la validation est bloquée.

Commande rapide pour lister les soldeurs actifs :

kubectl get pods -A | grep cm-acme-http-solver

Débloquer un certificat

# Lister les certificats non prêts
kubectl get certificate -A | grep -v ' True '

# Voir les challenges et orders dans le namespace concerné
kubectl -n <ns> get challenge,order

# Lire le détail de l'erreur
kubectl -n <ns> describe challenge <nom>

# Dans le fichier de valeurs Helm de l'application,
# remplacez l'annotation de l'Ingress par :
# cert-manager.io/cluster-issuer: letsencrypt-cloudflare
#
# Puis synchronisez l'Application dans ArgoCD.

# Supprimer les challenges et orders bloqués
kubectl -n <ns> delete challenge --all
kubectl -n <ns> delete order --all

# cert-manager recréera automatiquement les objets
# au prochain cycle de réconciliation.

Convention des secrets TLS

Par convention, le champ spec.tls[].secretName d’un Ingress porte le nom d’hôte complet. Par exemple, un Ingress pour api.exemple.com référencera secretName: api.exemple.com. Cette convention facilite l’identification visuelle du secret dans les listes Kubernetes.

Exemple d’Ingress avec la convention appliquée :

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: mon-app
  annotations:
    cert-manager.io/cluster-issuer: letsencrypt-dns
spec:
  tls:
    - hosts:
        - api.exemple.com
      secretName: api.exemple.com
  rules:
    - host: api.exemple.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: mon-app-rollout-v2
                port:
                  number: 80

Si vous basculez d’un émetteur à l’autre, le secret TLS est remplacé automatiquement. Aucune action manuelle sur le secret n’est nécessaire. En cas de doute sur le choix de l’émetteur ou de blocage persistant, contactez l’équipe DevOps : devops@kaeyros-analytics.com.

Modèle GitOps

Anatomie d'une application

Les deux émetteurs

Comment ça fonctionne

Quand HTTP-01 échoue

Reconnaître un certificat en attente

Débloquer un certificat

Convention des secrets TLS

​Les deux émetteurs

​Comment ça fonctionne

​Quand HTTP-01 échoue

​Reconnaître un certificat en attente

​Débloquer un certificat

​Convention des secrets TLS

Les deux émetteurs

Comment ça fonctionne

Quand HTTP-01 échoue

Reconnaître un certificat en attente

Débloquer un certificat

Convention des secrets TLS