在 Artifact Registry 中存储 Ruby gem

本快速入门介绍如何设置私有 Artifact Registry Ruby 代码库，然后向该代码库上传软件包（也称为 gem）。

准备工作

  1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

  2. 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

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

  4. Enable the Artifact Registry API.

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

    Enable the API

  5. 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.

      前往 IAM
    2. 选择项目。
    3. 点击 授予访问权限。

    4. 在新的主账号字段中，输入您的用户标识符。 这通常是 Google 账号的电子邮件地址。

    5. 在选择角色列表中，选择一个角色。
    6. 如需授予其他角色，请点击 添加其他角色，然后添加其他各个角色。
    7. 点击 Save（保存）。

  6. 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

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

  8. Enable the Artifact Registry API.

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

    Enable the API

  9. 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.

      前往 IAM
    2. 选择项目。
    3. 点击 授予访问权限。

    4. 在新的主账号字段中，输入您的用户标识符。 这通常是 Google 账号的电子邮件地址。

    5. 在选择角色列表中，选择一个角色。
    6. 如需授予其他角色，请点击 添加其他角色，然后添加其他各个角色。
    7. 点击 Save（保存）。

    10. 启动 Cloud Shell

    在本快速入门中，您将使用 Cloud Shell，这是一个用于管理Google Cloud上托管资源的 Shell 环境。

    Cloud Shell 预安装有 Google Cloud CLI 和 Ruby。gcloud CLI 为 Google Cloud提供了主要命令行界面。

    启动 Cloud Shell：

    1. 前往 Google Cloud 控制台。

      Google Cloud 控制台

    2. 在 Google Cloud 控制台工具栏上，点击激活 Cloud Shell。

    控制台下方的框架内会打开一个 Cloud Shell 会话。您可以使用此 shell 运行 gcloud 命令。

    配置身份验证

    Ruby 支持两种方法来对向 Artifact Registry 代码库发出的请求进行身份验证：

    • RubyGems CLI：支持推送和拉取请求。此 CLI 默认随 Ruby 提供。使用 RubyGems 进行身份验证时，您每次向代码库发出推送或拉取请求时都必须进行身份验证。

    • Bundler CLI：支持拉取请求。Bundler 会将软件包和上游存储在 Gemfile 中，这样用户就可以在多台机器上标准化设置，而无需对每个单独的拉取请求进行身份验证。不过，您仍需偶尔重新向 Bundler 验证凭据。

      如需安装 Bundler CLI，请输入 gem install bundler。

    使用 RubyGems CLI 进行身份验证

    RubyGems CLI 使用 OAuth2 令牌对请求进行身份验证。如需将 OAuth2 令牌传递给对 Artifact Registry 代码库的调用，您必须先生成令牌，然后在发出请求时将其与代码库的地址一起传递。令牌的有效期为 1 小时，必须每小时刷新一次。

    对拉取请求进行身份验证

    您可以在 Google Cloud CLI 命令行中或通过更新 .gemrc 文件来对拉取请求进行身份验证。

    在命令行中对拉取请求进行身份验证

    如需对拉取请求中的最新版 gem 进行身份验证，请运行以下命令：

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

    如需针对特定 gem 版本进行身份验证，请将 -v GEM_VERSION 添加到 gem install 命令。

    其中：

    • GEM_NAME 是相应请求所针对的 gem 的名称。
    • LOCATION 是代码库的单区域或多区域位置。
    • PROJECT 是包含代码库的项目的 ID。
    • REPOSITORY 是代码库的 ID。

    在 .gemrc 文件中进行身份验证

    您可以配置全局或项目特定的 /.gemrc 文件，以通过添加以下内容来对拉取请求中的来源进行身份验证：

    # File: ~/.gemrc

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

<...>
:sources:
    - https://GEM_TOKEN@LOCATION-ruby.pkg.dev/PROJECT/REPO/
