Feature flags en Python sur GitLab : guide de démarrage

Imaginez le scénario suivant : vous avez passé des semaines à développer une nouvelle fonctionnalité. Elle passe tous les tests, la revue de code est terminée, et elle est prête à être livrée. Vous la déployez donc en production et, en moins d'une heure, votre boîte de réception déborde de rapports de bogues. La fonctionnalité fonctionne parfaitement pour la plupart des utilisateurs, mais un comportement du trafic de production que vous n’aviez pas anticipé provoque des échecs pour une partie d'entre eux. Vous voilà en train de vous démener pour effectuer un retour à la version précédente, rédiger des rapports d'incident et gérer les retombées en termes de relations publiques.

Les feature flags empêchent précisément ce genre de scénarios. Ils vous permettent de dissocier le déploiement de la release : vous effectuez un push de votre code en production dès qu'il est prêt, puis contrôlez qui voit réellement la nouvelle fonctionnalité en activant un bouton bascule sur GitLab. Commencez par votre équipe QA à l'aide d'une stratégie « identifiants des utilisateurs », passez ensuite à un « déploiement progressif à 10 % », puis basculez sur « tous les utilisateurs » lorsque vous êtes sûr de vous. Si quelque chose ne se déroule pas comme prévu à un moment donné, il vous suffit de désactiver la fonctionnalité en quelques secondes. Aucun redéploiement, aucun correctif d'urgence, aucun impact sur votre réputation.

Ce tutoriel vous guide à travers une application Flask fonctionnelle qui lit les feature flags GitLab via le SDK Unleash en Python. Une version complète et exécutable du code est disponible sur gitlab.com/omid-blogs/gitlab-feature-flags-demo. Clonez-la dans votre propre groupe ou workspace pour disposer d'un contrôle en temps réel avec des feature flags en quelques minutes.

À la fin de ce tutoriel, vous comprendrez le fonctionnement de l'intégration et disposerez d'un template pour vos propres projets.

Ce dont vous aurez besoin

• Un projet GitLab (version gratuite, GitLab Premium ou GitLab Ultimate) avec les feature flags activés. C'est ici que vous créerez et gérerez vos feature flags. Pour les activer, accédez à votre projet et naviguez vers Paramètres > Général > Visibilité, fonctionnalités du projet, autorisations, puis vérifiez que l'option Feature flags est activée.
• Le dépôt de démonstration dupliqué dans votre propre espace de nommage GitLab, puis cloné localement.

Fonctionnement des feature flags GitLab en coulisses

GitLab expose une API compatible avec Unleash pour chaque projet. Cela signifie que n'importe quel SDK de client Unleash (Go, Ruby, Python, JavaScript, et bien d'autres) peut se connecter directement à GitLab sans serveur Unleash séparé.

Au démarrage, le SDK récupère toutes les définitions des feature flags, puis les actualise selon un intervalle configurable (15 secondes dans la démo). Chaque appel à is_enabled() s'évalue localement à partir de la configuration en cache, sans appel réseau par vérification de feature flag. L'évaluation des feature flags est donc quasi instantanée et résiliente face aux problèmes réseau transitoires.

Voici les étapes à suivre pour intégrer les feature flags GitLab dans une application Flask en Python à l'aide du SDK Unleash.

1. Configurer votre projet GitLab et cloner la démo

Vous aurez besoin des éléments suivants :

• Votre propre projet GitLab pour héberger les feature flags
• Le dépôt de démonstration cloné localement pour exécuter l'application

Dupliquer ou cloner le dépôt de démonstration

Accédez à gitlab.com/omid-blogs/gitlab-feature-flags-demo et dupliquez-le dans votre propre espace de nommage GitLab. Vous obtiendrez ainsi une copie personnelle du projet où vous pourrez gérer vos propres feature flags. Clonez-le ensuite localement et ouvrez-le dans votre IDE préféré :

      git clone https://gitlab.com/<your-namespace>/gitlab-feature-flags-demo.git
cd gitlab-feature-flags-demo

    

Contenu du dépôt

      .
├── app.py                # Flask app + Unleash SDK integration
├── requirements.txt      # Python dependencies
├── .env.example          # Template for required environment variables
├── .gitignore
├── templates/
│   └── index.html        # Web UI template
└── static/
    └── styles.css        # Styling

    

2. Créer vos feature flags dans GitLab

Ouvrez votre propre projet GitLab et naviguez vers Déploiement > Feature flags, puis cliquez sur Nouveau feature flag. Créez les quatre feature flags suivants, en définissant le statut de chacun sur Actif avec une stratégie Tous les utilisateurs.

• dark_mode : bascule la page vers un schéma de couleurs sombre.
• holiday_banner : affiche une bannière festive en haut de la page.
• new_layout : passe la grille de cartes à une disposition en une seule colonne.
• fun_fonts : remplace la police du corps de texte par un style manuscrit ludique.

