Memberi Config Sync akses ke repositori Git Anda

Halaman ini menjelaskan cara mengautentikasi Config Sync ke repositori Git Anda. Config Sync memerlukan akses hanya baca ke sumber tepercaya Anda agar dapat membaca konfigurasi, menerapkannya ke cluster, dan menyinkronkannya.

Memilih metode autentikasi

Metode autentikasi yang Anda gunakan bergantung pada apa yang didukung untuk jenis sumber Anda.

Tabel berikut merangkum metode autentikasi yang dapat Anda gunakan dengan Config Sync:

Metode Sumber yang didukung Deskripsi Batasan
Tidak ada autentikasi Git, OCI, Helm Tidak diperlukan penyiapan tambahan. Hanya berfungsi jika sumber tepercaya Anda bersifat publik.
Pasangan kunci SSH Git Didukung oleh sebagian besar penyedia Git. Memerlukan pengelolaan kunci. Tidak didukung untuk OCI atau Helm.
token Git, Helm Didukung oleh sebagian besar penyedia Git. Alternatif yang baik jika organisasi Anda tidak mengizinkan penggunaan kunci SSH. Mendukung nama pengguna dan sandi untuk Helm. Memerlukan pengelolaan token. Masa berlaku token dapat berakhir. Tidak didukung untuk OCI.
Akun layanan Kubernetes OCI, Helm Menggunakan IAM untuk memberikan akses Artifact Registry langsung ke akun layanan Kubernetes. Memerlukan Workload Identity Federation for GKE diaktifkan di cluster Anda. Tidak didukung untuk Git.
Akun layanan Google Git Menggunakan IAM, yang menghindari penyimpanan kredensial di Secret Kubernetes. Direkomendasikan untuk Secure Source Manager dan Cloud Source Repositories. Memerlukan Workload Identity Federation for GKE diaktifkan di cluster Anda. Memerlukan konfigurasi sebelum dan setelah menginstal Config Sync di cluster Anda. Tidak didukung untuk repositori yang dihosting di luar Secure Source Manager atau Cloud Source Repositories.
Aplikasi GitHub Git Integrasi langsung dengan GitHub. Memungkinkan izin terperinci. Hanya didukung untuk repositori yang dihosting di GitHub. Hanya didukung di Config Sync versi 1.19.1 dan yang lebih baru.

Config Sync juga mendukung metode autentikasi berikut; namun, metode ini hanya direkomendasikan jika Anda tidak dapat menggunakan salah satu opsi yang tercantum dalam tabel sebelumnya:

  • cookiefile: mungkin tidak didukung untuk semua penyedia Git. Tidak didukung untuk OCI atau Helm.
  • Akun layanan default Compute Engine (gcenode): tidak direkomendasikan karena metode ini hanya berfungsi jika Workload Identity Federation for GKE dinonaktifkan. Didukung untuk Git, OCI, dan Helm.
  • Akun layanan Google untuk Helm dan OCI: didukung, tetapi tidak direkomendasikan karena metode akun layanan Kubernetes memerlukan lebih sedikit konfigurasi.

Autentikasi dengan paket armada

Jika Anda menggunakan paket armada, Anda tidak perlu menyelesaikan petunjuk di halaman ini. Paket fleet menggunakan Cloud Build untuk melakukan autentikasi ke Git, yang memungkinkan Anda melakukan autentikasi satu kali per project sehingga Anda tidak perlu memberikan akses setiap kali Anda menginstal Config Sync di cluster.

Sebelum memulai

Sebelum Anda memberikan akses hanya baca Config Sync ke repositori Git Anda, selesaikan tugas berikut:

Menggunakan pasangan kunci SSH

Pasangan kunci SSH terdiri dari dua file, yaitu kunci publik dan kunci pribadi. Config Sync tidak mendukung pembuatan frasa sandi. Bergantung pada persyaratan keamanan dan kepatuhan, Anda dapat menggunakan satu pasangan kunci untuk semua cluster, atau pasangan kunci per cluster.

