Menyinkronkan artefak OCI dari Artifact Registry

Halaman ini menunjukkan cara membuat dan memublikasikan image 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. Sebaiknya gunakan 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, mengirim diagram Helm, atau menggunakan library go-containerregistry untuk menggunakan registry container. Pilih alat yang paling sesuai untuk Anda.

Sebelum memulai

  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. Install the Google Cloud CLI.

  3. To use a federated identity with the gcloud CLI, you must first configure the tool to use a federated identity.

    For more information, see Browser-based sign-in with the gcloud CLI.

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

    gcloud init

  5. Create or select a Google Cloud project.

    • Create a Google Cloud project:

      gcloud projects create PROJECT_ID

      Replace PROJECT_ID with a name for the Google Cloud project you are creating.

    • Select the Google Cloud project that you created:

      gcloud config set project PROJECT_ID

      Replace PROJECT_ID with your Google Cloud project name.

  6. Make sure that billing is enabled for your Google Cloud project.

  7. Enable the GKE Enterprise, Config Sync, Artifact Registry APIs: 

    gcloud services enable anthos.googleapis.com  anthosconfigmanagement.googleapis.com  artifactregistry.googleapis.com
  8. Install the Google Cloud CLI.

  9. To use a federated identity with the gcloud CLI, you must first configure the tool to use a federated identity.

    For more information, see Browser-based sign-in with the gcloud CLI.

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

    gcloud init

  11. Create or select a Google Cloud project.

    • Create a Google Cloud project:

      gcloud projects create PROJECT_ID

      Replace PROJECT_ID with a name for the Google Cloud project you are creating.

    • Select the Google Cloud project that you created:

      gcloud config set project PROJECT_ID

      Replace PROJECT_ID with your Google Cloud project name.

  12. Make sure that billing is enabled for your Google Cloud project.

  13. Enable the GKE Enterprise, Config Sync, Artifact Registry APIs: 

    gcloud services enable anthos.googleapis.com  anthosconfigmanagement.googleapis.com  artifactregistry.googleapis.com
  14. Buat, atau miliki akses ke, cluster yang memenuhi persyaratan untuk Config Sync dan menggunakan Config Sync versi terbaru.
  15. Instal nomos CLI atau upgrade ke versi terbaru.
  16. (Opsional) Jika Anda ingin menggunakan Cosign untuk memverifikasi tanda tangan image OCI, instal hal berikut:
    • Cosign untuk menandatangani image OCI.
    • OpenSSL untuk membuat kredensial server webhook.
    • Docker untuk mem-build dan mengirim image server Admission Webhook.

Biaya

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

Untuk membuat perkiraan biaya berdasarkan proyeksi penggunaan Anda, gunakan kalkulator harga. Pengguna baru Google Cloud 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.

  1. Buat repositori Artifact Registry:

    gcloud artifacts repositories create AR_REPO_NAME \
   --repository-format=docker \
   --location=AR_REGION \
   --description="Config Sync Helm 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_ID: jika Anda menggunakan Workload Identity Federation GKE untuk GKE, nilai ini sama dengan PROJECT_ID. Jika Anda menggunakan Workload Identity Federation fleet untuk GKE, ini adalah project ID fleet tempat cluster Anda terdaftar.
  • GSA_NAME: nama akun layanan Google kustom yang ingin Anda gunakan untuk terhubung ke Artifact Registry.
  • KSA_NAME: akun layanan Kubernetes untuk rekonsiliator.
    • 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

Jika versi Config Sync adalah 1.17.2 atau yang lebih baru di cluster Anda, Anda dapat menggunakan akun layanan Kubernetes untuk mengautentikasi ke Artifact Registry. Jika tidak, gunakan akun layanan Google untuk autentikasi.

Menggunakan akun layanan Kubernetes

Berikan peran IAM Artifact Registry Reader (roles/artifactregistry.reader) ke akun layanan Kubernetes dengan Workload Identity Federation untuk kumpulan GKE:

