Verwalten der Agentenkonfiguration mithilfe von Git

Wenn Sie das Git Repository selbst hosten, können Sie ein selbstsigniertes Zertifikat verwenden. Damit der Agent eine sichere Verbindung zu einem Git Repository herstellen kann, müssen Sie das selbstsignierte Zertifikat in den Java-Truststore importieren. Weitere Informationen finden Sie unter Selbstsignierte Zertifikate.

Der Zugriff auf ein Git Repository kann autorisiert werden, indem eine .netrc Datei verwendet wird, um das Passwort oder den Zugriffstoken bereitzustellen. .netrc ist weit verbreitet und Details dazu finden Sie auf der .netrc-Manpage.

Sie können die .netrc Datei im Home-Verzeichnis des Benutzers (z. B. root) konfigurieren, auf dem der Instana-Host-Agent ausgeführt wird. Siehe die folgende .netrc Beispieldatei für das github.com Repository:

machine github.com
login oauth2
password <access_token>

Im Repository Git müssen Sie dieselbe Verzeichnisstruktur wie in haben *instanaAgentDir*/etc. Wenn Sie beispielsweise Daten aus der Git Datei mit dem Namen configuration-mysql.yamlabrufen möchten, muss diese Datei im Git Verzeichnis mit dem Namen instana abgelegt sein (d. h. die Datei instana/configuration-mysql.yaml). Andernfalls wird die Datei beim Abruf aus dem Git Repository am falschen Speicherort auf dem Server abgelegt und vom Instana-Host-Agent nicht verwendet.

Die folgende Abbildung zeigt die Beispielstruktur eines Git Repositorys:

repository-root/
├── instana/
│   ├── configuration-mysql.yaml
│   └── com.instana.agent.main.config.UpdateManager.cfg
└── org.ops4j.pax.url.mvn.cfg

Bei Verwendung von systemd lassen sich die zusätzlichen Parameter am einfachsten über eine Drop-in-Datei festlegen. Um den Pfad zum Drop-in-Verzeichnis anzuzeigen, führen Sie den folgenden Befehl aus:

systemctl status instana-agent

Die Dateien in diesem Verzeichnis müssen die Dateiendung haben .conf, andernfalls werden die Dateien ignoriert.

1. Erstellen Sie eine neue Datei im /etc/systemd/system/instana-agent.service.d/ Verzeichnis mit der Erweiterung .conf, z. B. git-configuration-environments.conf.
2. Fügen Sie der Datei folgenden Inhalt hinzu:

   [Service]
   Environment=INSTANA_GIT_REMOTE_BRANCH=<branch>
   Environment=INSTANA_GIT_REMOTE_REPOSITORY=<repository_url>
   Environment=INSTANA_GIT_REMOTE_USERNAME=<username>
   Environment=INSTANA_GIT_REMOTE_PASSWORD=<access_token>
   ```   **Notes:**
    - Replace *<branch>* with the name of the remote branch that the Instana host agent connects to.
    - Replace *<repository_url>* with the URL of the remote Git repository; for example, `https://github.com/<your_account>/<your_repo>.git`.
    - Replace *<username>* with a username or access token (for basic authentication). If you are using a `.netrc` file or a public repository, you can remove the whole line `Environment=INSTANA_GIT_REMOTE_USERNAME=<username>`.
    - Replace *<access_token>* with an access token. If you are using an access token as username (basic authentication), a `.netrc` file, or a public repository, you can remove the whole line `Environment=INSTANA_GIT_REMOTE_PASSWORD=<access_token>`.
   
   

Nachdem Sie eine Drop-In-Datei hinzugefügt oder geändert haben, führen Sie die folgenden Schritte aus:

1. Laden Sie die Drop-in-Dateien neu, indem Sie den Befehl systemctl daemon-reload ausführen.
2. Starten Sie den Instana-Host-Agent neu, indem Sie den Befehl systemctl restart instana-agent ausführen.

Wenn Sie die folgenden Umgebungsvariablen festgelegt haben, überprüft der Host-Agent beim Start, ob das lokale Git Repository im *instanaAgentDir*/etc/ Ordner vorhanden ist. Wenn das lokale Git Repository nicht vorhanden ist, erstellt der Host-Agent ein lokales Repository, das mit dem Remote-Repository verbunden ist.

