Mengupgrade Apigee Hybrid ke versi 1.17

Prosedur ini mencakup upgrade dari Apigee hybrid versi 1.16.x ke Apigee hybrid versi 1.17.3 dan dari rilis hybrid 1.17.x sebelumnya ke versi 1.17.3.

Gunakan prosedur yang sama untuk upgrade versi minor (misalnya versi 1.16 ke 1.17) dan untuk upgrade rilis patch (misalnya 1.17.0 ke 1.17.3).

Jika Anda mengupgrade dari Apigee hybrid versi 1.15 atau yang lebih lama, Anda harus mengupgrade ke hybrid versi 1.16 terlebih dahulu sebelum mengupgrade ke versi 1.17.3. Lihat petunjuk untuk Mengupgrade Apigee hybrid ke versi 1.16.

Perubahan dari Apigee hybrid v1.16

Perhatikan perubahan berikut:

  • Dukungan Model Context Protocol (MCP): Apigee hybrid versi 1.17 menambahkan dukungan untuk Model Context Protocol (MCP), sebuah protokol terbuka yang memungkinkan aplikasi AI agentic menggunakan API Anda sebagai alat melalui endpoint MCP terkelola. Apigee hybrid merutekan, mengizinkan, dan mengamankan panggilan alat MCP ini dengan cara yang sama seperti mengelola API Anda yang lain, sehingga Anda tidak perlu menjalankan atau memelihara server MCP Anda sendiri. Untuk mengetahui informasi selengkapnya, lihat Ringkasan Model Context Protocol (MCP) di Apigee dan panduan memulai MCP.
  • Rotasi sertifikat root CA: Apigee hybrid versi 1.17 menambahkan dukungan untuk merotasi sertifikat root certificate authority (CA) yang menjadi jangkar kepercayaan untuk komunikasi TLS antara komponen runtime Anda. Anda kini dapat mengganti root CA sebelum masa berlakunya habis, tanpa periode nonaktif, dengan mengikuti prosedur rotasi bertahap. Untuk mengetahui informasi selengkapnya, lihat Merotasi sertifikat root CA.
  • Dukungan TLS 1.3: Apigee hybrid versi 1.17 menambahkan dukungan untuk TLS 1.3, versi terbaru protokol Transport Layer Security. TLS 1.3 menawarkan handshake koneksi yang lebih cepat dan keamanan yang lebih kuat daripada versi TLS sebelumnya. Untuk mengetahui informasi tentang cara mengonfigurasi TLS di gateway ingress, lihat Mengonfigurasi TLS dan mTLS di gateway ingress.
  • Dukungan proxy penerusan untuk kebijakan AI: Apigee hybrid versi 1.17 menambahkan dukungan proxy penerusan untuk kebijakan AI, seperti kebijakan Model Armor dan caching semantik. Panggilan keluar yang dilakukan oleh kebijakan ini kini dapat dirutekan melalui proxy penerusan HTTP, yang tidak didukung di versi Apigee hybrid sebelumnya. Untuk informasi selengkapnya, lihat Mengonfigurasi proxy penerusan untuk proxy API.
  • Dukungan endpoint Private Service Connect (PSC) cache semantik: Apigee hybrid versi 1.17 menambahkan dukungan endpoint Private Service Connect (PSC) untuk caching semantik. Kebijakan caching semantik kini dapat menjangkau layanan pendukungnya melalui endpoint Private Service Connect, yang menjaga traffic tersebut tetap berada di jaringan pribadi Anda. Untuk mengetahui informasi selengkapnya, lihat Memulai kebijakan caching semantik.

Untuk mengetahui informasi tambahan tentang fitur di Hybrid versi 1.17, lihat catatan rilis Apigee hybrid v1.17.3.

Prasyarat

Sebelum mengupgrade ke hybrid versi 1.17, pastikan penginstalan Anda memenuhi persyaratan berikut:

