Menggunakan datastore Cassandra eksternal

Version 1.17 (latest)

   Versi yang didukung:

• v1.16 (terbaru)                        
• v1.15                         
• v1.14                        
• Daftar versi yang didukung

   Versi yang tidak didukung:

• v1.13                         
• v1.12                         
• v1.11                         
• v1.10                                      
• v1.9                                         
• v1.8                                         
• v1.7                                         
• v1.6                                         
• v1.5                                         
• v1.4                                         
• v1.3                                         
• v1.2                                         
• v1.1                                         

Topik ini menjelaskan cara menghubungkan runtime Apigee Hybrid ke datastore Cassandra di cluster Kubernetes yang berbeda. Dalam konfigurasi ini, cluster runtime tidak memiliki pod Cassandra. Nama konfigurasi ini adalah mode datastore eksternal.

Catatan: Mode datastore eksternal tersedia di versi hybrid 1.17.1 dan yang lebih baru. Sebagian besar penginstalan hybrid menjalankan Cassandra di cluster yang sama dengan runtime. Mode datastore eksternal ditujukan untuk penginstalan yang harus mengoperasikan Cassandra dalam cluster terpisah, misalnya, saat Cassandra dikelola oleh tim khusus. Untuk mengetahui ring Cassandra di cluster runtime, lihat Mengonfigurasi Cassandra untuk produksi.

Topologi dua cluster

Mode datastore eksternal menggunakan dua cluster Kubernetes:

• Cluster Cassandra menjalankan ring Cassandra. Opsi ini tidak menjalankan komponen runtime hibrida.
• Cluster runtime menjalankan komponen runtime hybrid, tetapi tidak memiliki pod Cassandra. Komponen runtime terhubung ke ring Cassandra di cluster Cassandra melalui jaringan.

Operator Apigee berjalan di kedua cluster. Anda menginstal cert-manager, definisi resource kustom (CRD) Apigee, dan diagram apigee-operator di setiap cluster. Tabel berikut menunjukkan komponen di setiap klaster:

Komponen	Cluster Cassandra	Cluster runtime
cert-manager	Ya	Ya
CRD Apigee dan diagram apigee-operator	Ya	Ya
Diagram apigee-datastore	Ya, dengan pod Cassandra	Ya, dengan replicaCount: 0 dan tanpa pod Cassandra
Semua diagram hybrid lainnya, seperti apigee-telemetry, apigee-redis, apigee-ingress-manager, apigee-org, apigee-env, dan apigee-virtualhost	Tidak	Ya

Operator Apigee melakukan tugas yang berbeda di setiap cluster:

• Di cluster Cassandra, operator membuat pod Cassandra. Operator ini juga mengelola siklus proses Cassandra, misalnya, saat Anda menskalakan ring.
• Di cluster runtime, operator tidak membuat pod Cassandra. Layanan headless dan objek Endpoints yang mengarah ke ring Cassandra di cluster Cassandra. Jika Anda mengaktifkan sinkronisasi endpoint dinamis, operator di cluster runtime juga membaca endpoint Cassandra dari cluster Cassandra.

Catatan: Semua cluster dan region dari satu organisasi Apigee harus menggunakan satu ring Cassandra. Mode datastore eksternal mengubah lokasi Cassandra. Anda tidak dapat menghubungkan lebih dari satu cincin ke satu organisasi. Untuk mengetahui informasi selengkapnya, lihat peringatan split-brain di Deployment multi-region.

Ringkasan penyiapan

Lakukan langkah-langkah berikut secara berurutan. Urutan ini penting. Otoritas (CA) sertifikat bersama harus ada di cluster runtime sebelum cluster runtime menerbitkan sertifikat. Untuk mengetahui informasi selengkapnya, lihat Membagikan CA Apigee sebelum menginstal operator.

1. Di cluster Cassandra, instal cert-manager, CRD Apigee, diagram apigee-operator, dan diagram apigee-datastore.
2. Pastikan pod Cassandra di cluster Cassandra sudah siap.
3. Di cluster runtime, instal cert-manager.
4. Salin secret apigee-ca dari cluster Cassandra ke cluster runtime. Lakukan langkah ini sebelum Anda menginstal diagram apigee-operator di cluster runtime.
5. Di cluster runtime, instal komponen runtime hybrid. Gunakan penggantian datastore eksternal untuk diagram apigee-datastore. Gunakan kredensial Cassandra yang sama seperti di cluster Cassandra.
6. (Direkomendasikan) Aktifkan sinkronisasi endpoint dinamis.
7. Verifikasi koneksi.

