Ruby-Gems in Artifact Registry speichern

In dieser Kurzanleitung wird gezeigt, wie Sie ein privates Artifact Registry-Repository für Ruby einrichten und dann ein Paket, auch Gem genannt, in dieses Repository hochladen.

Hinweis

  1. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  2. Verify that billing is enabled for your Google Cloud project.

  3. Enable the Artifact Registry API.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the API

  4. Make sure that you have the following role or roles on the project: Artifact Registry Administrator

    Check for the roles

    1. In the Google Cloud console, go to the IAM page.

      Go to IAM
    2. Select the project.

    3. In the Principal column, find all rows that identify you or a group that you're included in. To learn which groups you're included in, contact your administrator.

    4. For all rows that specify or include you, check the Role column to see whether the list of roles includes the required roles.

    Grant the roles

    1. In the Google Cloud console, go to the IAM page.

      Go to IAM
    2. Select the project.
    3. Click Grant access.

    4. In the New principals field, enter your user identifier. This is typically the identifier for a user in a workforce identity pool. For details, see Represent workforce pool users in IAM policies, or contact your administrator.

    5. Click Select a role, then search for the role.
    6. To grant additional roles, click Add another role and add each additional role.
    7. Click Save.

Erforderliche Rollen

Bitten Sie Ihren Administrator, Ihnen die IAM-Rolle „Artifact Registry-Administrator“ (roles/artifactregistry.admin) für Ihr Projekt zuzuweisen, um die Berechtigungen zu erhalten, die Sie zum Erstellen und Verwalten von Artifact Registry-Repositorys für Ruby-Gems benötigen. Weitere Informationen zum Zuweisen von Rollen finden Sie unter Zugriff auf Projekte, Ordner und Organisationen verwalten.

Sie können die erforderlichen Berechtigungen auch über benutzerdefinierte Rollen oder andere vordefinierte Rollen erhalten.

Cloud Shell starten

In dieser Kurzanleitung verwenden Sie Cloud Shell, eine Shell-Umgebung für die Verwaltung von Ressourcen, die in gehostet werden Google Cloud.

Die Google Cloud CLI und Ruby sind in Cloud Shell vorinstalliert. Die gcloud CLI bietet die primäre Befehlszeile für Google Cloud.

Cloud Shell aufrufen

  1. Zur Google Cloud Console.

    Google Cloud Console

  2. Klicken Sie in der Symbolleiste der Google Cloud Console auf Cloud Shell aktivieren.

In einem Frame im unteren Teil der Console wird eine Cloud Shell-Sitzung geöffnet. Mit dieser Shell führen Sie gcloud-Befehle aus.

Authentifizierung konfigurieren

Ruby unterstützt zwei Methoden zum Authentifizieren von Anfragen an Ihr Artifact Registry-Repository:

  • RubyGems CLI: Unterstützt Push- und Pull-Anfragen. Diese CLI ist standardmäßig mit Ruby verfügbar. Wenn Sie sich mit RubyGems authentifizieren, müssen Sie sich bei jeder Push- oder Pull-Anfrage an Ihr Repository authentifizieren.

  • Bundler CLI: Unterstützt Pull-Anfragen. Bundler speichert Pakete und Upstreams in einer Gemfile-Datei. So können Nutzer Setups auf mehreren Computern standardisieren, ohne jede einzelne Pull-Anfrage authentifizieren zu müssen. Sie müssen Ihre Anmeldedaten jedoch gelegentlich neu bei Bundler authentifizieren.

    Geben Sie gem install bundler ein, um die Bundler CLI zu installieren.

Mit der RubyGems CLI authentifizieren

Die RubyGems CLI verwendet OAuth2-Tokens, um eine Anfrage zu authentifizieren. Wenn Sie OAuth2-Tokens an Aufrufe Ihrer Artifact Registry-Repositorys übergeben möchten, müssen Sie Ihr OAuth2-Token mit der Adresse Ihres Repositorys übergeben, wenn Sie eine Anfrage stellen. Tokens haben eine Gültigkeitsdauer von einer Stunde und müssen stündlich aktualisiert werden.

Pull-Anfragen authentifizieren

Sie können eine Pull-Anfrage in der Google Cloud CLI-Befehlszeile authentifizieren oder Ihre .gemrc-Datei aktualisieren.

Pull-Anfragen in der Befehlszeile authentifizieren

Führen Sie den folgenden Befehl aus, um sich für die neueste Version des Gems in Ihrer Pull-Anfrage zu authentifizieren:

gem install GEM_NAME --source https://$ACCESS_TOKEN@LOCATION-ruby.pkg.dev/PROJECT/REPOSITORY

Wenn Sie sich für eine bestimmte Gem-Version authentifizieren möchten, fügen Sie -v GEM_VERSION dem gem install Befehl hinzu.

Wobei:

  • GEM_NAME ist der Name des Gems, für das die Anfrage gestellt wird.
  • LOCATION ist der regionale oder multiregionale Standort für das Repository.
  • PROJECT ist die ID des Projekts, das das Repository enthält.
  • REPOSITORY ist die ID des Repositorys.