Sebelum mengupgrade ke 1.17.3 - batasan dan catatan penting

  • Mengupgrade ke Apigee hybrid versi 1.17 mungkin memerlukan periode nonaktif.

    Saat mengupgrade pengontrol Apigee ke versi 1.17.3, semua deployment Apigee akan menjalani mulai ulang berkelanjutan. Untuk meminimalkan periode nonaktif di lingkungan hybrid produksi selama mulai ulang berkelanjutan, pastikan Anda menjalankan setidaknya dua cluster (di region/pusat data yang sama atau berbeda). Alihkan semua traffic produksi ke satu cluster dan buat cluster yang akan diupgrade menjadi offline, lalu lanjutkan proses upgrade. Ulangi proses ini untuk setiap cluster.

    Apigee merekomendasikan agar setelah memulai upgrade, Anda harus mengupgrade semua cluster sesegera mungkin untuk mengurangi kemungkinan dampak produksi. Tidak ada batas waktu kapan semua cluster yang tersisa harus diupgrade setelah cluster pertama diupgrade. Namun, hingga semua cluster yang tersisa diupgrade, pencadangan dan pemulihan Cassandra tidak dapat berfungsi dengan versi campuran. Misalnya, cadangan dari Hybrid 1.16 tidak dapat digunakan untuk memulihkan instance Hybrid 1.17.

  • Perubahan bidang pengelolaan tidak perlu ditangguhkan sepenuhnya selama upgrade. Setiap penangguhan sementara yang diperlukan untuk perubahan bidang pengelolaan dicantumkan dalam petunjuk upgrade di bawah.

Ringkasan upgrade ke versi 1.17.3

Prosedur untuk mengupgrade Apigee hybrid diatur di bagian berikut:

  1. Bersiap untuk mengupgrade.
  2. Instal runtime hybrid versi 1.17.3.

Bersiap untuk mengupgrade ke versi 1.17

Mencadangkan penginstalan hybrid Anda

  1. Petunjuk ini menggunakan variabel lingkungan APIGEE_HELM_CHARTS_HOME untuk direktori dalam sistem file tempat Anda menginstal diagram Helm. Jika perlu, ubah direktori ke direktori ini dan tentukan variabel dengan perintah berikut:

    Linux 

    export APIGEE_HELM_CHARTS_HOME=$PWD
echo $APIGEE_HELM_CHARTS_HOME

    Mac OS 

    export APIGEE_HELM_CHARTS_HOME=$PWD
echo $APIGEE_HELM_CHARTS_HOME

    Windows 

    set APIGEE_HELM_CHARTS_HOME=%CD%
echo %APIGEE_HELM_CHARTS_HOME%
  2. Buat salinan cadangan direktori $APIGEE_HELM_CHARTS_HOME/ versi 1.16 Anda. Anda dapat menggunakan proses pencadangan apa pun. Misalnya, Anda dapat membuat file tar dari seluruh direktori dengan: 
    tar -czvf $APIGEE_HELM_CHARTS_HOME/../apigee-helm-charts-v1.16-backup.tar.gz $APIGEE_HELM_CHARTS_HOME
  3. Cadangkan database Cassandra Anda dengan mengikuti petunjuk di Pencadangan dan pemulihan Cassandra.
  4. Pastikan file kunci dan sertifikat TLS Anda (.crt, .key, dan/atau .pem) berada di direktori $APIGEE_HELM_CHARTS_HOME/apigee-virtualhost/.

Mengupgrade versi Kubernetes

Periksa versi platform Kubernetes Anda dan jika perlu, upgrade platform Kubernetes Anda ke versi yang didukung oleh hybrid 1.16 dan hybrid 1.17. Ikuti dokumentasi platform Anda jika memerlukan bantuan.

Ambil diagram Helm Apigee.

Chart Apigee hybrid dihosting di Google Artifact Registry:

oci://us-docker.pkg.dev/apigee-release/apigee-hybrid-helm-charts

Dengan menggunakan perintah pull, salin semua chart Helm Apigee hybrid ke penyimpanan lokal Anda dengan perintah berikut: 

export CHART_REPO=oci://us-docker.pkg.dev/apigee-release/apigee-hybrid-helm-charts
export CHART_VERSION=1.17.3
helm pull $CHART_REPO/apigee-operator --version $CHART_VERSION --untar
helm pull $CHART_REPO/apigee-datastore --version $CHART_VERSION --untar
helm pull $CHART_REPO/apigee-env --version $CHART_VERSION --untar
helm pull $CHART_REPO/apigee-ingress-manager --version $CHART_VERSION --untar
helm pull $CHART_REPO/apigee-org --version $CHART_VERSION --untar
helm pull $CHART_REPO/apigee-redis --version $CHART_VERSION --untar
helm pull $CHART_REPO/apigee-telemetry --version $CHART_VERSION --untar
helm pull $CHART_REPO/apigee-virtualhost --version $CHART_VERSION --untar

