Übertragungs-Agents verwalten

Storage Transfer Service-Agents sind Anwendungen, die in einem Docker-Container ausgeführt werden und sich für Übertragungen mit Dateisystemen oder S3-kompatiblen Speicher mit Storage Transfer Service abstimmen.

Wenn Sie zur Übertragung kein Dateisystem oder einen S3-kompatiblen Speicher verwenden, müssen Sie keine Agents einrichten.

Für Weiterleitungen von Amazon S3 ist kein Kundenservicemitarbeiter erforderlich. S3-kompatibler Speicher bezieht sich auf Speichersysteme, die die S3 API verwenden, aber nicht direkt von Amazon gehostet werden.

In diesem Dokument wird beschrieben, wie Sie Übertragungs-Agents auf Ihren Servern verwalten.

Überblick

• Agent-Prozesse sind dynamisch. Sie können während der Übertragung auch Agents hinzufügen, um die Leistung zu verbessern. Neu gestartete Agents werden dem entsprechenden Agent-Pool hinzugefügt und sind an der Verarbeitung vorhandener Übertragungen beteiligt. Damit können Sie anpassen, wie viele Agents ausgeführt werden, oder die Übertragungsleistung an die sich ändernde Übertragungsnachfrage anpassen.

• Agent-Prozesse sind eine fehlertolerante Sammlung. Wenn ein Agent nicht mehr ausgeführt wird, funktionieren die verbleibenden Agents weiterhin. Wenn alle Ihre Agents angehalten werden und Sie die Agents neu starten, wird die Übertragung an der Stelle fortgesetzt, an der die Agents angehalten wurden. Auf diese Weise können Sie vermeiden, Agents zu überwachen, Übertragungen zu wiederholen oder Wiederherstellungslogik zu implementieren. Wenn Sie Agents mit Google Kubernetes Engine koordinieren, können Sie Ihre Agent-Pools ohne Ausfallzeiten bei der Übertragung patchen, verschieben und dynamisch skalieren.

  Beispiel: Sie senden zwei Übertragungen, während zwei Agents ausgeführt werden. Wenn einer der Agents aufgrund eines Neustarts oder Betriebssystem-Patches gestoppt wird, funktioniert der verbleibende Agent weiterhin. Die beiden Übertragungen werden weiterhin ausgeführt, sind jedoch langsamer, da ein einzelner Agent Daten verschiebt. Wenn der verbleibende Agent ebenfalls beendet wird, werden alle Übertragungen unterbrochen, da keine Agents ausgeführt werden. Wenn Sie die Agent-Prozesse neu starten, werden die Übertragungen an der Stelle fortgesetzt, an der sie unterbrochen wurden.

• Agent-Prozesse gehören zu einem Pool. Sie verschieben Ihre Daten parallel. Aus diesem Grund müssen alle Agents in einem Pool denselben Zugriff auf alle Datenquellen haben, die Sie übertragen möchten.

  Wenn Sie beispielsweise Daten aus einem bestimmten Dateisystem übertragen, müssen Sie das Dateisystem auf jedem Computer bereitstellen, auf dem Agents in Ihrem Agent-Pool gehostet werden. Wenn einige Agents in Ihrem Pool eine Datenquelle erreichen können und andere nicht, sind Übertragungen von dieser Datenquelle nicht erfolgreich.

Hinweise

Bevor Sie die Übertragungen konfigurieren, müssen Sie folgenden Zugriff konfiguriert haben: für Nutzer und Dienstkonten.

Wenn Sie gcloud-Befehle verwenden, installieren Sie die gcloud CLI.

Übertragungs-Agents installieren und ausführen

Wichtig: Nutzer, die Übertragungsjobs erstellen können, können Daten aus jedem Dateisystemverzeichnis, auf das der Agent zugreifen kann, abrufen und herunterladen. Wenn Agents als Root ausgeführt werden und Zugriff auf das gesamte Dateisystem erhalten, kann ein böswilliger Akteur möglicherweise den Host übernehmen. Es wird dringend empfohlen, den Agent-Zugriff auf erforderliche Verzeichnisse zu beschränken.

