Menginstal Config Connector secara manual

Halaman ini menjelaskan cara menginstal Config Connector secara manual. Penginstalan manual adalah opsi fleksibel yang memberi Anda kontrol atas versi yang diinstal dan jadwal upgrade.

Untuk mengetahui informasi selengkapnya tentang berbagai opsi penginstalan, lihat Memilih jenis penginstalan.

Untuk sebagian besar kasus penggunaan, sebaiknya instal Config Connector secara manual dalam mode namespace. Alternatifnya adalah mode cluster. Mode namespace lebih skalabel dan menawarkan isolasi izin yang lebih baik, yang ideal untuk kasus penggunaan multi-tenant atau saat mengelola resource dari beberapa project.

Jika Anda lebih memilih akun layanan tunggal di seluruh cluster, ikuti petunjuk untuk menginstal dalam mode cluster.

Sebelum memulai

Sebelum menginstal operator Config Connector secara manual, selesaikan langkah-langkah berikut:

• Buat atau identifikasi cluster GKE tempat Config Connector belum diinstal dan yang telah mengaktifkan Workload Identity dan Kubernetes Engine Monitoring.
• Konfigurasi kubectl untuk terhubung ke cluster Anda.

Menginstal operator Config Connector

Config Connector menggunakan operator Kubernetes untuk memastikan instalasinya selalu yang terbaru. Operator harus diinstal, baik Anda menginstal Config Connector dalam mode namespace maupun mode cluster.

Untuk menginstal operator Config Connector, selesaikan langkah-langkah berikut:

1. Download file .tar operator Config Connector terbaru:

   gcloud storage cp gs://configconnector-operator/latest/release-bundle.tar.gz release-bundle.tar.gz
   

   Catatan: Simpan salinan paket penginstalan karena Anda memerlukan paket ini untuk meng-uninstal Config Connector.

2. Ekstrak file tar:

   tar zxvf release-bundle.tar.gz
   

3. Instal operator Config Connector di cluster Anda:

   Autopilot

   kubectl apply -f operator-system/autopilot-configconnector-operator.yaml
   

   Standar

   kubectl apply -f operator-system/configconnector-operator.yaml
   

4. Untuk mengonfigurasi operator Config Connector agar berjalan dalam mode namespace, selesaikan langkah-langkah berikut:

   1. Buat manifes bernama configconnector.yaml dengan konten berikut:

      apiVersion: core.cnrm.cloud.google.com/v1beta1
      kind: ConfigConnector
      metadata:
        # the name is restricted to ensure that there is only ConfigConnector resource installed in your cluster
        name: configconnector.core.cnrm.cloud.google.com
      spec:
        mode: namespaced
        stateIntoSpec: Absent
      

   2. Terapkan manifes ke cluster Anda:

      kubectl apply -f configconnector.yaml
      

Menginstal Config Connector dalam mode namespace

Catatan: Anda harus melakukan langkah-langkah ini untuk setiap namespace yang Anda inginkan agar Config Connector membuat resource darinya.

Di bagian berikut, project tempat Anda menginstal Config Connector adalah project host. Project lain tempat Anda dapat meminta Config Connector mengelola resource adalah project terkelola. Project host dan project terkelola dapat berupa project yang sama, jika Anda ingin Config Connector hanya membuat resource dalam project yang sama dengan cluster Anda.

Buat namespace

Buat namespace baru dengan menjalankan perintah berikut:

kubectl create namespace NAMESPACE

Mengganti NAMESPACE dengan nama untuk namespace.

Membuat identitas

Buat akun layanan Identity and Access Management (IAM) dan buat binding antara Akun Layanan IAM dan akun layanan Kubernetes Config Connector dengan menyelesaikan langkah-langkah berikut:

