NGINX-Konfigurationen mit GitHub verwalten

Michael Vernik

Nina Forsyth

Softwareeinstellungen, Optionen und Konfigurationen gibt es in vielen verschiedenen Formen. Am einen Ende des Spektrums stehen elegante, reaktionsschnelle grafische Benutzeroberflächen, die intuitiv bedienbar sein sollen und zugleich ungültige Zustände verhindern. Am anderen Ende: Textdateien. Textdateien werden zwar sowohl von Entwicklern als auch von DevOps-Teams für ihre Übersichtlichkeit, ihr Automatisierungspotenzial und ihre geringen Nutzungsanforderungen geschätzt (Sie haben wahrscheinlich gerade ein paar Terminalfenster geöffnet, oder?), doch die Konfiguration von Software mithilfe solcher Dateien bringt auch deutliche Nachteile mit sich. Versuchen Sie beispielsweise einmal, einen Linux-Benutzer zu finden, der es noch nie geschafft hat, ein Softwarepaket durch eine fehlerhaft konfigurierte Textdatei zum Absturz zu bringen.

Als einzige All-in-One-Softwarelösung, die Proxy, Load Balancer, Webserver und API-Gateway vereint, ist NGINX eine zentrale Komponente der modernen Internetinfrastruktur. Diese Infrastruktur basiert in den meisten Fällen auf Betriebssystemen, denen der Linux-Kernel zugrunde liegt. Um diesem Ökosystem und den Fachleuten, die es betreuen, gerecht zu werden, setzt NGINX in hohem Maße auf textbasierte Konfigurationen.

Das F5 NGINX Instance Manager-Modul ist seit Langem die erste Wahl für die Orchestrierung von NGINX-Konfigurationen. Über seine intuitive Benutzeroberfläche und API bietet es erweiterte Funktionen für die Remote- und Stapelverwaltung von Konfigurationen sowie eine unterstützende Dokumentation und integrierte Schutzmechanismen. Einzelne NGINX-Konfigurationsdateien ähneln jedoch stark Programmcode, und Softwareteams verfügen bereits über ein hervorragendes Werkzeug zur Codeverwaltung: Git. Git bietet Entwicklungs- und Betriebsteams zahlreiche Funktionen zur Verwaltung von Arbeitsabläufen mit Textdateien.

Die neue Integration von Instance Manager mit Git und anderen externen Systemen ermöglicht Funktionen wie Versionskontrolle, dezentrale Mitwirkung, Genehmigungsworkflows und Teamkoordination. Plattformen wie GitHub und GitLab erweitern diesen Funktionsumfang über eine webbasierte Benutzeroberfläche um Continuous Integration/Continuous Deployment (CI/CD), Zusammenarbeit, Issue-Tracking und weitere nützliche Funktionen.

In diesem Blogbeitrag zeigen wir, wie sich GitHub zur Verwaltung von NGINX-Konfigurationen nutzen lässt, die bei jeder Änderung automatisch auf die Instanzen übertragen werden.

Instance-Manager-API

Instance Manager bietet eine umfangreiche Auswahl an REST-APIs, die seine Webbenutzeroberfläche ergänzen. Ein wesentlicher Vorteil der API besteht darin, dass sich damit die Konfigurationsdateien verwalteter Datenebeneninstanzen aktualisieren lassen. Vor Kurzem haben wir diese Funktionalität erweitert, sodass Konfigurationsaktualisierungen nun mit einer bestimmten Version der Datei verknüpft werden können. Bei der Verwaltung in einem Git-Repository können Konfigurationen mit einem Git-Commit-Hash gekennzeichnet werden. Darüber hinaus haben wir in Instance Manager einen neuen Status für extern verwaltete Konfigurationen implementiert, der potenzielle Bearbeiter darauf hinweist, dass die Konfigurationen extern verwaltet werden.

GitHub Actions

GitHub ermöglicht es Entwicklern, mithilfe einer Funktion namens „Actions“ benutzerdefinierte Bereitstellungspipelines in ihren Repositorys zu erstellen. Benutzer können eigene Actions definieren oder vorhandene Skripte über eine YAML-Definition aufrufen. Diese Pipelines können auf verschiedene Arten ausgelöst werden, beispielsweise wenn ein Repository durch einen Commit oder das Zusammenführen eines Pull Requests aktualisiert wird.