Untuk mengetahui langkah-langkah menginstal setiap diagram, lihat Menginstal Apigee Hybrid menggunakan Helm.

Sebelum memulai

Pastikan lingkungan Anda memenuhi persyaratan berikut:

• Koneksi jaringan ke Cassandra. Cluster runtime harus terhubung ke pod Cassandra di port TCP 9042. Tempatkan kedua cluster di VPC bersama, atau di jaringan dengan koneksi pribadi di antara keduanya.
• Satu wilayah. Tempatkan kedua cluster di region yang sama. Waktu round-trip antara cluster menambah latensi setiap permintaan runtime.
• cert-manager di kedua cluster. Di setiap cluster, cert-manager menerbitkan sertifikat untuk koneksi mTLS antara runtime dan Cassandra. Instal cert-manager di cluster Cassandra dan di cluster runtime.
• Rute ke setiap pod Cassandra. Driver klien Cassandra terhubung langsung ke setiap pod Cassandra. Cluster runtime harus terhubung ke alamat IP setiap pod Cassandra, bukan hanya ke satu alamat. Load balancer atau satu alamat IP virtual di depan ring tidak memenuhi persyaratan ini.
• Koneksi jaringan ke server Kubernetes API. Persyaratan ini hanya berlaku jika Anda menggunakan sinkronisasi endpoint dinamis. Cluster runtime harus terhubung ke server Kubernetes API dari cluster Cassandra.

Bagikan CA Apigee sebelum Anda menginstal operator

Salin rahasia apigee-ca ke cluster runtime sebelum Anda menginstal diagram apigee-operator di cluster runtime.

Runtime dan Cassandra menggunakan mTLS, sehingga kedua cluster harus memercayai CA yang sama. Diagram apigee-operator membuat CA yang ditandatangani sendiri di setiap cluster. CA ini adalah cert-manager Certificate bernama apigee-ca di namespace cert-manager.

Jika setiap cluster membuat apigee-ca-nya sendiri, kedua CA akan memiliki sidik jari yang berbeda. Kemudian, handshake mTLS gagal, dan runtime tidak dapat terhubung ke Cassandra.

Jika rahasia apigee-ca sudah ada di cluster, cert-manager tidak akan menggantinya. Jadi, jika Anda menyalin secret terlebih dahulu, cluster runtime akan menggunakan CA bersama. Jika cluster runtime menerbitkan sertifikat dari CA yang berbeda, salinan secret tidak cukup. Anda juga harus membuat ulang sertifikat tersebut agar ditandatangani oleh CA bersama.

Instal cert-manager di cluster runtime. Kemudian, salin secret CA dari cluster Cassandra ke cluster runtime:

kubectl --context CASSANDRA_CLUSTER -n cert-manager get secret apigee-ca -o yaml \
  | grep -v -E '^\s+(resourceVersion|uid|creationTimestamp|selfLink):' \
  | kubectl --context RUNTIME_CLUSTER -n cert-manager apply -f -

Ganti kode berikut:

• CASSANDRA_CLUSTER: konteks kubectl cluster Cassandra.
• RUNTIME_CLUSTER: konteks kubectl cluster runtime.

Perintah grep menghapus kolom metadata yang termasuk dalam cluster Cassandra. Server Kubernetes API tidak membuat objek yang memiliki nilai resourceVersion.

Penginstalan multi-region menggunakan prinsip CA bersama yang sama. Untuk langkah penyalinan serupa, lihat Merotasi sertifikat CA root. Untuk konfigurasi mTLS Cassandra, lihat Mengonfigurasi autentikasi untuk Cassandra.

Gunakan kredensial Cassandra yang sama di kedua cluster

Tetapkan kredensial Cassandra yang sama dalam file penggantian kedua cluster.

Diagram apigee-datastore di setiap cluster membuat secret kredensial dari nilai cassandra.auth cluster tersebut. Komponen runtime dan tugas penyiapan Cassandra di cluster runtime menggunakan kredensial ini untuk terhubung ke ring Cassandra. Jika kredensial di cluster runtime berbeda, autentikasi akan gagal.

