Verwalten Ihrer NGINX-Konfigurationen mit GitHub

Softwareeinstellungen, Optionen und Konfigurationen gibt es in vielen verschiedenen Formen. Am einen Ende des Spektrums stehen die eleganten, reaktionsschnellen GUIs, die intuitiv sein sollen und gleichzeitig Schutz vor ungültigen Zuständen bieten. Am anderen Ende: Textdateien. Obwohl Textdateien sowohl von Ingenieuren als auch von DevOps-Teams für ihre Übersichtlichkeit, ihr Automatisierungspotenzial und ihren minimalen Nutzungsbedarf gelobt werden (Sie haben wahrscheinlich einige Terminalfenster geöffnet, oder?), bringt die Softwarekonfiguration mit ihnen klare Nachteile mit sich. Versuchen Sie beispielsweise, einen Linux-Benutzer zu finden, der es nicht geschafft hat, ein Softwarepaket durch die falsche Konfiguration einer Textdatei zum Absturz zu bringen.

Als einziger All-in-One-Software-Proxy, Load Balancer, Webserver und API-Gateway ist NGINX eine Schlüsselkomponente der modernen Internet-Infrastruktur. Eine Infrastruktur, die in den meisten Fällen auf Betriebssystemen basiert, die auf dem Linux-Kernel basieren. Um sich diesem Ökosystem und den es unterstützenden Fachleuten anzupassen, verlässt sich NGINX in hohem Maße auf textbasierte Konfigurationen.

Das F5 NGINX Instance Manager-Modul ist seit langem die erste Wahl für die NGINX-bezogene Konfigurationsorchestrierung. Es bietet erweiterte Funktionen für die Remote-Batch-Konfigurationsverwaltung über seine intuitive Benutzeroberfläche und API, mit unterstützender Dokumentation und zusätzlichen Sicherheitsvorkehrungen. Allerdings ähneln einzelne NGINX-Konfigurationsdateien stark dem Code und Softwareteams verfügen bereits über ein erstaunliches Tool zur Verwaltung des Codes: Git. Git bietet Entwicklern und Betriebsteams zahlreiche Funktionen für die Verwaltung von Textdatei-Workflows.

Die neue Integration von Instance Manager mit Git und anderen externen Systemen ermöglicht Funktionen wie Versionskontrolle, dezentrale Beiträge, Genehmigungs-Workflows und Teamkoordination. Plattformen wie GitHub und GitLab erweitern diesen Funktionsumfang um kontinuierliche Integration/kontinuierliche Bereitstellung (CI/CD), Zusammenarbeit, Problemverfolgung und andere wertvolle Funktionen über eine webbasierte Benutzeroberfläche.

In diesem Blogbeitrag veranschaulichen wir, wie GitHub zum Verwalten von NGINX-Konfigurationen verwendet werden kann, indem diese bei jeder Änderung automatisch an Instanzen gesendet werden.

Instanz-Manager-API

Instance Manager bietet eine Vielzahl von REST-APIs, die die Web-Benutzeroberfläche ergänzen. Ein wesentlicher Vorteil der API ist die Möglichkeit, Konfigurationsdateien der verwalteten Datenebeneninstanzen zu aktualisieren. Vor Kurzem haben wir diese Funktionalität erweitert , indem wir die Möglichkeit geschaffen haben, Konfigurationsaktualisierungen an eine bestimmte Version der Datei zu binden. Bei der Verwaltung in einem Git-Repository können Konfigurationen mit einem Git-Commit-Hash markiert werden. Darüber hinaus haben wir im Instance Manager einen neuen Status für extern verwaltete Konfigurationen implementiert, der potenzielle Dateieditoren warnt, dass die Konfigurationen extern verwaltet werden.

GitHub-Aktionen

GitHub ermöglicht Entwicklern die Erstellung benutzerdefinierter Bereitstellungspipelines in ihren Repositories mithilfe einer Funktion namens „Actions“ . Ein Benutzer kann eigene Aktionen definieren oder vorhandene Skripte über eine YAML-Definition aufrufen. Diese Pipelines können auf verschiedene Weise ausgelöst werden, etwa wenn ein Repository mit einem Commit oder einer Pull Request-Zusammenführung aktualisiert wird.

Im Beispiel dieses Blogs stützen wir uns auf sofort einsatzbereite GitHub-Aktionen und Linux-Befehle. Sie lernen, sie zu verwenden, um GitHub-verwaltete NGINX-Konfigurationsdateien auf Ihren NGINX-Instanzen über die Instance Manager-API zu aktualisieren. Befolgen Sie zunächst diese Schritte in GitHub Docs, um ein neues YAML zum Ausführen von Aktionen in Ihrem Repository zu erstellen.

