Menyimpan modul Go di Artifact Registry

Repositori Go Artifact Registry memungkinkan Anda menyimpan, membuat versi, dan membagikan modul Go pribadi di seluruh project Anda. Dalam panduan memulai ini, Anda akan membuat repositori, memaketkan dan mengupload modul contoh, serta mengimpor modul sebagai dependensi.

Sebelum memulai

  1. Login ke Akun Google Anda.

    Jika Anda belum memilikinya, Daftar untuk membuat akun baru.

  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, if it is not already enabled.

    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

  5. Install the Google Cloud CLI.

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

  7. To initialize the gcloud CLI, run the following command: 

    gcloud init

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

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

  10. Enable the Artifact Registry API, if it is not already enabled.

    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

  11. Install the Google Cloud CLI.

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

  13. To initialize the gcloud CLI, run the following command: 

    gcloud init
  14. Instal versi utama terbaru atau versi utama kedua terbaru Go. Versi yang lebih lama tidak didukung.
  15. Instal add-on gcloud CLI package-go-module: 
    gcloud components install package-go-module

Peran yang diperlukan

Untuk mendapatkan izin yang diperlukan guna membuat dan mengelola repositori modul Go Artifact Registry, minta administrator untuk memberi Anda peran IAM Artifact Registry Administrator (roles/artifactregistry.admin) di project Anda. Untuk mengetahui informasi selengkapnya tentang cara memberikan peran, lihat Mengelola akses ke project, folder, dan organisasi.

Anda mungkin juga bisa mendapatkan izin yang diperlukan melalui peran khusus atau peran bawaan lainnya.

Membuat repositori

Untuk membuat dan mengonfigurasi repositori baru:

  1. Jalankan perintah berikut untuk membuat repositori baru.

    gcloud artifacts repositories create REPOSITORY \
    --repository-format=go \
    --location=LOCATION \
    --description=DESCRIPTION

    Ganti kode berikut:

    • REPOSITORY adalah nama repositori. Untuk setiap lokasi repositori dalam project, nama repositori harus unik.
    • LOCATION adalah lokasi regional atau multi-regional untuk repositori. Anda dapat menghapus flag ini jika menetapkan default. Untuk melihat daftar lokasi yang didukung, jalankan perintah gcloud artifacts locations list.
    • DESCRIPTION adalah deskripsi opsional repositori. Jangan sertakan data sensitif, karena deskripsi repositori tidak dienkripsi.

  2. Jalankan perintah berikut untuk melihat detail repositori.

      gcloud artifacts repositories describe --location=LOCATION REPOSITORY

    Outputnya akan terlihat seperti berikut:

      Encryption: Google-managed key
  Repository Size: 0.000MB
  createTime: '2022-06-03T20:20:01.644813Z'
  format: GO
  mode: STANDARD_REPOSITORY
  name: projects/my-project/locations/us-west1/repositories/my-repo
  updateTime: '2022-06-03T20:20:01.644813Z'

Menetapkan default untuk perintah gcloud

Anda dapat menyederhanakan perintah gcloud CLI dengan mengonfigurasi nilai default untuk nilai project, repositori, dan lokasi. Setelah default dikonfigurasi, tag --project, --location, dan --repository tidak diperlukan.

Mengemas dan mengupload modul Go

Add-on gcloud CLI package-go-module mengemas modul Go Anda, sehingga Anda dapat membuat versi dan mengupload ke Artifact Registry menggunakan perintah gcloud.

Membuat modul Go

Pertama, buat modul Go sederhana untuk diupload ke repositori Anda.

  1. Di direktori beranda, buat direktori bernama "foo" untuk modul Anda

    mkdir foo

  2. Ubah direktori ke direktori modul Anda dan jalankan go mod init untuk membuat file go.mod untuk modul Anda.

      cd foo \
  go mod init example.com/foo

    Ganti example.com/foo dengan jalur modul. Lihat Referensi Modul Go untuk mengetahui informasi selengkapnya.

  3. Buat file foo.go di direktori foo Anda dengan konten berikut:

    
package foo

const HelloWorld = "Hello World!"

Mengemas dan mengupload modul

Kemas dan upload modul ke repositori Anda:

  gcloud artifacts go upload --project=PROJECT \
      --repository=REPOSITORY \
      --location=LOCATION \
      --module-path=example.com/foo \
      --version=VERSION \
      --source=SOURCE_LOCATION

