Menyinkronkan artefak OCI dari Artifact Registry

Halaman ini menunjukkan cara membuat dan memublikasikan image Anda ke repositori di Artifact Registry dengan crane dan oras.

Anda dapat mengonfigurasi Config Sync untuk menyinkronkan dari image OCI menggunakan Artifact Registry. Untuk menggunakan fitur ini, Anda harus mengaktifkan RootSync dan RepoSync API.

Tentang Artifact Registry

Artifact Registry adalah layanan terkelola sepenuhnya dengan dukungan untuk image container dan artefak non-container. Kami merekomendasikan Artifact Registry untuk penyimpanan dan pengelolaan image container Anda di Google Cloud. Ada banyak alat yang tersedia untuk mengirim artefak ke Artifact Registry. Misalnya, Anda dapat mengirim image Docker atau menggunakan library go-containerregistry untuk bekerja dengan container registry. Pilih alat yang paling sesuai untuk Anda.

Perhatian: Jangan menambahkan image dasar ke file OCI yang disimpan di Artifact Registry. Karena gambar OCI berfungsi sebagai penyimpanan file, penambahan gambar dasar dapat menyebabkan masalah izin saat menyinkronkan.

Sebelum memulai

Login ke akun Google Cloud Anda. Jika Anda baru menggunakan Google Cloud, buat akun untuk mengevaluasi performa produk kami dalam skenario dunia nyata. Pelanggan baru juga mendapatkan kredit gratis senilai $300 untuk menjalankan, menguji, dan men-deploy workload.

Instal Google Cloud CLI.

Catatan: Jika Anda telah menginstal gcloud CLI sebelumnya, pastikan Anda memiliki versi terbaru dengan menjalankan gcloud components update.

Jika Anda menggunakan penyedia identitas (IdP) eksternal, Anda harus login ke gcloud CLI dengan identitas gabungan Anda terlebih dahulu.

Untuk melakukan inisialisasi gcloud CLI, jalankan perintah berikut:

gcloud init

Buat atau pilih Google Cloud project.

Peran yang diperlukan untuk memilih atau membuat project

• Pilih project: Memilih project tidak memerlukan peran IAM tertentu—Anda dapat memilih project yang telah diberi peran.
• Membuat project: Untuk membuat project, Anda memerlukan peran Project Creator (roles/resourcemanager.projectCreator), yang berisi izin resourcemanager.projects.create. Pelajari cara memberikan peran.

Catatan: Jika Anda tidak berencana untuk menyimpan resource yang Anda buat dalam prosedur ini, buatlah project, bukan memilih project yang ada. Setelah menyelesaikan langkah ini, Anda dapat menghapus project, yang menghapus semua resource yang terkait dengan project ini.

• Buat Google Cloud project:

  gcloud projects create PROJECT_ID

  Ganti PROJECT_ID dengan nama untuk Google Cloud project yang Anda buat.

• Pilih project Google Cloud yang Anda buat:

  gcloud config set project PROJECT_ID

  Ganti PROJECT_ID dengan nama project Google Cloud Anda.

Verifikasi bahwa penagihan diaktifkan untuk project Google Cloud Anda.

Aktifkan GKE API, Config Sync API, dan Artifact Registry API, jika ada yang belum diaktifkan:

Peran yang diperlukan untuk mengaktifkan API

Untuk mengaktifkan API, Anda memerlukan izin serviceusage.services.enable. Jika Anda membuat project, kemungkinan Anda sudah memiliki izin ini melalui peran Pemilik (roles/owner). Jika tidak, Anda bisa mendapatkan izin ini melalui peran Admin Penggunaan Layanan (roles/serviceusage.serviceUsageAdmin). Pelajari cara memberikan peran.

gcloud services enable container.googleapis.com  anthosconfigmanagement.googleapis.com  artifactregistry.googleapis.com

Instal Google Cloud CLI.

Catatan: Jika Anda telah menginstal gcloud CLI sebelumnya, pastikan Anda memiliki versi terbaru dengan menjalankan gcloud components update.

Jika Anda menggunakan penyedia identitas (IdP) eksternal, Anda harus login ke gcloud CLI dengan identitas gabungan Anda terlebih dahulu.

Untuk melakukan inisialisasi gcloud CLI, jalankan perintah berikut:

gcloud init

Buat atau pilih Google Cloud project.

Peran yang diperlukan untuk memilih atau membuat project