Wir empfehlen, mindestens drei Agents pro Agent-Pool zu installieren, idealerweise auf separaten Maschinen. Weitere Informationen zum Festlegen, wie viele Agents ausgeführt werden sollen, finden Sie unter Leistung des Übertragungs-Agents maximieren.

Das Agent-ID-Präfix sollte keine vertraulichen Informationen wie personenidentifizierbare Informationen oder Sicherheitsdaten enthalten. Ressourcennamen können an die Namen anderer Google Cloud-Ressourcen weitergegeben und für Google-interne Systeme außerhalb Ihres Projekts bereitgestellt werden.

So installieren und führen Sie Übertragungs-Agents aus:

12. April 2023:Agents, die für Übertragungen aus einem S3-kompatiblen Speicher verwendet werden, müssen sich mit einem Dienstkontoschlüssel authentifizieren. Verwenden Sie das Flag --creds-file, um den Pfad zu einer Dienstkonto-Schlüsseldatei anzugeben. Wenn ein Dienstkonto nicht verwendet wird, verzögert sich die Übertragung. Der Job wird als in Bearbeitung angezeigt, es werden jedoch keine Daten übertragen.

Dieser Hinweis wird entfernt, sobald das Problem behoben ist.

Google Cloud Console

1. Rufen Sie in der Google Cloud Console die Seite Agent-Pools auf.

   Zu „Agent-Pools“

2. Wählen Sie den Agent-Pool aus, dem Sie den neuen Agent hinzufügen möchten.

3. Klicken Sie auf Agent installieren.

4. Folgen Sie der Anleitung, um den Agent zu installieren und auszuführen.

   Weitere Informationen zu den Befehlszeilenoptionen des Agents finden Sie unter Agent-Befehlszeilenoptionen.

gcloud-CLI

Wenn Sie einen oder mehrere Agents mithilfe der gcloud CLI installieren möchten, führen Sie gcloud transfer agents install aus:

gcloud transfer agents install --pool=POOL_NAME --count=NUM_AGENTS \
  --mount-directories=MOUNT_DIRECTORIES

Das Tool führt Sie durch die erforderlichen Schritte zur Installation des Agents. Dieser Befehl installiert NUM_AGENTS Agents auf Ihrem Computer, die dem Poolnamen angegeben als POOL_NAME zugeordnet sind und authentifiziert die Agents mithilfe Ihrer gcloud-Anmeldedaten. Der Poolname muss vorhanden sein oder ein Fehler wird zurückgegeben.

Das Flag --mount-directories ist optional, wird aber dringend empfohlen. Der Wert ist eine durch Kommas getrennte Liste von Verzeichnissen im Dateisystem, auf die dem Agent Zugriff gewährt werden soll. Durch Weglassen dieses Flags wird das gesamte Dateisystem für den Agent-Container bereitgestellt. Weitere Informationen finden Sie in der Referenz zu gcloud.

S3-kompatible Quellen

Wenn Sie Agents installieren, um sie mit einer S3-kompatiblen Quelle zu verwenden, müssen Sie AWS-Anmeldedaten entweder als Umgebungsvariablen als Werte von AWS_ACCESS_KEY_ID und AWS_SECRET_ACCESS_KEY oder als Standardanmeldedaten in den Konfigurationsdateien Ihres Systems angeben.

export AWS_ACCESS_KEY_ID=ID
export AWS_SECRET_ACCESS_KEY=SECRET
gcloud transfer agents install --pool=POOL_NAME \
  --creds-file=/relative/path/to/service-account-key.json

Dienstkontoschlüssel verwenden

