Authentifizierung für Python-Paket-Repositories in Artifact Registry konfigurieren

Sie müssen sich bei Artifact Registry authentifizieren, wenn Sie eine Drittanbieteranwendung für die Verbindung mit einem Repository verwenden.

Sie müssen die Authentifizierung für Cloud Build- oder Google Cloud-Laufzeitumgebungen wie Google Kubernetes Engine und Cloud Run nicht konfigurieren. Sie sollten jedoch prüfen, ob die erforderlichen Berechtigungen konfiguriert sind.

Artifact Registry unterstützt die folgenden Authentifizierungsmethoden für Python-Paket-Repositories:

  • Zugriffstokens: Verwenden Sie Zugriffstokens in Automatisierungen, CI/CD-Pipelines, Container-Builds oder Umgebungen, in denen die Installation der Schlüsselbundbibliothek nicht unterstützt wird.
  • Python-Schlüsselringbibliothek (empfohlen für die lokale Entwicklung): Verwenden Sie diese Option auf Entwicklerarbeitsplätzen, um die Aktualisierung von Anmeldedaten automatisch zu verarbeiten.
  • Passwortauthentifizierung: Verwenden Sie diese Option, wenn eine Anwendung keine Standardanmeldedaten für Anwendungen unterstützt, aber die Authentifizierung mit einem Nutzernamen und Passwort.

Hinweis

  1. Wenn das Ziel-Repository nicht vorhanden ist, erstellen Sie ein neues Python-Paket-Repository.
  2. Prüfen Sie, ob Python 3 installiert ist. Eine Installationsanleitung finden Sie imGoogle Cloud Tutorial zum Einrichten von Python.
  3. Prüfen Sie, ob das von Ihnen verwendete Nutzerkonto oder Dienstkonto die erforderlichen Berechtigungen für den Zugriff auf das Repository hat.

  4. Installieren Sie die Google Cloud CLI. Initialisieren Sie die Google Cloud CLI nach der Installation mit dem folgenden Befehl: 

    gcloud init

    Wenn Sie einen externen Identitätsanbieter (IdP) verwenden, müssen Sie sich zuerst mit Ihrer föderierten Identität in der gcloud CLI anmelden.

  5. (Optional) Standardeinstellungen für gcloud CLI-Befehle konfigurieren.

Tokens für die Authentifizierung generieren

Um Ihr Paket in Artifact Registry zu authentifizieren, müssen Sie zuerst ein Authentifizierungstoken generieren. Sie können dieses Token dann verwenden, wenn Sie Anfragen von Ihrem Paket an Artifact Registry senden.

Sie können ein oauth2-Zugriffstoken mit Google Cloud oder ein oauth2l-Token außerhalb von Google Cloudgenerieren.

Zugriffstokens sind 60 Minuten lang gültig. Generieren Sie ein Zugriffstoken kurz vor dem Ausführen von Befehlen, die mit Repositorys interagieren. Wenn Ihr Zugriffstoken abgelaufen ist, müssen Sie ein neues generieren.

Token mit gcloud generieren

Führen Sie den folgenden Befehl aus, um mit Google Cloudein oauth2-Zugriffstoken zu generieren:

export ACCESS_TOKEN="oauth2accesstoken:$(gcloud auth print-access-token)"

Sie können jetzt auf ACCESS_TOKEN verweisen, wenn Sie Anfragen von Ihrem Python-Paket an Artifact Registry senden.

Token ohne gcloud generieren

So generieren Sie ein Zugriffstoken nur mit der oauth2l-CLI:

  1. Installieren Sie die aktuelle Version von oauth2l mit dem folgenden Befehl:

    go install github.com/google/oauth2l@latest

  2. Führen Sie dazu diesen Befehl aus:

    export ACCESS_TOKEN="oauth2l fetch --scope cloud-platform"

    Google Cloud generiert ein SHA256-Hash-Token und speichert es in der Variablen ACCESS_TOKEN. Sie können jetzt auf ACCESS_TOKEN verweisen, wenn Sie Anfragen von Ihrem Python-Paket an Artifact Registry senden.

Mit pip authentifizieren

Nachdem Sie ACCESS_TOKEN exportiert haben, können Sie es an pip übergeben, um Pakete zu installieren:

pip install PACKAGE --index-url https://$ACCESS_TOKEN@LOCATION-python.pkg.dev/PROJECT/REPOSITORY/simple/

