Gérer vos configurations NGINX avec GitHub

Michael Vernik

Nina Forsyth

Les paramètres, options et configurations des logiciels se présentent sous de nombreuses formes. À une extrémité du spectre, on trouve des interfaces graphiques élégantes et réactives, conçues pour être intuitives tout en empêchant les configurations non valides. À l’autre extrémité : les fichiers texte. Bien que les ingénieurs comme les équipes DevOps apprécient les fichiers texte pour leur clarté, leur potentiel d’automatisation et le peu de ressources qu’ils nécessitent (vous avez probablement quelques fenêtres de terminal ouvertes, n’est-ce pas ?), leur utilisation pour configurer des logiciels implique des compromis évidents. Par exemple, essayez de trouver un utilisateur de Linux qui n’a jamais réussi à faire planter un logiciel en configurant incorrectement un fichier texte.

En tant que seule solution logicielle tout-en-un faisant office de proxy, d’équilibreur de charge, de serveur web et de passerelle API, NGINX est un composant essentiel de l’infrastructure Internet moderne. Une infrastructure qui repose, dans la plupart des cas, sur des systèmes d’exploitation basés sur le noyau Linux. Pour s’adapter à cet écosystème et aux professionnels qui en assurent le fonctionnement, NGINX s’appuie largement sur des configurations textuelles.

Le module F5 NGINX Instance Manager est depuis longtemps la solution de référence pour orchestrer les configurations NGINX. Grâce à son interface utilisateur intuitive et à son API, il offre des fonctionnalités avancées de gestion à distance et en masse des configurations, ainsi qu’une documentation et des garde-fous. Cependant, les fichiers de configuration NGINX ressemblent beaucoup à du code, et les équipes logicielles disposent déjà d’un outil remarquable pour gérer le code : Git. Git offre aux équipes de développement et d’exploitation une multitude de fonctionnalités conçues pour gérer les workflows liés aux fichiers texte.

La nouvelle intégration d’Instance Manager avec Git et d’autres systèmes externes offre des fonctionnalités telles que la gestion des versions, la contribution décentralisée, les workflows d’approbation et la coordination des équipes. Des plateformes comme GitHub et GitLab enrichissent cet ensemble de fonctionnalités avec l’intégration et le déploiement continus (CI/CD), la collaboration, le suivi des problèmes et d’autres fonctions utiles accessibles depuis une interface utilisateur web.

Dans cet article de blog, nous expliquons comment utiliser GitHub pour gérer les configurations NGINX et les déployer automatiquement sur les instances à chaque modification.

API d’Instance Manager

Instance Manager propose un riche ensemble d’API REST qui complètent son interface utilisateur web. L’un des principaux avantages de l’API est sa capacité à mettre à jour les fichiers de configuration des instances de plan de données gérées. Récemment, nous avons étendu cette fonctionnalité afin de permettre d’associer les mises à jour de configuration à une version spécifique du fichier. Lorsque les configurations sont gérées dans un dépôt Git, elles peuvent être étiquetées avec le hachage d’un commit Git. Nous avons également ajouté dans Instance Manager un nouvel état pour les configurations gérées en externe, qui avertit les personnes souhaitant modifier les fichiers que les configurations font l’objet d’une gestion externe.

GitHub Actions

GitHub permet aux développeurs de créer des pipelines de déploiement personnalisés dans leurs dépôts grâce à une fonctionnalité appelée « Actions ». Un utilisateur peut choisir de définir ses propres actions ou d’exécuter des scripts existants au moyen d’une définition YAML. Ces pipelines peuvent être déclenchés de différentes manières, par exemple lorsqu’un dépôt est mis à jour à la suite d’un commit ou de la fusion d’une pull request.

Dans l’exemple présenté dans cet article, nous nous appuyons sur les GitHub Actions prêtes à l’emploi et sur des commandes Linux. Vous apprendrez à les utiliser pour mettre à jour, via l’API d’Instance Manager, les fichiers de configuration NGINX gérés dans GitHub sur vos instances NGINX. Pour commencer, suivez ces étapes dans la documentation GitHub afin de créer un nouveau fichier YAML permettant d’exécuter des Actions dans votre dépôt.

Configuration des secrets Actions