Hinweis: Dienstkontoschlüssel stellen ein Sicherheitsrisiko dar, wenn sie nicht ordnungsgemäß verwaltet werden. Sie sollten nach Möglichkeit eine sicherere Alternative zu Dienstkontoschlüsseln auswählen. Wenn Sie sich mit einem Dienstkontoschlüssel authentifizieren müssen, sind Sie für die Sicherheit des privaten Schlüssels und für andere Vorgänge verantwortlich, die unter Best Practices für die Verwaltung von Dienstkontoschlüsseln beschrieben werden. Wenn Sie keinen Dienstkontoschlüssel erstellen können, ist das Erstellen von Dienstkontoschlüsseln für Ihre Organisation möglicherweise deaktiviert. Weitere Informationen finden Sie unter Standardmäßig sichere Organisationsressourcen verwalten.

Verwenden Sie die Option --creds-file, um Agents mit einem Dienstkontoschlüssel auszuführen:

gcloud transfer agents install --pool=POOL_NAME --count=NUM_AGENTS \
   --creds-file=/relative/path/to/service-account-key.json

Weitere Informationen

Für eine vollständige Liste der optionalen Flags führen Sie gcloud transfer agents install --help aus oder lesen Sie die Referenz zu gcloud transfer.

docker run

Bevor Sie docker run zum Installieren von Agents verwenden, folgen Sie der Anleitung zum Installieren von Docker.

Mit dem Befehl docker run wird ein Agent installiert. Wenn Sie die Anzahl der Agents in Ihrem Pool erhöhen möchten, führen Sie diesen Befehl so oft wie nötig aus.

Bei der Installation von Agents können Sie sich mit Ihren gcloud-Standardanmeldedaten oder mit einem Dienstkonto authentifizieren.

Standardanmeldedaten

Damit sich der Docker-Container mit Ihren gcloud-Standardanmeldedaten authentifizieren kann, erstellen Sie mit dem folgenden Befehl ein Docker-Volume, das eine Datei mit den Standardanmeldedaten Ihrer Anwendung enthält:

sudo docker run -ti --name gcloud-config google/cloud-sdk gcloud auth application-default login

Verwenden Sie dann den folgenden Befehl, um einen Agent zu installieren. Verwenden Sie dazu das Flag --volumes-from, um das Volume gcloud-config mit den Anmeldedaten bereitzustellen:

sudo docker run --ulimit memlock=64000000 -d --rm \
--volumes-from gcloud-config \
-v HOST_DIRECTORY:CONTAINER_DIRECTORY \
gcr.io/cloud-ingest/tsop-agent:latest \
--project-id=PROJECT_ID \
--hostname=$(hostname) \
--agent-pool=POOL_NAME

Dienstkontoauthentifizierung

Wenn Sie die Übertragungs-Agents docker run mit Dienstkonto-Anmeldedaten installieren und ausführen möchten, geben Sie den Pfad zu Ihrem Dienstkontoschlüssel im JSON-Format mit dem Flag --creds-file an.

Dem Pfad muss der String /transfer_root vorangestellt werden.

Weitere Informationen finden Sie unter Dienstkontoschlüssel erstellen und verwalten.

Hinweis: Dienstkontoschlüssel stellen ein Sicherheitsrisiko dar, wenn sie nicht ordnungsgemäß verwaltet werden. Sie sollten nach Möglichkeit eine sicherere Alternative zu Dienstkontoschlüsseln auswählen. Wenn Sie sich mit einem Dienstkontoschlüssel authentifizieren müssen, sind Sie für die Sicherheit des privaten Schlüssels und für andere Vorgänge verantwortlich, die unter Best Practices für die Verwaltung von Dienstkontoschlüsseln beschrieben werden. Wenn Sie keinen Dienstkontoschlüssel erstellen können, ist das Erstellen von Dienstkontoschlüsseln für Ihre Organisation möglicherweise deaktiviert. Weitere Informationen finden Sie unter Standardmäßig sichere Organisationsressourcen verwalten.

sudo docker run --ulimit memlock=64000000 -d --rm \
-v HOST_DIRECTORY:CONTAINER_DIRECTORY \
-v PATH/TO/KEY.JSON:PATH/TO/KEY.JSON \
gcr.io/cloud-ingest/tsop-agent:latest \
--project-id=PROJECT_ID \
--creds-file=/transfer_root/PATH/TO/KEY.JSON
--hostname=$(hostname) \
--agent-pool=POOL_NAME