• Pilih project: Memilih project tidak memerlukan peran IAM tertentu—Anda dapat memilih project yang telah diberi peran.
• Membuat project: Untuk membuat project, Anda memerlukan peran Project Creator (roles/resourcemanager.projectCreator), yang berisi izin resourcemanager.projects.create. Pelajari cara memberikan peran.

Catatan: Jika Anda tidak berencana untuk menyimpan resource yang Anda buat dalam prosedur ini, buatlah project, bukan memilih project yang ada. Setelah menyelesaikan langkah ini, Anda dapat menghapus project, yang menghapus semua resource yang terkait dengan project ini.

• Buat Google Cloud project:

  gcloud projects create PROJECT_ID

  Ganti PROJECT_ID dengan nama untuk Google Cloud project yang Anda buat.

• Pilih project Google Cloud yang Anda buat:

  gcloud config set project PROJECT_ID

  Ganti PROJECT_ID dengan nama project Google Cloud Anda.

Verifikasi bahwa penagihan diaktifkan untuk project Google Cloud Anda.

Aktifkan GKE API, Config Sync API, dan Artifact Registry API, jika ada yang belum diaktifkan:

Peran yang diperlukan untuk mengaktifkan API

Untuk mengaktifkan API, Anda memerlukan izin serviceusage.services.enable. Jika Anda membuat project, kemungkinan Anda sudah memiliki izin ini melalui peran Pemilik (roles/owner). Jika tidak, Anda bisa mendapatkan izin ini melalui peran Admin Penggunaan Layanan (roles/serviceusage.serviceUsageAdmin). Pelajari cara memberikan peran.

gcloud services enable container.googleapis.com  anthosconfigmanagement.googleapis.com  artifactregistry.googleapis.com

1. Buat, atau miliki akses ke, cluster yang memenuhi persyaratan untuk Config Sync dan menggunakan Config Sync versi terbaru.
2. Instal nomos CLI atau upgrade ke versi terbaru.
3. (Opsional) Jika Anda ingin menggunakan Cosign untuk memverifikasi tanda tangan gambar OCI, instal berikut ini:
• Cosign untuk menandatangani image OCI.
• OpenSSL untuk membuat kredensial bagi server webhook.
• Docker untuk membangun dan mengirim image server Admission Webhook.

Biaya

Dalam dokumen ini, Anda akan menggunakan komponen Google Cloudyang dapat ditagih berikut:

• GKE
• Artifact Registry

Untuk membuat perkiraan biaya berdasarkan proyeksi penggunaan Anda, gunakan kalkulator harga.

Pengguna Google Cloud baru mungkin memenuhi syarat untuk mendapatkan uji coba gratis.

Membuat repositori Artifact Registry

Di bagian ini, Anda akan membuat repositori Artifact Registry. Untuk mempelajari lebih lanjut cara membuat repositori Artifact Registry, lihat Membuat repositori.

Buat repositori Artifact Registry:

gcloud artifacts repositories create AR_REPO_NAME \
   --repository-format=docker \
   --location=AR_REGION \
   --description="Config Sync repo" \
   --project=PROJECT_ID

Ganti kode berikut:

• PROJECT_ID: project ID organisasi.
• AR_REPO_NAME: ID repositori.
• AR_REGION: lokasi repositori regional atau multi-regional.

Variabel yang digunakan di bagian berikut:

• FLEET_HOST_PROJECT_NUMBER: jika Anda menggunakan GKE Workload Identity Federation for GKE, nilai ini sama dengan nomor project untuk PROJECT_ID. Jika Anda menggunakan Workload Identity Federation for GKE, ini adalah nomor project fleet tempat cluster Anda terdaftar.
• FLEET_HOST_PROJECT_ID: jika Anda menggunakan GKE Workload Identity Federation for GKE, nilai ini sama dengan PROJECT_ID. Jika Anda menggunakan fleet Workload Identity Federation untuk GKE, ini adalah project ID fleet tempat cluster Anda terdaftar.
• KUBERNETES_SERVICEACCOUNT: ServiceAccount Kubernetes untuk rekonsiliasi:
  • Untuk repositori root, jika nama RootSync adalah root-sync, tambahkan root-reconciler. Jika tidak, tambahkan root-reconciler-ROOT_SYNC_NAME.
  • Untuk repositori namespace, jika nama RepoSync adalah repo-sync, tambahkan ns-reconciler-NAMESPACE. Jika tidak, tambahkan ns-reconciler-NAMESPACE-REPO_SYNC_NAME-REPO_SYNC_NAME_LENGTH dengan REPO_SYNC_NAME_LENGTH adalah jumlah karakter dalam REPO_SYNC_NAME.

Memberikan izin pembaca