Instance Manager prend en charge différentes formes d’authentification. Dans cet exemple, nous utilisons la méthode d’authentification de base, mais nous recommandons de configurer l’authentification OIDC dans les environnements de production.

Au lieu de stocker les identifiants d’Instance Manager dans le dépôt, GitHub vous permet de définir des secrets en tant que variables du dépôt. Ces variables sont accessibles dans l’environnement Actions, mais masquées dans les journaux. Suivez ces étapes pour stocker le nom d’utilisateur et le mot de passe d’Instance Manager en tant que secrets afin de pouvoir les utiliser pour authentifier vos appels d’API.

Ici, nous avons défini ces variables sur « NMS_USERNAME » et « NMS_PASSWORD ».

Configuration des variables Actions

De même, plutôt que de définir des variables constantes dans votre fichier YAML, il peut être utile de les en extraire afin de les gérer dans l’interface utilisateur de GitHub. Sur la page Variables (Variables), vous trouverez des instructions pour définir des variables applicables à toutes les Actions du dépôt. Dans cet exemple, nous en profitons pour définir le nom de domaine complet (FQDN) ou l’adresse IP d’Instance Manager (NMS_HOSTNAME), l’identifiant du système sur lequel NGINX s’exécute (SYSTEM_ID) et l’identifiant de l’instance NGINX spécifique à mettre à jour (INSTANCE_ID).

Remarque : Nous avons défini ces variables pour simplifier notre exemple, mais vous pouvez choisir de gérer autrement les informations d’identification d’Instance Manager, du système et de NGINX. Par exemple, vous pouvez créer dans votre dépôt des répertoires contenant des configurations propres à différentes instances et nommer ces répertoires à l’aide d’identifiants de système ou d’instance. Vous pouvez ensuite modifier votre script YAML ou Action afin qu’il lise les noms des répertoires et mette à jour les fichiers de configuration sur l’instance correspondante.

Anatomie de l’appel à l’API REST d’Instance Manager pour la mise à jour des configurations NGINX

L’appel à l’API REST de mise à jour de la configuration d’Instance Manager nécessite plusieurs composants clés pour fonctionner. Votre fichier YAML devra définir chacun de ces paramètres et les intégrer à l’appel d’API dans le format approprié.

Dans cet exemple, nous utilisons l’appel d’API permettant de mettre à jour une seule instance. Toutefois, il est également possible de configurer un groupe d’instances dans Instance Manager. Vous pouvez ainsi mettre à jour toutes les instances d’un groupe chaque fois qu’une nouvelle configuration est envoyée depuis GitHub. Pour plus d’informations, consultez notre guide pratique sur la publication de configurations.

Voici le détail de l’appel à l’API REST de mise à jour de la configuration d’Instance Manager :

https://{INSTANCE MANAGER HOSTNAME}/api/platform/v1/systems/{SYSTEM ID}/instances/{INSTANCE ID}/config' 
--header "accept: application/json" 
--header "Authorization: Basic {LOGIN CREDENTIALS}" 
--header 'Content-Type: application/json'
--data '{
    "configFiles": '{
        "rootDir": "/etc/nginx",
        "files": [{
            "contents": "{NGINX CONFIGURATION FILE}",
            "name": "{PATH TO CONFIGURATION FILE ON SYSTEM}"
        }]
    },
    "externalIdType": "{SOURCE OF CONFIGS}",
    "externalId": "{COMMIT HASH}",
    "updateTime": "{TIMESTAMP}"
}'}'

Paramètres d’URI

• Identifiant du système – Une clé unique identifiant le système sur lequel NGINX s’exécute. Dans notre exemple, ces données sont définies dans l’interface Variables de GitHub Actions.
• Identifiant de l’instance NGINX – Clé unique permettant d’identifier une instance NGINX spécifique sur le système. Dans notre exemple, ces données sont définies dans l’interface Variables de GitHub Actions.

Paramètres d’en-tête

• Autorisation – La méthode d’autorisation et les identifiants encodés en Base64 qu’Instance Manager utilise pour authentifier l’appel d’API. Dans cet exemple, vous utiliserez l’authentification Basic avec les identifiants provenant des secrets définis dans le dépôt.

Paramètres des données JSON