Mit Schlüsselbund authentifizieren

Die Python-Bibliothek keyring bietet Anwendungen die Möglichkeit, auf Schlüsselbund-Back-Ends zuzugreifen, d. h. auf Anmeldedatenspeicher des Betriebssystems und von Drittanbietern. Artifact Registry bietet das Schlüsselbund-Backend keyrings.google-artifactregistry-auth, um die Authentifizierung bei Artifact Registry-Repositories zu verarbeiten.

In diesem Abschnitt wird beschrieben, wie Sie pip als einzigen Paketindex konfigurieren, in dem pip nach Paketen sucht. Wir empfehlen, virtuelle Repositories zu verwenden, um Pakete in Ihren privaten Paketen in Artifact Registry und öffentlichen Paketen von PyPI zu suchen, anstatt mehrere Paketindexe in der pip-Konfigurationsdatei zu konfigurieren. Das pip-Tool durchsucht Paketindexe nicht in einer bestimmten Reihenfolge. Daher kann es passieren, dass Ihre Kunden versehentlich ein öffentliches Paket mit demselben Namen wie eines Ihrer privaten Pakete herunterladen oder installieren. Mit virtuellen Repositorys können Sie Prioritäten für Upstream-Quellen konfigurieren, um dieses Risiko zu minimieren.

Reihenfolge der Anmeldedatensuche

Wenn Sie das Artifact Registry-Schlüsselbund-Backend verwenden, werden Ihre Anmeldedaten nicht in Ihrem Python-Projekt gespeichert. Stattdessen sucht Artifact Registry in der folgenden Reihenfolge nach Anmeldedaten:

  1. Standardanmeldedaten für Anwendungen (ADC), eine Strategie, die in der folgenden Reihenfolge nach Anmeldedaten sucht:

    1. In der Umgebungsvariable GOOGLE_APPLICATION_CREDENTIALS definierte Anmeldedaten.

    2. Anmeldedaten, die vom Standarddienstkonto für Compute Engine, Google Kubernetes Engine, Cloud Run, App Engine oder Cloud Run Functions bereitgestellt werden.

  2. Von der Google Cloud CLI bereitgestellte Anmeldedaten, einschließlich Nutzeranmeldedaten aus dem Befehl gcloud auth application-default login.

Die Variable GOOGLE_APPLICATION_CREDENTIALS macht das Konto für die Authentifizierung explizit, was die Fehlerbehebung erleichtert. Wenn Sie die Variable nicht verwenden, prüfen Sie, ob alle Konten, die ADC möglicherweise verwendet, die erforderlichen Berechtigungen haben. Das Standarddienstkonto für Compute Engine-VMs, Google Kubernetes Engine-Knoten und Cloud Run-Revisionen hat beispielsweise nur Lesezugriff auf Repositories. Wenn Sie aus diesen Umgebungen mit dem Standarddienstkonto hochladen möchten, müssen Sie die Berechtigungen ändern.

Schlüsselbund einrichten

So richten Sie die Authentifizierung mit dem Artifact Registry-Schlüsselbund-Backend ein:

  1. Installieren Sie die Schlüsselbundbibliothek.

    pip install keyring

  2. Installieren Sie das Artifact Registry-Backend.

    pip install keyrings.google-artifactregistry-auth

  3. Listen Sie die Back-Ends auf, um die Installation zu bestätigen.

    keyring --list-backends

    Die Liste sollte Folgendes enthalten:

    • ChainerBackend(priority:10)
    • GooglePythonAuth(priority: 9)

  4. Führen Sie den folgenden Befehl aus, um die Repository-Konfiguration auszugeben, die dem Python-Projekt hinzugefügt werden soll.

    gcloud artifacts print-settings python --project=PROJECT \
    --repository=REPOSITORY \
    --location=LOCATION

    Ersetzen Sie die folgenden Werte:

  5. Fügen Sie der Datei .pypirc die folgenden Einstellungen hinzu. Der Standardspeicherort ist:

    • Linux und macOS: $HOME/.pypirc
    • Windows: %USERPROFILE%\.pypirc
    [distutils]
index-servers =
    PYTHON-REPO-ID