Berikan peran Artifact Registry Reader (roles/artifactregistry.reader) di repositori ke ServiceAccount Kubernetes:

gcloud artifacts repositories add-iam-policy-binding AR_REPO_NAME \
   --location=AR_REGION \
   --member="principal://iam.googleapis.com/projects/FLEET_HOST_PROJECT_NUMBER/locations/global/workloadIdentityPools/FLEET_HOST_PROJECT_ID.svc.id.goog/subject/ns/config-management-system/sa/KUBERNETES_SERVICEACCOUNT" \
   --role=roles/artifactregistry.reader \
   --project=PROJECT_ID \
   --condition=None

Mengirim image ke repositori Artifact Registry

Di bagian ini, Anda akan membuat image OCI dan mengirimkannya ke Artifact Registry.

1. Buat file manifes Namespace:

   cat <<EOF> test-namespace.yaml
   apiVersion: v1
   kind: Namespace
   metadata:
     name: test
   EOF
   

2. Login ke Artifact Registry:

   gcloud auth configure-docker AR_REGION-docker.pkg.dev
   

3. Kemasi dan kirim image ke Artifact Registry:

   crane

   Perintah di bagian ini menggunakan crane untuk berinteraksi dengan image dan registry jarak jauh.

   1. Paketkan file:

      tar -cf test-namespace.tar test-namespace.yaml
      

   2. Instal alat crane.

   3. Mengirim image ke Artifact Registry:

      crane append -f test-namespace.tar -t AR_REGION-docker.pkg.dev/PROJECT_ID/AR_REPO_NAME/test-namespace:v1
      

   oras

   Perintah di bagian ini menggunakan oras untuk berinteraksi dengan image dan registry jarak jauh.

   1. Paketkan file:

      tar -czf test-namespace.tar.gz test-namespace.yaml
      

   2. Instal alat oras.

   3. Mengirim image ke Artifact Registry:

      oras push AR_REGION-docker.pkg.dev/PROJECT_ID/AR_REPO_NAME/test-namespace:v1 test-namespace.tar.gz
      

   Perhatian: Config Sync mengharuskan lapisan OCI dikompresi dalam format tar atau tar+gzip. Format lain (misalnya, tar+bz2) tidak dikenali oleh Config Sync. Beralih dari REPO yang valid ke image OCI dengan format yang tidak didukung akan menyebabkan resource terkelola dipangkas tanpa error.

Mengonfigurasi Config Sync untuk menyinkronkan dari image Anda

Di bagian ini, Anda akan membuat objek RootSync dan mengonfigurasi Config Sync untuk menyinkronkan dari image OCI.

1. Buat objek RootSync dengan nama unik:

   cat <<EOF>> ROOT_SYNC_NAME.yaml
   apiVersion: configsync.gke.io/v1beta1
   kind: RootSync
   metadata:
     name: ROOT_SYNC_NAME
     namespace: config-management-system
   spec:
     sourceFormat: unstructured
     sourceType: oci
     oci:
       image: AR_REGION-docker.pkg.dev/PROJECT_ID/AR_REPO_NAME/test-namespace:v1
       dir: .
       auth: k8sserviceaccount
   EOF
   

   Ganti ROOT_SYNC_NAME dengan nama objek RootSync Anda. Nama harus unik dalam cluster dan tidak boleh lebih dari 26 karakter. Untuk mengetahui daftar lengkap opsi saat mengonfigurasi objek RootSync, lihat kolom RootSync dan RepoSync.

2. Terapkan objek RootSync:

   kubectl apply -f ROOT_SYNC_NAME.yaml
   

3. Pastikan Config Sync menyinkronkan dari image:

   nomos status --contexts=$(kubectl config current-context)
   

   Anda akan melihat output yang mirip dengan contoh berikut ini:

   Connecting to clusters...
   
   *publish-config-registry
      --------------------
      <root>:root-sync-test   AR_REGION-docker.pkg.dev/PROJECT_ID/AR_REPO_NAME/test-namespace:v1   
      SYNCED                  05e6a6b77de7a62286387cfea833d45290105fe84383224938d7b3ab151a55a1
      Managed resources:
         NAMESPACE   NAME             STATUS    SOURCEHASH
                     namespace/test   Current   05e6a6b
   

   Anda kini telah berhasil menyinkronkan image ke cluster.

(Opsional) Memverifikasi tanda tangan sumber OCI