Sandi default diagram sama di kedua cluster. Oleh karena itu, penginstalan dengan sandi default akan terhubung. Namun, jika Anda mengubah sandi hanya di satu cluster, koneksi akan gagal.

Gunakan salah satu metode ini dalam file penggantian dua cluster:

• Tetapkan nama pengguna dan sandi yang sama di cassandra.auth: default, admin, ddl, dml, jmx, dan jolokia.
• Setel cassandra.auth.secret. Di setiap cluster, secret harus berisi pengguna dan sandi yang sama. Lihat Membuat Secret.
• Tetapkan cassandra.auth.secretProviderClass ke SecretProviderClass yang membaca secret store yang sama. Lihat Menyimpan secret Cassandra di Hashicorp Vault.

Anda tidak menyalin rahasia kredensial dari cluster Cassandra. Diagram di cluster runtime membuat secret dari penggantian Anda. Untuk menemukan kegagalan autentikasi, lihat Verifikasi koneksi.

Mengonfigurasi datastore eksternal

Di cluster runtime, diagram apigee-datastore tidak boleh membuat pod Cassandra. Harus mengarah ke ring Cassandra di cluster Cassandra. Tambahkan setelan cassandra ini ke file penggantian cluster runtime:

cassandra:
  # No Cassandra pods in the runtime cluster.
  replicaCount: 0
  properties:
    # A comma-separated list of the Cassandra pod IP addresses.
    externalHost: "CASSANDRA_IP_ADDRESSES"
  storage:
    # Required, even with replicaCount: 0.
    storageSize: "10Gi"

Dengan:

• CASSANDRA_IP_ADDRESSES adalah daftar alamat IP yang dipisahkan koma pod Cassandra di cluster Cassandra. Contoh: 10.0.0.1:9042,10.0.0.2:9042,10.0.0.3:9042. Akhiran :9042 bersifat opsional. Untuk mendapatkan daftar, jalankan perintah ini:

  kubectl --context CASSANDRA_CLUSTER -n APIGEE_NAMESPACE get pods -l app=apigee-cassandra \
    -o jsonpath='{.items[*].status.podIP}' | tr ' ' ','

• APIGEE_NAMESPACE adalah namespace Apigee Anda. Default-nya adalah apigee.
• replicaCount: 0 memberi tahu operator untuk tidak membuat pod Cassandra di cluster runtime. Operator membuat Service headless dan objek Endpoints yang mengarah ke alamat externalHost.
• cassandra.properties.externalHost adalah daftar alamat IP Cassandra yang dipisahkan koma. Setiap alamat dapat memiliki sufiks :port, tetapi operator mengabaikan port dan selalu menggunakan port 9042. Operator hanya menerima alamat IP. Hostnames dan nama DNS diabaikan, dan peringatan ditulis ke log untuk setiap entri yang diabaikan.
• cassandra.storage.storageSize diperlukan, tetapi cluster runtime tidak membuat PersistentVolume untuk Cassandra. Webhook ApigeeDatastorevalidasi selalu memeriksa storageSize. Gunakan jumlah yang valid, misalnya 10Gi.

Catatan: Diagram apigee-datastore menyertakan contoh lengkap penggantian ini di apigee-datastore/examples/external-datastore-values.yaml.

Alamat IP pod berubah saat Anda menskalakan ring dan saat Kubernetes menjadwalkan ulang pod. Kemudian, daftar di externalHost menjadi salah. Oleh karena itu, sebaiknya gunakan sinkronisasi endpoint dinamis. Sinkronisasi endpoint dinamis membuat daftar alamat IP pod Cassandra tetap terbaru secara otomatis. Gunakan externalHost saja hanya untuk penginstalan sederhana atau untuk penyiapan pertama.

Menjaga endpoint tetap terbaru dengan sinkronisasi endpoint dinamis

Dengan hanya externalHost, Anda harus mengedit penggantian setiap kali ring Cassandra berubah. Sinkronisasi endpoint dinamis menghilangkan langkah manual ini. Operator di cluster runtime membaca endpoint Cassandra yang siap dari cluster Cassandra secara berkala. Kemudian, endpoint ini disalin ke objek Endpoints di cluster runtime.

Sebaiknya gunakan sinkronisasi endpoint dinamis. Alamat IP Pod berubah setiap kali Anda menskalakan cincin atau Kubernetes menjadwalkan ulang pod. Sinkronisasi endpoint dinamis membaca alamat IP pod yang siap dari Service headless Cassandra. Dengan demikian, objek Endpoints di cluster runtime selalu berisi alamat IP pod Cassandra saat ini.