[PYTHON-REPO-ID]
repository = https://LOCATION-python.pkg.dev/PROJECT/REPOSITORY/

    Ersetzen Sie die folgenden Werte:

    • PYTHON-REPO-ID ist eine ID für das Repository, auf das Sie mit Tools wie Twine verweisen können.
    • PROJECT ist die Projekt-ID. Wenn dieses Flag nicht angegeben ist, wird das aktuelle Projekt oder das Standardprojekt verwendet.
    • REPOSITORY ist die ID des Repositorys. Wenn Sie ein Standard-Artifact Registry-Repository konfiguriert haben, wird es verwendet, wenn dieses Flag im Befehl ausgelassen wird.
    • LOCATION ist der regionale oder multiregionale Standort für das Repository.

  6. Fügen Sie Ihr Repository der pip-Konfigurationsdatei hinzu. Der Dateispeicherort hängt davon ab, ob Sie die Datei für den einzelnen Nutzer oder die Datei für eine bestimmte virtuelle Umgebung aktualisieren möchten.

    Für die Datei, die Ihrem Betriebssystemnutzer zugeordnet ist:

    • Unix: $HOME/.config/pip/pip.conf oder $HOME/.pip/pip.conf
    • macOS: /Library/Application Support/pip/pip.conf oder $HOME/.config/pip/pip.conf
    • Windows: %APPDATA%\pip\pip.ini oder %USERPROFILE%\pip\pip.ini

    Für virtuelle Umgebungen:

    • Unix und macOS: $VIRTUAL_ENV/pip.conf
    • Windows: %VIRTUAL_ENV%\pip.ini

    Wenn Sie pip so konfigurieren möchten, dass nur in Ihrem Repository gesucht wird, verwenden Sie die Einstellung index-url und achten Sie darauf, dass mit der Einstellung extra-index-url keine anderen Paketindexe konfiguriert sind.

    [global]
index-url = https://LOCATION-python.pkg.dev/PROJECT/REPOSITORY/simple/

    Der String /simple/ am Ende des Repository-Pfads gibt an, dass das Repository die Python Simple Repository API implementiert.

Ihre Python-Umgebung ist jetzt für die Authentifizierung bei Artifact Registry konfiguriert.

Schlüsselbundauthentifizierung mit Nutzeranmeldedaten

Nachdem Sie einen Schlüsselbund eingerichtet haben, können Sie ihn mit Ihren Nutzeranmeldedaten in der gcloud CLI verwenden. Melden Sie sich in der Google Cloud CLI an, bevor Sie eine Verbindung zu einem Python-Paket-Repository herstellen.

Führen Sie dazu diesen Befehl aus:

gcloud auth login

Schlüsselbundauthentifizierung mit Dienstkontoanmeldedaten

Nachdem Sie den Schlüsselbund eingerichtet haben, können Sie ein Dienstkonto für die Authentifizierung einrichten.

  1. Erstellen Sie ein Dienstkonto oder wählen Sie ein vorhandenes Dienstkonto für die Automatisierung aus.
  2. Gewähren Sie dem Dienstkonto die entsprechende Artifact Registry-Rolle, um Repository-Zugriff zu ermöglichen.

  3. Verwenden Sie eine der folgenden Optionen, um sich mit Ihrem Dienstkonto zu authentifizieren:

    • Standardanmeldedaten für Anwendungen (empfohlen)

      Weisen Sie der Variablen GOOGLE_APPLICATION_CREDENTIALS den Speicherort des Dienstkontoschlüssels zu, damit die Artifact Registry-Credential Helper Ihren Schlüssel beim Herstellen einer Verbindung zu Repositories abrufen können.

      export GOOGLE_APPLICATION_CREDENTIALS=KEY-FILE

    • gcloud CLI-Anmeldedaten

      Bevor Sie eine Verbindung zu einem Repository herstellen, melden Sie sich als Dienstkonto an. Vermeiden Sie diese Option, wenn Sie von Compute Engine-VMs aus eine Verbindung zu Repositories herstellen, da Artifact Registry die Anmeldedaten des VM-Dienstkontos vor den Anmeldedaten in der gcloud CLI findet.

      gcloud auth activate-service-account --key-file=KEY-FILE

    Ersetzen Sie KEY-FILE durch den Pfad zur Schlüsseldatei des Dienstkontos.

Passwortauthentifizierung mit Dienstkontoschlüsseln konfigurieren

Verwenden Sie diesen Ansatz, wenn eine Authentifizierung mit einem Nutzernamen und einem Passwort erforderlich ist.