In diesem Blogbeispiel verwenden wir sofort einsatzbereite GitHub Actions und Linux-Befehle. Sie erfahren, wie Sie damit die von GitHub verwalteten NGINX-Konfigurationsdateien auf Ihren NGINX-Instanzen über die Instance Manager API aktualisieren. Befolgen Sie zunächst diese Schritte in der GitHub-Dokumentation, um eine neue YAML-Datei zum Ausführen von Actions in Ihrem Repository zu erstellen.

Actions-Secrets festlegen

Instance Manager unterstützt verschiedene Authentifizierungsformen. In diesem Beispiel verwenden wir die Standardauthentifizierung, empfehlen jedoch, in Produktionsumgebungen eine OIDC-Authentifizierung einzurichten.

Anstatt die Anmeldedaten für Instance Manager im Repository zu speichern, können Sie diese in GitHub als Repository-Variablen als Geheimnisse definieren. Auf diese Variablen kann die Actions-Umgebung zugreifen, sie werden jedoch nicht in Protokollen angezeigt. Führen Sie diese Schritte aus, um den Benutzernamen und das Passwort für Instance Manager als Geheimnisse zu speichern, damit Sie damit Ihre API-Aufrufe authentifizieren können.

Hier haben wir diese Variablen auf „NMS_USERNAME“ und „NMS_PASSWORD“ gesetzt.

Actions-Variablen festlegen

Ebenso kann es hilfreich sein, konstante Variablen nicht in Ihrer YAML-Datei zu definieren, sondern sie zur Verwaltung in die GitHub-Benutzeroberfläche auszulagern. Auf der Seite Variables finden Sie Anweisungen zum Definieren von Variablen, die für alle Actions des Repositorys gelten. In diesem Beispiel nutzen wir diese Möglichkeit, um den FQDN oder die IP-Adresse des Instance Managers (NMS_HOSTNAME), die Kennung des Systems, auf dem NGINX ausgeführt wird (SYSTEM_ID), und die Kennung der zu aktualisierenden NGINX-Instanz (INSTANCE_ID) zu definieren.

Hinweis: Wir haben diese Variablen festgelegt, um unser Beispiel zu vereinfachen. Sie können die Identifikationsinformationen für Instance Manager, System und NGINX jedoch auch auf andere Weise verwalten. Beispielsweise können Sie in Ihrem Repository Verzeichnisse erstellen, die spezifische Konfigurationen für verschiedene Instanzen enthalten, und diese Verzeichnisse nach den jeweiligen System- oder Instanz-IDs benennen. Anschließend können Sie Ihr YAML- oder Action-Skript so anpassen, dass es die Verzeichnisnamen ausliest und die Konfigurationsdateien auf der entsprechenden Instanz aktualisiert.

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

Der REST-API-Aufruf des Instance Managers zur Konfigurationsaktualisierung erfordert mehrere zentrale Komponenten. In Ihrer YAML-Datei müssen Sie jeden dieser Parameter definieren und im richtigen Format in den API-Aufruf einbinden.

In diesem Beispiel verwenden wir den API-Aufruf zum Aktualisieren einer einzelnen Instanz. Sie können im Instance Manager jedoch auch eine Instanzgruppe konfigurieren. Dadurch können Sie alle Instanzen einer Gruppe aktualisieren, sobald eine neue Konfiguration von GitHub übertragen wird. Weitere Informationen finden Sie in unserem Leitfaden zum Veröffentlichen von Konfigurationen.

Nachfolgend finden Sie eine Aufschlüsselung des REST-API-Aufrufs Konfigurationsaktualisierung von 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}"
}'}'

URI-Parameter

• Systemkennung – Ein eindeutiger Schlüssel zur Identifizierung des Systems, auf dem NGINX ausgeführt wird. In unserem Beispiel werden diese Daten in der Benutzeroberfläche für Variablen von GitHub Actions definiert.
• NGINX-Instanzkennung – Ein eindeutiger Schlüssel zur Identifizierung einer bestimmten NGINX-Instanz auf dem System. In unserem Beispiel werden diese Daten in der Benutzeroberfläche für GitHub Actions-Variablen definiert.

Header-Parameter

• Autorisierung – Die Autorisierungsmethode und die Base64-codierten Anmeldedaten, die Instance Manager zur Authentifizierung des API-Aufrufs verwendet. In diesem Beispiel verwenden Sie die Basic-Authentifizierung mit Anmeldedaten aus den im Repository hinterlegten Secrets.

JSON-Datenparameter