Dengan sinkronisasi endpoint dinamis, externalHost masih diperlukan. Operator menggunakannya dalam dua kondisi berikut:

• Sebelum pembacaan pertama yang berhasil dari cluster Cassandra.
• Saat pembacaan dari cluster Cassandra gagal dan tidak ada endpoint dari pembacaan sebelumnya yang berhasil.

Jika pembacaan gagal dan ada endpoint dari pembacaan sebelumnya yang berhasil, operator akan mempertahankan endpoint tersebut. Runtime mempertahankan koneksinya ke Cassandra.

Untuk mengaktifkan sinkronisasi endpoint dinamis, tambahkan blok externalEndpointsSync ke file penggantian cluster runtime:

cassandra:
  replicaCount: 0
  properties:
    # The first endpoints, and the fallback if a read fails.
    externalHost: "CASSANDRA_IP_ADDRESSES"
    externalEndpointsSync:
      # A secret in the runtime cluster. Its "kubeconfig" key holds the
      # kubeconfig for the Cassandra cluster.
      secretRef: apigee-remote-cass-kubeconfig
      # The namespace of the Cassandra headless Service in the Cassandra cluster.
      namespace: apigee
      # The Cassandra headless Service in the Cassandra cluster.
      serviceName: apigee-cassandra-default
      # The interval between reads, in seconds. The default is 30.
      intervalSeconds: 30
  storage:
    storageSize: "10Gi"

Catatan: Diagram apigee-datastore menyertakan contoh lengkap penggantian ini di apigee-datastore/examples/external-datastore-endpoint-sync-values.yaml.

Buat akun layanan hanya baca di cluster Cassandra

Operator di cluster runtime menggunakan kubeconfig untuk terhubung ke cluster Cassandra. kubeconfig ini harus menggunakan ServiceAccount hanya baca dengan hak istimewa terendah. ServiceAccount ini hanya dapat membaca endpoint Cassandra. Cluster ini tidak dapat mengubah resource di cluster Cassandra.

Di cluster Cassandra, buat resource berikut:

• ServiceAccount, misalnya apigee-endpoint-reader.
• Role dan RoleBinding di namespace Cassandra. Peran ini hanya memberikan kata kerja get, list, dan watch pada endpoints inti. Jangan memberikan kata kerja lain, seperti create, update, patch, atau delete. Jangan berikan akses ke resource lain.
• Secret token yang berlaku lama untuk ServiceAccount.

Kemudian, buat file kubeconfig untuk server API Kubernetes dari cluster Cassandra. kubeconfig ini harus menggunakan token ServiceAccount. Di cluster runtime, buat secret dengan nama yang Anda tetapkan di externalEndpointsSync.secretRef. Masukkan kubeconfig di kunci kubeconfig:

kubectl --context RUNTIME_CLUSTER -n APIGEE_NAMESPACE create secret generic \
  apigee-remote-cass-kubeconfig --from-file=kubeconfig=READER_KUBECONFIG_FILE

Ganti READER_KUBECONFIG_FILE dengan jalur ke file kubeconfig untuk ServiceAccount hanya baca.

Kubeconfig berisi token yang berlaku lama. Jaga kerahasiaan ini sebaik kredensial Anda yang lain.

Catatan: Diagram apigee-datastore menyertakan sampel resource ini di apigee-datastore/examples/external-cassandra-reader-rbac.yaml. Contoh ini mencakup ServiceAccount, Role, RoleBinding, token Secret, dan kubeconfig secret untuk cluster runtime.

Memantau sinkronisasi endpoint dinamis

Jika pembacaan dari cluster Cassandra gagal, runtime akan mempertahankan koneksinya. Namun, endpoint di cluster runtime tidak berubah hingga pembacaan berhasil lagi. Pantau sinkronisasi sehingga Anda menemukan kegagalan yang terus-menerus sebelum ring Cassandra berubah.

Operator di cluster runtime memberikan sinyal berikut:

• Kondisi EndpointSyncDegraded dalam status resource ApigeeDatastore. Kondisi menjadi True setelah tiga pembacaan gagal berturut-turut. Alasannya adalah RemoteReadFailed atau NoReadyRemoteEndpoints. Setelah pembacaan berhasil, kondisi akan menjadi False dengan alasan SyncSucceeded.
• Metrik external_endpoint_sync_last_success_timestamp. Metrik ini adalah waktu pembacaan terakhir yang berhasil, dalam detik Unix.
• Metrik external_endpoint_sync_failures_total. Metrik ini menghitung kegagalan pembacaan.