Untuk memberikan akses hanya baca Config Sync ke repositori Git Anda menggunakan pasangan kunci SSH, selesaikan langkah-langkah berikut:

  1. Buat, atau minta administrator keamanan Anda untuk menyediakan, pasangan kunci SSH. Jika Anda perlu membuat pasangan kunci SSH, buat kunci RSA 4096-bit dengan menjalankan perintah berikut:

    ssh-keygen -t rsa -b 4096 \
  -C "GIT_REPOSITORY_USERNAME" \
  -N '' \
  -f /path/to/KEYPAIR_FILENAME

    Ganti kode berikut:

    • GIT_REPOSITORY_USERNAME: nama pengguna yang Anda inginkan Config Sync gunakan untuk mengautentikasi ke repositori. Jika Anda menggunakan host repositori Git pihak ketiga seperti GitHub, atau Anda ingin menggunakan akun layanan dengan Secure Source Manager, sebaiknya Anda menggunakan akun terpisah untuk autentikasi.
    • /path/to/KEYPAIR_FILENAME: jalur ke file pasangan kunci.

  2. Konfigurasi repositori Anda untuk mengenali kunci publik yang baru dibuat. Lihat dokumentasi untuk penyedia hosting Git Anda. Anda dapat menemukan petunjuk untuk beberapa penyedia hosting Git umum dalam daftar berikut:

  3. Buat Secret git-creds dengan kunci pribadi:

    kubectl create ns config-management-system && \
kubectl create secret generic git-creds \
    --namespace=config-management-system \
    --from-file=ssh=/path/to/KEYPAIR_PRIVATE_KEY_FILENAME

    Ganti /path/to/KEYPAIR_PRIVATE_KEY_FILENAME dengan nama kunci pribadi.

  4. Opsional, tetapi direkomendasikan: Untuk mengonfigurasi pemeriksaan host yang dikenal saat menggunakan autentikasi SSH, tambahkan kunci host yang dikenal ke kolom data.known_hosts di Secret git_creds.

    1. Untuk menambahkan kunci host tepercaya, jalankan perintah berikut:

      kubectl edit secret git-creds --namespace=config-management-system

    2. Untuk menambahkan entri known_hosts di bagian data, jalankan perintah berikut:

        known_hosts: KNOWN_HOSTS_KEY

      Ganti KNOWN_HOSTS_KEY dengan kunci host yang dikenal.

    Untuk menonaktifkan pemeriksaan known_hosts, hapus kolom known_hosts dari Secret.

Saat menginstal Config Sync, gunakan pasangan kunci SSH (ssh) sebagai jenis autentikasi.

Saat Anda memasukkan URL repositori Git, URL harus menggunakan format protokol SSH. Format URL berbeda-beda, bergantung pada penyedia Git.

Menggunakan file cookie

Proses untuk mendapatkan cookiefile bergantung pada konfigurasi repositori Anda. Umumnya, kredensial disimpan dalam file .gitcookies di direktori beranda, atau diberikan oleh administrator keamanan.

Untuk memberikan akses hanya baca Config Sync ke repositori Git Anda menggunakan cookiefile, selesaikan langkah-langkah berikut:

Setelah Anda membuat atau mendapatkan cookiefile, tambahkan cookiefile tersebut ke Secret baru dalam cluster. Sebaiknya Anda menggunakan HTTPS karena alasan keamanan:

kubectl create ns config-management-system && \
kubectl create secret generic git-creds \
  --namespace=config-management-system \
  --from-file=cookie_file=/path/to/COOKIEFILE

Ganti /path/to/COOKIEFILE dengan jalur dan nama file Anda.

Saat menginstal Config Sync, gunakan cookiefile (cookiefile) sebagai jenis autentikasi.

Menggunakan token

Jika organisasi Anda tidak mengizinkan penggunaan kunci SSH, sebaiknya gunakan token.

Untuk memberikan akses hanya baca Config Sync ke repositori Git Anda menggunakan token, selesaikan langkah-langkah berikut:

  1. Buat token dari penyedia Git Anda. Lihat dokumentasi penyedia hosting Git Anda untuk mendapatkan petunjuk. Anda dapat menemukan petunjuk untuk beberapa penyedia hosting Git umum dalam daftar berikut:

  2. Setelah Anda membuat atau mendapatkan token, tambahkan token tersebut ke Secret baru di cluster. Sebaiknya Anda menggunakan HTTPS karena alasan keamanan:

    kubectl create ns config-management-system && \
kubectl create secret generic git-creds \
  --namespace=config-management-system \
  --from-literal=username=USERNAME \
  --from-literal=token=TOKEN

    Ganti kode berikut:

    • USERNAME: nama pengguna yang ingin Anda gunakan.
    • TOKEN: token yang Anda buat pada langkah sebelumnya.

Saat Anda menginstal Config Sync, gunakan token (token) sebagai jenis autentikasi.

