> ## Documentation Index
> Fetch the complete documentation index at: https://infra-docs.kaeyros.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Certificats TLS avec cert-manager et Let's Encrypt

> cert-manager obtient et renouvelle automatiquement les certificats Let's Encrypt. Découvrez les deux ClusterIssuers, quand utiliser chacun, et comment débloquer un certificat bloqué.

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

> [!WARNING]
>
> 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.

```mermaid theme={null}
sequenceDiagram
    autonumber
    participant Ingress
    participant CM as cert-manager
    participant LE as Let's Encrypt
    participant T as Traefik
    participant Solver as Pod cm-acme-http-solver

    Ingress->>CM: Annotation cert-manager.io/cluster-issuer: letsencrypt-dns
    CM->>LE: Crée un Order + Challenge
    CM->>Solver: Déploie un pod cm-acme-http-solver-*
    LE->>T: Requête GET /.well-known/acme-challenge/...
    T->>Solver: Route vers le pod solver
    Solver-->>LE: Réponse du challenge
    LE-->>CM: Validation réussie
    CM->>Ingress: Stocke le certificat TLS dans le secret
```

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

> [!WARNING]
>
> 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

> [!TIP]
>
> 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 :

```bash theme={null}
kubectl get pods -A | grep cm-acme-http-solver
```

## Débloquer un certificat

```bash Diagnostic theme={null}
# 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>
```

```bash Basculer vers Cloudflare theme={null}
# 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.
```

```bash Purger et repartir theme={null}
# 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

> [!NOTE]
>
> 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 :

```yaml theme={null}
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](mailto:devops@kaeyros-analytics.com).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.