Memigrasikan Apigee Hybrid ke Helm dari apigeectl

Alat migrasi ini membantu memigrasikan situs yang berbasis apigeectl cluster hibrida ke cluster hibrid berbasis Helm. Alat ini tidak menjalankan penggantian komponen cluster apa pun. Hal ini bersifat idempoten dan dapat dijalankan di banyak tempat waktu di cluster yang sama, menyiapkan subset komponen dan organisasi masing-masing baik.

Anda dapat memigrasikan semua komponen apigee sekaligus, dan Helm operasi upgrade dapat dilakukan per komponen setelah alat akan dijalankan.

Lihat Menginstal dan mengelola Apigee Hybrid dengan diagram Helm untuk mendapatkan informasi tentang cara mengelola cluster hybrid yang telah Anda migrasikan ke Helm pengelolaan biaya dengan alat ini.

Prasyarat

  • Helm versi v3.10+.
  • File kubeconfig yang berfungsi dan mengarah ke cluster dengan instalasi Apigee Hybrid 1.12 yang berfungsi.
  • Izin untuk mengubah metadata dan anotasi di Kubernetes komponen hybrid yang ingin Anda migrasikan.

Cakupan

Alat ini mendukung opsi berikut saat run-time:

  • Penyesuaian namespace untuk resource apigee. Default namespace: apigee
  • Migrasi komponen campuran yang dipilih saja. Default: semua komponen dimigrasikan
  • Migrasi hanya satu organisasi
  • Migrasi hanya dengan satu lingkungan
  • Migrasi satu grup env (apigee-virtualhost) saja
  • Penyesuaian nama rilis Helm untuk organisasi, lingkungan, dan grup env.

Batasan

  • Alat ini tidak mendukung penyesuaian nama rilis Helm untuk alat hybrid ini komponen: apigee-operator, apigee-datastore, apigee-redis, apigee-telemetry, dan apigee-ingress-manager.
  • Penyesuaian interaktif yang dilakukan pada nama rilis Helm untuk organisasi, lingkungan, dan {i>env-groups<i} tidak secara otomatis bertahan antaroperasi. Anda dapat mengedit {i>temp<i} dan menyediakannya sebagai opsi untuk dijalankan di lain waktu.
  • Pemfilteran env dan env-group dilakukan hanya berdasarkan nama. Dalam beberapa kasus, dapat mengakibatkan beberapa env dan env-grup dimigrasikan di multi-org klaster.

    Misalnya, pada cluster multi-org dengan organisasi org1 dan org2, jika env prod ada di kedua org, dan hanya --env=prod yang ditentukan, kedua env akan dimigrasikan. Jika Anda hanya ingin memigrasikan satu env, Anda juga harus tentukan filter org --org=org1 atau --org=org2.

Penggunaan

Sintaks

apigee-helm-migration [--apigee-namespace=] [--components=] [--dry-run] [--env=org1] [--env-group=org2] [--org=baz] [--kubeconfig=] [-y] [-v] [-f /path/to/releaseNames.yaml]

Nama rilis Helm yang dibuat

Setiap Helm Chart yang di-deploy pada cluster harus memiliki nama rilis, yang harus unik di dalam namespace. Nama rilis Helm tidak memiliki konvensi penamaan atau batasan terkait nama diagram. Migrasi menghasilkan nama rilis Helm yang unik untuk setiap komponen.

Diagram Cluster org tunggal Cluster multi-org
apigee-operator operator operator
apigee-datastore datastore datastore
apigee-telemetry telemetry telemetry
apigee-redis redis redis
apigee-ingress-manager ingress-manager ingress-manager
apigee-org ORG_NAME ORG_NAME
apigee-env ENV_NAME[-env[-n]](1) ORG_NAME-ENV_NAME[-env[-n]](1)
apigee-virtualhost (envgroup) VH_NAME[-env-group[-n]](1) ORG_NAME-VH_NAME[-env-group[-n]](1)

(1) Nama diakhiri dengan -env atau -env-group jika nama yang dibuat bertentangan dengan nama lain nama yang dibuat. Selanjutnya, nama tersebut akan diberi akhiran -1 atau -2 … jika masih bertentangan.

Menyesuaikan nama rilis Helm

