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

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

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

事前準備

  1. 安裝 Google Cloud CLI。 安裝完成後，執行下列指令初始化 Google Cloud CLI： 

    gcloud init

    如果您使用外部識別資訊提供者 (IdP)，請先 使用聯合身分登入 gcloud CLI。

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

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

    主控台

    1. 在 Google Cloud 控制台中開啟「Repositories」(存放區) 頁面。

      開啟「存放區」頁面

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

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

    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 讀者角色。
  • 如果貴機構中的群組需要不同層級的特定存放區存取權，請在存放區層級授予存取權，而非專案層級。
  • 遵循管理憑證的最佳做法。

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

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。這項設定會覆寫從超級 POM 沿用的 central 存放區 ID 預設值。

    • <build> 區段會將 Artifact Registry wagon 設為擴充功能。如要瞭解 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 "gradle.plugin.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 "gradle.plugin.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. 在 Maven 專案的 pom.xml 檔案中，將傳回的存放區設定新增至 <project> 元素適當的區段。如要進一步瞭解檔案結構，請參閱 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. 在 ~/.m2/settings.xml 檔案的 <servers> 區段中，將傳回的驗證設定新增至 <settings> 元素。在下列範例中，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。這項設定會覆寫從超級 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 或完整識別碼。如果您已設定預設 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 區段中定義套件的依附元件。

驗證設定完成。

後續步驟