Mengedit kustomization.yaml untuk namespace apigee kustom

Jika namespace Apigee Anda bukan apigee, edit file apigee-operator/etc/crds/default/kustomization.yaml dan ganti nilai namespace dengan namespace Apigee Anda.

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization

namespace: APIGEE_NAMESPACE

Jika Anda menggunakan apigee sebagai namespace, Anda tidak perlu mengedit file.

  • Instal CRD Apigee yang telah diupdate:

    1. Gunakan fitur uji coba kubectl dengan menjalankan perintah berikut:

      kubectl apply -k  apigee-operator/etc/crds/default/ --server-side --force-conflicts --validate=false --dry-run=server

    2. Setelah memvalidasi dengan perintah uji coba, jalankan perintah berikut:

      kubectl apply -k  apigee-operator/etc/crds/default/ \
  --server-side \
  --force-conflicts \
  --validate=false
    3. Validasi penginstalan dengan perintah kubectl get crds: 
      kubectl get crds | grep apigee

      Output Anda akan terlihat seperti berikut.

      apigeedatastores.apigee.cloud.google.com                    2024-08-21T14:48:30Z
apigeedeployments.apigee.cloud.google.com                   2024-08-21T14:48:30Z
apigeeenvironments.apigee.cloud.google.com                  2024-08-21T14:48:31Z
apigeeissues.apigee.cloud.google.com                        2024-08-21T14:48:31Z
apigeeorganizations.apigee.cloud.google.com                 2024-08-21T14:48:32Z
apigeeredis.apigee.cloud.google.com                         2024-08-21T14:48:33Z
apigeerouteconfigs.apigee.cloud.google.com                  2024-08-21T14:48:33Z
apigeeroutes.apigee.cloud.google.com                        2024-08-21T14:48:33Z
apigeetelemetries.apigee.cloud.google.com                   2024-08-21T14:48:34Z
cassandradatareplications.apigee.cloud.google.com           2024-08-21T14:48:35Z

  • Periksa label pada node cluster. Secara default, Apigee menjadwalkan pod data pada node dengan label cloud.google.com/gke-nodepool=apigee-data dan pod runtime dijadwalkan pada node dengan label cloud.google.com/gke-nodepool=apigee-runtime. Anda dapat menyesuaikan label node pool di file overrides.yaml.

    Untuk mengetahui informasi selengkapnya, lihat Mengonfigurasi node pool khusus.

    • Mengupgrade cert-manager

    Apigee hybrid v1.17 mendukung rilis cert-manager 1.16 hingga 1.19. Ada perubahan di cert-manager 1.18 yang dapat menyebabkan masalah pada traffic Anda. Dalam rilis cert-manager 1.18, nilai default Certificate.Spec.PrivateKey.rotationPolicy diubah dari Never menjadi Always. Untuk penginstalan hybrid Apigee yang diupgrade, hal ini dapat menyebabkan masalah pada traffic Anda. Saat mengupgrade ke hybrid v1.17 dari versi sebelumnya, Anda harus mengedit sertifikat apigee-ca untuk mengimbangi perubahan ini atau mempertahankan versi cert-manager Anda pada rilis 1.17.x atau yang lebih rendah.

    Sebelum mengupgrade cert-manager ke 1.18 atau 1.19, gunakan prosedur langkah-langkah berikut untuk mengedit sertifikat apigee-ca Anda guna menetapkan nilai Certificate.Spec.PrivateKey.rotationPolicy ke Never.

    1. Periksa konten sertifikat apigee-ca Anda untuk melihat apakah rotationPolicy telah ditetapkan: 
      kubectl get certificate apigee-ca -n cert-manager -o yaml

      Cari nilai di bagian spec.privateKey dalam output:

      ...
spec:
  commonName: apigee-hybrid
  duration: 87600h
  isCA: true
  issuerRef:
    group: cert-manager.io
    kind: ClusterIssuer
    name: apigee-root-certificate-issuer
  privateKey:
    algorithm: ECDSA
    # Note: rotationPolicy would appear here if it is set.
    size: 256
  secretName: apigee-ca