Conseil : un feature flag doit être actif et disposer d'au moins une stratégie pour être considéré comme activé. Sans stratégie, le SDK considère le feature flag comme désactivé même s'il est marqué comme « Actif ».

Comprendre les stratégies

« Tous les utilisateurs » est un simple bouton bascule, mais GitLab prend en charge plusieurs autres stratégies prêtes à l'emploi :

• Pourcentage de déploiement (recommandé) : déploiement progressif vers un pourcentage d'utilisateurs, basé sur l'identifiant de l'utilisateur, l'identifiant de session ou de manière aléatoire. C'est l'option la plus flexible et celle à privilégier en premier.
• Pourcentage d'utilisateurs : activation pour un pourcentage d'utilisateurs authentifiés. Moins flexible que le pourcentage de déploiement, car elle ne fonctionne qu'avec les utilisateurs connectés.
• ID des utilisateurs : activation pour des identifiants d'utilisateurs spécifiques uniquement, idéale pour les tests internes avec un groupe nommé.
• Listes d'utilisateurs : activation pour une liste prédéfinie d'utilisateurs.
• Tous les utilisateurs : activation pour tout le monde.

Les stratégies font la force des feature flags. Commencez par votre équipe QA avec une stratégie basée sur les ID des utilisateurs, passez à un déploiement progressif à 10 %, puis basculez sur tous les utilisateurs lorsque vous êtes sûr de vous. Tout est paramétrable depuis l'interface utilisateur GitLab, sans aucune modification de code.

3. Obtenir vos identifiants Unleash

Sur la page Feature flags, cliquez sur Configurer dans le coin supérieur droit. Vous verrez deux valeurs :

• URL de l'API : https://gitlab.com/api/v4/feature_flags/unleash/<your-project-id>
• Identifiant d'instance : un jeton unique limité à votre projet

Copiez les deux valeurs. Vous les transmettrez à l'application en tant que variables d'environnement. Notez que l'identifiant d'instance est en lecture seule. Il ne peut que récupérer l'état des feature flags, pas le modifier, mais traitez tout de même l'identifiant d'instance comme un secret afin d'éviter toute divulgation d'informations.

4. Configurer le projet localement

Le README contient le guide de configuration complet, mais en résumé :

      pip install -r requirements.txt

    

Définissez ensuite vos identifiants. Deux options s'offrent à vous :

Option A : utiliser le fichier .env (recommandé)

Le dépôt inclut un fichier .env.example. Copiez-le et renseignez vos valeurs :

      cp .env.example .env

    

Ouvrez .env dans votre éditeur et remplacez les valeurs par défaut par vos identifiants de l'étape 3 :

      UNLEASH_URL=https://gitlab.com/api/v4/feature_flags/unleash/<your-project-id>
UNLEASH_INSTANCE_ID=<your-instance-id>
UNLEASH_APP_NAME=production

    

Ensuite, exportez-les :

      export $(grep -v '^#' .env | xargs)

    

Option B : exporter directement dans votre terminal

      export UNLEASH_URL="https://gitlab.com/api/v4/feature_flags/unleash/<your-project-id>"
export UNLEASH_INSTANCE_ID="<your-instance-id>"
export UNLEASH_APP_NAME="production"

    

N'effectuez jamais un commit de votre fichier .env dans le contrôle de version. Le .gitignore du dépôt l'exclut déjà, mais il est utile de savoir pourquoi : votre identifiant d'instance est un secret et ne doit pas figurer dans l'historique Git.

Trois variables d'environnement pilotent l'ensemble de l'intégration :

UnleashClient est la dépendance clé. Il s'agit du SDK Python officiel d'Unleash qui gère l'interrogation périodique, la mise en cache et l'évaluation locale des feature flags afin que vous n'ayez pas à développer tout cela vous-même.

5. Comprendre l'application

Avant de l'exécuter, parcourez app.py. Voici les modèles clés à comprendre pour les reproduire dans vos propres projets.

Initialisation du SDK

      unleash_client = UnleashClient(
    url=UNLEASH_URL,
    app_name=UNLEASH_APP_NAME,
    instance_id=UNLEASH_INSTANCE_ID,
    refresh_interval=15,
    metrics_interval=60,
)

unleash_client.initialize_client()

    

Aucun jeton d'accès personnel, aucun identifiant codé en dur dans le code source. L'application s'arrête immédiatement avec un message d'erreur clair si l'une des deux variables requises est manquante.

Vérification d'un feature flag

      def is_flag_enabled(flag_name):
    return unleash_client.is_enabled(flag_name)

    

Étant donné que le SDK met en cache les définitions des feature flags en mémoire, is_enabled() renvoie un résultat instantanément, sans aller-retour réseau.

Contrôler le comportement réel derrière les feature flags

La route index construit un dictionnaire de fonctionnalités, évalue chaque feature flag et transmet les résultats au template :

      features = {}