Alat migrasi memungkinkan penyesuaian interaktif untuk nama rilis Helm. Jika Anda ingin menyesuaikan nama rilis Helm secara noninteraktif:

  1. Jalankan alat sekali dan keluar dari perintah pertama untuk membuat file sementara yang berisi nama rilis yang dibuat secara otomatis. Anda akan melihat baris seperti:
    INFO: 21:32:56 using temp file for release names:  /tmp/apigee-helm-migration-1229129207-releaseNames
    
  2. Pindahkan atau salin, lalu edit file ini. Anda bisa meneruskan file yang diedit ini dengan opsi -f saat Anda jalankan alat migrasi. Parameter yang dibuat secara otomatis nama rilis akan terlihat seperti ini:

    orgs:
      example-apigee-org:
        helmReleaseName: example-apigee-org
        envs:
          prod:
            helmReleaseName: prod
        envGroups:
          prod-envgroup:
            helmReleaseName: prod-envgroup
    

    Edit nama rilis Helm untuk organisasi, env, atau envgroup, edit kolom helmReleaseName dari objek tersebut. Misalnya, untuk mengganti nama rilis org menjadi custom-org, rilis env menjadi custom-env, dan rilis envgroup ke custom-group, file yang dihasilkan akan terlihat seperti ini:

    orgs:
      example-apigee-org:
        helmReleaseName: custom-org
        envs:
          prod:
            helmReleaseName: custom-env
        envGroups:
          prod-envgroup:
            helmReleaseName: custom-group
    

Menggunakan namespace kustom

Apigee Hybrid berjalan di dua namespace Kubernetes:

  • apigee-system: Komponen apigee-operator selalu berjalan di Namespace apigee-system. Alat migrasi Helm akan memperbarui komponen apigee-operator dalam namespace apigee-system, apa pun apa yang Anda tentukan dengan flag --apigee-namespace.
  • apigee: Semua komponen campuran kecuali apigee-operator berjalan di sini namespace. Nama defaultnya adalah apigee. Anda dapat menggunakan namespace kustom apa pun untuk komponen.

    Jika menggunakan namespace kustom, Anda harus menentukannya dengan flag --apigee-namespace my_custom_namespace saat Anda menjalankan Alat migrasi Helm.

    Anda juga harus menambahkan namespace: my_custom_namespace properti tingkat teratas ke file penggantian.