...
    2. Jika rotationPolicy tidak ditetapkan atau jika ditetapkan ke Always, edit sertifikat apigee-ca untuk menetapkan nilai rotationPolicy ke Never:
      1. Lakukan uji coba terlebih dahulu: 
        kubectl patch Certificate \
  --dry-run=server \
  -n cert-manager \
  --type=json \
  -p='[{"op": "replace", "path": "/spec/privateKey/rotationPolicy", "value": "Never"}]' \
  -o=yaml \
  apigee-ca
      2. Patch sertifikat: 
        kubectl patch Certificate \
  -n cert-manager \
  --type=json \
  -p='[{"op": "replace", "path": "/spec/privateKey/rotationPolicy", "value": "Never"}]' \
  -o=yaml \
  apigee-ca
    3. Pastikan nilai rotationPolicy sekarang ditetapkan ke Never: 
      kubectl get certificate apigee-ca -n cert-manager -o yaml

      Output-nya akan terlihat seperti berikut:

      ...
spec:
  commonName: apigee-hybrid
  duration: 87600h
  isCA: true
  issuerRef:
    group: cert-manager.io
    kind: ClusterIssuer
    name: apigee-root-certificate-issuer
  privateKey:
    algorithm: ECDSA
    rotationPolicy: Never
    size: 256
  secretName: apigee-ca
...
    4. Mengupgrade cert-manager. Perintah berikut akan mendownload dan menginstal cert-manager v1.19.2: 
      kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.19.2/cert-manager.yaml

      Lihat Platform dan versi yang didukung: cert-manager untuk mengetahui daftar versi yang didukung.

    Lihat:

    Menginstal runtime hybrid 1.17.3

    1. Jika belum, buka direktori APIGEE_HELM_CHARTS_HOME Anda. Jalankan perintah berikut dari direktori tersebut.
    2. Upgrade Operator/Pengontrol Apigee:

      Uji coba:

      helm upgrade operator apigee-operator/ \
  --install \
  --namespace APIGEE_NAMESPACE \
  -f OVERRIDES_FILE \
  --dry-run=server

      Upgrade diagram:

      helm upgrade operator apigee-operator/ \
  --install \
  --namespace APIGEE_NAMESPACE \
  -f OVERRIDES_FILE

      Verifikasi penginstalan Operator Apigee:

      helm ls -n APIGEE_NAMESPACE

      NAME       NAMESPACE       REVISION   UPDATED                                STATUS     CHART                   APP VERSION
operator   apigee   3          2024-08-21 00:42:44.492009 -0800 PST   deployed   apigee-operator-1.17.3   1.17.3

      Pastikan layanan ini aktif dan berjalan dengan memeriksa ketersediaannya:

      kubectl -n APIGEE_NAMESPACE get deploy apigee-controller-manager

      NAME                        READY   UP-TO-DATE   AVAILABLE   AGE
apigee-controller-manager   1/1     1            1           7d20h
    3. Upgrade datastore Apigee:

      Uji coba:

      helm upgrade datastore apigee-datastore/ \
  --install \
  --namespace APIGEE_NAMESPACE \
  -f OVERRIDES_FILE \
  --dry-run=server

      Upgrade diagram:

      helm upgrade datastore apigee-datastore/ \
  --install \
  --namespace APIGEE_NAMESPACE \
  -f OVERRIDES_FILE

      Pastikan apigeedatastore aktif dan berjalan dengan memeriksa statusnya:

      kubectl -n APIGEE_NAMESPACE get apigeedatastore default

      NAME      STATE       AGE
default   running    2d
    4. Mengupgrade telemetri Apigee:

      Uji coba:

      helm upgrade telemetry apigee-telemetry/ \
  --install \
  --namespace APIGEE_NAMESPACE \
  -f OVERRIDES_FILE \
  --dry-run=server

      Upgrade diagram:

      helm upgrade telemetry apigee-telemetry/ \
  --install \
  --namespace APIGEE_NAMESPACE \
  -f OVERRIDES_FILE

      Pastikan cluster aktif dan berjalan dengan memeriksa statusnya:

      kubectl -n APIGEE_NAMESPACE get apigeetelemetry apigee-telemetry

      NAME               STATE     AGE