Menggunakan akun layanan Google

Anda dapat memberikan akses Config Sync ke repositori dalam project yang sama dengan cluster terkelola Anda menggunakan akun layanan Google. Anda harus memenuhi persyaratan berikut:

Untuk memberikan akses hanya baca Config Sync ke repositori Git Anda menggunakan akun layanan Google, selesaikan langkah-langkah berikut:

  1. Untuk mendapatkan izin yang diperlukan untuk membuat binding kebijakan, minta administrator untuk memberi Anda peran IAM Admin Akun Layanan (roles/iam.serviceAccountAdmin) pada akun layanan. 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 kustom atau peran yang telah ditentukan lainnya.

  2. Jika Anda belum memiliki akun layanan, buat akun layanan.

  3. Berikan peran IAM ke akun layanan Google, bergantung pada jenis repositori yang Anda gunakan:

    Secure Source Manager

    Berikan peran IAM Secure Source Manager Instance Accessor (roles/securesourcemanager.instanceAccessor) dan Secure Source Manager Repo Reader (roles/securesourcemanager.repoReader) ke akun layanan Google:

    • Berikan izin di seluruh project jika izin yang sama berlaku untuk semua repositori dalam project:

      gcloud projects add-iam-policy-binding PROJECT_ID \
  --role=roles/securesourcemanager.instanceAccessor \
  --member="serviceAccount:GSA_NAME@PROJECT_ID.iam.gserviceaccount.com"

      gcloud projects add-iam-policy-binding PROJECT_ID \
  --role=roles/securesourcemanager.repoReader \
  --member="serviceAccount:GSA_NAME@PROJECT_ID.iam.gserviceaccount.com"

      Ganti kode berikut:

      • PROJECT_ID: project ID Anda.
      • GSA_NAME: nama akun layanan Google yang ingin Anda hubungkan ke Secure Source Manager.

    • Untuk memberikan izin khusus repositori, lihat dokumentasi Secure Source Manager untuk Memberi pengguna peran tingkat repositori.

    Saat Anda menginstal Config Sync, gunakan Workload Identity (gcpserviceaccount) sebagai jenis autentikasi. Anda juga harus menambahkan email akun layanan Anda.

    Secure Source Manager memerlukan format tertentu untuk URL repositori: https://SSM_INSTANCE_ID-PROJECT_NUMBER-git.INSTANCE_LOCATION.sourcemanager.dev/PROJECT_ID/REPO_NAME.git.

    Cloud Source Repositories

    Berikan peran IAM Cloud Source Repositories Reader (roles/source.reader) ke akun layanan Google:

    • Berikan izin di seluruh project jika izin yang sama berlaku untuk semua repositori dalam project:

      gcloud projects add-iam-policy-binding PROJECT_ID \
  --role=roles/source.reader \
  --member="serviceAccount:GSA_NAME@PROJECT_ID.iam.gserviceaccount.com"

      Ganti kode berikut:

      • PROJECT_ID: project ID Anda.
      • GSA_NAME: nama akun layanan Google yang ingin Anda hubungkan ke Cloud Source Repositories.

    • Berikan izin khusus repositori jika Anda ingin akun layanan memiliki tingkat akses yang berbeda untuk setiap repositori di project Anda:

      gcloud source repos set-iam-policy REPOSITORY POLICY_FILE --project=PROJECT_ID

      Ganti kode berikut:

      • PROJECT_ID: project ID Anda.
      • REPOSITORY: nama repositori.
      • POLICY_FILE: file JSON atau YAML yang berisi kebijakan Identity and Access Management.

    Saat Anda menginstal Config Sync, gunakan Workload Identity (gcpserviceaccount) sebagai jenis autentikasi. Anda juga harus menambahkan email akun layanan Anda.

Langkah berikut harus diselesaikan setelah mengonfigurasi Config Sync karena akun layanan Kubernetes tidak dibuat hingga Anda mengonfigurasi Config Sync untuk pertama kalinya. Anda hanya perlu melakukannya sekali per armada. Untuk membuat binding yang memungkinkan akun layanan Kubernetes bertindak sebagai akun layanan Google, jalankan perintah berikut:

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