Ganti kode berikut:

  • PROJECT dengan Google Cloud project ID Anda.
  • REPOSITORY dengan nama repositori tempat paket disimpan.
  • LOCATION dengan lokasi regional atau multi-regional repositori.
  • example.com/foo dengan jalur modul. Lihat Referensi Modul Go untuk mengetahui informasi selengkapnya.
  • VERSION dengan versi semantik modul dalam bentuk vX.Y.Z dengan X adalah versi utama, Y adalah versi minor, dan Z adalah versi patch.
  • SOURCE_LOCATION dengan jalur ke direktori root modul Go Anda. Jika Anda menghilangkan tanda --source, defaultnya adalah direktori saat ini.

Modul diupload ke Artifact Registry.

Untuk mengetahui informasi selengkapnya tentang cara membuat modul Go, lihat tutorial ini.

Membuat daftar modul

Jalankan perintah berikut untuk memeriksa modul Go yang diupload di project, repositori, dan lokasi default saat nilai default dikonfigurasi:

  gcloud artifacts packages list

Outputnya akan terlihat seperti berikut:

  Listing items under project my-project, location us-west1, repository my-repo.

  PACKAGE                   CREATE_TIME          UPDATE_TIME
  example.com/foo           2022-06-03T20:43:39  2022-06-20T20:37:40

Melihat detail versi modul

Jalankan perintah berikut untuk melihat versi modul Anda di project, repositori, dan lokasi default saat nilai default dikonfigurasi:

  gcloud artifacts versions list --package=MODULE_PATH

Outputnya akan terlihat seperti berikut:

  Listing items under project my-project, location us-west1, repository my-repo, package example.com/foo.

  VERSION  DESCRIPTION  CREATE_TIME          UPDATE_TIME
  v0.1.0                2022-06-03T20:43:39  2022-06-03T20:43:39
  v0.1.1                2022-06-20T20:37:40  2022-06-20T20:37:40

Download modul

Untuk mengimpor modul yang disimpan di Artifact Registry, Anda perlu menginstruksikan Go untuk mencari dependensi dari Artifact Registry, dan melewati database checksum.