Optionen und Flags

Ersetzen Sie die Variablen in den obigen Beispielen durch die folgenden Informationen:

• HOST_DIRECTORY ist das Verzeichnis auf dem Hostcomputer, aus dem Sie kopieren möchten. Sie können mehr als ein -v-Flag verwenden, um zusätzliche Verzeichnisse anzugeben, aus denen kopiert werden soll.
• CONTAINER_DIRECTORY ist das Verzeichnis, das dem Agent-Container zugeordnet ist. Er muss mit HOST_DIRECTORY identisch sein.
• PROJECT_ID ist die Projekt-ID, in der die Übertragung gehostet wird.
• POOL_NAME ist der Name des Agent-Pools, in dem dieser Agent installiert werden soll. Wenn Sie dieses Flag weglassen, wird der Agent im Pool transfer_service_default Ihres Projekts installiert.

Der Befehl docker run unterstützt zusätzliche Flags.

• --enable-mount-directory stellt das gesamte Dateisystem im Verzeichnis /transfer_root im Container bereit. Wenn --enable-mount-directory angegeben ist, werden Verzeichniseinschränkungen mit dem Flag -v nicht angewendet.

  Achtung: Wenn Agents als Root ausgeführt werden und Zugriff auf das gesamte Dateisystem erhalten, kann ein böswilliger Akteur möglicherweise den Host übernehmen. Es wird dringend empfohlen, den Agent-Zugriff auf notwendige Verzeichnisse zu beschränken.

• --creds-file=CREDENTIAL_FILE gibt den Pfad zu einer Datei mit Anmeldedaten für Dienstkonten im JSON-Format an. Wenn Sie --enable_mount_directory nicht verwenden, müssen Sie Folgendes tun:

  1. Stellen Sie die Datei mit den Anmeldedaten mit dem Flag -v bereit.
  2. Stellen Sie dem Pfad zu --creds-file das Präfix /transfer_root voran.

  Beispiel:

  -v /tmp/key.json:/tmp/key.json \
  --creds-file=/transfer_root/tmp/key.json
  

• --enable-s3 gibt an, dass dieser Agent für Übertragungen aus einem S3-kompatiblen Speicher bestimmt ist. Agents, die mit dieser Option installiert sind, können nicht für Übertragungen von POSIX-Dateisystemen verwendet werden.

• Wenn die Übertragung aus einem AWS S3- oder S3-kompatiblen Speicher stammt, geben Sie Ihre Zugriffsschlüssel-ID und Ihren geheimen Schlüssel mithilfe von Umgebungsvariablen weiter:

  -e AWS_ACCESS_KEY_ID=AWS_ACCESS_KEY_ID \
  -e AWS_SECRET_ACCESS_KEY=AWS_SECRET_ACCESS_KEY
  

• --env HTTPS_PROXY=PROXY gibt einen Weiterleitungsproxy in Ihrem Netzwerk an. Der Wert von PROXY ist die HTTP-URL und der Port des Proxyservers. Achten Sie darauf, die HTTP-URL und keine HTTPS-URL anzugeben, damit Anfragen in der TLS-Verschlüsselung nicht doppelt verpackt werden. Doppelt verpackte Anfragen verhindern, dass der Proxyserver gültige ausgehende Anfragen sendet.

• --agent-id-prefix=ID_PREFIX gibt ein optionales Präfix an, das der Agent-ID vorangestellt wird, um den Agent oder seinen Computer in der Google Cloud Console zu identifizieren. Wenn ein Präfix verwendet wird, hat die Agent-ID das Format prefix + hostname + Docker container ID.

• --log-dir=LOGS_DIRECTORY ändert das Verzeichnis, in das der Agent Logs schreibt. Das Standardverzeichnis ist /tmp/.

  Wenn Sie --enable_mount_directory nicht angegeben haben, müssen Sie diesem Pfad das Präfix /transfer_root voranstellen. Beispiel: /transfer_root/logs.