Petunjuk

  1. Temukan alat migrasi.

    Alat migrasi dikemas dengan apigeectl di bagian /tools/migration/.

  2. Ekstrak file yang dikompresi menggunakan salah satu perintah berikut:

    • Mac:
      tar -xzf apigee-helm-migration_1.0.2_mac_64.tar.gz
    • Linux:
      tar -xzf apigee-helm-migration_1.0.2_linux_64.tar.gz
    • Windows:
      tar -xzf apigee-helm-migration_1.0.2_windows_64.zip
  3. Jalankan alat migrasi. Jika opsi {i>default<i} dapat diterima, maka memadai untuk menjalankan alat tanpa argumen apa pun, dan menyetujui prompt jika nama rilis helm yang dihasilkan memuaskan. Beberapa contoh skenario berikut diberikan:
    • Penginstalan sederhana, menggunakan kubeconfig default (~/.kube/config), apigee default namespace, dan nama rilis Helm default.

      Perintah berikut sudah memadai untuk sebagian besar, atau bahkan semua, penginstalan. Operasi upgrade Helm dapat dilakukan pada per komponen setelah alat dijalankan.

      ./apigee-helm-migration
      
    • Memigrasikan semua komponen menggunakan namespace kustom:
      ./apigee-helm-migration --apigee-namespace my_custom_namespace
      
    • Hanya memigrasikan komponen operator dan datastore:

      ./apigee-helm-migration --components operator,datastore
      
        INFO: 00:22:48 using kubeconfig file  /usr/local/google/home/example/.kube/config
        INFO: 00:22:48 namespace for apigee resources:
        INFO: 00:22:48 	 apigee
        INFO: 00:22:48 processing all organizations in cluster
        INFO: 00:22:48 Components to migrate:
        INFO: 00:22:48 	 operator,datastore
        INFO: 00:22:48 dry-run:
        INFO: 00:22:48 	 false
        Continue with patching apigee resources for Helm migration? [y/n]: y
        INFO: 00:22:52 Processing component:  operator
        INFO: 00:22:54 Processing component:  datastore
        INFO: 00:22:55 Migration successful!
      
    • Menunjuk ke file kubeconfig tertentu dan menentukan nama yang berbeda untuk namespace apigee.

      ./apigee-helm-migration --kubeconfig /abs/path/to/kubeconf --namespace org1_namespace
      
    • Memigrasikan semua komponen, tetapi hanya satu organisasi:

      ./apigee-helm-migration --org=some-test-org
      

    Berikut adalah contoh output dari migrasi yang berhasil:

    INFO: 21:32:55 using kubeconfig file  /usr/local/google/home/example/.kube/config
    INFO: 21:32:55 namespace for apigee resources:
    INFO: 21:32:55 	 apigee
    INFO: 21:32:55 processing all organizations in cluster
    INFO: 21:32:55 processing all components
    INFO: 21:32:55 dry-run:
    INFO: 21:32:55 	 false
    INFO: 21:32:55 cluster Apigee information:
    INFO: 21:32:55 Apigee Organizations found:
    INFO: 21:32:56 	 example-hybrid-dev
    INFO: 21:32:56 Apigee Environments found (org: env):
    INFO: 21:32:56 	 example-hybrid-dev : prod
    INFO: 21:32:56 Apigee EnvGroups(apigeerouteconfigs) found (org: envGroup):
    INFO: 21:32:56 	 example-hybrid-dev : prod-envgroup
    INFO: 21:32:56 using temp file for release names:  /tmp/apigee-helm-migration-1229129207-releaseNames
    INFO: 21:32:56 Helm release names for Apigee orgs/envs/envgroups:
    orgs:
    example-hybrid-dev:
    helmReleaseName: example-hybrid-dev
    envs:
      prod:
        helmReleaseName: prod
    envGroups:
      prod-envgroup:
        helmReleaseName: prod-envgroup
    Make changes to the release names for Apigee orgs/env/envgroups? [y/n]: n
    Continue with patching apigee resources for Helm migration? [y/n]: y
    INFO: 21:32:59 Processing component:  operator
    INFO: 21:33:01 Processing component:  datastore
    INFO: 21:33:01 Processing component:  redis
    INFO: 21:33:02 Processing component:  ingress-manager
    INFO: 21:33:02 Processing component:  telemetry
    INFO: 21:33:03 Processing component:  orgs
    INFO: 21:33:05 Processing component:  envs
    INFO: 21:33:06 Processing component:  env-groups
    INFO: 21:33:07 Migration successful!
    

    Potensi error:

    • Terjadi error saat menguraikan file nama rilis: Periksa item yang diteruskan nama rilis.
    • Resource tidak ditemukan: Periksa apakah Apigee Hybrid sepenuhnya diinstal, dan Anda memiliki izin untuk mengakses Resource apigee.

Perubahan properti konfigurasi

Lakukan perubahan berikut pada file yang diganti:

  • Buat stanza apigeeIngressGateway tambahan di file penggantian, yang akan harus berisi minimal:
    apigeeIngressGateway:
      image:
        url: "PATH_TO_REPOSITORY/apigee-asm-ingress"
        tag: "tag"
    

    Contoh:

    apigeeIngressGateway:
      image:
        url: "gcr.io/apigee-release/hybrid/apigee-asm-ingress"
        tag: "1.17.8-asm.20-distroless"
    

    Lihat apigeeIngressGateway

  • Properti untuk mengaktifkan Workload Identity telah berubah:
    • gcp.workloadIdentity.enabled menggantikan gcp.workloadIdentityEnabled.
    • Jika menggunakan satu akun layanan untuk semua komponen, Anda dapat menentukannya dengan: gcp.workloadIdentity.gsa. Contoh:
      gcp:
        workloadIdentity:
          enabled: true
          gsa: "apigee-non-prod@my-hybrid-project."
      
    • Jika Anda menggunakan akun layanan terpisah untuk setiap komponen (standar untuk sebagian besar produk penginstalan), tentukan akun layanan dengan properti gsa komponen. Contoh:
      logger:
        gsa: "apigee-logger@my-hybrid-project."
      

    Lihat: gcp.workloadIdentity.enabled, gcp.federatedWorkloadIdentity.enabled, Mengaktifkan Workload Identity di GKE atau Mengaktifkan Workload Identity Federation di AKS dan EKS.