apigee-telemetry   running   2d
    5. Upgrade Apigee Redis:

      Uji coba:

      helm upgrade redis apigee-redis/ \
  --install \
  --namespace APIGEE_NAMESPACE \
  -f OVERRIDES_FILE \
  --dry-run=server

      Upgrade diagram:

      helm upgrade redis apigee-redis/ \
  --install \
  --namespace APIGEE_NAMESPACE \
  -f OVERRIDES_FILE

      Pastikan cluster aktif dan berjalan dengan memeriksa statusnya:

      kubectl -n APIGEE_NAMESPACE get apigeeredis default

      NAME      STATE     AGE
default   running   2d
    6. Upgrade pengelola ingress Apigee:

      Uji coba:

      helm upgrade ingress-manager apigee-ingress-manager/ \
  --install \
  --namespace APIGEE_NAMESPACE \
  -f OVERRIDES_FILE \
  --dry-run=server

      Upgrade diagram:

      helm upgrade ingress-manager apigee-ingress-manager/ \
  --install \
  --namespace APIGEE_NAMESPACE \
  -f OVERRIDES_FILE

      Pastikan layanan ini aktif dan berjalan dengan memeriksa ketersediaannya:

      kubectl -n APIGEE_NAMESPACE get deployment apigee-ingressgateway-manager

      NAME                            READY   UP-TO-DATE   AVAILABLE   AGE
apigee-ingressgateway-manager   2/2     2            2           2d
    7. Upgrade organisasi Apigee:

      Uji coba:

      helm upgrade ORG_NAME apigee-org/ \
  --install \
  --namespace APIGEE_NAMESPACE \
  -f OVERRIDES_FILE \
  --dry-run=server

      Upgrade diagram:

      helm upgrade ORG_NAME apigee-org/ \
  --install \
  --namespace APIGEE_NAMESPACE \
  -f OVERRIDES_FILE

      Pastikan instance tersebut aktif dan berjalan dengan memeriksa status organisasi yang bersangkutan:

      kubectl -n APIGEE_NAMESPACE get apigeeorg

      NAME                      STATE     AGE
apigee-my-org-my-env      running   2d
    8. Mengupgrade lingkungan.

      Anda harus menginstal satu lingkungan dalam satu waktu. Tentukan lingkungan dengan --set env=ENV_NAME.

      Uji coba:

      helm upgrade ENV_RELEASE_NAME apigee-env/ \
  --install \
  --namespace APIGEE_NAMESPACE \
  --set env=ENV_NAME \
  -f OVERRIDES_FILE \
  --dry-run=server
      • ENV_RELEASE_NAME adalah nama yang digunakan untuk melacak penginstalan dan upgrade diagram apigee-env. Nama ini harus unik dari nama rilis Helm lainnya dalam penginstalan Anda. Biasanya, ini sama dengan ENV_NAME. Namun, jika lingkungan Anda memiliki nama yang sama dengan grup lingkungan, Anda harus menggunakan nama rilis yang berbeda untuk lingkungan dan grup lingkungan, misalnya dev-env-release dan dev-envgroup-release. Untuk mengetahui informasi selengkapnya tentang rilis di Helm, lihat Tiga konsep besar dalam dokumentasi Helm.
      • ENV_NAME adalah nama lingkungan yang Anda upgrade.
      • OVERRIDES_FILE adalah file penggantian baru Anda untuk v.1.17.3

      Upgrade diagram:

      helm upgrade ENV_RELEASE_NAME apigee-env/ \
  --install \
  --namespace APIGEE_NAMESPACE \
  --set env=ENV_NAME \
  -f OVERRIDES_FILE

      Pastikan lingkungan tersebut aktif dan berjalan dengan memeriksa status lingkungan yang bersangkutan:

      kubectl -n APIGEE_NAMESPACE get apigeeenv

      NAME                          STATE       AGE   GATEWAYTYPE