1. Buat akun layanan IAM. Jika memiliki akun layanan yang sudah ada, Anda dapat menggunakannya, bukan membuat akun layanan baru. Gunakan gcloud untuk membuat akun layanan dengan menjalankan perintah berikut:

   gcloud iam service-accounts create NAMESPACE_GSA --project HOST_PROJECT_ID
   

   Ganti kode berikut:

   • NAMESPACE_GSA dengan nama akun layanan Google (GSA) yang terikat ke namespace Anda.
   • HOST_PROJECT_ID dengan ID project host Anda.

   Untuk mempelajari lebih lanjut cara membuat akun layanan, lihat Membuat dan mengelola akun layanan.

2. Beri akun layanan IAM izin yang lebih tinggi di project terkelola Anda:

   gcloud projects add-iam-policy-binding MANAGED_PROJECT_ID \
       --member="serviceAccount:NAMESPACE_GSA@HOST_PROJECT_ID.iam.gserviceaccount.com" \
       --role="roles/owner"
   

   Ganti MANAGED_PROJECT_ID dengan ID project terkelola Anda.

   Catatan: Jika Anda lebih memilih untuk memberikan akses editor ke project, ganti roles/owner dengan roles/editor. Dengan memberikan peran editor, sebagian besar fungsi Config Connector dapat digunakan, kecuali konfigurasi di tingkat Project atau Organisasi seperti modifikasi IAM.

3. Buat binding kebijakan IAM antara akun layanan IAM dan akun layanan Kubernetes Config Connector:

   gcloud iam service-accounts add-iam-policy-binding \
       NAMESPACE_GSA@HOST_PROJECT_ID.iam.gserviceaccount.com \
       --member="serviceAccount:HOST_PROJECT_ID.svc.id.goog[cnrm-system/cnrm-controller-manager-NAMESPACE]" \
       --role="roles/iam.workloadIdentityUser"
   

4. Berikan izin akun layanan IAM untuk memublikasikan metrik Prometheus ke Google Cloud Observability di project host Anda:

   gcloud projects add-iam-policy-binding HOST_PROJECT_ID \
       --member="serviceAccount:NAMESPACE_GSA@HOST_PROJECT_ID.iam.gserviceaccount.com" \
       --role="roles/monitoring.metricWriter"
   

Buat ConfigConnectorContext

Untuk membuat resource Google Cloud , konfigurasi Config Connector untuk memantau namespace Anda dengan menambahkan objek ConfigConnectorContext di namespace tersebut.

Untuk membuat ConfigConnectorContext, selesaikan langkah-langkah berikut:

1. Buat manifes bernama configconnectorcontext.yaml dengan konten berikut:

   apiVersion: core.cnrm.cloud.google.com/v1beta1
   kind: ConfigConnectorContext
   metadata:
     # you need one ConfigConnectorContext per namespace
     name: configconnectorcontext.core.cnrm.cloud.google.com
     namespace: NAMESPACE
   spec:
     googleServiceAccount: "NAMESPACE_GSA@HOST_PROJECT_ID.iam.gserviceaccount.com"
     stateIntoSpec: Absent
   

2. Terapkan manifes ke cluster Anda:

   kubectl apply -f configconnectorcontext.yaml
   

3. Pastikan operator Config Connector membuat akun layanan Kubernetes untuk namespace Anda dengan menjalankan perintah berikut:

   kubectl get serviceaccount/cnrm-controller-manager-NAMESPACE  -n cnrm-system
   

4. Pastikan Pod pengontrol Config Connector berjalan untuk namespace Anda:

   kubectl wait -n cnrm-system \
       --for=condition=Ready pod \
       -l cnrm.cloud.google.com/component=cnrm-controller-manager \
       -l cnrm.cloud.google.com/scoped-namespace=NAMESPACE
   

   Jika pengontrol Config Connector sedang berjalan, outputnya akan mirip dengan:

   cnrm-controller-manager-abcdefghijk-0 condition met.
   

Berhenti mengelola resource dalam namespace

Jika Anda ingin Config Connector berhenti mengelola resource dalam namespace, hapus semua resource Config Connector dan objek ConfigConnectorContext dalam namespace tersebut.