Festlegen von Aktionsgeheimnissen

Instance Manager unterstützt verschiedene Formen der Authentifizierung . Im Beispiel verwenden wir die Methode der grundlegenden Authentifizierung , wir empfehlen jedoch die Bereitstellung einer OIDC-Authentifizierung in Produktionsumgebungen.

Anstatt die Anmeldeinformationen des Instance Managers im Repository zu speichern, können Sie mit GitHub Geheimnisse als Repository-Variablen definieren . Auf diese Variablen kann über die Actions-Umgebung zugegriffen werden, sie sind jedoch in Protokollen ausgeblendet. Befolgen Sie diese Schritte, um Benutzernamen und Kennwortschlüssel des Instance Managers als Geheimnisse zu speichern, damit Sie sie zur Authentifizierung Ihrer API-Aufrufe verwenden können.

Hier haben wir diese Variablen auf NMS_USERNAME und NMS_PASSWORD gesetzt.

Festlegen von Aktionsvariablen

Anstatt konstante Variablen in Ihrem YAML zu definieren, kann es ähnlich hilfreich sein, sie für die Verwaltung in der GitHub-Benutzeroberfläche auszugliedern. Auf der Seite „Variablen“ finden Sie Anweisungen zum Definieren von Variablen, die sich über alle Repository-Aktionen erstrecken. Im Beispiel nutzen wir diese Gelegenheit, um den FQDN oder die IP des Instanz-Managers ( NMS_HOSTNAME ), die Kennung des Systems, auf dem NGINX ausgeführt wird ( SYSTEM_ID ), und die Kennung der spezifischen NGINX-Instanz, die aktualisiert werden soll ( INSTANCE_ID ) zu definieren.

Notiz: Wir haben diese Variablen festgelegt, um unser Beispiel zu vereinfachen. Sie können die Identifizierungsinformationen für Instance Manager, System und NGINX jedoch auch anders verwalten. Sie können beispielsweise Verzeichnisse in Ihrem Repository erstellen, die Konfigurationen enthalten, die für verschiedene Instanzen spezifisch sind, und diese Verzeichnisse mit System- oder Instanz-IDs benennen. Sie können dann Ihr YAML- oder Aktionsskript ändern, um Verzeichnisnamen zu lesen und Konfigurationsdateien auf der entsprechenden Instanz zu aktualisieren.

Anatomie des Instance Manager-REST-API-Aufrufs zum Aktualisieren von NGINX-Konfigurationen

Damit der REST-API-Aufruf zur Konfigurationsaktualisierung des Instance Managers funktioniert, sind mehrere Schlüsselkomponenten erforderlich. Ihr YAML muss jeden dieser Parameter definieren und sie im richtigen Format in den API-Aufruf packen.

Im Beispiel verwenden wir den API-Aufruf zum Aktualisieren einer einzelnen Instanz. Es ist jedoch auch möglich, eine Instanzgruppe im Instance Manager zu konfigurieren. Auf diese Weise können Sie alle Instanzen in einer Gruppe aktualisieren, wenn eine neue Konfiguration von GitHub gepusht wird. Weitere Informationen finden Sie in unserer Anleitung zum Veröffentlichen von Konfigurationen .

Nachfolgend finden Sie eine Aufschlüsselung des REST-API-Aufrufs des Instance Managers zur Konfigurationsaktualisierung :

https://{INSTANCE MANAGER HOSTNAME}/api/platform/v1/systems/{SYSTEM ID}/instances/{INSTANCE ID}/config' 
--header "accept: application/json" 
--header "Authorization: Grundlegende {ANMELDEDATEN}" 
--header 'Content-Type: application/json'
--data '{
"configFiles": '{
"rootDir": "/etc/nginx",
"files": [{
"contents": "{NGINX-KONFIGURATIONSDATEI}",
"name": "{PFAD ZUR KONFIGURATIONSDATEI AUF DEM SYSTEM}"
}]
},
"externalIdType": "{QUELLE DER KONFIGURATIONEN}",
"externalId": "{COMMIT HASH}",
"updateTime": "{TIMESTAMP}"
}'}'

URI-Parameter

• Systemkennung – Ein eindeutiger Schlüssel, der das System identifiziert, auf dem NGINX ausgeführt wird. In unserem Beispiel sind diese Daten in der GitHub Actions Variables-Schnittstelle definiert.
• NGINX-Instanzkennung – Ein eindeutiger Schlüssel, der eine bestimmte NGINX-Instanz auf dem System identifiziert. In unserem Beispiel sind diese Daten in der GitHub Actions Variables-Schnittstelle definiert.