• configFiles – Le contenu encodé en Base64 des fichiers de configuration en cours de mise à jour, ainsi que leur emplacement sur le système exécutant NGINX. Vous devrez également fournir le chemin d’accès au répertoire racine de vos fichiers de configuration NGINX, généralement configuré comme suit : /etc/nginx.
• externalIdType – Une étiquette qui identifie la source du fichier de configuration auprès d’Instance Manager. Les valeurs possibles sont git ou other. Dans notre exemple, nous définissons ce paramètre en dur sur git.
• externalId – L’algorithme de hachage sécurisé (SHA) du commit Git qui identifie la modification apportée aux fichiers de configuration.
• updateTime – Une chaîne contenant la date et l’heure actuelles au %Y-%m-%dT%H:%M:%SZ format.

Encodage Base64

Pour respecter les spécifications de l’API d’Instance Manager, vous devez transformer certaines données en les encodant au format Base64. Bien que les GitHub Actions existantes ne permettent pas de le faire nativement, nous pouvons utiliser des outils Linux accessibles depuis notre fichier YAML.

Identifiants d’Instance Manager

Commencez par référencer les identifiants de connexion à Instance Manager précédemment définis en tant que secrets, puis concaténez-les. Convertissez ensuite la chaîne en Base64, affichez-la en tant que variable Linux (NMS_LOGIN) et ajoutez le résultat à une variable d’environnement prédéfinie (GITHUB_ENV), accessible par l’exécuteur Actions.

run: echo "NMS_LOGIN=`echo -n "${{ secrets.NMS_USERNAME }}:${{ secrets.NMS_PASSWORD }}" | base64`" >> $GITHUB_ENV

Horodatage

L’API Instance Manager exige qu’un horodatage dans un format spécifique soit envoyé avec certaines charges utiles d’API. Vous pouvez générer l’horodatage dans ce format à l’aide de la commande Linux « date ». Comme dans l’exemple précédent, ajoutez la chaîne générée à l’environnement Linux en tant que variable.

run: echo "NMS_TIMESTAMP=`date -u +"%Y-%m-%dT%H:%M:%SZ"`" >> $GITHUB_ENV

Configurations NGINX

Ensuite, ajoutez au dépôt les configurations NGINX que vous prévoyez de gérer. Il existe de nombreuses façons d’ajouter des fichiers à un dépôt GitHub. Pour plus d’informations, suivez ce guide dans la documentation de GitHub. Pour suivre notre exemple, vous pouvez créer dans votre dépôt GitHub une arborescence de répertoires identique à celle de l’instance.

L’entrée YAML ci-dessous lit le fichier de configuration depuis votre dépôt, encode son contenu en Base64 et ajoute le résultat à une variable d’environnement, comme précédemment.

run: echo "NGINX_CONF_CONFIG_FILE=`cat nginx-server/etc/nginx/nginx.conf | base64 -w 0`" >> $GITHUB_ENV

Dans notre exemple, nous répétons cette opération pour chaque fichier de configuration de notre dépôt GitHub.

Assemblage de tous les éléments

Enfin, vous pouvez utiliser l’exemple d’implémentation de référence de GitHub pour mettre en pratique ce que vous avez appris dans un fichier YAML fonctionnel. Comme défini dans ce fichier, tous les scripts GitHub Actions associés s’exécuteront chaque fois qu’un utilisateur mettra à jour le dépôt au moyen d’un commit ou d’une pull request. La dernière entrée du fichier YAML exécutera une commande curl qui effectuera l’appel d’API approprié avec les données nécessaires pour permettre à Instance Manager de mettre à jour tous les fichiers de configuration concernés.

Remarque : Utilisez l’entrée d’exécution multiligne (run: |) dans votre fichier YAML pour exécuter la commande curl, car cela indique à l’interpréteur YAML de traiter les deux-points « : » comme du texte dans la partie de l’entrée contenant les paramètres.

name: Managing NGINX configs with GitHub and GitHub Actions 
# Controls when the workflow will run 
on: 
  # Triggers the workflow on push or pull request events but only for the "main" branch 
  push: 
    branches: [ "main" ] 
  pull_request: 
    branches: [ "main" ] 
  
  # Allows you to run this workflow manually from the Actions tab 
  workflow_dispatch: 

