為 Maven 和 Gradle 設定 Artifact Registry 的驗證機制

使用第三方應用程式連線至 Artifact Registry 存放區時，必須對 Artifact Registry 進行驗證。本文件著重於 Maven 和 Gradle 的設定。

您不需要為 Cloud Build 或 Google Cloud執行階段環境 (例如 Google Kubernetes Engine 和 Cloud Run) 設定驗證，但應確認已設定必要的權限。如需更多資訊，請參閱有關 Cloud Build 和部署至 Google Cloud 執行階段環境的相關資訊。

事前準備

  1. After installing the Google Cloud CLI, initialize it by running the following command: 

    gcloud init

    If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

  2. (選用) 設定 gcloud 指令的預設值。

  3. 如果您要使用標準存放區設定驗證，請驗證版本政策，以便針對可上傳的 Java 套件類型正確設定 Maven 專案。

    主控台

    1. 在 Google Cloud 控制台中開啟「Repositories」頁面。

      開啟「存放區」頁面

    2. 按一下要驗證的存放區。

      「Details」部分會顯示版本政策。如果存放區有快照版本政策，則「允許覆寫快照」欄位會指出快照是否可覆寫存放區中相符的快照版本。

    gcloud

    執行下列指令，查看存放區的說明。

    gcloud artifacts repositories describe REPOSITORY \
      --project=PROJECT \
      --location=LOCATION

    地點

    • REPOSITORY 是存放區的 ID。如果您已設定預設 Artifact Registry 存放區，當指令中省略這個旗標時，系統就會使用該存放區。
    • PROJECT 是專案 ID。如果省略這個標記，系統會使用目前或預設專案。
    • LOCATION 是存放區的位置 (單一區域或多區域)。

    指令的輸出內容包含 mavenConfig 底下的版本政策資訊。在這個範例中，存放區有快照版本政策，快照無法覆寫存放區中的相同版本。

    Encryption: Google-owned and Google-managed encryption key
createTime: '2021-10-04T19:39:10.897404Z'
format: MAVEN
mavenConfig:
  allowSnapshotOverwrites: false
  versionPolicy: SNAPSHOT

    如果存放區沒有版本政策，mavenConfig 的值就是 {}。

總覽

Artifact Registry 支援下列驗證方法。

使用驗證輔助程式
這個選項最具彈性。在 Maven 或 Gradle 設定中加入輔助程式後，Artifact Registry 會在環境中搜尋服務帳戶憑證。
指定服務帳戶金鑰做為憑證
如果應用程式不支援應用程式預設憑證，但支援使用者名稱和密碼驗證，請使用這個選項。

服務帳戶金鑰是長效憑證。請遵循下列規範，限制存放區的存取權：

  • 建議您使用專屬服務帳戶與存放區互動。
  • 授予服務帳戶所需的最低 Artifact Registry 角色。舉例來說，將 Artifact Registry Reader 指派給只下載構件服務帳戶。
  • 如果貴機構中的群組需要對特定存放區的不同存取層級，請在存放區層級 (而非專案層級) 授予存取權。
  • 請遵循憑證管理的最佳做法。

使用憑證輔助程式進行驗證

Artifact Registry 提供 Maven wagon 和 Gradle 外掛程式做為憑證輔助程式。使用憑證輔助程式時，憑證不會儲存在 Java 專案中。相反地，Artifact Registry 會按照以下順序搜尋憑證：

  1. 應用程式預設憑證 (ADC)：這種策略會依照以下順序尋找憑證：

    1. 在 GOOGLE_APPLICATION_CREDENTIALS 環境變數中定義的憑證。

    2. Compute Engine、Google Kubernetes Engine、Cloud Run、App Engine 或 Cloud Run 函式提供的預設服務帳戶憑證。

  2. Google Cloud CLI 提供的憑證，包括 gcloud auth application-default login 指令的使用者憑證。