1. Untuk menemukan semua resource Config Connector di namespace Anda, buat daftar semua resource untuk setiap Definisi Resource Kustom Config Connector.

   kubectl get gcp -n NAMESPACE
   

   Output perintah ini mencantumkan semua Definisi Resource Kustom (CRD) yang merepresentasikan resource yang dikelola oleh Config Connector di namespace tersebut, termasuk nama dan jenis Kubernetes dari resource tersebut.

2. Untuk menghapus semua resource Config Connector, untuk setiap resource dalam output langkah sebelumnya, jalankan perintah berikut:

   kubectl delete -n NAMESPACE KIND NAME
   

   Ganti kode berikut:

   • KIND: jenis resource Kubernetes.
   • NAME: nama resource.

3. Hapus objek ConfigConnectorContext di namespace Anda.

   kubectl delete -n NAMESPACE ConfigConnectorContext configconnectorcontext.core.cnrm.cloud.google.com
   

   Penting: Jangan hapus objek ConfigConnectorContext hingga semua resource yang dikelola Config Connector dihapus.

Meng-uninstal Config Connector

Untuk meng-uninstal Config Connector, selesaikan langkah-langkah berikut:

1. Untuk menghapus CRD dan komponen pengontrol Config Connector, jalankan perintah berikut:

   kubectl delete ConfigConnectorContext --all -A –wait=false
   
   kubectl delete ConfigConnector configconnector.core.cnrm.cloud.google.com \
       --wait=true
   

2. Untuk meng-uninstal operator Config Connector, jalankan perintah berikut:

   kubectl delete -f operator-system/configconnector-operator.yaml  --wait=true
   

Menginstal dalam mode cluster

Anda mungkin lebih memilih untuk menginstal dan mengelola Config Connector dalam mode cluster jika ingin mengelola resource dalam satu project dan tidak memerlukan pemisahan izin yang disediakan oleh mode namespace.

Membuat identitas

Config Connector membuat dan mengelola Google Cloud resource dengan mengautentikasi menggunakan akun layanan Identity and Access Management (IAM) dan menggunakan Workload Identity Federation untuk GKE guna mengikat akun layanan IAM dengan akun layanan Kubernetes.

Catatan: Anda hanya perlu melakukan langkah-langkah ini satu kali per cluster.

Untuk membuat identitas, selesaikan langkah-langkah berikut:

1. Buat akun layanan IAM. Jika ingin menggunakan akun layanan yang sudah ada, Anda dapat menggunakan akun tersebut dan melewati langkah ini:

   gcloud iam service-accounts create SERVICE_ACCOUNT_NAME
   

   Ganti SERVICE_ACCOUNT_NAME dengan nama untuk akun layanan Anda.

   Untuk mempelajari lebih lanjut cara membuat akun layanan, lihat Membuat dan mengelola akun layanan.

2. Berikan izin yang lebih tinggi kepada akun layanan IAM di project Anda:

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

   Ganti PROJECT_ID dengan project ID Anda.

   Catatan: Pemberian peran editor memungkinkan sebagian besar fungsi Config Connector, kecuali konfigurasi di seluruh project dan organisasi seperti modifikasi IAM. Di lingkungan produksi, sebaiknya Anda menetapkan izin yang lebih terperinci. Untuk mengetahui informasi selengkapnya tentang peran IAM, lihat Memahami peran.

3. Buat binding kebijakan IAM antara akun layanan IAM dan akun layanan Kubernetes standar yang menjalankan Config Connector:

   gcloud iam service-accounts add-iam-policy-binding \
   SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com \
     --member="serviceAccount:PROJECT_ID.svc.id.goog[cnrm-system/cnrm-controller-manager]" \
     --role="roles/iam.workloadIdentityUser"
   

Mengonfigurasi Config Connector

Untuk menyelesaikan penginstalan, buat file konfigurasi untuk ConfigConnector CustomResource, lalu terapkan menggunakan perintah kubectl apply. Operator Config Connector menginstal CRD resourceGoogle Cloud dan komponen Config Connector di cluster Anda.

Untuk mengonfigurasi operator sebagai mode cluster, selesaikan langkah-langkah berikut:

1. Salin file YAML berikut ke dalam file bernama configconnector.yaml:

   # configconnector.yaml
   apiVersion: core.cnrm.cloud.google.com/v1beta1
   kind: ConfigConnector
   metadata:
     # the name is restricted to ensure that there is only one
     # ConfigConnector resource installed in your cluster
     name: configconnector.core.cnrm.cloud.google.com
   spec:
     mode: cluster
     googleServiceAccount: "SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com"
     # Setting `stateIntoSpec` to `Absent` is recommended. It means setting `cnrm.cloud.google.com/state-into-spec`
     # annotation to `absent` for all Config Connector resources created in the cluster in the future.
     # It prevents Config Connector from populating unspecified fields into the spec.
     stateIntoSpec: Absent

   Ganti kode berikut:
   • SERVICE_ACCOUNT_NAME dengan nama akun layanan Anda.
   • PROJECT_ID dengan ID project Anda.
2. Terapkan konfigurasi ke cluster Anda dengan kubectl apply:

     kubectl apply -f configconnector.yaml

Menentukan tempat untuk membuat resource

Config Connector dapat mengatur resource menurut project, folder, atau organisasi, yang sama dengan cara Anda mengatur resource dengan Google Cloud.

Sebelum membuat resource dengan Config Connector, Anda harus mengonfigurasi tempat untuk membuat resource. Untuk menentukan tempat membuat resource, Config Connector menggunakan anotasi pada konfigurasi resource atau Namespace yang ada. Untuk mengetahui informasi selengkapnya, lihat Mengatur resource.

Jika Anda tidak memiliki Namespace untuk tujuan ini, buat Namespace dengan kubectl.

kubectl create namespace NAMESPACE

Ganti NAMESPACE dengan nama namespace Anda. Contoh config-connector.

Pilih tab untuk memilih tempat Anda ingin Config Connector membuat resource.

Project

Untuk membuat resource di project tertentu, jalankan perintah berikut:

    kubectl annotate namespace \
    NAMESPACE cnrm.cloud.google.com/project-id=PROJECT_ID

Ganti kode berikut:

• NAMESPACE dengan nama namespace Anda.
• PROJECT_ID dengan project ID Google Cloud Anda.

Folder

Untuk membuat resource di folder tertentu, jalankan perintah berikut:

    kubectl annotate namespace \
    NAMESPACE cnrm.cloud.google.com/folder-id=FOLDER_ID

Ganti kode berikut:

• NAMESPACE dengan nama namespace Anda.
• FOLDER_ID dengan ID folder Google Cloud Anda.

Organisasi

Untuk membuat resource di organisasi tertentu, jalankan perintah berikut:

    kubectl annotate namespace \
    NAMESPACE cnrm.cloud.google.com/organization-id=ORGANIZATION_ID

Ganti kode berikut:

• NAMESPACE dengan nama namespace Anda.
• ORGANIZATION_ID dengan ID organisasi Google Cloud Anda.

Saat Anda membuat anotasi namespace, Config Connector akan membuat resource di project, folder, atau organisasi yang sesuai. Untuk mempelajari lebih lanjut cara Config Connector menggunakan namespace Kubernetes, lihat Namespace Kubernetes dan Google Cloud project.

Memverifikasi penginstalan Anda

Config Connector menjalankan semua komponennya dalam namespace bernama cnrm-system. Anda dapat memverifikasi bahwa Pod sudah siap dengan menjalankan perintah berikut:

kubectl wait -n cnrm-system \
      --for=condition=Ready pod --all

Jika Config Connector diinstal dengan benar, outputnya akan mirip dengan berikut:

pod/cnrm-controller-manager-0 condition met

Catatan: Pod pengontrol dapat memerlukan waktu beberapa menit untuk dimulai.

Meng-uninstal Config Connector

Untuk meng-uninstal Config Connector, selesaikan langkah-langkah berikut:

1. Untuk menghapus CRD dan komponen pengontrol Config Connector, jalankan perintah berikut:

   kubectl delete ConfigConnector configconnector.core.cnrm.cloud.google.com \
       --wait=true
   