# A workflow run is made up of one or more jobs that can run sequentially or in parallel 
jobs: 
  # This workflow contains a single job called "build" 
  build: 
    # The type of runner that the job will run on 
    runs-on: ubuntu-latest 

    # Steps represent a sequence of tasks that will be executed as part of the job 
    steps: 
      # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it 
      - uses: actions/checkout@v4 

      - name: Set environment variable for NMS API login credentials 
        run: echo "NMS_LOGIN=`echo -n "${{ secrets.NMS_USERNAME }}:${{ secrets.NMS_PASSWORD }}" | base64`" >> $GITHUB_ENV 

      - name: Set environment variable for NMS API timestamp 
        run: echo "NMS_TIMESTAMP=`date -u +"%Y-%m-%dT%H:%M:%SZ"`" >> $GITHUB_ENV 

      - name: Set environment variable for base64 encoded config file 
        run: echo "NGINX_CONF_CONFIG_FILE=`cat app-sfo-01/etc/nginx/nginx.conf | base64 -w 0`" >> $GITHUB_ENV 

      - name: Set environment variable for base64 encoded config file 
        run: echo "MIME_TYPES_CONFIG_FILE=`cat app-sfo-01/etc/nginx/mime.types | base64 -w 0`" >> $GITHUB_ENV 

      - name: Set environment variable for base64 encoded config file 
        run: echo "DEFAULT_CONF_CONFIG_FILE=`cat app-sfo-01/etc/nginx/conf.d/default.conf | base64 -w 0`" >> $GITHUB_ENV 

      - name: Set environment variable for base64 encoded config file 
        run: echo "SSL_CONF_CONFIG_FILE=`cat app-sfo-01/etc/nginx/conf.d/ssl.conf | base64 -w 0`" >> $GITHUB_ENV 

      - name: API call to Instance Manager 
        run: | 
          curl --location 'https://${{ vars.NMS_HOSTNAME }}/api/platform/v1/systems/${{ vars.SYSTEM_ID }}/instances/${{ vars.INSTANCE_ID }}/config' --header "accept: application/json" --header "Authorization: Basic ${{ env.NMS_LOGIN }}" --header 'Content-Type: application/json' --data '{"configFiles": {"rootDir": "/etc/nginx","files": [{"contents": "${{ env.NGINX_CONF_CONFIG_FILE }}","name": "/etc/nginx/nginx.conf"},{"contents": "${{ env.MIME_TYPES_CONFIG_FILE }}","name": "/etc/nginx/mime.types"},{"contents": "${{ env.DEFAULT_CONF_CONFIG_FILE }}","name": "/etc/nginx/conf.d/default.conf"},{"contents": "${{ env.SSL_CONF_CONFIG_FILE }}","name": "/etc/nginx/conf.d/ssl.conf"}]},"externalIdType": "git","externalId": "${{ github.sha }}","updateTime": "${{ env.NMS_TIMESTAMP }}"}' 

Implémentation de référence de NGINX

L’exécution d’un appel d’API de mise à jour de la configuration après la modification d’un fichier peut s’effectuer de différentes manières. Bien que GitHub Actions soit la méthode la plus pratique pour les utilisateurs de GitHub, elle ne fonctionne pas avec GitLab ni avec les implémentations Git autonomes. Pour répondre à ces cas d’usage, nous avons développé un script shell complémentaire servant d’implémentation de référence et pouvant être déclenché depuis la ligne de commande ou appelé à partir de scripts personnalisés.

En conclusion, notre nouvelle extension de l’API Instance Manager offre un outil puissant permettant de gérer les mises à jour de configuration, les restaurations et l’historique des versions de manière moderne et décentralisée. L’association de cette extension à une plateforme tierce de gestion de fichiers texte et de code telle que GitHub permet de bénéficier de fonctionnalités supplémentaires de gestion des workflows, d’intégration et de déploiement continus (CI/CD), de collaboration et de suivi des problèmes, par l’intermédiaire d’une interface utilisateur web intuitive.

Nous serions ravis de connaître votre avis ! Essayez cette extension et dites-nous ce que vous en pensez dans les commentaires ou en rejoignant notre canal Slack de la communauté NGINX.

À propos des auteurs

Michael Vernik

Autres articles de Michael Vernik

Nina Forsyth

Autres articles de Nina Forsyth