Kedua metrik memiliki label namespace dan name dari resource ApigeeDatastore. Operator menampilkannya di endpoint metriknya.

Untuk melihat kondisi, jalankan perintah ini:

kubectl --context RUNTIME_CLUSTER -n APIGEE_NAMESPACE get apigeedatastore default \
  -o jsonpath='{.status.conditions}'

Sebaiknya buat pemberitahuan pada kondisi EndpointSyncDegraded. Status ApigeeDatastore mempertahankan kondisi saat operator dimulai ulang. Hanya pembacaan yang berhasil yang menetapkan kondisi ke False.

Jika Anda juga menggunakan pemberitahuan pada metrik, kirim pemberitahuan saat salah satu dari dua ekspresi ini benar:

• time() - external_endpoint_sync_last_success_timestamp > 300
• absent(external_endpoint_sync_last_success_timestamp)

Operator menetapkan metrik hanya setelah pembacaan berhasil. Jika operator dimulai ulang saat pembacaan gagal, metrik tidak ada. Kemudian, ekspresi pertama tidak cocok, dan hanya ekspresi kedua yang mengirimkan pemberitahuan.

Memverifikasi koneksi

Setelah menginstal komponen runtime, lakukan pemeriksaan berikut di cluster runtime:

1. Pastikan cluster runtime tidak memiliki pod Cassandra:

   kubectl --context RUNTIME_CLUSTER -n APIGEE_NAMESPACE get pods -l app=apigee-cassandra

   Outputnya adalah No resources found.

2. Pastikan objek Endpoints mengarah ke ring Cassandra:

   kubectl --context RUNTIME_CLUSTER -n APIGEE_NAMESPACE get endpoints apigee-cassandra-default

   Kolom ENDPOINTS menampilkan alamat IP Cassandra. Jika Anda menggunakan sinkronisasi endpoint dinamis, ini adalah alamat IP pod Cassandra yang siap di cluster Cassandra.

3. Pastikan tugas penyiapan Cassandra telah selesai:

   kubectl --context RUNTIME_CLUSTER -n APIGEE_NAMESPACE get jobs \
     | grep -E 'apigee-cassandra-(schema|user)-setup'

   Kolom COMPLETIONS menampilkan 1/1 untuk setiap tugas. Jika tugas tidak selesai, periksa log tugas untuk mengetahui apakah ada error autentikasi. Kemudian, pastikan kedua cluster menggunakan kredensial Cassandra yang sama.

Menskalakan ring Cassandra

Operator Apigee di cluster Cassandra memiliki siklus proses Cassandra. Menskalakan Cassandra di cluster Cassandra. Anda tidak dapat menskalakan Cassandra dari cluster runtime.

Jangan jalankan nodetool decommission secara manual sebelum Anda mengurangi jumlah pod Cassandra.

Operator di cluster Cassandra mengelola keanggotaan ring saat Anda mengurangi jumlah pod. Jika Anda menonaktifkan node secara manual, lalu mengurangi jumlah pod, StatefulSet dan operator akan menjadi tidak konsisten. Penurunan kemudian berhenti dan tidak dapat dilanjutkan. Izinkan operator menonaktifkan node.

Patuhi aturan yang sama seperti untuk ring Cassandra di cluster runtime:

• Menskalakan Cassandra dalam kelipatan tiga. Hal ini menjaga keseimbangan ring di tiga zona ketersediaan.
• Sebelum Anda menambah jumlah pod, pastikan cluster Cassandra memiliki kapasitas node yang memadai.
• Jika Anda tidak menggunakan sinkronisasi endpoint dinamis, perbarui externalHost setelah setiap operasi penskalaan.

Untuk mengetahui informasi selengkapnya, lihat Menskalakan Cassandra.

Langkah berikutnya

• Untuk menginstal diagram di setiap cluster, lihat Menginstal Apigee Hybrid menggunakan Helm.
• Untuk mTLS dan kredensial Cassandra, lihat Mengonfigurasi autentikasi untuk Cassandra.
• Untuk menambahkan kapasitas ke ring Cassandra, lihat Menskalakan Cassandra.