2. Untuk meng-uninstal operator Config Connector, jalankan perintah berikut:

   kubectl delete -f operator-system/configconnector-operator.yaml  --wait=true
   

Mengupgrade Config Connector

Untuk mendownload dan menginstal operator Config Connector versi terbaru, jalankan perintah berikut:

gcloud storage cp gs://configconnector-operator/latest/release-bundle.tar.gz release-bundle.tar.gz
tar zxvf release-bundle.tar.gz
kubectl apply -f operator-system/configconnector-operator.yaml

Menurunkan versi Config Connector

Downgrade Config Connector sepenuhnya tidak didukung. Untuk melakukan downgrade operator dan CRD Config Connector, Anda harus meng-uninstal, menginstal ulang Config Connector, lalu menerapkan kembali resource Anda.

Di Config Connector versi 1.123.1 dan yang lebih baru, Anda dapat melakukan roll back versi operator untuk penginstalan yang menggunakan mode namespace. Di setiap namespace yang memiliki operator yang ingin Anda rollback, tetapkan kolom spec.version di objek ConfigConnectorContext ke versi Config Connector sebelumnya.

Anda dapat melakukan roll back pengontrol Config Connector hingga maksimal 3 versi minor. Anda harus selalu melakukan roll back ke versi patch terbaru untuk versi minor tertentu.

Melakukan upgrade dari penginstalan non-operator

Config Connector versi 1.33.0 dan yang lebih tinggi hanya mendukung penginstalan dengan add-on GKE, atau operator.

Untuk mengupgrade ke operator (dan mempertahankan semua resource Config Connector), Anda harus menghapus semua komponen sistem Config Connector kecuali CRD, lalu menginstal operator.

1. Jalankan perintah berikut untuk menghapus komponen non-CRD sistem Config Connector:

   kubectl delete sts,deploy,po,svc,roles,clusterroles,clusterrolebindings --all-namespaces -l cnrm.cloud.google.com/system=true --wait=true
   kubectl delete validatingwebhookconfiguration abandon-on-uninstall.cnrm.cloud.google.com --ignore-not-found --wait=true
   kubectl delete validatingwebhookconfiguration validating-webhook.cnrm.cloud.google.com --ignore-not-found --wait=true
   kubectl delete mutatingwebhookconfiguration mutating-webhook.cnrm.cloud.google.com --ignore-not-found --wait=true
   

2. Instal Config Connector dengan add-on GKE, atau operator.

Beralih dari add-on ke penginstalan manual

Saat diinstal sebagai add-on, versi Config Connector terikat langsung dengan versi GKE yang diinstal.

Penginstalan manual memungkinkan update yang lebih cepat dengan mengorbankan upgrade manual.

Untuk beralih metode penginstalan dan mempertahankan resource Anda dengan aman, selesaikan langkah-langkah berikut:

1. Menonaktifkan add-on tanpa menghapus objek ConfigConnector atau ConfigConnectorContext:

   gcloud container clusters update CLUSTER_NAME --update-addons ConfigConnector=DISABLED
   

   Ganti CLUSTER_NAME dengan nama cluster tempat Anda menginstal Config Connector.

2. Instal operator manual versi yang dipilih.

   Untuk mencegah potensi error validasi CRD (misalnya, KNV2009: Invalid value: "v1beta1": must appear in spec.versions), versi operator manual yang dipilih harus sama atau lebih baru dari versi yang Anda gunakan untuk add-on. Melakukan downgrade versi operator manual dapat menyebabkan error (misalnya, KNV2009) karena add-on GKE mungkin telah mengupgrade CRD tertentu ke versi Config Connector yang lebih baru.

Catatan: Karena namespace-id ConfigMap di namespace configconnector-operator-system dihapus sebagai bagian dari penonaktifan add-on, cnrm-controller-manager StatefulSets lama akan dibuat ulang.

Langkah berikutnya

• Mulai menggunakan Config Connector.
• Pelajari praktik terbaik untuk Config Connector.