apigee-my-org-my-env          running     2d
    9. Upgrade grup lingkungan (virtualhosts).
      1. Anda harus mengupgrade grup lingkungan (virtualhost) satu per satu. Tentukan grup lingkungan dengan --set envgroup=ENV_GROUP_NAME. Ulangi perintah berikut untuk setiap grup lingkungan yang disebutkan dalam file overrides.yaml:

        Uji coba:

        helm upgrade ENV_GROUP_RELEASE_NAME apigee-virtualhost/ \
  --install \
  --namespace APIGEE_NAMESPACE \
  --set envgroup=ENV_GROUP_NAME \
  -f OVERRIDES_FILE \
  --dry-run=server

        ENV_GROUP_RELEASE_NAME adalah nama yang Anda gunakan untuk menginstal diagram apigee-virtualhost sebelumnya. Biasanya, nilainya adalah ENV_GROUP_NAME.

        Upgrade diagram:

        helm upgrade ENV_GROUP_RELEASE_NAME apigee-virtualhost/ \
  --install \
  --namespace APIGEE_NAMESPACE \
  --set envgroup=ENV_GROUP_NAME \
  -f OVERRIDES_FILE
      2. Periksa status ApigeeRoute (AR).

        Menginstal virtualhosts akan membuat ApigeeRouteConfig (ARC) yang secara internal membuat ApigeeRoute (AR) setelah watcher Apigee mengambil detail terkait grup lingkungan dari bidang kontrol. Oleh karena itu, pastikan status AR yang sesuai sedang berjalan: 

        kubectl -n APIGEE_NAMESPACE get arc

        NAME                                STATE   AGE
apigee-org1-dev-egroup                       2d
         
        kubectl -n APIGEE_NAMESPACE get ar

        NAME                                        STATE     AGE
apigee-org1-dev-egroup-123abc               running   2d

    Melakukan roll back ke versi sebelumnya

    Untuk melakukan rollback ke versi sebelumnya, gunakan versi chart yang lebih lama untuk melakukan rollback proses upgrade dalam urutan terbalik. Mulai dengan apigee-virtualhost dan lanjutkan kembali ke apigee-operator, lalu kembalikan CRD.

    1. Mengembalikan diagram. Perintah berikut mengasumsikan bahwa Anda menggunakan chart dari versi sebelumnya (v1.16.x).

      1. Jalankan perintah berikut untuk setiap grup lingkungan:

        helm upgrade ENV_GROUP_RELEASE_NAME apigee-virtualhost/ \
  --install \
  --namespace APIGEE_NAMESPACE \
  --atomic \
  --set envgroup=ENV_GROUP_NAME \
  -f 1.16_OVERRIDES_FILE

      2. Jalankan perintah berikut untuk setiap lingkungan:

        helm upgrade ENV_RELEASE_NAME apigee-env/ \
  --install \
  --namespace APIGEE_NAMESPACE \
  --atomic \
  --set env=ENV_NAME \
  -f 1.16_OVERRIDES_FILE

      3. apigee-org:

        helm upgrade ORG_NAME apigee-org/ \
  --install \
  --namespace APIGEE_NAMESPACE \
  --atomic \
  -f 1.16_OVERRIDES_FILE

      4. apigee-ingress-manager:

        helm upgrade ingress-manager apigee-ingress-manager/ \
  --install \
  --namespace APIGEE_NAMESPACE \
  --atomic \
  -f 1.16_OVERRIDES_FILE

      5. apigee-redis:

        helm upgrade redis apigee-redis/ \
  --install \
  --namespace APIGEE_NAMESPACE \
  --atomic \
  -f 1.16_OVERRIDES_FILE

      6. apigee-telemetry:

        helm upgrade telemetry apigee-telemetry/ \
  --install \
  --namespace APIGEE_NAMESPACE \
  --atomic \
  -f 1.16_OVERRIDES_FILE

      7. apigee-datastore:

        helm upgrade datastore apigee-datastore/ \
  --install \
  --namespace APIGEE_NAMESPACE \
  --atomic \
  -f 1.16_OVERRIDES_FILE

      8. apigee-operator:

        helm upgrade operator apigee-operator/ \
  --install \
  --namespace APIGEE_NAMESPACE \
  --atomic \
  -f 1.16_OVERRIDES_FILE
    2. Kembalikan CRD dengan menginstal ulang CRD yang lebih lama. 
      kubectl apply -k apigee-operator/etc/crds/default/ \
  --server-side \
  --force-conflicts \
  --validate=false