Gérer vos configurations NGINX avec GitHub

Les paramètres, options et configurations du logiciel existent sous de nombreuses formes différentes. À une extrémité du spectre se trouvent les interfaces graphiques fluides et réactives, censées être intuitives tout en offrant des garde-fous contre les états non valides. À l’autre extrémité : les fichiers texte. Bien que les fichiers texte soient salués par les ingénieurs et les équipes DevOps pour leur clarté, leur potentiel d'automatisation et leurs exigences d'utilisation minimales (vous avez probablement quelques fenêtres de terminal ouvertes, n'est-ce pas ?), la configuration des logiciels avec eux comporte des compromis évidents. Par exemple, essayez de trouver un utilisateur Linux qui n'a pas réussi à faire planter un logiciel en configurant mal un fichier texte.

En tant que seul proxy logiciel tout-en-un, équilibreur de charge, serveur Web et passerelle API, NGINX est un élément clé de l'infrastructure Internet moderne. Une infrastructure qui est, dans la plupart des cas, basée sur des systèmes d’exploitation reposant sur le noyau Linux. Pour se conformer à cet écosystème et aux professionnels qui le soutiennent, NGINX s'appuie fortement sur des configurations textuelles.

Le module F5 NGINX Instance Manager est depuis longtemps la référence pour l’orchestration de configuration liée à NGINX. Il offre des fonctionnalités avancées pour la gestion de configuration à distance et par lots via son interface utilisateur intuitive et son API, avec une documentation de support et des garde-fous pour démarrer. Cependant, les fichiers de configuration NGINX individuels ressemblent fortement au code et les équipes de logiciels disposent déjà d'un outil incroyable pour gérer le code : Git. Git fournit aux développeurs et aux équipes d'exploitation une multitude de fonctionnalités destinées à la gestion des flux de travail de fichiers texte.

La nouvelle intégration d’Instance Manager avec Git et d’autres systèmes externes permet des fonctionnalités telles que le contrôle de version, la contribution décentralisée, les flux de travail d’approbation et la coordination d’équipe. Des plateformes comme GitHub et GitLab étendent cet ensemble de fonctionnalités à l'intégration continue/au déploiement continu (CI/CD), à la collaboration, au suivi des problèmes et à d'autres fonctions précieuses via une interface utilisateur Web.

Dans cet article de blog, nous illustrons comment GitHub peut être utilisé pour gérer les configurations NGINX, en les poussant automatiquement vers les instances chaque fois qu'une modification est apportée.

API du gestionnaire d'instances

Instance Manager fournit 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 sous gestion. Récemment, nous avons étendu cette fonctionnalité en permettant de lier les mises à jour de configuration à une version spécifique du fichier. Lorsqu'elles sont gérées dans un référentiel Git, les configurations peuvent être étiquetées avec un hachage de validation Git. De plus, nous avons implémenté un nouvel état dans Instance Manager pour les configurations gérées en externe qui avertit les éditeurs de fichiers potentiels que les configurations sont sous gestion externe.

Actions GitHub

GitHub permet aux développeurs de créer des pipelines de déploiement personnalisés dans leurs référentiels à l'aide d'une fonctionnalité appelée Actions . Un utilisateur peut choisir de définir ses propres actions ou d'invoquer des scripts existants via une définition YAML . Ces pipelines peuvent être déclenchés de diverses manières, par exemple lorsqu'un référentiel est mis à jour avec une validation ou une fusion de demande d'extraction.

Dans l'exemple de ce blog, nous nous appuyons sur les actions GitHub et les commandes Linux prêtes à l'emploi. Vous apprendrez à les utiliser pour mettre à jour les fichiers de configuration NGINX gérés par GitHub sur vos instances NGINX via l'API Instance Manager. Pour commencer, suivez ces étapes sur GitHub Docs pour créer un nouveau YAML pour exécuter des actions dans votre référentiel.

Définir les secrets des actions

Instance Manager prend en charge différentes formes d'authentification . Dans l’exemple, nous utilisons la méthode d’authentification de base , même si nous recommandons de provisionner l’authentification OIDC dans les environnements de production.

Plutôt que de stocker les informations d’identification d’Instance Manager dans le référentiel, GitHub vous permet de définir des secrets en tant que variables de référentiel. Ces variables sont accessibles par l'environnement Actions mais masquées dans les logs. Suivez ces étapes pour stocker les clés de nom d’utilisateur et de 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 .

Définition des variables d'actions

De même, plutôt que de définir des variables constantes dans votre YAML, il peut être utile de les factoriser pour la gestion dans l'interface utilisateur GitHub. Sur la page Variables , vous pouvez trouver des instructions sur la façon de définir des variables qui couvrent toutes les actions du référentiel. Dans l'exemple, nous utilisons cette opportunité pour définir le nom de domaine complet ou l'adresse IP du gestionnaire d'instances ( 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 ).

Note: Nous avons défini ces variables pour simplifier notre exemple, mais vous pouvez choisir de gérer les informations d’identification d’Instance Manager, du système et de NGINX d’autres manières. Par exemple, vous pouvez choisir de créer des répertoires dans votre référentiel contenant des configurations spécifiques à différentes instances et de nommer ces répertoires avec des ID système ou d'instance. Vous pouvez ensuite modifier votre script YAML ou Action pour lire les noms de répertoire et mettre à jour les fichiers de configuration sur l'instance correspondante.

Anatomie de l'appel de l'API REST du gestionnaire d'instances pour la mise à jour des configurations NGINX

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

Dans l'exemple, nous utilisons l'appel API pour mettre à jour une seule instance. Cependant, il est également possible de configurer un groupe d'instances dans Instance Manager. Cela vous permet de mettre à jour toutes les instances d’un groupe chaque fois qu’une nouvelle configuration est envoyée depuis GitHub. Pour plus d'informations, veuillez consulter notre guide pratique sur la publication des configurations .

Vous trouverez ci-dessous une description détaillée de l'appel d'API REST de mise à jour de configuration d'Instance Manager :

https://{NOM D'HÔTE DU GESTIONNAIRE D'INSTANCE}/api/platform/v1/systems/{ID SYSTÈME}/instances/{ID INSTANCE}/config' 
--header "accept: application/json" 
--header "Autorisation: {IDENTIFIANTS DE CONNEXION}" 
--header 'Content-Type: application/json'
--data '{
"configFiles": '{
"rootDir": "/etc/nginx",
"files": [{
"contents": "{FICHIER DE CONFIGURATION NGINX}",
"name": "{CHEMIN VERS LE FICHIER DE CONFIGURATION SUR LE SYSTÈME}"
}]
},
"externalIdType": "{SOURCE DES CONFIGURATION}",
"externalId": "{HASH DE COMMIT}",
"updateTime": "{HORODATAGE}"
}'}'