In einer .gemrc-Datei authentifizieren

Sie können Ihre globale oder projektspezifische /.gemrc-Datei so konfigurieren, dass Sie sich bei Pull-Anfragen bei Ihren Quellen authentifizieren. Fügen Sie dazu Folgendes hinzu:

# File: ~/.gemrc

# Use the ACCESS_TOKEN retrieved from export ACCESS_TOKEN="oauth2accesstoken:$(gcloud auth print-access-token)"

<...>
:sources:
    - https://ACCESS_TOKEN@LOCATION-ruby.pkg.dev/PROJECT/REPOSITORY/
<...>

Wobei:

  • ACCESS_TOKEN ist Ihr OAuth2-Zugriffstoken.
  • LOCATION ist der regionale oder multiregionale Standort für das Repository.
  • PROJECT ist die ID des Projekts, das das Repository enthält.
  • REPOSITORY ist die ID des Repositorys.

Führen Sie Folgendes aus, um ein Gem mit der oder den in Ihrer /.gemrc-Datei definierten Quelle(n) zu installieren:

gem install GEM_NAME

Push-Anfragen authentifizieren

Sie können eine Push-Anfrage in der Google Cloud CLI-Befehlszeile authentifizieren oder Ihre Datei mit den Anmeldedaten aktualisieren.

Push-Anfragen in der Befehlszeile authentifizieren

Führen Sie den folgenden Befehl aus, um Ihre Push-Anfrage zu authentifizieren:

export GEM_HOST_API_KEY="Bearer $(gcloud auth print-access-token)"
gem push GEM_NAME --host https://LOCATION-ruby.pkg.dev/PROJECT/REPOSITORY

Wobei:

  • GEM_NAME ist der Name des Gems, für das die Anfrage gestellt wird.
  • LOCATION ist der regionale oder multiregionale Standort für das Repository.
  • PROJECT ist die ID des Projekts, das das Repository enthält.
  • REPOSITORY ist die ID des Repositorys.

Push-Anfragen in einer Datei mit Anmeldedaten authentifizieren

Das gem Befehlszeilentool verwendet die Datei ~/.gem/credentials, um API-Schlüssel für das Pushen und Pullen von Gems zu speichern. So konfigurieren Sie Ihre Datei mit den Anmeldedaten, um sich bei Push-Anfragen bei Ihren Quellen zu authentifizieren:

  1. Aktualisieren Sie die Datei mit den Anmeldedaten:

    1. Öffnen Sie ~/.gem/credentials und fügen Sie eine Zeile für Ihr Repository hinzu. Der Schlüssel ist die URL Ihres Repositorys und der Wert ist Bearer, gefolgt von Ihrem Token:

      :rubygems_api_key: RUBYGEMS_ORG_KEY
https://LOCATION-ruby.pkg.dev/PROJECT/REPOSITORY: Bearer ACCESS_TOKEN

      Wobei:

      • RUBYGEMS_ORG_KEY ist der API-Schlüssel für RubyGems.org.
      • LOCATION ist der regionale oder multiregionale Standort für das Repository.
      • PROJECT ist die ID des Projekts, das das Repository enthält.
      • REPOSITORY ist die ID des Repositorys.
      • ACCESS_TOKEN ist Ihr OAuth2-Zugriffstoken.

    2. Pushen Sie Ihr Gem. Sie müssen GEM_HOST_API_KEY nicht festlegen, da Sie den Schlüssel bereits in Ihrer Datei mit den Anmeldedaten definiert haben.

      gem push GEM_NAME --host https://LOCATION-ruby.pkg.dev/PROJECT/REPOSITORY

Mit Bundler authentifizieren

Der Ruby Bundler verwaltet Anwendungsabhängigkeiten für ein oder mehrere Gems. So richten Sie Bundler ein:

  1. Fügen Sie die Adresse Ihres Repositorys als source in Ihrer Gemfile-Datei hinzu:

    # Gemfile
# <...>
source "https://LOCATION-ruby.pkg.dev/PROJECT/REPOSITORY"

  2. Authentifizieren Sie sich mit bundle config bei Ihrem Repository:

    export GEM_TOKEN="oauth2accesstoken:$(gcloud auth print-access-token)"
export HOST="https://LOCATION-ruby.pkg.dev/PROJECT/REPOSITORY"
bundle config $HOST $GEM_TOKEN

Wobei:

  • LOCATION ist der regionale oder multiregionale Standort für das Repository.
  • 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.

Sie müssen sich gelegentlich neu bei Ihrem Remote-Repository authentifizieren. Führen Sie in diesem Fall denselben Authentifizierungsbefehl aus Schritt 2 aus.

Weitere Informationen zum Konfigurieren von Bundler, siehe Gemfiles in der Dokumentation zu bundler.io.

Weitere Informationen zu Authentifizierungsmethoden finden Sie unter Authentifizierung für Artifact Registry-Repositorys für Ruby-Gems konfigurieren.

Repository erstellen