Anda dapat memverifikasi keaslian image sumber OCI sebelum konfigurasi diterapkan ke cluster Anda. Metode ini menggunakan objek ValidatingWebhookConfiguration dan server webhook validasi untuk mencegat permintaan update untuk objek RootSync dan RepoSync. Config Sync mengupdate anotasi configsync.gke.io/image-to-sync objek RootSync dan RepoSync setelah berhasil mengambil ringkasan image baru. Server webhook validasi membandingkan nilai antara anotasi lama dan anotasi baru, serta menjalankan validasi dengan alat validasi seperti Cosign saat perubahan terdeteksi.

Menyiapkan server verifikasi tanda tangan

Untuk memastikan keaslian sumber OCI Anda, Anda memerlukan server HTTP untuk memverifikasi tanda tangan. Anda dapat menggunakan contoh di repositori contoh Config Sync atau menggunakan image Docker Anda sendiri.

1. Jika Anda ingin menggunakan sampel yang disediakan, selesaikan langkah-langkah berikut:

   1. Gandakan repositori contoh:

      git clone https://github.com/GoogleCloudPlatform/anthos-config-management-samples/
      

   2. Ubah ke direktori yang berisi contoh server verifikasi tanda tangan:

      cd anthos-config-management-samples/tree/main/pre-sync/oci-image-verification
      

2. Untuk membuat image Docker bagi server verifikasi tanda tangan dan mengirimkannya ke registry image, jalankan perintah berikut:

   docker build -t SIGNATURE_VERIFICATION_SERVER_IMAGE_URL:latest . && docker push SIGNATURE_VERIFICATION_SERVER_IMAGE_URL:latest
   

   Ganti SIGNATURE_VERIFICATION_SERVER_IMAGE_URL dengan URL image server verifikasi tanda tangan Anda.

Mengautentikasi ke layanan

Untuk menyiapkan server verifikasi tanda tangan, Anda harus mengautentikasi ke Artifact Registry, klien Cosign, dan server webhook.

1. Buat namespace

   kubectl create ns signature-verification
   

2. Untuk melakukan autentikasi ke Artifact Registry dengan ServiceAccount Kubernetes, selesaikan langkah-langkah berikut:

   1. Buat ServiceAccount Kubernetes di namespace yang Anda buat:

      kubectl create sa signature-verification-sa -n signature-verification
      

   2. Berikan peran Artifact Registry Reader (roles/artifactregistry.reader) di repositori ke ServiceAccount Kubernetes:

      gcloud artifacts repositories add-iam-policy-binding REPOSITORY_NAME \
         --location=REPOSITORY_LOCATION \
         --member="principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/PROJECT_ID.svc.id.goog/subject/ns/signature-verification/sa/signature-verification-sa" \
         --role=roles/artifactregistry.reader \
         --project=PROJECT_ID \
         --condition=None
      

      Ganti kode berikut:

      • REPOSITORY_NAME: nama repositori Artifact Registry tempat Anda menyimpan image OCI.
      • REPOSITORY_LOCATION: lokasi repositori Artifact Registry Anda.
      • PROJECT_NUMBER: nomor project Anda.
      • PROJECT_ID: project ID Anda.

3. Untuk melakukan autentikasi ke klien Cosign, selesaikan langkah-langkah berikut:

   1. Buat pasangan kunci Cosign. Perintah ini menghasilkan kunci publik dan pribadi:

      cosign generate-key-pair
      

   2. Simpan kunci publik di Secret Kubernetes dalam namespace yang Anda buat:

      kubectl create secret generic cosign-key --from-file=cosign.pub -n signature-verification
      

4. Untuk mengautentikasi server verifikasi tanda tangan, selesaikan langkah-langkah berikut:

   1. Untuk mengenkripsi komunikasi dalam server verifikasi tanda tangan, buat sertifikat TLS dan kunci pribadi dengan OpenSSL:

      openssl req -nodes -x509 -sha256 -newkey rsa:4096 \
      -keyout tls.key \
      -out tls.crt \
      -days 356 \
      -subj "/CN=signature-verification-service.signature-verification.svc"  \
      -addext "subjectAltName = DNS:signature-verification-service,DNS:signature-verification-service.signature-verification.svc,DNS:signature-verification-service.signature-verification"
      

   2. Simpan kredensial yang Anda buat di Secret Kubernetes:

      kubectl create secret tls webhook-tls --cert=tls.crt --key=tls.key -n signature-verification
      

   3. Dapatkan konten berenkode base64 dari tls.cert. Hal ini diperlukan untuk konfigurasi webhook validasi yang Anda buat di bagian berikutnya:

      cat tls.crt | base64 -w 0.
      

Men-deploy webhook penerimaan