Header-Parameter

• Autorisierung – Die Autorisierungsmethode und die Base64-codierten Anmeldeinformationen, die der Instance Manager zur Authentifizierung des API-Aufrufs verwendet. Im Beispiel verwenden Sie die Basisautorisierung mit Anmeldedaten aus den im Repository festgelegten Geheimnissen.

JSON-Datenparameter

• configFiles – Der Base64-codierte Inhalt der zu aktualisierenden Konfigurationsdateien sowie deren Speicherorte auf dem System, auf dem NGINX ausgeführt wird. Sie müssen auch einen Pfad zum Stammverzeichnis Ihrer NGINX-Konfigurationsdateien angeben, das in der Regel wie folgt konfiguriert ist: /etc/nginx .
• externalIdType – Eine Bezeichnung, die dem Instance Manager die Quelle der Konfigurationsdatei identifiziert. Mögliche Werte sind „git“ oder „other“ . In unserem Beispiel codieren wir diesen Parameter fest in git .
• externalId – Der Git-Commit Secure Hash Algorithm (SHA), der die Änderung an den Konfigurationsdateien identifiziert.
• updateTime – Eine Zeichenfolge mit dem aktuellen Datum und der aktuellen Uhrzeit im Format %Y-%m-%dT%H:%M:%SZ .

Base64-Kodierung

Um der API-Spezifikation des Instance Managers gerecht zu werden, müssen Sie bestimmte Daten transformieren, indem Sie sie in das Base64-Format kodieren. Obwohl es keine native Möglichkeit gibt, dies mit vorhandenen GitHub-Aktionen zu erreichen, können wir auf Linux-Tools zurückgreifen, auf die über unser YAML zugegriffen werden kann.

Anmeldeinformationen des Instance-Managers

Beginnen Sie mit der Referenzierung der Anmeldeinformationen des Instance Managers, die zuvor als Geheimnisse definiert wurden, und verketten Sie diese. Konvertieren Sie dann die Zeichenfolge in Base64, geben Sie sie als Linux-Variable ( NMS_LOGIN ) wieder und hängen Sie das Ergebnis an eine vordefinierte Umgebungsvariable ( GITHUB_ENV ) an, auf die der Actions-Runner zugreifen kann.

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

Zeitstempel

Die Instance Manager-API erfordert, dass mit bestimmten API-Nutzdaten ein speziell formatierter Zeitstempel gesendet wird. Sie können den Zeitstempel in diesem Format mit dem Linux-Befehl „ date “ erstellen. Ähnlich wie im vorherigen Beispiel fügen wir die erstellte Zeichenfolge als Variable an die Linux-Umgebung an.

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

NGINX-Konfigurationen

Fügen Sie als Nächstes die NGINX-Konfigurationen, die Sie verwalten möchten, zum Repository hinzu. Es gibt viele Möglichkeiten, Dateien zu einem GitHub-Repository hinzuzufügen. Weitere Informationen finden Sie in dieser Anleitung in der GitHub-Dokumentation. Um unserem Beispiel zu folgen, können Sie in Ihrem GitHub-Repository eine Verzeichnisstruktur erstellen, die die der Instanz widerspiegelt.

Der folgende YAML-Eintrag liest die Konfigurationsdatei aus Ihrem Repository, kodiert ihren Inhalt in Base64 und fügt das Ergebnis wie zuvor einer Umgebungsvariablen hinzu.

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

In unserem Beispiel wiederholen wir dies für jede Konfigurationsdatei in unserem GitHub-Repository.

Alles zusammenfügen

Schließlich können Sie die Beispielreferenzimplementierung von GitHub verwenden, um das Gelernte in einer funktionierenden YAML-Datei zusammenzufügen. Wie in der Datei definiert, werden alle zugehörigen GitHub Actions-Skripte ausgeführt, wenn ein Benutzer das Repository über ein Commit oder einen Pull Request aktualisiert. Der letzte Eintrag im YAML führt einen Curl -Befehl aus, der den entsprechenden API-Aufruf durchführt und die erforderlichen Daten enthält, damit der Instance Manager alle zugehörigen Konfigurationsdateien aktualisieren kann.

Notiz: Verwenden Sie den mehrzeiligen Run-Eintrag ( run: | ) in Ihrem YAML, um den Curl -Befehl auszuführen, da dieser den YAML-Interpreter anweist, Doppelpunkte „:“ im Parameterteil des Eintrags als Text zu behandeln.