Paramètres URI

• Identifiant 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 GitHub Actions Variables.
• Identifiant d’instance NGINX – Une clé unique identifiant une instance NGINX spécifique sur le système. Dans notre exemple, ces données sont définies dans l'interface GitHub Actions Variables.

Paramètres d'en-tête

• Autorisation – La méthode d’autorisation et les informations d’identification codées en Base64 qu’Instance Manager utilise pour authentifier l’appel d’API. Dans l'exemple, vous utiliserez l'autorisation de base avec des données d'identification provenant des secrets définis dans le référentiel.

Paramètres de données JSON

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

Codage Base64

Pour prendre en charge la spécification API d’Instance Manager, vous devez transformer certaines données en les codant au format Base64. Bien qu’il n’existe pas de moyen natif d’accomplir cela avec les actions GitHub existantes, nous pouvons compter sur les outils Linux, accessibles depuis notre YAML.

Informations d'identification du gestionnaire d'instances

Commencez par référencer les informations de connexion du gestionnaire d’instances qui ont été définies précédemment comme secrets et concaténez-les. Ensuite, convertissez la chaîne en Base64, faites-la écho en tant que variable Linux ( NMS_LOGIN ) et ajoutez le résultat à une variable d'environnement prédéfinie ( GITHUB_ENV ), accessible par le coureur d'actions.

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

Horodatage

L'API Instance Manager requiert qu'un horodatage spécifiquement formaté soit envoyé avec certaines charges utiles d'API. Vous pouvez construire l'horodatage dans ce format à l'aide de la commande date de Linux. Similaire à l’exemple précédent, ajoutez la chaîne construite en tant que variable à l’environnement Linux.

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

Configurations NGINX

Ensuite, ajoutez les configurations NGINX que vous prévoyez de gérer dans le référentiel. Il existe de nombreuses façons d'ajouter des fichiers à un référentiel GitHub. Pour plus d'informations, suivez ce guide dans la documentation de GitHub. Pour suivre notre exemple, vous pouvez créer une structure de répertoire dans votre référentiel GitHub qui reflète celle de l'instance.

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

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

Dans notre exemple, nous répétons cela pour chaque fichier de configuration de notre référentiel GitHub.

Mettre tout cela ensemble

