update doc
This commit is contained in:
@@ -1,226 +0,0 @@
|
|||||||
# Configuration Let's Encrypt avec cert-manager
|
|
||||||
|
|
||||||
Ce document explique comment générer et utiliser des certificats Let's Encrypt avec cert-manager dans votre cluster Kubernetes.
|
|
||||||
|
|
||||||
## Architecture
|
|
||||||
|
|
||||||
- **cert-manager** : Opérateur Kubernetes qui gère automatiquement les certificats TLS
|
|
||||||
- **ClusterIssuer** : Ressource qui définit comment obtenir des certificats (Let's Encrypt Production ou Staging)
|
|
||||||
- **Certificate** : Ressource Kubernetes qui demande un certificat pour un domaine spécifique
|
|
||||||
- **Traefik** : Ingress Controller qui utilise les certificats générés
|
|
||||||
|
|
||||||
## Installation
|
|
||||||
|
|
||||||
### 1. Déployer cert-manager
|
|
||||||
|
|
||||||
cert-manager est déployé via ArgoCD via l'ApplicationSet `cert-manager-apps`.
|
|
||||||
|
|
||||||
Le chart inclut :
|
|
||||||
- cert-manager (controller, webhook, cainjector)
|
|
||||||
- ClusterIssuer pour Let's Encrypt Production (`letsencrypt-prod`)
|
|
||||||
- ClusterIssuer pour Let's Encrypt Staging (`letsencrypt-staging`)
|
|
||||||
|
|
||||||
### 2. Vérifier l'installation
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Vérifier que cert-manager est déployé
|
|
||||||
kubectl get pods -n cert-manager
|
|
||||||
|
|
||||||
# Vérifier les ClusterIssuers
|
|
||||||
kubectl get clusterissuers
|
|
||||||
|
|
||||||
# Vérifier le statut d'un ClusterIssuer
|
|
||||||
kubectl describe clusterissuer letsencrypt-prod
|
|
||||||
```
|
|
||||||
|
|
||||||
## Configuration
|
|
||||||
|
|
||||||
### ClusterIssuers
|
|
||||||
|
|
||||||
Deux ClusterIssuers sont créés :
|
|
||||||
|
|
||||||
1. **letsencrypt-prod** : Pour les certificats de production
|
|
||||||
- Serveur : `https://acme-v02.api.letsencrypt.org/directory`
|
|
||||||
- Limite de taux : 50 certificats par semaine par domaine
|
|
||||||
|
|
||||||
2. **letsencrypt-staging** : Pour les tests
|
|
||||||
- Serveur : `https://acme-staging-v02.api.letsencrypt.org/directory`
|
|
||||||
- Limite de taux : 300 certificats par semaine par domaine
|
|
||||||
- ⚠️ Les certificats staging ne sont pas fiables par les navigateurs
|
|
||||||
|
|
||||||
### Modifier l'email
|
|
||||||
|
|
||||||
L'email utilisé pour l'enregistrement ACME est défini dans :
|
|
||||||
- `helm/cert-manager/dev/templates/cluster-issuer-letsencrypt-prod.yaml`
|
|
||||||
- `helm/cert-manager/dev/templates/cluster-issuer-letsencrypt-staging.yaml`
|
|
||||||
|
|
||||||
Modifiez la ligne `email: admin@gkdomaine.fr` avec votre email.
|
|
||||||
|
|
||||||
## Utilisation
|
|
||||||
|
|
||||||
### Méthode 1 : Via annotations Ingress (Recommandé)
|
|
||||||
|
|
||||||
Ajoutez les annotations suivantes à votre Ingress :
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
ingress:
|
|
||||||
enabled: true
|
|
||||||
className: traefik
|
|
||||||
hosts:
|
|
||||||
- host: monapp.dev.gkdomaine.fr
|
|
||||||
paths:
|
|
||||||
- path: /
|
|
||||||
tls:
|
|
||||||
- secretName: monapp-dev-tls
|
|
||||||
hosts:
|
|
||||||
- monapp.dev.gkdomaine.fr
|
|
||||||
annotations:
|
|
||||||
cert-manager.io/cluster-issuer: "letsencrypt-prod" # ou "letsencrypt-staging" pour les tests
|
|
||||||
```
|
|
||||||
|
|
||||||
### Méthode 2 : Via ressource Certificate (Pour plus de contrôle)
|
|
||||||
|
|
||||||
Créez une ressource Certificate :
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
apiVersion: cert-manager.io/v1
|
|
||||||
kind: Certificate
|
|
||||||
metadata:
|
|
||||||
name: monapp-dev-tls
|
|
||||||
namespace: monapp-dev
|
|
||||||
spec:
|
|
||||||
secretName: monapp-dev-tls
|
|
||||||
issuerRef:
|
|
||||||
name: letsencrypt-prod
|
|
||||||
kind: ClusterIssuer
|
|
||||||
dnsNames:
|
|
||||||
- monapp.dev.gkdomaine.fr
|
|
||||||
```
|
|
||||||
|
|
||||||
Puis référencez le secret dans votre Ingress :
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
ingress:
|
|
||||||
tls:
|
|
||||||
- secretName: monapp-dev-tls
|
|
||||||
hosts:
|
|
||||||
- monapp.dev.gkdomaine.fr
|
|
||||||
```
|
|
||||||
|
|
||||||
## Validation HTTP-01
|
|
||||||
|
|
||||||
cert-manager utilise la méthode HTTP-01 pour valider la propriété du domaine :
|
|
||||||
|
|
||||||
1. cert-manager crée un challenge HTTP
|
|
||||||
2. Traefik expose le challenge sur `/.well-known/acme-challenge/`
|
|
||||||
3. Let's Encrypt vérifie que le challenge est accessible
|
|
||||||
4. Le certificat est émis et stocké dans un Secret Kubernetes
|
|
||||||
|
|
||||||
### Prérequis
|
|
||||||
|
|
||||||
- Le domaine doit pointer vers l'IP publique de Traefik (LoadBalancer)
|
|
||||||
- Le port 80 doit être accessible depuis Internet
|
|
||||||
- Traefik doit être configuré pour gérer les ingress avec la classe `traefik`
|
|
||||||
|
|
||||||
## Vérification
|
|
||||||
|
|
||||||
### Vérifier le statut d'un certificat
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Lister les certificats
|
|
||||||
kubectl get certificates --all-namespaces
|
|
||||||
|
|
||||||
# Détails d'un certificat
|
|
||||||
kubectl describe certificate monapp-dev-tls -n monapp-dev
|
|
||||||
|
|
||||||
# Vérifier les challenges ACME
|
|
||||||
kubectl get challenges --all-namespaces
|
|
||||||
```
|
|
||||||
|
|
||||||
### Vérifier le secret TLS
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Le secret est créé automatiquement quand le certificat est émis
|
|
||||||
kubectl get secret monapp-dev-tls -n monapp-dev
|
|
||||||
|
|
||||||
# Voir les détails du certificat
|
|
||||||
kubectl get secret monapp-dev-tls -n monapp-dev -o jsonpath='{.data.tls\.crt}' | base64 -d | openssl x509 -text -noout
|
|
||||||
```
|
|
||||||
|
|
||||||
## Renouvellement automatique
|
|
||||||
|
|
||||||
cert-manager renouvelle automatiquement les certificats avant expiration (30 jours avant la date d'expiration).
|
|
||||||
|
|
||||||
Les certificats Let's Encrypt sont valides pendant 90 jours.
|
|
||||||
|
|
||||||
## Dépannage
|
|
||||||
|
|
||||||
### Le certificat n'est pas émis
|
|
||||||
|
|
||||||
1. Vérifier les logs de cert-manager :
|
|
||||||
```bash
|
|
||||||
kubectl logs -n cert-manager deployment/cert-manager
|
|
||||||
```
|
|
||||||
|
|
||||||
2. Vérifier les challenges :
|
|
||||||
```bash
|
|
||||||
kubectl describe challenge -n monapp-dev
|
|
||||||
```
|
|
||||||
|
|
||||||
3. Vérifier que le domaine est accessible :
|
|
||||||
```bash
|
|
||||||
curl http://monapp.dev.gkdomaine.fr/.well-known/acme-challenge/test
|
|
||||||
```
|
|
||||||
|
|
||||||
### Erreur "rate limit exceeded"
|
|
||||||
|
|
||||||
Let's Encrypt a des limites de taux :
|
|
||||||
- Production : 50 certificats par semaine par domaine
|
|
||||||
- Staging : 300 certificats par semaine par domaine
|
|
||||||
|
|
||||||
Solution : Utilisez `letsencrypt-staging` pour les tests, ou attendez la fin de la période de limitation.
|
|
||||||
|
|
||||||
### Le certificat n'est pas utilisé par Traefik
|
|
||||||
|
|
||||||
Vérifiez que :
|
|
||||||
1. Le secret TLS existe dans le même namespace que l'Ingress
|
|
||||||
2. L'Ingress référence correctement le secret dans `spec.tls[].secretName`
|
|
||||||
3. Traefik peut accéder au secret (même namespace ou RBAC approprié)
|
|
||||||
|
|
||||||
## Exemples de configuration
|
|
||||||
|
|
||||||
### Homarr
|
|
||||||
|
|
||||||
Voir `helm/homarr/dev/values.yaml` pour un exemple complet avec annotations cert-manager.
|
|
||||||
|
|
||||||
### Traefik Dashboard
|
|
||||||
|
|
||||||
Pour sécuriser le dashboard Traefik, ajoutez TLS à l'IngressRoute :
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
apiVersion: traefik.io/v1alpha1
|
|
||||||
kind: IngressRoute
|
|
||||||
metadata:
|
|
||||||
name: traefik-dashboard
|
|
||||||
namespace: traefik-dev
|
|
||||||
annotations:
|
|
||||||
cert-manager.io/cluster-issuer: "letsencrypt-prod"
|
|
||||||
spec:
|
|
||||||
entryPoints:
|
|
||||||
- websecure
|
|
||||||
routes:
|
|
||||||
- match: Host(`traefik.dev.gkdomaine.fr`)
|
|
||||||
kind: Rule
|
|
||||||
services:
|
|
||||||
- name: api@internal
|
|
||||||
kind: TraefikService
|
|
||||||
tls:
|
|
||||||
secretName: traefik-dashboard-tls
|
|
||||||
```
|
|
||||||
|
|
||||||
## Références
|
|
||||||
|
|
||||||
- [cert-manager Documentation](https://cert-manager.io/docs/)
|
|
||||||
- [Let's Encrypt Documentation](https://letsencrypt.org/docs/)
|
|
||||||
- [Traefik ACME Documentation](https://doc.traefik.io/traefik/https/acme/)
|
|
||||||
|
|
||||||
@@ -5,11 +5,13 @@ Ce chart gère les certificats Let's Encrypt générés par cert-manager dans le
|
|||||||
## Structure
|
## Structure
|
||||||
|
|
||||||
- `Chart.yaml` : Définition du chart Helm
|
- `Chart.yaml` : Définition du chart Helm
|
||||||
- `templates/` : Dossiers organisés par application
|
- `templates/` : Dossiers organisés par application (uniquement des fichiers YAML)
|
||||||
- `homarr/` : Certificats pour l'application Homarr
|
- `homarr/` : Certificats pour l'application Homarr
|
||||||
- `[autre-app]/` : Certificats pour d'autres applications
|
- `[autre-app]/` : Certificats pour d'autres applications
|
||||||
|
- `docs/` : Documentation par application
|
||||||
|
- `homarr/README.md` : Documentation pour les certificats Homarr
|
||||||
|
|
||||||
Chaque dossier d'application contient les certificats pour tous les environnements de cette application.
|
**⚠️ IMPORTANT** : Seuls les fichiers YAML doivent être dans `templates/`. Les fichiers de documentation doivent être dans `docs/`.
|
||||||
|
|
||||||
## Ajout d'un nouveau certificat
|
## Ajout d'un nouveau certificat
|
||||||
|
|
||||||
@@ -35,8 +37,8 @@ spec:
|
|||||||
### Pour une nouvelle application
|
### Pour une nouvelle application
|
||||||
|
|
||||||
1. Créez un nouveau dossier dans `templates/` : `templates/<app>/`
|
1. Créez un nouveau dossier dans `templates/` : `templates/<app>/`
|
||||||
2. Créez le fichier Certificate dans ce dossier
|
2. Créez le fichier Certificate dans ce dossier (uniquement des fichiers YAML)
|
||||||
3. Optionnellement, créez un `README.md` dans le dossier pour documenter les certificats de cette application
|
3. Optionnellement, créez un `README.md` dans `docs/<app>/` pour documenter les certificats de cette application
|
||||||
|
|
||||||
## Déploiement
|
## Déploiement
|
||||||
|
|
||||||
@@ -1,27 +0,0 @@
|
|||||||
# Certificats pour Homarr
|
|
||||||
|
|
||||||
Ce dossier contient les certificats Let's Encrypt pour l'application Homarr.
|
|
||||||
|
|
||||||
## Certificats disponibles
|
|
||||||
|
|
||||||
- `certificate-homarr-dev.yaml` : Certificat pour Homarr DEV (homarr.dev.gkdomaine.fr)
|
|
||||||
|
|
||||||
## Ajout d'un nouveau certificat Homarr
|
|
||||||
|
|
||||||
Pour ajouter un certificat pour un nouvel environnement (ex: RCT, PRD), créez un nouveau fichier :
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
apiVersion: cert-manager.io/v1
|
|
||||||
kind: Certificate
|
|
||||||
metadata:
|
|
||||||
name: homarr-<env>-tls
|
|
||||||
namespace: homarr-<env>
|
|
||||||
spec:
|
|
||||||
secretName: homarr-<env>-tls
|
|
||||||
issuerRef:
|
|
||||||
name: letsencrypt-prod
|
|
||||||
kind: ClusterIssuer
|
|
||||||
dnsNames:
|
|
||||||
- homarr.<env>.gkdomaine.fr
|
|
||||||
```
|
|
||||||
|
|
||||||
Reference in New Issue
Block a user