Name: Verwalten von NGINX-Konfigurationen mit GitHub und GitHub Actions 
# Steuert, wann der Workflow ausgeführt wird 
on: 
# Löst den Workflow bei Push- oder Pull-Request-Ereignissen aus, aber nur für den „main“-Zweig 
push: 
branches: [ „main“ ] 
pull_request: 
branches: [ „main“ ] 

# Ermöglicht Ihnen, diesen Workflow manuell über die Registerkarte „Aktionen“ auszuführen 
workflow_dispatch: 

# Ein Workflow-Lauf besteht aus einem oder mehreren Jobs, die nacheinander oder parallel ausgeführt werden können 
jobs: 
# Dieser Workflow enthält einen einzelnen Job namens „build“ 
build: 
# Der Runner-Typ, auf dem der Job ausgeführt wird 
runs-on: ubuntu-latest 

# Schritte stellen eine Abfolge von Aufgaben dar, die als Teil des Jobs ausgeführt werden 
steps: 
# Checkt Ihr Repository unter $GITHUB_WORKSPACE aus, damit Ihr Job darauf zugreifen kann 
- uses: actions/checkout@v4 

- Name: Umgebungsvariable für NMS API-Anmeldeinformationen festlegen 
ausführen: echo "NMS_LOGIN=`echo -n "${{ secrets.NMS_USERNAME }}:${{ secrets.NMS_PASSWORD }}" | base64`" >> $GITHUB_ENV 

- Name: Umgebungsvariable für NMS-API-Zeitstempel festlegen 
ausführen: echo "NMS_TIMESTAMP=`date -u +"%Y-%m-%dT%H:%M:%SZ"`" >> $GITHUB_ENV 

- Name: Umgebungsvariable für base64-kodierte Konfigurationsdatei festlegen 
Ausführen: echo "NGINX_CONF_CONFIG_FILE=`cat app-sfo-01/etc/nginx/nginx.conf | base64 -w 0`" >> $GITHUB_ENV 

- Name: Umgebungsvariable für base64-kodierte Konfigurationsdatei festlegen 
ausführen: echo "MIME_TYPES_CONFIG_FILE=`cat app-sfo-01/etc/nginx/mime.types | base64 -w 0`" >> $GITHUB_ENV 

- Name: Umgebungsvariable für base64-kodierte Konfigurationsdatei festlegen 
ausführen: echo "DEFAULT_CONF_CONFIG_FILE=`cat app-sfo-01/etc/nginx/conf.d/default.conf | base64 -w 0`" >> $GITHUB_ENV 

- Name: Umgebungsvariable für base64-kodierte Konfigurationsdatei festlegen 
ausführen: echo "SSL_CONF_CONFIG_FILE=`cat app-sfo-01/etc/nginx/conf.d/ssl.conf | base64 -w 0`" >> $GITHUB_ENV 

- Name: API-Aufruf an Instance Manager 
ausführen: | 
curl --location 'https://${{ vars.NMS_HOSTNAME }}/api/platform/v1/systems/${{ vars.SYSTEM_ID }}/instances/${{ vars.INSTANCE_ID }}/config' --header "accept: application/json" --header "Authorization: Grundlegend ${{ env.NMS_LOGIN }}" --header 'Inhaltstyp: 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 }}"}' 

NGINX-Referenzimplementierung

Das Ausführen eines API-Aufrufs zur Konfigurationsaktualisierung nach einer Dateiänderung kann auf verschiedene Arten erfolgen. Während GitHub Actions für GitHub-Benutzer die bequemste Methode ist, funktioniert es nicht für GitLab oder eigenständige Git-Implementierungen. Um diese Anwendungsfälle abzudecken, haben wir eine begleitende Shell-Skript- Referenzimplementierung entwickelt, die über die Befehlszeile ausgelöst oder von benutzerdefinierten Skripten aufgerufen werden kann.

Zusammenfassend lässt sich sagen, dass unsere neue Erweiterung der Instance Manager-API ein leistungsstarkes Tool für die moderne, dezentrale Verwaltung von Konfigurationsaktualisierungen, Rollbacks und Versionsverlaufen bietet. Durch die Kopplung der Erweiterung mit einer Textdatei- und Codeverwaltungsplattform eines Drittanbieters wie GitHub werden zusätzliche Funktionen für Workflow, CI/CD, Zusammenarbeit und Problemverfolgung über eine intuitive webbasierte Benutzeroberfläche ermöglicht.

Wir würden gerne Ihre Meinung hören! Probieren Sie es aus und teilen Sie uns in den Kommentaren oder durch Beitritt zu unserem NGINX Community Slack-Kanal mit, was Sie davon halten.