Enfin, vous pouvez utiliser l'exemple d'implémentation de référence de GitHub pour rassembler ce que vous avez appris dans un fichier YAML fonctionnel. Comme défini dans le fichier, tous les scripts GitHub Actions associés s'exécuteront chaque fois qu'un utilisateur mettra à jour le référentiel via une validation ou une demande d'extraction. L'entrée finale dans le YAML exécutera une commande curl qui effectuera l'appel API approprié, contenant les données nécessaires à Instance Manager pour mettre à jour tous les fichiers de configuration associés.

Note: Utilisez l’entrée d’exécution multiligne ( run: | ) dans votre 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 paramètre de l’entrée.

nom: Gestion des configurations NGINX avec GitHub et les actions GitHub 
# Contrôle le moment où le workflow s'exécutera 
on: 
# Déclenche le workflow sur les événements de demande push ou pull mais uniquement pour la branche « main » 
push: 
branches: [ "main" ] 
pull_request: 
branches: [ "main" ] 

# Vous permet d'exécuter ce workflow manuellement à partir de l'onglet Actions 
workflow_dispatch: 

# Une exécution de workflow est composée d'une ou plusieurs tâches qui peuvent s'exécuter de manière séquentielle ou en parallèle 
jobs: 
# Ce workflow contient une seule tâche appelée « build » 
build: 
# Le type d'exécuteur sur lequel le travail s'exécutera 
runs-on: ubuntu-latest 

# Les étapes représentent une séquence de tâches qui seront exécutées dans le cadre du travail 
steps: 
# Extrait votre référentiel sous $GITHUB_WORKSPACE, afin que votre travail puisse y accéder 
- uses: actions/checkout@v4 

- nom : Définir une variable d'environnement pour les identifiants de connexion à l'API NMS 
exécuter : echo "NMS_LOGIN=`echo -n "${{ secrets.NMS_USERNAME }}:${{ secrets.NMS_PASSWORD }}" | base64`" >> $GITHUB_ENV 

- nom : Définir la variable d'environnement pour l'horodatage de l'API NMS 
exécuter : echo "NMS_TIMESTAMP=`date -u +"%Y-%m-%dT%H:%M:%SZ"`" >> $GITHUB_ENV 

- nom : Définir une variable d'environnement pour le fichier de configuration codé en base64 
exécuter : echo "NGINX_CONF_CONFIG_FILE=`cat app-sfo-01/etc/nginx/nginx.conf | base64 -w 0`" >> $GITHUB_ENV 

- nom : Définir une variable d'environnement pour le fichier de configuration codé en base64 
exécuter : echo "MIME_TYPES_CONFIG_FILE=`cat app-sfo-01/etc/nginx/mime.types | base64 -w 0`" >> $GITHUB_ENV 

- nom : Définir une variable d'environnement pour le fichier de configuration codé en base64 
exécuter : echo "DEFAULT_CONF_CONFIG_FILE=`cat app-sfo-01/etc/nginx/conf.d/default.conf | base64 -w 0`" >> $GITHUB_ENV 

- nom : Définir une variable d'environnement pour le fichier de configuration codé en base64 
exécuter : echo "SSL_CONF_CONFIG_FILE=`cat app-sfo-01/etc/nginx/conf.d/ssl.conf | base64 -w 0`" >> $GITHUB_ENV 

- nom : Appel d'API au gestionnaire d'instances 
exécuter : | 
curl --location 'https://${{ vars.NMS_HOSTNAME }}/api/platform/v1/systems/${{ vars.SYSTEM_ID }}/instances/${{ vars.INSTANCE_ID }}/config' --header "accept : application/json" --header "Authorization : ${{ 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 NGINX

L'exécution d'un appel d'API de mise à jour de configuration après la modification d'un fichier peut être réalisée de différentes manières. Bien que GitHub Actions soit la méthode la plus pratique pour ceux qui utilisent GitHub, elle ne fonctionnera pas pour GitLab ou les implémentations Git autonomes. Pour répondre à ces cas d'utilisation, nous avons développé une implémentation de référence de script shell complémentaire qui peut être déclenchée à partir de la ligne de commande ou invoquée à partir de scripts personnalisés.

En conclusion, notre nouvelle extension de l’API Instance Manager fournit un outil puissant pour gérer les mises à jour de configuration, les restaurations et les historiques de versions de manière moderne et décentralisée. Le couplage de l'extension avec une plate-forme de gestion de code et de fichiers texte tierce comme GitHub permet des fonctionnalités supplémentaires de flux de travail, de CI/CD, de collaboration et de suivi des problèmes via une interface utilisateur Web intuitive.

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