Wenn der Instana-Agent direkt auf einem Host ausgeführt wird, müssen die folgenden Umgebungsvariablen auf dem Host festgelegt werden. Wenn der Host-Agent in einer containerisierten Umgebung ausgeführt wird, legen Sie die Variablen auf Containerebene fest.

Siehe die -g, -b, -u und -p Optionen in der OneLiner Dokumentation, die den INSTANA_GIT_REMOTE_REPOSITORYUmgebungsvariablen INSTANA_GIT_REMOTE_PASSWORD , INSTANA_GIT_REMOTE_BRANCH, INSTANA_GIT_REMOTE_USERNAME und für die zugeordnet Umweltmethode sind.

Die folgende Tabelle zeigt die Zuordnung zwischen den Umgebungsvariablen und den Parametern des Einzeiler-Befehls:

Die Schritte sind im Wesentlichen dieselben wie bei der Umgebungsmethode, indem die INSTANA_GIT_REMOTE_REPOSITORYUmgebungsvariablen INSTANA_GIT_REMOTE_PASSWORD , INSTANA_GIT_REMOTE_BRANCH, INSTANA_GIT_REMOTE_USERNAME und zum Docker Container hinzugefügt werden.

Das folgende Codebeispiel enthält beispielsweise die Parameter, die zum Starten des Host-Agenten in einem Container erforderlich sind, sowie die erforderlichen Git Parameter zum Aktivieren der Git -basierten Konfigurationsverwaltung:

# Please enter proper values for all --env arguments.
docker run \
   --detach \
   --name instana-agent \
   --volume /var/run:/var/run \
   --volume /run:/run \
   --volume /dev:/dev:ro \
   --volume /sys:/sys:ro \
   --volume /var/log:/var/log:ro \
   --privileged \
   --net=host \
   --pid=host \
   --env="INSTANA_AGENT_ENDPOINT=" \
   --env="INSTANA_AGENT_ENDPOINT_PORT=" \
   --env="INSTANA_AGENT_KEY=" \
   --env="INSTANA_DOWNLOAD_KEY=" \
   --env="INSTANA_AGENT_ZONE=" \
   --env="INSTANA_GIT_REMOTE_BRANCH=" \
   --env="INSTANA_GIT_REMOTE_PASSWORD=" \
   --env="INSTANA_GIT_REMOTE_REPOSITORY=" \
   --env="INSTANA_GIT_REMOTE_USERNAME=" \
   icr.io/instana/agent

Die Git -basierte Konfigurationsverwaltung kann im Abschnitt „Konfigurationsverwaltung“ auf dem Dashboard „Agentenverwaltung“ eingerichtet werden.

Die Git -basierte Konfigurationsverwaltung kann mithilfe der API initialisiert und konfiguriert werden, wie im Host Agent Abschnitt der Web-REST-API-Dokumentation beschrieben.

Eine manuelle Einrichtung besteht aus der Initialisierung eines Git Repositorys im *instanaAgentDir*/etc/ Ordner und dem Hinzufügen einer remote mit dem Namen configuration.

Der Host-Agent ruft den lokalen main Zweig unter Verwendung des konfigurierten Tracking-Zweigs aus dem configuration Remote-Zweig ab. Es gibt mehrere Möglichkeiten, das Git-Repository zu konfigurieren, und Sie können frei wählen, was am besten zu Ihrer Konfiguration passt.

Mit der folgenden Konfiguration können Sie beispielsweise den Host-Agenten Konfigurationen aus dem main Zweig des configuration Remotes abrufen:

etc> git init
etc> git remote add -m main -t main configuration <git-repository-url>
etc> git fetch configuration
etc> git checkout -f -b main --track configuration/main

Mit dem folgenden Beispiel können Sie die Konfigurationen aus dem my-configurations Zweig im configuration Remote abrufen:

etc> git init
etc> git remote add -m main -t my-configurations configuration <git-repository-url>
etc> git fetch configuration
etc> git checkout -f -b main --track configuration/my-configurations

Mögliche <git-repository-url> Formate sind in der offiziellen Dokumentation zu Git URLs beschrieben.

Git Hooks sind Programme, die Sie im .git/hooks Verzeichnis des Repositorys ablegen können und die zu verschiedenen Zeitpunkten im Lebenszyklus Ihres Git Repositorys ausgelöst werden. Git bietet viele verschiedene Hooks, und der post-update Hook eignet sich am besten für die Integration in die Git -basierte Konfigurationsverwaltung von Host-Agenten.

