Ansible Role : Keycloak HA

Description

 

🔐 Arrêtez de vous battre avec la configuration de JGroups.

Le rôle keycloak_ha vous livre un cluster Keycloak Production-Ready en moins de 10 minutes. Fini les problèmes de découverte de nœuds, de multicast Docker ou de lenteur au démarrage. Nous avons automatisé les meilleures pratiques (JDBC_PING, Image Optimisée, Monitoring) pour que vous n’ayez pas à le faire.

 

✨ Fonctionnalités Clés

• 🚀 Démarrage Éclair : Build automatique d’une image Keycloak optimisée pour un démarrage 60% plus rapide qu’une installation standard. L’attente Java, c’est fini.
• 🔐 SSO Enterprise : Authentification centralisée avec support OIDC, SAML 2.0, OAuth 2.0.
• 🔄 Haute Disponibilité : Cluster Keycloak avec découverte automatique des nœuds via JDBC_PING.
• ⚡ Scaling Horizontal : Ajoutez des réplicas en changeant une simple variable (keycloak_replicas).
• 🐘 PostgreSQL Externe : Connexion à un cluster PostgreSQL existant ou dédié.
• 🔧 Hautement Configurable : Ports, mémoire JVM, hostname OAuth personnalisables via variables.
• 📊 Prêt pour le Monitoring : Labels Promtail/Loki pour centralisation des logs, métriques Prometheus exposées.
• 💻 Large Compatibilité d’OS : Déployez sur Debian 12/13 et Ubuntu 22.04/24.04 LTS.
• 🔒 Sécurisé : HTTPS natif, credentials via Ansible Vault recommandé.

 

🏗️ Architecture Haute Disponibilité

 

---

 

⚙️ Configuration & Usage

 

Prérequis

• Système d’exploitation : Debian 12/13 ou Ubuntu 22.04/24.04.
• Docker : Docker et Docker Compose installés (via devops_store.docker_engine).
• PostgreSQL : Compatible avec n’importe quel cluster PostgreSQL : AWS RDS, Azure Database, instance gérée, ou notre rôle devops_store.postgres_ha.
• Ansible : Collection community.docker installée.
• Privilèges : Un utilisateur avec des droits sudo sur les serveurs cibles (become: true dans votre playbook).

 

Exemple de Playbook (votre_playbook.yml)

---
- hosts: keycloak_servers
  become: true

  vars:
    # =============================================================================
    # CREDENTIALS (À DÉFINIR DANS UN VAULT!)
    # =============================================================================
    keycloak_admin_password: "{{ vault_keycloak_admin_password }}"
    keycloak_db_host: "postgres.example.com"
    keycloak_db_password: "{{ vault_keycloak_db_password }}"

    # =============================================================================
    # CONFIGURATION CLUSTER
    # =============================================================================
    keycloak_replicas: 3
    keycloak_hostname: "auth.example.com"

    # =============================================================================
    # VERSIONS ET IMAGES
    # =============================================================================
    keycloak_version: "26.0"
    keycloak_use_optimized_image: true

    # =============================================================================
    # PORTS EXPOSÉS
    # =============================================================================
    keycloak_http_port: 8080
    keycloak_https_port: 8443

    # =============================================================================
    # CONFIGURATION BASE DE DONNÉES
    # =============================================================================
    keycloak_db_port: 5432
    keycloak_db_name: "keycloak"
    keycloak_db_user: "keycloak"

    # =============================================================================
    # PERFORMANCE JVM
    # =============================================================================
    keycloak_java_opts_heap: "1024m"
    # keycloak_java_opts_extra: "-XX:+UseG1GC"

    # =============================================================================
    # MONITORING (Promtail/Loki)
    # =============================================================================
    keycloak_enable_logging_labels: false

  roles:
    - role: devops_store.keycloak_ha

 

Exemple d’Inventaire (votre_inventaire)

[keycloak_servers]
keycloak-01 ansible_host=192.168.1.30

[keycloak_servers:vars]
ansible_user=ubuntu
ansible_ssh_private_key_file=~/.ssh/id_rsa

 

Lancement

ansible-playbook -i votre_inventaire votre_playbook.yml

 

---

 

🔬 Détails Techniques