Dienstkontoschlüssel sind langlebige Anmeldedaten. Verwenden Sie die folgenden Richtlinien, um den Zugriff auf Ihre Repositories einzuschränken:

  • Verwenden Sie ein dediziertes Dienstkonto für die Interaktion mit Repositories.
  • Erteilen Sie die vom Dienstkonto erforderliche Artifact Registry-Mindestrolle. Weisen Sie z. B. Artifact Registry-Reader einem Dienstkonto zu, das nur Artefakte herunterlädt.
  • Wenn Gruppen in Ihrer Organisation verschiedene Zugriffsebenen für bestimmte Repositories benötigen, erteilen Sie den Zugriff auf Repository-Ebene und nicht auf Projektebene.
  • Folgen Sie den Best Practices für die Verwaltung von Anmeldedaten.

So konfigurieren Sie die Authentifizierung:

  1. Erstellen Sie ein Dienstkonto, das im Namen Ihrer Anwendung agieren soll, oder wählen Sie ein vorhandenes Dienstkonto für die Automatisierung aus.

    Sie benötigen den Speicherort der Dienstkonto-Schlüsseldatei, um damit die Authentifizierung bei Artifact Registry einzurichten. Auf der Seite „Dienstkonten“ können Sie die Schlüssel vorhandener Konten aufrufen und neue Schlüssel erstellen.

    Zur Seite „Dienstkonten“

  2. Weisen Sie dem Dienstkonto die entsprechende Artifact Registry-Rolle zu, um Repository-Zugriff zu ermöglichen.

  3. Führen Sie den folgenden Befehl aus, um die Repository-Konfiguration auszugeben, die dem Python-Projekt hinzugefügt werden soll.

    gcloud artifacts print-settings python --project=PROJECT \
    --repository=REPOSITORY \
    --location=LOCATION \
    --json-key=KEY-FILE

    Ersetzen Sie die folgenden Werte:

  4. Fügen Sie der Datei .pypirc die folgenden Einstellungen hinzu. Der standardmäßige Standort für die Pip-Konfigurationsdatei für Nutzer ist:

    • Linux und macOS: $HOME/.pypirc
    • Windows: %USERPROFILE%\.pypirc
    [distutils]
index-servers =
    PYTHON-REPO-ID

[PYTHON-REPO-ID]
repository = https://LOCATION-python.pkg.dev/PROJECT/REPOSITORY/
username: _json_key_base64
password: KEY

    Ersetzen Sie die folgenden Werte:

    • PYTHON-REPO-ID ist eine ID für das Repository, auf das Sie mit Tools wie Twine verweisen können.
    • PROJECT ist die Projekt-ID. Wenn dieses Flag nicht angegeben ist, wird das aktuelle Projekt oder das Standardprojekt verwendet.
    • REPOSITORY ist die ID des Repositorys. Wenn Sie ein Standard-Artifact Registry-Repository konfiguriert haben, wird es verwendet, wenn dieses Flag im Befehl ausgelassen wird.
    • LOCATION ist der regionale oder multiregionale Standort für das Repository.
    • KEY ist der base64-codierte Schlüssel in Ihrer Dienstkonto-Schlüsseldatei.

  5. Fügen Sie Ihr Repository der pip-Konfigurationsdatei hinzu. Der Speicherort der pip-Konfigurationsdatei hängt davon ab, ob Sie die Datei für den jeweiligen Nutzer oder die Datei für eine bestimmte virtuelle Umgebung aktualisieren möchten.

    Für die Datei, die Ihrem Betriebssystemnutzer zugeordnet ist:

    • Unix: $HOME/.config/pip/pip.conf oder $HOME/.pip/pip.conf
    • macOS: /Library/Application Support/pip/pip.conf oder $HOME/.config/pip/pip.conf
    • Windows: %APPDATA%\pip\pip.ini oder %USERPROFILE%\pip\pip.ini

    Für virtuelle Umgebungen:

    • Unix und macOS: $VIRTUAL_ENV/pip.conf
    • Windows: %VIRTUAL_ENV%\pip.ini

    Fügen Sie der pip-Konfigurationsdatei die folgende Zeile hinzu:

    [global]
index-url = https://_json_key_base64:KEY@LOCATION-python.pkg.dev/PROJECT/REPOSITORY/simple/
    • KEY ist der private Schlüssel in der Schlüsseldatei Ihres Dienstkontos.
    • Der String /simple/ am Ende des Repository-Pfads gibt an, dass das Repository die Python Simple Repository API implementiert.

Nächste Schritte