Ganti kode berikut:

  • FLEET_HOST_PROJECT_ID: jika Anda menggunakan Workload Identity Federation for GKE, nilainya sama dengan PROJECT_ID. Jika Anda menggunakan Workload Identity Federation fleet untuk GKE, gunakan project ID fleet tempat cluster Anda terdaftar sebagai nilai.
  • GSA_NAME: akun layanan Google kustom yang ingin Anda gunakan untuk terhubung ke Secure Source Manager atau Cloud Source Repositories.
  • KSA_NAME: akun layanan Kubernetes untuk rekonsiliasi. Dalam sebagian besar kasus, nilainya adalah root-sync karena Config Sync otomatis membuat objek RootSync bernama root-sync saat diinstal dengan konsol Google Cloud atau Google Cloud CLI. Jika tidak, gunakan root-reconciler-ROOT_SYNC_NAME sebagai nilai.

Jika Anda mengalami masalah saat menghubungkan ke Config Sync dengan akun layanan Google, lihat Memecahkan masalah izin dengan akun layanan Google.

Menggunakan akun layanan default Compute Engine

Sebagai alternatif untuk akun layanan Google, jika Anda belum mengaktifkan Workload Identity Federation untuk GKE, Anda dapat menggunakan akun layanan Compute Engine untuk melakukan autentikasi. Metode ini hanya didukung untuk repositori di Secure Source Manager dan Cloud Source Repositories.

Untuk memberikan akses hanya baca Config Sync ke repositori Anda menggunakan akun layanan default Compute Engine, berikan peran roles/source.reader ke akun layanan default:

gcloud projects add-iam-policy-binding PROJECT_ID \
  --role=roles/source.reader \
  --member="serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com"

Ganti kode berikut:

  • PROJECT_ID: project ID Anda
  • PROJECT_NUMBER: dengan nomor project Anda.

Saat menginstal Config Sync, gunakan Google Cloud Repository (gcenode) sebagai jenis autentikasi.

Menggunakan Aplikasi GitHub

Jika repositori Anda ada di GitHub, Anda dapat menggunakan Aplikasi GitHub untuk menghubungkan repositori Anda ke Config Sync:

  1. Ikuti petunjuk di GitHub untuk menyediakan Aplikasi GitHub dan memberinya izin untuk membaca dari repositori Anda.

  2. Tambahkan konfigurasi Aplikasi GitHub ke Secret baru di cluster menggunakan ID klien atau aplikasi:

    ID klien 

    kubectl create ns config-management-system && \
kubectl create secret generic git-creds \
  --namespace=config-management-system \
  --from-literal=github-app-client-id=CLIENT_ID \
  --from-literal=github-app-installation-id=INSTALLATION_ID \
  --from-file=github-app-private-key=/path/to/GITHUB_PRIVATE_KEY \
  --from-literal=github-app-base-url=BASE_URL
    • Ganti CLIENT_ID dengan ID klien untuk Aplikasi GitHub.
    • Ganti INSTALLATION_ID dengan ID penginstalan untuk Aplikasi GitHub.
    • Ganti /path/to/GITHUB_PRIVATE_KEY dengan nama file yang berisi kunci pribadi.
    • Ganti BASE_URL dengan URL dasar untuk endpoint GitHub API. Nilai ini hanya diperlukan jika repositori tidak dihosting di www.github.com. Argumen dapat dihilangkan dan secara default adalah https://api.github.com/.

    ID aplikasi 

    kubectl create ns config-management-system && \
kubectl create secret generic git-creds \
    --namespace=config-management-system \
    --from-literal=github-app-application-id=APPLICATION_ID \
    --from-literal=github-app-installation-id=INSTALLATION_ID \
    --from-file=github-app-private-key=/path/to/GITHUB_PRIVATE_KEY \
    --from-literal=github-app-base-url=BASE_URL
    • Ganti APPLICATION_ID dengan ID aplikasi untuk Aplikasi GitHub.
    • Ganti INSTALLATION_ID dengan ID penginstalan untuk Aplikasi GitHub.
    • Ganti /path/to/GITHUB_PRIVATE_KEY dengan nama file yang berisi kunci pribadi.
    • Ganti BASE_URL dengan URL dasar untuk endpoint GitHub API. Nilai ini hanya diperlukan jika repositori tidak dihosting di www.github.com. Argumen dapat dihilangkan dan secara default ditetapkan ke https://api.github.com/.

Saat menginstal Config Sync, gunakan aplikasi GitHub (githubapp) sebagai jenis autentikasi.

Pemecahan masalah

Untuk mendapatkan bantuan dalam memecahkan masalah terkait menghubungkan Config Sync ke sumber tepercaya Anda, tinjau topik pemecahan masalah berikut:

Langkah berikutnya