• --max-physical-mem=MAX_MEMORY: Agents verwenden standardmäßig maximal 8 GiB Systemspeicher. Wenn der Standardwert nicht zu Ihrer Umgebung passt, können Sie in den folgenden Formaten eine geeignete maximale Speichernutzung angeben:

  max-physical-mem Wert	Einstellung für den maximalen Arbeitsspeicher
  6g	6 Gigabyte
  6gb	6 Gigabyte
  6GiB	6 Gibibyte

Agent-Verbindungen bestätigen

So prüfen Sie, ob Ihre Agents verbunden sind:

1. Rufen Sie in der Google Cloud Console die Seite Agent-Pools auf.

   Zu „Agent-Pools“

   Ihre Agent-Pools werden mit der Anzahl der verbundenen Agents angezeigt.

2. Wählen Sie einen Agent-Pool aus, um Details zu verbundenen Agents aufzurufen.

Wenn ein neuer Agent nicht innerhalb von zehn Minuten nach der Erstellung auf der Seite des Agent-Pools angezeigt wird, finden Sie weitere Informationen unter Agents sind nicht verbunden.

Agent-Aktivität überwachen

Sie können Cloud Monitoring-Benachrichtigungen verwenden, um die Agent-Aktivität zu überwachen.

Monitoring ist für die Dimensionen project, agent_pool und agent_id verfügbar.

Mit diesen Monitoring-Daten können Sie Benachrichtigungen einrichten, um über potenzielle Probleme bei der Übertragung informiert zu werden. Erstellen Sie dazu eine Benachrichtigung für einen der folgenden Google Cloud-Messwerte:

Messwertname	Beschreibung	Empfohlene Anwendungsmöglichkeiten
storagetransfer.googleapis.com/agent/transferred_bytes_count	Gibt an, wie schnell ein bestimmter Agent Daten über alle von ihm bereitgestellten Jobs zu einem bestimmten Zeitpunkt verschiebt.	Benachrichtigung bei Leistungsrückgängen.
storagetransfer.googleapis.com/agent/connected	Ein boolescher Wert, der true ist, für jeden Agent, von dem Google Cloud eine aktuelle Heartbeat-Nachricht erhalten hat.	Benachrichtigung bei fehlgeschlagenen Agents Die Anzahl erfolgreicher Agents unterschreitet einen Mindestwert, den Sie für eine angemessene Leistung als erforderlich erachten Problem mit Agent-Rechnern melden

Agent beenden

Führen Sie zum Beenden eines Agents docker stop für die Docker-Container-ID des Agents aus. So finden Sie die ID und beenden den Agent:

1. Rufen Sie in der Google Cloud Console die Seite Agent-Pools auf.

   Zu „Agent-Pools“

2. Wählen Sie den Agent-Pool aus, der den zu beendenden Agent enthält.

3. Wählen Sie einen Agent aus der Liste aus. Im Feld Filter können Sie nach Präfixen, Agent-Status, Agent-Alter und mehr suchen.

4. Klicken Sie auf Agent beenden. Der Befehl docker stop mit der spezifischen Container-ID wird angezeigt.

5. Führen Sie den Befehl auf dem Computer aus, auf dem der Agent ausgeführt wird. Ein erfolgreicher docker stop-Befehl gibt die Container-ID zurück.

Nach dem Beenden wird der Agent in der Liste der Agent-Pools als Nicht verbunden angezeigt.

Agent löschen

Um bestimmte Agents zu löschen, listen Sie auf, welche Agents auf Ihrem Computer ausgeführt werden:

docker container list --all --filter ancestor=gcr.io/cloud-ingest/tsop-agent

Übergeben Sie dann die Agent-IDs an transfer agents delete:

gcloud transfer agents delete --ids=id1,id2,…

Verwenden Sie zum Löschen aller Agents, die auf dem Computer ausgeführt werden, eines der Flags --all oder --uninstall. Beide Flags löschen alle Agents auf dem Computer. Das --uninstall-Flag deinstalliert zusätzlich das Agent-Docker-Image.