GOOGLE_APPLICATION_CREDENTIALS 變數會明確指出用於驗證的帳戶，方便排解問題。如果您未使用變數，請確認 ADC 可能會使用的任何帳戶都具備必要的權限。舉例來說，Compute Engine VM、Google Kubernetes Engine 節點和 Cloud Run 修訂版本的預設服務帳戶，對存放區只有唯讀存取權。如果您打算使用預設服務帳戶從這些環境上傳資料，就必須修改權限。

為憑證輔助程式設定服務帳戶

如要建立服務帳戶並使用環境變數設定驗證，請按照下列步驟操作：

  1. 建立服務帳戶，以便代表應用程式執行動作，或選擇用於自動化的現有服務帳戶。

    您需要服務帳戶金鑰檔案的位置，才能設定 Artifact Registry 的驗證機制。如要查看現有帳戶的金鑰，或建立新的金鑰，請前往「服務帳戶」頁面。

    前往「Service Accounts」(服務帳戶) 頁面

  2. 授予服務帳戶特定的 Artifact Registry 角色，以便提供存放區存取權。

  3. 將服務帳戶金鑰檔案位置指派給 GOOGLE_APPLICATION_CREDENTIALS 變數，這樣 Artifact Registry 憑證輔助程式就能在連線至存放區時取得您的金鑰。

    export GOOGLE_APPLICATION_CREDENTIALS=KEY-FILE

    其中 KEY-FILE 是服務帳戶金鑰檔案的路徑。

設定 Maven

  1. 根據您使用的存放區類型設定 Maven。

    標準

    1. 執行下列指令，即可列印要新增至 Java 專案的存放區設定。

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

      地點

      • PROJECT 是專案 ID。如果省略這個標記，系統會使用目前或預設專案。
      • REPOSITORY 是存放區的 ID。如果您已設定預設 Artifact Registry 存放區，當指令省略這個旗標時，系統就會使用該存放區。
      • LOCATION 是存放區的位置 (單一區域或多區域)。

    2. 將傳回的設定新增至 Maven 專案 pom.xml 檔案中的適當部分。如要進一步瞭解檔案結構，請參閱 Maven POM 參考資料。

      以下範例顯示同時儲存快照和發布版本的存放區設定。

      <distributionManagement>
  <snapshotRepository>
    <id>artifact-registry</id>
    <url>artifactregistry://LOCATION-maven.pkg.dev/PROJECT/REPOSITORY</url>
  </snapshotRepository>
  <repository>
    <id>artifact-registry</id>
    <url>artifactregistry://LOCATION-maven.pkg.dev/PROJECT/REPOSITORY</url>
  </repository>
</distributionManagement>

<repositories>
  <repository>
    <id>artifact-registry</id>
    <url>artifactregistry://LOCATION-maven.pkg.dev/PROJECT/REPOSITORY</url>
    <releases>
      <enabled>true</enabled>
    </releases>
    <snapshots>
      <enabled>true</enabled>
    </snapshots>
  </repository>
</repositories>

<build>
  <extensions>
    <extension>
      <groupId>com.google.cloud.artifactregistry</groupId>
      <artifactId>artifactregistry-maven-wagon</artifactId>
      <version>2.2.5</version>
    </extension>
  </extensions>