for flag_name, config in feature_configs.items():
    features[flag_name] = {
        **config,
        'enabled': is_flag_enabled(flag_name)
    }

return render_template('index.html', features=features)

    

Le template utilise ces valeurs pour appliquer conditionnellement des classes CSS et afficher des éléments de l'interface. dark_mode bascule une classe sur le corps, holiday_banner affiche ou masque entièrement un élément de bannière. Ouvrez templates/index.html pour voir comment le tout est connecté.

Veuillez noter que index.html se rafraîchit également automatiquement toutes les 30 secondes via un petit extrait JavaScript, ce qui vous permet d'observer les changements de feature flags sans recharger manuellement la page.

Transmettre le contexte utilisateur pour les stratégies ciblées

Lorsque vous souhaitez aller au-delà de la stratégie Tous les utilisateurs et utiliser des déploiements par pourcentage ou le ciblage par utilisateur, transmettez un objet de contexte à is_enabled() :

      unleash_client.is_enabled(
    'new_layout',
    context={'userId': current_user.id}
)

    

Le SDK gère automatiquement le hachage cohérent pour les déploiements par pourcentage, sans calcul de votre côté.

6. Exécuter l'application

      python3 app.py

    

Accédez à http://localhost:8080. Vous devriez voir les quatre cartes de fonctionnalités affichant leur état actuel (activé/désactivé).

7. Activer les feature flags en temps réel

Retournez dans Déploiement > Feature flags dans GitLab et activez l'un des feature flags. Essayez dark_mode ou holiday_banner pour tester l'effet le plus visible. Attendez environ 15 secondes, puis rechargez la page. La carte se met à jour pour refléter le nouvel état, et si vous avez activé dark_mode, l'ensemble de la page passe en thème sombre. Désactivez la fonctionnalité, attendez, rechargez, et tout revient instantanément à la normale.

C'est le principal atout des feature flags : vous contrôlez le comportement de l'application depuis GitLab sans toucher au code ni effectuer de redéploiement.

Pourquoi utiliser le SDK Unleash plutôt que l'API REST GitLab ?

Pour une application qui évalue des feature flags à chaque requête, le SDK est le choix évident. Il est plus rapide, plus simple, et l'identifiant d'instance qu'il utilise ne dispose d'aucune autorisation au-delà de la lecture de l'état des feature flags. La surface d'exposition est bien plus réduite qu'avec un jeton d'accès personnel.

Dépannage

Note sur les limites de débit en production

L'intervalle d'interrogation de 15 secondes convient parfaitement au développement et aux petits déploiements. Lorsque tous les clients interrogent depuis la même IP, GitLab.com peut prendre en charge environ 125 clients à un intervalle de 15 secondes avant d'atteindre les limites de débit. Si vous développez une application de production à plus grande échelle, envisagez de placer un proxy Unleash en amont de vos clients. Ce dernier regroupe les requêtes vers GitLab pour l'ensemble de vos instances et réduit considérablement le trafic en amont.

Considérations de sécurité

1. debug=False est déjà défini dans la démo : conservez ce paramètre. Le mode de débogage de Flask expose un débogueur interactif qui permet l'exécution de code à distance.
2. Maintenez vos dépendances à jour : le fichier requirements.txt fixe des versions spécifiques. Activez l'analyse des dépendances de GitLab dans votre pipeline CI/CD pour surveiller les vulnérabilités.
3. Utilisez des variables d'environnement pour les identifiants : ne codez jamais l'identifiant d'instance ni aucun jeton en dur dans le code source. Le fichier .env.example de la démo illustre cette bonne pratique.
4. L'identifiant d'instance est en lecture seule : il ne peut que récupérer l'état des feature flags, pas le modifier. Traitez-le néanmoins comme un secret.

Synthèse

Ce tutoriel a couvert le cycle complet d'intégration des feature flags GitLab dans une application Python : création des feature flags avec les bonnes stratégies, récupération des identifiants Unleash, initialisation du SDK, évaluation locale des feature flags dans Flask et activation du comportement en temps réel sans redéploiement.

L'ensemble de l'intégration nécessite une seule dépendance (UnleashClient), trois variables d'environnement et un unique appel de méthode (is_enabled()). Aucun serveur Unleash séparé, aucun jeton d'accès personnel, aucune infrastructure complexe.

Les feature flags comptent parmi les outils les plus pratiques pour réduire les risques de déploiement. La possibilité de désactiver instantanément une fonctionnalité en échec, ou de la déployer progressivement d'un groupe d'utilisateurs ciblé à un pourcentage puis à l'ensemble des utilisateurs, sans toucher à un pipeline de déploiement, offre une valeur considérable avec une configuration minimale. Le dépôt de démonstration fournit une base fonctionnelle à dupliquer et adapter pour n'importe quel projet.

Ressources

• Projet de démonstration sur GitLab
• Documentation sur les feature flags GitLab
• SDK Unleash en Python sur GitHub
• SDK Unleash (tous les langages)