• Clustering JDBC_PING : Utilise la base PostgreSQL partagée comme registre de découverte, évitant les problèmes de multicast en Docker/cloud.
• Image Optimisée : Par défaut, une image Docker optimisée est construite localement avec keycloak_use_optimized_image: true, réduisant le temps de démarrage de ~60%.
• Idempotence Garantie : Vous pouvez exécuter ce rôle plusieurs fois en toute sécurité. Les builds sont mis en cache.
• Dépendance Docker : Ce rôle nécessite Docker (manuel ou via devops_store.docker_engine).
• Dépendance PostgreSQL : Ce rôle nécessite une base PostgreSQL externe (via devops_store.postgres_ha ou autre).
• Tests Complets Inclus : Suite de tests Molecule fournie pour les 4 OS supportés.

 

Ports Utilisés

Port	Service	Description
8080	Keycloak HTTP	Interface web (non sécurisé)
8443	Keycloak HTTPS	Interface web (sécurisé)
7800	JGroups	Communication inter-cluster

 

Accès aux Services

• Console Admin : https://<IP>:8443/admin/
• Account Console : https://<IP>:8443/realms/<realm>/account/
• Health Check : https://<IP>:8443/health/ready
• Métriques Prometheus : https://<IP>:8443/metrics

 

---

 

📚 Documentation Opérationnelle

Ce rôle inclut une documentation complète dans le dossier docs/ :

• Guide Jour 1 (docs/day1-guide.md) : Vérification cluster, accès console admin, création realm/users, test authentification OIDC/SAML.
• Runbook Jour 2+ (docs/day2-runbook.md) : Configuration SSO SAML/OIDC, intégration LDAP/AD, gestion sessions, scaling cluster, import/export, scénarios catastrophe et récupération.
  
  👀 Voir la table des matières complète

  1. 🔧 Troubleshooting Courant : Keycloak ne démarre pas, problèmes JDBC_PING, authentification échoue, timeout/lenteur
  2. 🔐 Configuration SSO (SAML/OIDC) : Clients OIDC, Service Provider SAML, métadonnées IdP
  3. 👥 Gestion des Sessions : Sessions actives, terminaison, configuration timeouts
  4. 📦 Import/Export de Configuration : Export realm complet, import partiel, export utilisateurs
  5. 📈 Scaling du Cluster : Ajout/retrait de nœuds, configuration Load Balancer (Nginx)
  6. 💾 Sauvegarde et Restauration : Scripts de backup PostgreSQL, restauration, automatisation cron
  7. 🔴 Scénarios Catastrophe : BDD inaccessible, corruption données, split-brain, perte serveur, accès admin perdu
  8. 🏢 Intégration LDAP/Active Directory : Configuration, synchronisation, mapping attributs
  9. 🔄 Maintenance et Upgrade : Mise à jour Keycloak, rollback, optimisation production

 

---

 

📦 Détails du Produit

• Nom du rôle : devops_store.keycloak_ha
• Cible OS : Debian (12/13), Ubuntu (22.04/24.04)
• Composants déployés : Keycloak 26.0, Docker Compose
• Dépendances : Docker requis, PostgreSQL externe requis

 

🛡️ Garantie de Qualité et Support

Trois durées de garantie sont disponibles : 3 mois, 1 an et 5 ans. Ces garanties incluent le support technique et les mises à jour du code pour les plateformes supportées.

N.B. : Le support du rôle se base sur le cycle de vie des OS pour lesquels il a été développé. Cela signifie que si un OS atteint sa date d’EOL durant la période de garantie, le support et les mises à jour du rôle s’arrêtent pour cet OS. A contrario, si une nouvelle version majeure d’un OS est publiée durant la période de garantie, le support et les mises à jour du rôle seront assurés pour cette nouvelle version.

 

🔑 Licence d’Utilisation

Trois niveaux de licence sont disponibles :

• Standard : Usage pour les projets internes de l’acheteur. Pas de redistribution, pas d’utilisation pour des clients tiers. Idéale pour les indépendants, PME gérant leur propre infra, passionnés.
• Entreprise : Inclut tous les droits Standard et permet d’utiliser le rôle pour configurer les serveurs de clients finaux. Droit d’intégration dans des produits et services vendus. Idéale pour les ESN, Agences Web, Infogérants (MSP), Consultants DevOps.
• Marque Blanche : Inclut tous les droits Entreprise avec l’autorisation exclusive de supprimer les mentions de l’auteur (attribution) pour présenter le code comme votre propre technologie. Idéale pour les grands Infogérants et éditeurs exigeant une image de marque unifiée sans trace de tiers.