gcloud artifacts repositories add-iam-policy-binding AR_REPO_NAME \
   --location=AR_REGION \
   --member="serviceAccount:FLEET_HOST_PROJECT_ID.svc.id.goog[config-management-system/KSA_NAME]" \
   --role=roles/artifactregistry.reader \
   --project=PROJECT_ID

Menggunakan akun layanan Google

  1. Berikan peran IAM Pembaca Artifact Registry (roles/artifactregistry.reader) ke akun layanan Google:

    gcloud artifacts repositories add-iam-policy-binding AR_REPO_NAME \
   --location=AR_REGION \
   --member=serviceAccount:GSA_NAME@PROJECT_ID.iam.gserviceaccount.com \
   --role=roles/artifactregistry.reader \
   --project=PROJECT_ID

  2. Buat binding kebijakan IAM antara akun layanan Kubernetes dan akun layanan Google:

    gcloud iam service-accounts add-iam-policy-binding \
   --role roles/iam.workloadIdentityUser \
   --member "serviceAccount:FLEET_HOST_PROJECT_ID.svc.id.goog[config-management-system/KSA_NAME]" \
   GSA_NAME@PROJECT_ID.iam.gserviceaccount.com \
   --project=PROJECT_ID

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

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: .
    # The k8sserviceaccount auth type is available in version 1.17.2 and
    # later. Use `gcpserviceaccount` if using an older version.
    # auth: gcpserviceaccount
    # gcpServiceAccountEmail: GSA_NAME@PROJECT_ID.iam.gserviceaccount.com
    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

Mulai dari Config Sync versi 1.20.0, Config Sync mendukung verifikasi keaslian image sumber OCI sebelum konfigurasi diterapkan ke cluster Anda. Metode ini menggunakan objek ValidatingWebhookConfiguration dan server webhook yang memvalidasi untuk mencegat permintaan update untuk objek RootSync dan RepoSync. Config Sync memperbarui anotasi configsync.gke.io/image-to-sync objek RootSync dan RepoSync setelah berhasil mengambil ringkasan gambar baru. Server webhook yang memvalidasi 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 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 sampel

      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 mendorongnya 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 mengautentikasi ke Artifact Registry dengan ServiceAccount Kubernetes, selesaikan langkah-langkah berikut:

    1. Buat Akun Layanan Kubernetes di namespace yang Anda buat:

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

    2. Tambahkan binding kebijakan IAM untuk peran Pembaca Artifact Registry (roles/artifactregistry.reader):

      gcloud artifacts repositories add-iam-policy-binding REPOSITORY_NAME \
   --location=REPOSITORY_LOCATION \
   --member="serviceAccount:PROJECT_ID.svc.id.goog[signature-verification/signature-verification-sa]" \
   --role=roles/artifactregistry.reader \
   --project=PROJECT_ID

      Ganti kode berikut:

      • REPOSITORY_NAME: nama repositori Artifact Registry tempat Anda menyimpan image OCI.
      • REPOSITORY_LOCATION: lokasi repositori Artifact Registry Anda.

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

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

      cosign generate-key-pair

    2. Simpan kunci publik di Secret Kubernetes di 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 tls.cert yang dienkode base64. 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 server verifikasi tanda tangan dan konfigurasi webhook yang memvalidasi.

  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 image server verifikasi tanda tangan.

  2. Terapkan deployment ke cluster:

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

  3. Buat konfigurasi webhook yang memvalidasi 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 yang dienkode base64 dari tls.cert.

  4. Terapkan konfigurasi webhook validasi ke cluster:

    kubectl apply -f signature-verification-validatingwebhookconfiguration.yaml

Memeriksa log untuk menemukan error verifikasi gambar

Setelah Anda menyiapkan server verifikasi gambar, setiap upaya untuk menyinkronkan dari gambar 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 yang terkait dengan verifikasi tanda tangan menyerupai hal berikut:

    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 menyerupai hal 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 mendapatkan error, Anda dapat mengonfirmasi bahwa gambar yang ditandatangani 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 selanjutnya