</build>

      <release> 和 <snapshot> 元素會指出存放區是否儲存發布套件、快照套件，或兩者皆儲存。這些設定應與存放區版本政策相符。

      <build> 元素會將 Artifact Registry 貨櫃定義為擴充功能。如需 Wagon 相關資訊，請參閱 Artifact Registry Maven 工具的說明文件。

    遠端或虛擬

    編輯專案中的 pom.xml 檔案。如要進一步瞭解檔案結構，請參閱 Maven POM 參考資料。

    以下範例顯示儲存快照和發布版本的遠端存放區設定。在這個範例中，專案依附元件是 Guava 套件的某個版本。

    <?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>

  <groupId>com.google.hello</groupId>
  <artifactId>repo-config</artifactId>
  <version>4.1-SNAPSHOT</version>
  <description>version 1 release</description>

  <properties>
    <maven.compiler.source>1.8</maven.compiler.source>
    <maven.compiler.target>1.8</maven.compiler.target>
  </properties>
  <dependencies>
    <dependency>
      <groupId>com.google.guava</groupId>
      <artifactId>guava</artifactId>
      <version>28.0-jre</version>
    </dependency>
  </dependencies>

  <repositories>
    <repository>
      <id>central</id>
      <name>Maven Central remote repository</name>
      <url>artifactregistry://LOCATION-maven.pkg.dev/PROJECT_ID/REMOTE-REPOSITORY-NAME</url>
      <layout>default</layout>
      <releases>
        <enabled>true</enabled>
      </releases>
      <snapshots>
        <enabled>true</enabled>
      </snapshots>
    </repository>
  </repositories>

  <build>
    <extensions>
      <extension>
        <groupId>com.google.cloud.artifactregistry</groupId>
        <artifactId>artifactregistry-maven-wagon</artifactId>
        <version>2.2.5</version>
      </extension>
    </extensions>
  </build>
</project>

    • <repositories> 部分會定義 Artifact Registry 存放區。對於遠端存放區，<id> 元素必須設為 central。這項設定會覆寫從 Super POM 繼承的 central 存放區 ID 的預設值。

    • <build> 部分會將 Artifact Registry 貨車設為擴充功能。如要瞭解 Wagon，請參閱 Artifact Registry Maven 工具的說明文件。

    • 在這個範例中，<dependencies> 區段會設定 Guava 套件版本 28.0-jre 的依附元件。

  2. Maven 會在套用 pom.xml 中定義的 wagon 之前，先解析部分依附元件，包括：

    • 子 Maven 專案中使用 <parent> 元素參照父專案。
    • 儲存在 Artifact Registry 中的外掛程式依附元件。

    如果專案需要解析這些依附元件，您必須使用核心擴充功能機制，確保 Maven 可以找到父項 POM 檔案和外掛程式。

    在專案中，建立含有以下內容的 ${maven.projectBasedir}/.mvn/extensions.xml 檔案。<extension> 元素會定義車廂。

    <extensions xmlns="http://maven.apache.org/EXTENSIONS/1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/EXTENSIONS/1.0.0 http://maven.apache.org/xsd/core-extensions-1.0.0.xsd">
  <extension>
    <groupId>com.google.cloud.artifactregistry</groupId>
    <artifactId>artifactregistry-maven-wagon</artifactId>
    <version>2.2.5</version>
  </extension>
</extensions>

    Maven 現在可以從 Artifact Registry 解析父項或外掛程式依附元件。

驗證設定已完成。

設定 Gradle

  1. 根據您使用的存放區類型設定 Gradle。

    標準

    1. 執行下列指令，即可列印要新增至 Java 專案的存放區設定。

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

      地點

      • PROJECT 是專案 ID。如果省略這個標記，系統會使用目前或預設專案。
      • REPOSITORY 是存放區的 ID。如果您已設定預設 Artifact Registry 存放區，當指令省略這個旗標時，系統就會使用該存放區。
      • LOCATION 是存放區的位置 (單一區域或多區域)。

    2. 將存放區設定新增至 build.gradle 檔案。以下範例顯示列印區段的相對位置。

      plugins {
  id "maven-publish"
  id "com.google.cloud.artifactregistry.gradle-plugin" version "2.2.5"
}

publishing {
  publications {
    mavenJava(MavenPublication) {
      groupId 'maven.example.id'
      from components.java
     }
  }
  repositories {
    maven {
      url "artifactregistry://LOCATION-maven.pkg.dev/PROJECT/REPOSITORY"
    }
  }
}
repositories {
  maven {
    url "artifactregistry://LOCATION-maven.pkg.dev/PROJECT/REPOSITORY"
  }
}

      • plugins 區段會宣告 Artifact Registry 外掛程式。如需瞭解外掛程式相關資訊，請參閱 Artifact Registry Maven 工具的說明文件。

      • publishing 部分會定義要上傳的檔案和目標 Artifact Registry 存放區。準備上傳時，您可以更新 publications 部分的檔案清單。如需發布設定的相關資訊，請參閱 Maven Publish 外掛程式說明文件。

    遠端或虛擬

    將存放區設定新增至 build.gradle 檔案。

    以下範例顯示遠端存放區的設定。在這個範例中，專案依附於 Guava 套件的某個版本。

    plugins {
  id 'java'
  id "maven-publish"
  id "com.google.cloud.artifactregistry.gradle-plugin" version "2.2.5"
  id 'maven'
}