• configFiles – Der Base64-codierte Inhalt der zu aktualisierenden Konfigurationsdateien sowie deren Speicherorte auf dem System, auf dem NGINX ausgeführt wird. Außerdem müssen Sie den Pfad zum Stammverzeichnis Ihrer NGINX-Konfigurationsdateien angeben. Dieser lautet in der Regel: /etc/nginx.
• externalIdType – Eine Bezeichnung, die dem Instance Manager die Quelle der Konfigurationsdatei angibt. Mögliche Werte sind git oder other. In unserem Beispiel legen wir diesen Parameter fest auf git.
• externalId – Der Secure Hash Algorithm (SHA) des Git-Commits, der die Änderung an den Konfigurationsdateien identifiziert.
• updateTime – Eine Zeichenfolge, die das aktuelle Datum und die aktuelle Uhrzeit im Format %Y-%m-%dT%H:%M:%SZ enthält.

Base64-Kodierung

Um die API-Spezifikation von Instance Manager zu erfüllen, müssen Sie bestimmte Daten durch Base64-Kodierung umwandeln. Da die vorhandenen GitHub Actions hierfür keine native Möglichkeit bieten, können wir auf Linux-Tools zurückgreifen, die über unsere YAML-Datei zugänglich sind.

Anmeldedaten für den Instance Manager

Verweisen Sie zunächst auf die zuvor als Secrets definierten Anmeldedaten für den Instance Manager und verketten Sie diese. Konvertieren Sie die Zeichenfolge anschließend in Base64, geben Sie sie als Linux-Variable (NMS_LOGIN) aus und hängen Sie das Ergebnis an eine vordefinierte Umgebungsvariable (GITHUB_ENV) an, auf die der Actions Runner zugreifen kann.

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

Zeitstempel

Die Instance Manager API erfordert, dass bei bestimmten API-Nutzdaten ein speziell formatierter Zeitstempel mitgesendet wird. Sie können den Zeitstempel in diesem Format mit dem Linux-Befehl date erstellen. Fügen Sie die erstellte Zeichenfolge wie im vorherigen Beispiel als Variable zur Linux-Umgebung hinzu.

run: 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 der Verzeichnisstruktur der Instanz entspricht.

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

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

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

Alles zusammenführen

Abschließend können Sie die Referenzimplementierung von GitHub als Beispiel verwenden, um das Gelernte in einer funktionsfähigen YAML-Datei zusammenzuführen. Wie in der Datei festgelegt, werden alle zugehörigen GitHub-Actions-Skripte ausgeführt, sobald ein Benutzer das Repository durch einen Commit oder Pull-Request aktualisiert. Der letzte Eintrag in der YAML-Datei führt einen curl-Befehl aus, der den entsprechenden API-Aufruf mit den erforderlichen Daten durchführt, damit Instance Manager alle zugehörigen Konfigurationsdateien aktualisieren kann.

Hinweis: Verwenden Sie den mehrzeiligen run-Eintrag (run: |) in Ihrer YAML-Datei, um den Befehl curl auszuführen, da der YAML-Interpreter dadurch angewiesen wird, Doppelpunkte („:“) im Parameterteil des Eintrags als Text zu behandeln.

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 }}"}' 

NGINX-Referenzimplementierung

Das Ausführen eines API-Aufrufs zur Konfigurationsaktualisierung nach einer Dateiänderung kann auf unterschiedliche Weise erfolgen. GitHub Actions ist zwar die bequemste Methode für GitHub-Nutzer, funktioniert jedoch nicht mit GitLab oder eigenständigen Git-Implementierungen. Für diese Anwendungsfälle haben wir ein begleitendes Shell-Skript als Referenzimplementierung entwickelt, das ü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 Werkzeug bietet, um Konfigurationsaktualisierungen, Rollbacks und Versionsverläufe auf moderne, dezentrale Weise zu verwalten. Durch die Verknüpfung der Erweiterung mit einer externen Plattform zur Verwaltung von Textdateien und Code wie GitHub stehen über eine intuitive webbasierte Benutzeroberfläche zusätzliche Funktionen für Workflows, CI/CD, Zusammenarbeit und die Nachverfolgung von Problemen zur Verfügung.

Wir würden uns über Ihr Feedback freuen! Probieren Sie es aus und teilen Sie uns Ihre Meinung in den Kommentaren oder in unserem NGINX Community Slack-Kanal mit.

Über die Autoren

Michael Vernik

Weitere Blogbeiträge von Michael Vernik

Nina Forsyth

Weitere Blogbeiträge von Nina Forsyth