<...>

    如需使用 /.gemrc 文件中定义的来源安装 gem，请运行以下命令：

    gem install GEM_NAME

    对推送请求进行身份验证

    您可以在 Google Cloud CLI 命令行中或通过更新凭据文件来对推送请求进行身份验证。

    在命令行中对推送请求进行身份验证

    如需对推送请求进行身份验证，请运行以下命令：

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

    其中：

    • GEM_NAME 是相应请求所针对的 gem 的名称。
    • LOCATION 是代码库的单区域或多区域位置。
    • PROJECT 是包含代码库的项目的 ID。
    • REPOSITORY 是代码库的 ID。

    在凭据文件中对推送请求进行身份验证

    gem 命令行工具使用 ~/.gem/credentials 文件来存储用于推送和拉取 gem 的 API 密钥。如需将凭据文件配置为在推送请求中向来源进行身份验证，请执行以下操作：

    1. 运行以下命令，生成 OAuth2 访问令牌：

      gcloud auth print-access-token

      此令牌充当 Artifact Registry 的 API 密钥。

    2. 更新凭据文件：

      1. 打开 ~/.gem/credentials 并为您的代码库添加一行代码。键是您的代码库网址，值是 Bearer，后跟您的令牌：

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

        其中：

        • RUBYGEMS_ORG_KEY 是 RubyGems.org 的 API 密钥。
        • LOCATION 是代码库的单区域或多区域位置。
        • PROJECT 是包含代码库的项目的 ID。
        • REPOSITORY 是代码库的 ID。
        • OAUTH_TOKEN 是您的 OAuth2 访问令牌。

      2. 推送 Gem。请注意，您无需设置 GEM_HOST_API_KEY，因为您已在凭据文件中定义了密钥。

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

    使用 Bundler 进行身份验证

    Ruby Bundler 可跨一个或多个 gem 管理应用依赖项。如需设置 Bundler，请执行以下操作：

    1. 在 Gemfile 中将代码库的地址添加为 source：

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

    2. 使用 bundle config 向代码库进行身份验证：

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

    其中：

    • LOCATION 是代码库的单区域或多区域位置。
    • PROJECT 是项目 ID。如果省略此标志，则系统会使用当前项目或默认项目。
    • REPOSITORY 是代码库的 ID。如果您配置了默认 Artifact Registry 代码库，则当您从命令中省略此标志时，系统会使用该代码库。

    您需要偶尔重新对远程代码库进行身份验证。在这种情况下，请运行第 2 步中的同一身份验证命令。

    如需详细了解如何配置 Bundler，请参阅 bundler.io 文档中的 Gemfiles。

    如需详细了解身份验证方法，请参阅为 Ruby gem 代码库配置向 Artifact Registry 的身份验证。

    创建代码库

    为 gem 创建代码库。

    1. 运行以下命令，在位置 us-west1 的当前项目 quickstart-ruby-repo 中创建一个新的 Ruby gem 代码库。

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

    2. 运行以下命令确认已创建代码库：

      gcloud artifacts repositories list

    3. 为了简化 gcloud 命令，请将默认代码库设置为 quickstart-ruby-repo，并将默认位置设置为 us-west1。设置以上值之后，您无需在需要代码库或位置的 gcloud 命令中指定这些值。

      如需设置代码库，请运行以下命令：

      gcloud config set artifacts/repository quickstart-ruby-repo

      如需设置位置，请运行以下命令：

      gcloud config set artifacts/location us-west1

      如需详细了解这些命令，请参阅 gcloud config set 文档。

    下载 gem

    构建 Ruby 项目时，分发文件会保存在 Ruby 项目的 lib 子目录中。为简化本快速入门，您将创建一个目录，然后将 gem 下载到该目录。

    如需创建目录，请运行以下命令：

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

    接下来，下载您的 gem。您可以使用自己的 gem，也可以从 rubygems.org 的热门 gem 页面下载示例 gem。如需从 rubygems.org 下载 gem，请运行以下命令：

    gem fetch GEM_NAME

    现在，您的 ruby_quickstart/lib 目录中有一个名为 GEM_NAME 的 gem。在下一部分中，您将使用 RubyGems CLI 将 gem 推送到您的代码库。

    将 gem 推送到代码库

    如需将 gem 推送到您的代码库，请运行以下命令：

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

    其中：

    • GEM_NAME 是要推送到代码库的 gem 的名称。
    • PROJECT 是项目 ID。如果省略此标志，则系统会使用当前项目或默认项目。

    查看代码库中的 gem

    如需验证您的 gem 是否已添加，请列出 ruby-quickstart 代码库中的软件包。

    运行以下命令：

    gcloud artifacts packages list --repository=ruby-quickstart

    如需查看 gem 的版本，请运行以下命令：

    gcloud artifacts versions list --package=GEM_NAME

    安装 gem

    如需安装您刚刚推送到 Artifact Registry 代码库的 gem，请运行以下命令：

    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

    其中：

    • GEM_NAME 是要在代码库中安装的 gem 的名称。
    • PROJECT 是项目 ID。如果省略此标志，则系统会使用当前项目或默认项目。

    问题排查

    如需了解详情，请参阅 Ruby gem 问题排查。

    清理

    为避免因本页中使用的资源导致您的 Google Cloud 账号产生费用，请按照以下步骤操作。

    在移除代码库之前，请确保已在其他位置保存了您要保留的任何 gem。

    1. 如需删除 quickstart-ruby-repo 代码库，请运行以下命令：

      gcloud artifacts repositories delete quickstart-ruby-repo

    2. 如果要移除您为活跃 gcloud 配置配置的默认代码库和位置设置，请运行以下命令：

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

    后续步骤