repositories {
  maven {
    url "artifactregistry://LOCATION-maven.pkg.dev /PROJECT_ID/REMOTE-REPOSITORY-NAME"
  }
}
dependencies {
  compile "com.google.guava:guava:31.1-jre"
}

    • plugins 區段會宣告 Artifact Registry 外掛程式。如需瞭解外掛程式相關資訊，請參閱 Artifact Registry Maven 工具的說明文件。

    • repositories 部分會定義 Artifact Registry 存放區。

    • 在這個範例中，dependencies 區段會設定 Guava 套件版本 31.1-jre 的依附元件。

    在 dependencies 部分定義套件的依附元件。

  2. 如果您需要在 init.gradle 或 settings.gradle 檔案中使用存放區，可以將外掛程式設定新增至這些檔案。

    針對 init.gradle，新增下列設定：

    initscript {
  repositories {
    maven {
      url "https://plugins.gradle.org/m2/"
    }
  }
  dependencies {
    classpath "com.google.cloud.artifactregistry:artifactregistry-gradle-plugin:2.2.5"
  }
}
apply plugin: com.google.cloud.artifactregistry.gradle.plugin.ArtifactRegistryGradlePlugin

    針對 settings.gradle，請新增下列設定：

    buildscript {
  repositories {
    maven {
      url "https://plugins.gradle.org/m2/"              }
    }
  dependencies {
    classpath "com.google.cloud.artifactregistry:artifactregistry-gradle-plugin:2.2.5"
  }
}
apply plugin: "com.google.cloud.artifactregistry.gradle-plugin"

驗證設定已完成。

設定密碼驗證

如果 Java 應用程式需要使用指定的使用者名稱和密碼進行驗證，請採用這種方法。

設定服務帳戶以進行密碼驗證

如何建立服務帳戶：

  1. 建立服務帳戶，以便代表應用程式執行動作，或選擇用於自動化的現有服務帳戶。

    您需要服務帳戶金鑰檔案的位置，才能設定 Artifact Registry 的驗證機制。如要查看現有帳戶的金鑰，或建立新的金鑰，請前往「服務帳戶」頁面。

    前往「Service Accounts」(服務帳戶) 頁面

  2. 如要在目前的 gcloud CLI 工作階段中啟用服務帳戶，請執行以下指令：

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

    地點

    • ACCOUNT 是使用者或服務帳戶。
    • KEY-FILE 是服務帳戶 JSON 金鑰檔案的路徑。

設定 Maven

  1. 根據您使用的存放區類型設定 Maven。

    標準

    1. 執行下列指令，即可列印要新增至 Java 專案的存放區設定。

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

      地點

      • PROJECT 是專案 ID。如果省略這個標記，系統會使用目前或預設專案。
      • REPOSITORY 是存放區的 ID。如果您已設定預設 Artifact Registry 存放區，當指令中省略這個旗標時，系統就會使用該存放區。
      • LOCATION 是存放區的位置 (單一區域或多區域)。
      • KEY-FILE 是服務帳戶 JSON 金鑰檔案的路徑。

    這項指令會傳回要納入 Java 專案的設定，包括私密金鑰的 Base64 編碼版本。

    1. 將 <project> 元素中傳回的存放區設定新增至 Maven 專案 pom.xml 檔案的適當部分。如要進一步瞭解檔案結構，請參閱 Maven POM 參考資料。
    <project>
  <distributionManagement>
    <snapshotRepository>
      <id>artifact-registry</id>
      <url>https://LOCATION-maven.pkg.dev/PROJECT/REPOSITORY</url>
    </snapshotRepository>
    <repository>
      <id>artifact-registry</id>
      <url>https://LOCATION-maven.pkg.dev/PROJECT/REPOSITORY</url>
    </repository>
  </distributionManagement>

  <repositories>
    <repository>
      <id>artifact-registry</id>
      <url>https://LOCATION-maven.pkg.dev/PROJECT/REPOSITORY</url>
      <releases>
        <enabled>true</enabled>
      </releases>
      <snapshots>
        <enabled>true</enabled>
      </snapshots>
    </repository>
  </repositories>