gcloud transfer agents delete --all
gcloud transfer agents delete --uninstall

Details zur Übertragung des Dateisystems

Inkrementelle Übertragungen

Der Storage Transfer Service beginnt mit allen Daten, die an der Quelle und am Ziel vorhanden sind, um festzustellen, welche Quelldateien seit der letzten Übertragung neu, aktualisiert oder gelöscht wurden. Dadurch soll die von Ihren Maschinen gesendete Datenmenge reduziert, die Bandbreite effektiv genutzt und die Übertragungszeiten reduziert werden.

Um festzustellen, ob sich eine Datei geändert hat, verwenden wir einen Algorithmus, der dem gsutil rsync ähnelt: Wir prüfen die letzte Änderung und Größe der Quelldatei und vergleicht sie mit dem Zeitpunkt und Größe der letzten Änderung, die aufgezeichnet wurden, als die Datei zuletzt kopiert wurde. Wird eine neue oder geänderte Datei erkannt, wird die gesamte Datei in das Ziel kopiert. Weitere Informationen zur Dateiaktualität finden Sie unter Details zur Datenkonsistenz.

Standardmäßig erkennen wir keine Dateien, die aus der Quelle gelöscht wurden, aber nicht darauf reagieren. Wenn Sie beim Erstellen oder Bearbeiten die Sync-Option Zieldateien löschen wählen, die sich nicht auch in der Quelle befinden, wird bei Ihrer Übertragung das entsprechende Objekt am Ziel gelöscht.

Wenn Sie die Synchronisierungsoption Zieldateien löschen, die nicht auch in der Quelle sind auswählen, werden Dateien, die versehentlich an der Quelle gelöscht wurden, auch am Ziel gelöscht. Wenn Sie verhindern möchten, dass Datenverluste versehentlich gelöscht werden, empfehlen wir, die Objektversionierung im Ziel-Bucket zu aktivieren, wenn Sie diese Option verwenden möchten. Wenn Sie dann versehentlich eine Datei löschen, können Sie Ihre Objekte in Cloud Storage in einer älteren Version wiederherstellen.

Details zur Datenkonsistenz

Bei einem erfolgreichen Übertragungsvorgang werden alle Quelldateien übertragen, die während der gesamten Ausführungszeit des Vorgangs nicht geändert wurden. Quelldateien, die während einer Übertragung erstellt, aktualisiert oder gelöscht wurden, können diese Änderungen im Zieldatensatz enthalten.

Storage Transfer Service verwendet den Zeitpunkt und die Größe der letzten Änderung einer Datei, um festzustellen, ob sie geändert wurde. Wenn eine Datei aktualisiert wird, ohne den Zeitpunkt oder die Größe ihrer letzten Änderung zu ändern, und Sie die Option delete-objects-from-source aktivieren, gehen bei dieser Änderung möglicherweise Daten verloren.

Wenn Sie das Feature delete-objects-from-source verwenden, empfehlen wir dringend, Schreibvorgänge in die Quelle für die Dauer der Übertragung einzufrieren, um vor Datenverlust zu schützen.

So fixieren Sie Schreibvorgänge in Ihrer Quelle:

• Klonen Sie das Verzeichnis, das Sie übertragen möchten, und verwenden Sie das geklonte Verzeichnis als Übertragungsquelle.
• Halten Sie Anwendungen an, die in das Quellverzeichnis schreiben.

Wenn es wichtig ist, während einer Übertragung vorgenommene Änderungen zu erfassen, können Sie die Übertragung noch einmal ausführen oder das Quelldateisystem während der Ausführung als schreibgeschützt festlegen.

Da Cloud Storage das Konzept von Verzeichnissen nicht hat, werden leere Quellverzeichnisse nicht übertragen.

Wichtig: Wir empfehlen dringend, zu prüfen, ob eine Übertragung erfolgreich war, bevor Sie Quelldaten löschen. Dieser Dienst hat keine Möglichkeit, Daten in Cloud Storage wiederherzustellen.