Menyiapkan lingkungan Go

  1. Instruksikan Go untuk mendownload modul dari Artifact Registry, proxy modul Go publik, lalu sumber dalam urutan tersebut:

      export GOPROXY=https://LOCATION-go.pkg.dev/PROJECT/REPOSITORY,https://proxy.golang.org,direct

    Ganti kode berikut:

    • LOCATION adalah lokasi repositori regional atau multi-regional.
    • PROJECT adalah Google Cloud project ID Anda.
    • REPOSITORY adalah nama repositori tempat paket disimpan.

  2. Mengecualikan modul Anda agar tidak diperiksa menggunakan database checksum publik:

      export GONOSUMDB=MODULE_PATH_REGEX

    Ganti MODULE_PATH_REGEX dengan jalur modul atau ekspresi reguler jika Anda ingin mengecualikan beberapa modul.

    Untuk mengecualikan modul example.com/foo agar tidak diperiksa menggunakan database checksum publik, jalankan perintah berikut:

      export GONOSUMDB=example.com/foo

    Jika Anda ingin semua modul dengan jalur modul yang dimulai dengan example.com dikecualikan dari pemeriksaan menggunakan database checksum publik, jalankan perintah berikut:

      export GONOSUMDB=example.com/*

Melakukan autentikasi ke Artifact Registry

Saat mendownload modul Go yang dipaketkan untuk digunakan sebagai dependensi dari Artifact Registry, program biner Go menggunakan kredensial dalam file netrc Anda untuk melakukan autentikasi ke Artifact Registry. Untuk menyederhanakan proses autentikasi, Anda dapat menggunakan helper kredensial Go untuk memperbarui token di file netrc Anda untuk autentikasi ke Artifact Registry.

Lokasi file netrc Anda dapat ditetapkan dengan variabel lingkungan netrc. Jika variabel NETRC tidak ditetapkan, perintah go akan membaca $HOME/.netrc di platform mirip UNIX atau %USERPROFILE%\_netrc di Windows.

Artifact Registry mendukung metode autentikasi berikut.

Kredensial berumur pendek (direkomendasikan)
Gunakan alat bantuan kredensial Go Artifact Registry untuk memperbarui token autentikasi dalam file netrc Anda.
Menggunakan kunci akun layanan

Gunakan opsi ini jika Anda tidak dapat menggunakan kredensial di lingkungan Anda untuk autentikasi. Tambahkan kunci akun layanan yang tidak dienkripsi ke file netrc Anda.

Tambahkan helper kredensial Go ke GONOPROXY

Sebelum menggunakan helper kredensial Go, Anda perlu menambahkannya ke daftar GONOPROXY untuk memaksa Go mendownloadnya langsung dari GitHub. Jika memiliki modul lain yang ingin didownload langsung dari sumber, Anda dapat menambahkannya dalam daftar yang dipisahkan koma seperti yang ditunjukkan dalam contoh berikut:

  export GONOPROXY=MODULE_PATH1, MODULE_PATH2

Dengan MODULE_PATH1 dan MODULE_PATH2 adalah jalur modul dari modul yang akan didownload dari sumber.

Untuk menambahkan helper kredensial Go ke daftar GONOPROXY dan menjalankannya untuk menyiapkan kredensial Anda:

  1. Tambahkan helper kredensial Go ke GONOPROXY Anda

      export GONOPROXY=github.com/GoogleCloudPlatform/artifact-registry-go-tools

  2. Jalankan perintah berikut untuk menambahkan kredensial Artifact Registry ke file netrc Anda dengan alat paket modul Go:

      GOPROXY=proxy.golang.org \
      go run github.com/GoogleCloudPlatform/artifact-registry-go-tools/cmd/auth@v0.4.0 \
      add-locations --locations=LOCATION \
      [--json_key=path/to/service/account/key.json]

    Dengan LOCATION adalah lokasi regional atau multi-regional repositori Anda. Untuk menambahkan beberapa lokasi, masukkan lokasi tersebut sebagai daftar yang dipisahkan koma.

    Helper kredensial Go menambahkan setelan ke file netrc Anda untuk mengautentikasi ke Artifact Registry. Jika Anda meneruskan flag --json_key, kunci akan ditambahkan ke file netrc Anda untuk autentikasi sandi.

Menggunakan modul Anda sebagai dependensi

  1. Jika Anda menggunakan kredensial berumur pendek untuk mengautentikasi ke Artifact Registry, Anda harus memperbarui token OAuth dengan menjalankan perintah berikut:

      GOPROXY=proxy.golang.org \
  go run github.com/GoogleCloudPlatform/artifact-registry-go-tools/cmd/auth@v0.4.0 refresh

  2. Di direktori beranda, buat direktori bernama "bar"

      mkdir bar

  3. Ubah direktori ke direktori modul Anda dan jalankan go mod init untuk membuat file go.mod untuk paket Anda.

      cd bar \
  go mod init example.com/bar

    Ganti example.com/bar dengan jalur modul. Lihat Referensi Modul Go untuk mengetahui informasi selengkapnya.

  4. Untuk mewajibkan versi foo yang disimpan di Artifact Registry, edit file go.mod Anda agar terlihat seperti berikut:

    
module example.com/bar

go 1.19

require example.com/foo v0.1.0

    Ganti kode berikut:

    • example.com/foo adalah jalur modul dari modul yang diperlukan
    • v0.1.0 adalah versi yang disimpan di Artifact Registry

  5. Buat file main.go di direktori bar Anda dengan konten berikut:

      
  package main

  import (
    "fmt"

    foo "example.com/foo"
  )

  func main() {
    fmt.Println(foo.HelloWorld)
  }

  6. Jalankan go mod tidy untuk mendownload dependensi, termasuk paket foo:

      go mod tidy

  7. Jalankan modul bar:

      go run .

    Outputnya akan terlihat seperti berikut:

      Hello World!

Pembersihan

Agar akun Google Cloud Anda tidak dikenai biaya untuk resource yang digunakan pada halaman ini, ikuti langkah-langkah berikut.

Agar akun Google Cloud Anda tidak dikenai biaya untuk resource yang digunakan di halaman ini, ikuti langkah-langkah berikut. Sebelum menghapus repositori, pastikan modul apa pun yang ingin Anda simpan tersedia di lokasi lain.

  1. Untuk menghapus repositori:

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

    Ganti kode berikut:

    • LOCATION dengan lokasi regional atau multi-regional repositori.
    • PROJECT dengan Google Cloud project ID Anda.
    • REPOSITORY dengan nama repositori.

  2. Jika Anda ingin menghapus setelan repositori dan lokasi default yang Anda konfigurasi untuk konfigurasi gcloud aktif, jalankan perintah berikut:

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

Langkah berikutnya