Anda dapat menggunakan contoh berikut untuk membuat deployment bagi server verifikasi tanda tangan dan konfigurasi webhook validasi.

1. Buat deployment untuk server verifikasi tanda tangan dengan menyimpan file berikut:

   apiVersion: apps/v1
   kind: Deployment
   metadata:
     name: signature-verification-server
   spec:
     replicas: 1
     selector:
       matchLabels:
         app: signature-verification-server
     template:
       metadata:
         labels:
           app: signature-verification-server
       spec:
         serviceAccountName: signature-verification-sa
         containers:
         - name: signature-verification-server
           command:
           - /signature-verification-server
           image: SIGNATURE_VERIFICATION_SERVER_IMAGE_URL
           imagePullPolicy: Always
           ports:
           - containerPort: 10250
           volumeMounts:
           - name: tls-certs
             mountPath: "/tls"
           - name: cosign-key
             mountPath: "/cosign-key"
         volumes:
         - name: cosign-key
           secret:
             secretName: cosign-key
         - name: tls-certs
           secret:
             secretName: webhook-tls
   ---
   apiVersion: v1
   kind: Service
   metadata:
     name: signature-verification-service
   spec:
     ports:
     - port: 10250
       targetPort: 10250
     selector:
       app: signature-verification-server

   Ganti SIGNATURE_VERIFICATION_SERVER_IMAGE_URL dengan URL lengkap gambar server verifikasi tanda tangan.

2. Terapkan deployment ke cluster:

   kubectl apply -f signature-verification-deployment.yaml -n signature-verification
   

3. Buat konfigurasi webhook validasi dengan menyimpan file berikut:

   apiVersion: admissionregistration.k8s.io/v1
   kind: ValidatingWebhookConfiguration
   metadata:
     name: image-verification-webhook
   webhooks:
   - name: imageverification.webhook.com
     clientConfig:
       service:
         name: signature-verification-service
         namespace: signature-verification
         path: "/validate"
         port: 10250
       caBundle: CA_BUNDLE
     rules:
     - apiGroups:
       - configsync.gke.io
       apiVersions:
       - v1beta1
       - v1alpha1
       operations:
       - UPDATE
       resources:
       - 'rootsyncs'
       - 'reposyncs'
       scope: '*'
     admissionReviewVersions: ["v1", "v1beta1"]
     sideEffects: None

   Ganti CA_BUNDLE dengan konten berenkode base64 dari tls.cert.

4. Terapkan konfigurasi webhook validasi ke cluster:

   kubectl apply -f signature-verification-validatingwebhookconfiguration.yaml
   

Memeriksa log untuk mengetahui error verifikasi gambar

Setelah Anda menyiapkan server verifikasi gambar, semua upaya sinkronisasi dari image OCI yang tidak ditandatangani akan gagal.

Untuk memeriksa error verifikasi tanda tangan, lihat log dari server verifikasi tanda tangan dengan menjalankan perintah berikut:

1. Periksa log kubectl:

   kubectl logs deployment  signature-verification-server -n  signature-verification
   

   Error dari kubectl terkait verifikasi tanda tangan menyerupai berikut ini:

   main.go:69: error during command execution: no signatures found
   

2. Periksa log Config Sync:

   nomos status
   

   Error dari Config Sync yang terkait dengan verifikasi tanda tangan akan terlihat seperti berikut:

   Error:   KNV2002: admission webhook "imageverification.webhook.com" denied the request: Image validation failed: cosign verification failed: exit status 10, output: Error: no signatures found
   

Jika tidak ada error, Anda dapat mengonfirmasi bahwa gambar bertanda tangan adalah objek yang disinkronkan dengan memeriksa konfigurasi RootSync atau RepoSync:

RootSync

 kubectl get rootsync ROOTSYNC_NAME -n config-management-system -oyaml

Ganti ROOTSYNC_NAME dengan nama RootSync Anda.

RepoSync

 kubectl get reposync REPOSYNC_NAME -n REPOSYNC_NAMESPACE -oyaml

Ganti kode berikut:

• REPOSYNC_NAME: nama RepoSync Anda.
• REPOSYNC_NAMESPACE: nama namespace yang terkait dengan RepoSync Anda.

Anda akan melihat anotasi configsync.gke.io/image-to-sync ditambahkan ke objek RootSync atau RepoSync. Anotasi berisi URL image OCI sumber dan ringkasan terbaru yang diambil oleh Config Sync.

Langkah berikutnya

• Pelajari lebih lanjut cara menginstal Config Sync.
• Memecahkan masalah Config Sync.