Mengupgrade Apigee Hybrid ke versi 1.17

Prosedur ini mencakup upgrade dari Apigee Hybrid versi 1.16.x ke Apigee Hybrid versi 1.17.0.

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 saat mengelola API Anda yang lain, sehingga Anda tidak perlu menjalankan atau memelihara server MCP sendiri. Untuk mengetahui informasi selengkapnya, lihat Model Context Protocol (MCP) dalam ringkasan Apigee dan panduan memulai MCP.
  • Rotasi sertifikat CA root: Apigee Hybrid versi 1.17 menambahkan dukungan untuk merotasi sertifikat Certificate Authority (CA) root yang menjadi dasar kepercayaan untuk komunikasi TLS antara komponen runtime Anda. Anda kini dapat mengganti CA root sebelum masa berlakunya berakhir, tanpa periode nonaktif, dengan mengikuti prosedur rotasi bertahap. Untuk mengetahui informasi selengkapnya, lihat Memutar sertifikat CA root.
  • 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 mengetahui informasi selengkapnya, lihat Mengonfigurasi penerusan proxy untuk proxy API.
  • Dukungan endpoint Private Service Connect (PSC) cache semantik: Apigee Hybrid versi 1.17 menambahkan dukungan endpoint Private Service Connect (PSC) untuk cache 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 informasi selengkapnya, lihat Mulai menggunakan kebijakan penyimpanan cache semantik.

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

Prasyarat

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

Sebelum mengupgrade ke 1.17.0 - batasan dan catatan penting

  • Mengupgrade ke Apigee Hybrid versi 1.17 mungkin memerlukan waktu non-operasional.

    Saat mengupgrade pengontrol Apigee ke versi 1.17.0, semua deployment Apigee akan mengalami mulai ulang bertahap. Untuk meminimalkan periode nonaktif di lingkungan hybrid produksi selama memulai ulang bertahap, pastikan Anda menjalankan minimal dua cluster (di region/pusat data yang sama atau berbeda). Alihkan semua traffic produksi ke satu cluster dan nonaktifkan cluster yang akan diupgrade, lalu lanjutkan proses upgrade. Ulangi proses untuk setiap cluster.

    Apigee merekomendasikan agar setelah Anda 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. Penangguhan sementara yang diperlukan untuk perubahan bidang pengelolaan dicantumkan dalam petunjuk upgrade di bawah.

Ringkasan upgrade ke versi 1.17.0

Prosedur untuk mengupgrade Apigee Hybrid diatur dalam bagian berikut:

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

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 1.16 $APIGEE_HELM_CHARTS_HOME/ versi Anda. Anda dapat menggunakan proses pencadangan apa pun. Misalnya, Anda dapat membuat file tar dari seluruh direktori Anda 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 sertifikat dan kunci 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 Anda memerlukan bantuan.

Tarik 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 diagram 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.0
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. Pada rilis cert-manager 1.18, nilai default Certificate.Spec.PrivateKey.rotationPolicy diubah dari Never menjadi Always. Untuk penginstalan Apigee hybrid 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 mengompensasi 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 untuk melihat apakah rotationPolicy disetel: 
      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. Verifikasi bahwa nilai rotationPolicy sekarang disetel 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. Upgrade 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.0

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

      Uji coba:

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

      Mengupgrade diagram:

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

      Verifikasi penginstalan Apigee Operator:

      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.0   1.17.0

      Verifikasi bahwa instance sudah 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

      Mengupgrade diagram:

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

      Pastikan apigeedatastore sudah 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

      Mengupgrade diagram:

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

      Pastikan instance 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

      Mengupgrade diagram:

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

      Pastikan instance 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

      Mengupgrade diagram:

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

      Verifikasi bahwa instance sudah 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

      Mengupgrade diagram:

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

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

      kubectl -n APIGEE_NAMESPACE get apigeeorg

      NAME                      STATE     AGE
apigee-my-org-my-env      running   2d
    8. Upgrade 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 di 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 penting di dokumentasi Helm.
      • ENV_NAME adalah nama lingkungan yang Anda upgrade.
      • OVERRIDES_FILE adalah file penggantian baru Anda untuk v.1.17.0

      Mengupgrade diagram:

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

      Pastikan instance berjalan dengan memeriksa status env masing-masing:

      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 satu grup lingkungan (virtualhost) dalam satu waktu. 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 sebelumnya untuk menginstal diagram apigee-virtualhost. Biasanya ENV_GROUP_NAME.

        Mengupgrade 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 membuat ApigeeRouteConfig (ARC) yang secara internal membuat ApigeeRoute (AR) setelah watcher Apigee menarik detail terkait grup lingkungan dari bidang kontrol. Oleh karena itu, periksa apakah 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

    Mengembalikan ke versi sebelumnya

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

    1. Kembalikan diagram. Perintah berikut mengasumsikan bahwa Anda menggunakan diagram 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