Pemecahan masalah

Ada masalah umum pada alat migrasi Helm dalam rilis hybrid v1.12. Hingga Jika masalah teratasi, Pencadangan dan pemulihan Cassandra memerlukan langkah tambahan.

Anda dapat mengikuti langkah-langkah berikut:

  • Sebelum atau setelah menjalankan alat migrasi
  • Sebelum menginstal diagram Helm

Untuk menginstal patch sebagai solusi:

  1. Pastikan kubeconfig saat ini mengarah ke cluster yang ingin Anda migrasikan. Anda dapat menjalankan langkah-langkah ini dari direktori mana pun.
  2. Buat file bernama migration-operator-patch.yaml dengan konten berikut:
    # migration-operator-patch.yaml
    metadata:
      annotations:
        meta.helm.sh/release-name: operator
        meta.helm.sh/release-namespace: apigee-system
      labels:
        app.kubernetes.io/managed-by: Helm
  3. Buat file bernama migration-datastore-patch.yaml dengan konten berikut:
    # migration-datastore-patch.yaml
    metadata:
      annotations:
        meta.helm.sh/release-name: datastore
        meta.helm.sh/release-namespace: apigee
      labels:
        app.kubernetes.io/managed-by: Helm
  4. Jalankan perintah kubectl berikut:
    kubectl patch clusterrole apigee-cassandra-backup --patch-file ./migration-operator-patch.yaml
    kubectl patch clusterrole apigee-cassandra-restore --patch-file ./migration-operator-patch.yaml
    kubectl patch clusterrolebinding apigee-cassandra-backup --patch-file ./migration-operator-patch.yaml
    kubectl patch clusterrolebinding apigee-cassandra-restore --patch-file ./migration-operator-patch.yaml
    kubectl patch -n apigee cronjob apigee-cassandra-backup --patch-file ./migration-datastore-patch.yaml
    kubectl patch -n apigee certificate apigee-cassandra-backup-tls --patch-file ./migration-datastore-patch.yaml --type merge
    kubectl patch -n apigee secret apigee-cassandra-backup-svc-account --patch-file ./migration-datastore-patch.yaml
    kubectl patch -n apigee secret apigee-cassandra-backup-key-file --patch-file ./migration-datastore-patch.yaml
    kubectl patch -n apigee ServiceAccount apigee-cassandra-backup-sa --patch-file ./migration-datastore-patch.yaml
    kubectl patch -n apigee job apigee-cassandra-restore --patch-file ./migration-datastore-patch.yaml
    kubectl patch -n apigee certificate apigee-cassandra-restore-tls --patch-file ./migration-datastore-patch.yaml --type merge
    kubectl patch -n apigee secret apigee-cassandra-restore-svc-account --patch-file ./migration-datastore-patch.yaml
    kubectl patch -n apigee secret apigee-cassandra-restore-key-file --patch-file ./migration-datastore-patch.yaml
    kubectl patch -n apigee ServiceAccount apigee-cassandra-restore-sa --patch-file ./migration-datastore-patch.yaml
  5. Bersihkan file patch menggunakan perintah berikut:
    rm migration-operator-patch.yaml
    rm migration-datastore-patch.yaml

Langkah berikutnya

Lanjutkan penginstalan diagram Helm hybrid Apigee dengan petunjuk di Menginstal dan mengelola Apigee Hybrid dengan diagram Helm.

Output dari -help

./apigee-helm-migration --help
Usage of ./apigee-helm-migration:
  -apigee-namespace string
      namespace used for apigee resources (default "apigee")
  -components string
      CSV of components to migrate. If empty then all components are migrated. Valid values are: operator,datastore,redis,ingress-manager,telemetry,orgs,envs,env-groups
  -dry-run
      perform a dry-run
  -env string
      restrict migration to a singular supplied env. If empty then all envs detected in the cluster are migrated
  -env-group string
      restrict migration to a singular supplied envGroup. If empty then all envGroups detected in the cluster are migrated
  -kubeconfig string
      (optional) absolute path to the kubeconfig file (default "/usr/local/google/home/example/.kube/config")
  -org string
      restrict migration to a singular supplied org. If empty then all orgs detected in the cluster are migrated
  -v	Increased logging verbosity
  -y	don't prompt for confirmation or for configuration of Helm releases