</project>

    <release> 和 <snapshot> 元素會指出存放區是否儲存發布套件、快照套件，或兩者皆儲存。這些設定應與存放區版本政策相符。

    1. 將 <settings> 元素中傳回的驗證設定新增至 ~/.m2/settings.xml 檔案的 <servers> 部分。在以下範例中，KEY 是金鑰檔案中的 Base64 編碼金鑰。

    詳情請參閱 Maven 設定參考資料。

    <settings>
  <servers>
    <server>
      <id>artifact-registry</id>
      <configuration>
        <httpConfiguration>
          <get>
            <usePreemptive>true</usePreemptive>
          </get>
          <head>
            <usePreemptive>true</usePreemptive>
          </head>
          <put>
            <params>
              <property>
                <name>http.protocol.expect-continue</name>
                <value>false</value>
              </property>
            </params>
          </put>
        </httpConfiguration>
      </configuration>
      <username>_json_key_base64</username>
      <password>KEY</password>
    </server>
  </servers>
</settings>

    遠端或虛擬

    1. 將存放區設定新增至 Maven 專案的 pom.xml 檔案中適當的部分。如要進一步瞭解檔案結構，請參閱 Maven POM 參考資料。

      <repositories>
  <repository>
     <id>central</id>
     <name>Maven Central remote repository</name>
     <url>artifactregistry://LOCATION-maven.pkg.dev/PROJECT_ID/REMOTE-REPOSITORY-NAME</url>
     <layout>default</layout>
     <releases>
       <enabled>true</enabled>
     </releases>
     <snapshots>
      <enabled>true</enabled>
    </snapshots>
  </repository>
</repositories>

    <repositories> 部分會定義 Artifact Registry 存放區。對於遠端存放區，<id> 元素必須設為 central。這項設定會覆寫從 Super POM 繼承的 central 存放區 ID 的預設值。

    1. 使用下列指令，以 Base64 編碼金鑰檔案。將 KEY-FILE 替換為金鑰檔案的名稱。

      base64 -w 0 KEY-FILE

    2. 將 <settings> 元素中的驗證設定新增至 ~/.m2/settings.xml 檔案的 <servers> 部分。

    詳情請參閱 Maven 設定參考資料。

    <settings>
  <servers>
    <server>
      <id>artifact-registry</id>
      <configuration>
        <httpConfiguration>
          <get>
            <usePreemptive>true</usePreemptive>
          </get>
          <head>
            <usePreemptive>true</usePreemptive>
          </head>
          <put>
            <params>
              <property>
                <name>http.protocol.expect-continue</name>
                <value>false</value>
              </property>
            </params>
          </put>
        </httpConfiguration>
      </configuration>
      <username>_json_key_base64</username>
      <password>KEY</password>
    </server>
  </servers>
</settings>
    1. 如果您使用的是 HTTP 端點，且想要使用 Maven 原生連線來驗證，可以在 settings.xml 中使用自訂 HTTP 標頭傳遞驗證標頭。

    範例：

    <settings>
<servers>
  <server>
    <id>artifact-registry</id>
    <configuration>
      <httpHeaders>
        <property>
          <name>Authorization </name>
          <value>Bearer ${artifact.registry.token}</value>
        </property>
      </httpHeaders>
      <httpConfiguration>
        <get>
          <usePreemptive>true</usePreemptive>
        </get>
        <head>
          <usePreemptive>true</usePreemptive>
        </head>
        <put>
          <params>
            <property>
              <name>http.protocol.expect-continue</name>
              <value>false</value>
            </property>
          </params>
        </put>
      </httpConfiguration>
    </configuration>
  </server>