Erstellen Sie das Repository für Ihr Gem.

  1. Führen Sie den folgenden Befehl aus, um ein neues Repository für Ruby-Gems im aktuellen Projekt mit dem Namen quickstart-ruby-repo am Standort us-west1 zu erstellen.

    gcloud artifacts repositories create quickstart-ruby-repo \
    --repository-format=ruby \
    --location=us-west1 \
    --description="Ruby gem repository"

  2. Führen Sie den folgenden Befehl aus, um zu prüfen, ob Ihr Repository erstellt wurde:

    gcloud artifacts repositories list

  3. Um die gcloud-Befehle zu vereinfachen, legen Sie für das Standard-Repository den Wert quickstart-ruby-repo und für den Standard-Speicherort us-west1 fest. Nachdem Sie die Werte festgelegt haben, müssen Sie diese nicht mehr in gcloud-Befehlen angeben, für die ein Repository oder Speicherort erforderlich ist.

    Führen Sie den folgenden Befehl aus, um das Repository festzulegen:

    gcloud config set artifacts/repository quickstart-ruby-repo

    Führen Sie den folgenden Befehl aus, um den Standort festzulegen:

    gcloud config set artifacts/location us-west1

    Weitere Informationen zu diesen Befehlen finden Sie in der Dokumentation zu gcloud config set.

Gem herunterladen

Wenn Sie ein Ruby-Projekt erstellen, werden die Verteilungsdateien in einem lib-Unterverzeichnis in Ihrem Ruby-Projekt gespeichert. Um diese Kurzanleitung zu vereinfachen, erstellen Sie ein Verzeichnis und laden dann ein Gem in dieses Verzeichnis herunter.

Führen Sie den folgenden Befehl aus, um das Verzeichnis zu erstellen:

mkdir ruby-quickstart
mkdir ruby-quickstart/lib
cd ruby-quickstart/lib

Laden Sie als Nächstes Ihr Gem herunter. Sie können entweder Ihr eigenes Gem verwenden oder ein Beispiel Gem von der Seite Popular Gems auf rubygems.org herunterladen. Führen Sie den folgenden Befehl aus, um ein Gem von rubygems.org herunterzuladen:

gem fetch GEM_NAME

Sie haben jetzt ein Gem mit dem Titel GEM_NAME im ruby_quickstart/lib Verzeichnis. Im nächsten Abschnitt verwenden Sie die RubyGems CLI, um Ihr Gem in Ihr Repository zu pushen.

Gem in das Repository pushen

Führen Sie den folgenden Befehl aus, um das Gem in Ihr Repository zu pushen:

gem push GEM_NAME --host https://us-west1-ruby.pkg.dev/PROJECT/quickstart-ruby-repo

Wobei:

  • GEM_NAME ist der Name des Gems, das in Ihr Repository gepusht werden soll.
  • PROJECT ist die Projekt-ID. Wenn dieses Flag nicht angegeben ist, wird das aktuelle Projekt oder das Standardprojekt verwendet.

Gem im Repository ansehen

Prüfen Sie, ob Ihr Gem hinzugefügt wurde, indem Sie die Pakete im Repository ruby-quickstart auflisten.

Führen Sie dazu diesen Befehl aus:

gcloud artifacts packages list --repository=ruby-quickstart

Führen Sie den folgenden Befehl aus, um Versionen für ein Gem anzusehen:

gcloud artifacts versions list --package=GEM_NAME

Gem installieren

Führen Sie den folgenden Befehl aus, um das Gem zu installieren, das Sie gerade in Ihr Artifact Registry-Repository gepusht haben:

export GEM_TOKEN="oauth2accesstoken:$(gcloud auth print-access-token)"
gem install GEM_NAME --source https://$GEM_TOKEN@us-west1-ruby.pkg.dev/PROJECT/quickstart-ruby-repo

Wobei:

  • GEM_NAME ist der Name des Gems, das in Ihrem Repository installiert werden soll.
  • PROJECT ist die Projekt-ID. Wenn dieses Flag nicht angegeben ist, wird das aktuelle Projekt oder das Standardprojekt verwendet.

Fehlerbehebung

Weitere Informationen finden Sie unter Fehlerbehebung bei Ruby-Gems.

Bereinigen

Mit den folgenden Schritten vermeiden Sie, dass Ihrem Google Cloud -Konto die auf dieser Seite verwendeten Ressourcen in Rechnung gestellt werden:

Prüfen Sie vor dem Entfernen des Repositorys, ob alle Gems, die Sie beibehalten möchten, an einem anderen Speicherort verfügbar sind.

  1. Führen Sie den folgenden Befehl aus, um das Repository quickstart-ruby-repo zu löschen:

    gcloud artifacts repositories delete quickstart-ruby-repo

  2. Wenn Sie die Einstellungen für das Standard-Repository und den Standard-Speicherort entfernen möchten, die Sie für die aktive gcloud-Konfiguration festgelegt haben, führen Sie die folgenden Befehle aus:

    gcloud config unset artifacts/repository
gcloud config unset artifacts/location

Nächste Schritte