Das GitOps-Demo Repository stellt einen Gitpost-update Beispiel-Hook bereit, der die Aktualisierung der Host-Agenten auslöst, sobald ein Zweig im Repository aktualisiert wird.

Sie sehen, dass die erwartete Ausgabe des Skripts an Ihren Git Client zurückgesendet wird, nachdem Sie einen Push ausgelöst haben:

$ gitops-test# git push origin HEAD:main
[detached HEAD 9632c09] origin
 1 file changed, 1 insertion(+), 1 deletion(-)
Enumerating objects: 7, done.
Counting objects: 100% (7/7), done.
Delta compression using up to 12 threads
Compressing objects: 100% (3/3), done.
Writing objects: 100% (4/4), 376 bytes | 376.00 KiB/s, done.
Total 4 (delta 1), reused 0 (delta 0)
remote: GitOps update: Triggering the configuration update of agents matching the following query: 'entity.zone:"test"' ... OK
   699ada9..9632c09  HEAD -> main

Mit GitHub der Instana-Aktion für GitOps können Sie die Remote-Funktion der Host-Agenten ganz einfach über die Web-API von Instana auslösen.

Das GitOps-Demo Repository zeigt, wie Sie ein Repository einrichten, GitHub um Ihre Host-Agent-Konfigurationen zu verwalten, und wie Sie die Aktualisierungen automatisch auslösen können, indem Sie die GitHub Instana-Aktion für verwenden GitOps.

GitHub Unterstützt HTTPS die Authentifizierung mithilfe von Tokens, die vom Host-Agenten wie in diesem Abschnitt beschrieben verwendet werden können.

Um ein GitHub Repository zu verwenden, müssen Sie zunächst einen persönlichen Zugriffstoken erstellen. Einzelheiten dazu finden Sie auf der Dokumentationsseite Erstellen GitHub eines persönlichen Zugriffstokens. Das Token benötigt nur Leseberechtigungen für den Zugriff auf das Repository.

GitHub erwartet, dass das Token als Benutzername HTTPS für die Basisauthentifizierung mit einem leeren Passwort bereitgestellt wird. Daher kann der Host-Agent so konfiguriert werden, dass er die Basisauthentifizierung HTTPS für GitHub Repositorys verwendet, indem die folgenden Umgebungsvariablen gesetzt werden:

INSTANA_GIT_REMOTE_REPOSITORY='https://github.com/<user/organization>/<repository>.git
INSTANA_GIT_REMOTE_BRANCH='<branch>'
INSTANA_GIT_REMOTE_USERNAME='<token>'
INSTANA_GIT_REMOTE_PASSWORD=''

Beachten Sie, dass das gleiche Prinzip des leeren Passworts und des persönlichen Tokens als Benutzername auch bei den anderen Möglichkeiten zur Konfiguration des Host-Agenten für die Git -basierte Konfigurationsverwaltung gilt. Eine Übersicht über die möglichen Konfigurationsansätze finden Sie im Abschnitt „Einrichtung “.

Sie können mehrere Methoden verwenden, um die Versionsaktualisierungen für den Host-Agenten zu steuern, der in Ihren Produktionsumgebungen bereitgestellt wird. Wenn Sie statische Agenten verwenden, müssen Sie den Host-Agenten nach Bedarf manuell aktualisieren. Wenn Sie dynamische Agenten verwenden, können Sie die Updates so konfigurieren, dass Sie Update-Intervalle, festgelegte Versionen usw. festlegen können. Weitere Informationen finden Sie unter Konfigurieren von Updates für dynamische Host-Agenten. Wenn keine Konfiguration angegeben ist, werden Updates automatisch täglich auf den dynamischen Agenten angewendet. Wenn Sie eine strengere Kontrolle über die Versionsaktualisierungen des Host-Agenten benötigen, können Sie zusätzlich eine Kombination aus dynamischer Agent-Versionsfixierung und Git -basierter Konfigurationsverwaltung verwenden. Wenn Sie über eine Testumgebung verfügen, können Sie die Agent-Bereitstellungen in einem produktionsähnlichen Szenario testen, bevor Sie das Update in der Produktion anwenden.