</servers>
</settings>

驗證設定已完成。

設定 Gradle

  1. 根據您使用的存放區類型設定 Gradle。

    標準

    1. 執行下列指令，即可列印要新增至 Java 專案的存放區設定。

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

      地點

      • PROJECT 是專案 ID。
      • REPOSITORY 是存放區的 ID 或完整修飾符 ID。如果您已設定預設 Artifact Registry 存放區，當指令省略這個旗標時，系統就會使用該存放區。
      • KEY-FILE 是服務帳戶 JSON 金鑰檔案的路徑。如果您已執行指令來啟用服務帳戶，可以略過這個標記。

      這項指令會傳回要納入 Java 專案的設定，包括私密金鑰的 Base64 編碼版本。

    2. 在傳回的設定中，下列一行會為服務帳戶鍵定義名為 artifactRegistryMavenSecret 的變數。將這行指令新增至 ~/.gradle/gradle.properties 檔案，這樣在版本或來源控制存放區中就不會顯示金鑰。

      artifactRegistryMavenSecret = KEY

      在這行中，KEY 是服務帳戶金鑰檔案中的私密金鑰。對於 _json_key_base64，artifactRegistryMavenSecret 會設為 Base64 編碼金鑰，做為密碼。

    3. 在 build.gradle 中指定存放區設定：

      plugins {
  id "maven-publish"
}

publishing {
  publications {
    mavenJava(MavenPublication) {
      groupId 'maven.example.id'
      from components.java
    }
  }
  repositories {
    maven {
      url "https://LOCATION-maven.pkg.dev/PROJECT/REPOSITORY"
      credentials {
        username = "_json_key_base64"
        password = "$artifactRegistryMavenSecret"
      }
      authentication {
        basic(BasicAuthentication)
      }
    }
  }
}
repositories {
  maven {
    url "https://LOCATION-maven.pkg.dev/PROJECT/REPOSITORY"
    credentials {
      username = "_json_key_base64"
      password = "$artifactRegistryMavenSecret"
    }
    authentication {
      basic(BasicAuthentication)
    }
  }
}
      • repositories 部分會設定存放區網址和驗證憑證。
      • publishing 部分會定義要上傳的檔案和目標 Artifact Registry 存放區。準備上傳時，您可以更新 publications 部分的檔案清單。如需發布設定的相關資訊，請參閱 Maven Publish 外掛程式說明文件。

    遠端或虛擬

    1. 使用下列指令，以 Base64 編碼金鑰檔案。將 KEY-FILE 替換為金鑰檔案的名稱。

      base64 -w 0 KEY-FILE

    2. 在 ~/.gradle/gradle.properties 檔案中新增下列行，這樣您的金鑰就不會顯示在版本或來源控管存放區中。

      artifactRegistryMavenSecret = KEY

      在這行中，KEY 是 base64 編碼金鑰檔案的內容。

    3. 將存放區設定新增至 build.gradle 檔案。

    以下範例說明遠端存放區的設定。

    plugins {
  id 'java'
  id "maven-publish"
  id 'maven'
}

repositories {
  maven {
    url "artifactregistry://LOCATION-maven.pkg.dev /PROJECT_ID/REMOTE-REPOSITORY-NAME"
    credentials {
    username = "_json_key_base64"
    password = "$artifactRegistryMavenSecret"
  }
  authentication {
    basic(BasicAuthentication)
  }
  dependencies {
    compile "com.google.guava:guava:31.1-jre"
  }

    • repositories 部分會定義 Artifact Registry 存放區。

    • 在這個範例中，dependencies 區段會設定 Guava 套件版本 31.1-jre 的依附元件。

    在 dependencies 部分定義套件的依附元件。

驗證設定已完成。

後續步驟