Schritt 2: Installationsverzeichnis neu konfigurieren
Ermitteln Sie das Basisinstallationsverzeichnis, das bei der ursprünglichen Installation von Apigee Hybrid erstellt wurde. Das Basisverzeichnis ist das Verzeichnis, in dem sich das Verzeichnis $APIGEEGTL_HOME befindet.
Im folgenden Beispiel ist das Basisverzeichnis /Users/myhome/hybrid:
Extrahieren Sie die heruntergeladenen gzip-Dateiinhalte in das Apigee Hybrid-Basisverzeichnis:
tar xvzf filename.tar.gz -C path-to-base-directory
cd zum Basisverzeichnis.
Die TAR-Inhalte werden standardmäßig in ein Verzeichnis mit der Version und der Plattform in ihrem Namen erweitert. Beispiel: ./apigeectl_1.2.0-f7b96a8_linux_64.
Benennen Sie das aktuelle apigeectl-Verzeichnis um. Wenn die aktuelle Version beispielsweise 1.1.1 ist, benennen Sie das Verzeichnis apigeectl in apigeectl_1.1.1 um.
Benennen Sie das neu extrahierte Installationsverzeichnis in apigeectl um. Hier verweist die Umgebung $APIGEECTL_HOME auf diese Umgebung.
Schritt 3: Überschreibungsdatei aktualisieren
Erstellen Sie eine Kopie Ihrer Überschreibungsdatei und speichern Sie die alte Datei unbedingt, falls Sie später ein Rollback durchführen müssen. In den folgenden Schritten nehmen Sie die erforderlichen Änderungen an der Überschreibungsdatei vor, bevor Sie sie auf den Cluster anwenden.
Aktualisieren Sie die Überschreibungsdatei mit den unten beschriebenen Änderungen:
Im Folgenden finden Sie eine Zusammenfassung der Konfigurationsänderungen, die Sie an Ihrer Überschreibungen-Datei vornehmen müssen. Ein vollständiges Beispiel finden Sie in der Tabelle nach der Zusammenfassung. Wie Sie sehen, hat sich das Attribut envs[] im Vergleich zu früheren Versionen deutlich geändert:
Das Attribut envs[].hostAlias wurde entfernt und durch das neue Attribut virtualhosts.hostAliases[] ersetzt.
Sie müssen das neue erforderliche Konfigurationsattribut virtualhosts hinzufügen.
Sie müssen die Attribute envs[].sslCertPath und envs[].sslKeyPath von envs in virtualhosts verschieben.
Sie müssen die virtualhosts.routingRules-Konfigurations-Stanza hinzufügen.
Das Attribut virtualhosts.routingRules ersetzt das vorherige Attribut envs[].paths. Wenn Ihre Überschreibungsdatei envs[].paths enthalten, müssen Sie sie entfernen. Weitere Informationen zur Konfiguration des virtuellen Hosts finden Sie unter Virtuelle Hosts konfigurieren.
Die folgende Tabelle zeigt die Unterschiede zwischen einer 1.1.1-Überschreibungsdatei und einer Version 1.2.0-Datei. In diesem Beispiel werden die Änderungen hervorgehoben, die Sie für Version 1.2.0 vornehmen müssen:
Wenn Sie Apigee Connect in der Version 1.1.1-Installation aktiviert haben, müssen Sie das Deployment entfernen:
Listen Sie zuerst die Apigee-Deployments auf:
kubectl -n namespace get ad
Löschen Sie das Apigee Connect-Deployment:
kubectl -n namespace delete ad apigee-connect-name
Listen Sie die Pods auf:
kubectl get pods -n namespace
Löschen Sie den Pod apigee-cps-setup aus dem Cluster. Verwenden Sie den vollständigen Namen des Pods, der den Namen Ihrer Organisation enthält, wie im vorherigen Befehl zurückgegeben. Beispiel:
kubectl -n namespace delete pod apigee-cps-setup-org
Löschen Sie den Pod apigee-cps-create-user im selben Namespace:
kubectl -n namespace delete pod apigee-cps-create-user
Bereinigen Sie abgeschlossene Jobs für den Namespace der Hybridlaufzeit. Dabei ist namespace der Namespace, der in der Überschreibungsdatei angegeben ist, wenn Sie einen Namespace angegeben haben. Wenn nicht, ist der Standard-Namespace apigee:
Wenn check-ready mit "Alle Container sind bereit" antwortet, können Sie eine "Probelauf"-Installation durchführen.
Führen Sie den Befehl apply mit dem Flag --dry-run=true aus. Mit einem Probelauf können Sie auf Fehler prüfen, bevor Änderungen am Cluster vorgenommen werden:
Führen Sie check-ready noch einmal aus, um zu ermitteln, wann das Upgrade abgeschlossen ist.
Rollback für Upgrade durchführen
So führen Sie ein Rollback für ein Upgrade durch:
Bereinigen Sie abgeschlossene Jobs für den Namespace der Hybridlaufzeit. Dabei ist namespace der Namespace, der in der Überschreibungsdatei angegeben ist, wenn Sie einen Namespace angegeben haben. Wenn nicht, ist der Standard-Namespace apigee:
Führen Sie im Stammverzeichnis der Installation, zu der Sie ein Rollback durchführen möchten, apigeectl init und dann apigeectl apply aus. Achten Sie darauf, die Original-Überschreibungsdatei für die Version zu verwenden, für die Sie ein Rollback durchführen möchten:
[[["Leicht verständlich","easyToUnderstand","thumb-up"],["Mein Problem wurde gelöst","solvedMyProblem","thumb-up"],["Sonstiges","otherUp","thumb-up"]],[["Schwer verständlich","hardToUnderstand","thumb-down"],["Informationen oder Beispielcode falsch","incorrectInformationOrSampleCode","thumb-down"],["Benötigte Informationen/Beispiele nicht gefunden","missingTheInformationSamplesINeed","thumb-down"],["Problem mit der Übersetzung","translationIssue","thumb-down"],["Sonstiges","otherDown","thumb-down"]],["Zuletzt aktualisiert: 2025-08-28 (UTC)."],[[["\u003cp\u003eVersion 1.2 of the Apigee hybrid documentation is end-of-life and should be upgraded to a newer version, as version 1.0.0 is not backward compatible with later versions and requires a new installation for upgrade.\u003c/p\u003e\n"],["\u003cp\u003eUpgrading to version 1.2.0 involves upgrading your Kubernetes platform, downloading the release package for your operating system, reconfiguring the installation directory, and updating your overrides file with new properties such as \u003ccode\u003evirtualhosts\u003c/code\u003e and \u003ccode\u003eroutingRules\u003c/code\u003e.\u003c/p\u003e\n"],["\u003cp\u003eTo apply the upgrade to the cluster, certain steps must be followed, including removing the Apigee Connect deployment if it exists, deleting specific pods (\u003ccode\u003eapigee-cps-setup\u003c/code\u003e and \u003ccode\u003eapigee-cps-create-user\u003c/code\u003e), cleaning up completed jobs in several namespaces, initializing \u003ccode\u003eapigeectl\u003c/code\u003e, and applying the changes with a dry run first.\u003c/p\u003e\n"],["\u003cp\u003eRolling back an upgrade involves cleaning up completed jobs from previous namespaces, deleting the Apigee Operators deployment, and then switching \u003ccode\u003e$APIGEECTL_HOME\u003c/code\u003e to the original version to re-initialize and apply the old overrides.\u003c/p\u003e\n"]]],[],null,["# Upgrading Apigee hybrid\n\n| You are currently viewing version 1.2 of the Apigee hybrid documentation. **This version is end of life.** You should upgrade to a newer version. For more information, see [Supported versions](/apigee/docs/hybrid/supported-platforms#supported-versions).\n| You cannot upgrade from 1.0.0 to any later versions, because they are not backward compatible with Version 1.0.0. If you are using Version 1.0.0 and wish to upgrade, you must perform a new installation.\n\nUpgrading to version 1.2.0\n--------------------------\n\n\nFollow these steps to upgrade Apigee hybrid to version 1.2.0:\n\n### Step 1: Upgrade Kubernetes and download the release package\n\n1. Upgrade your Kubernetes platform as follows. Follow your platform's documentation if you need help:\n\n2. Download the release package for your operating system:\n\n **Mac 64 bit:** \n\n ```\n curl -LO \\\n https://storage.googleapis.com/apigee-release/hybrid/apigee-hybrid-setup/1.2.0/apigeectl_mac_64.tar.gz\n ```\n\n **Linux 64 bit** \n\n ```\n curl -LO \\\n https://storage.googleapis.com/apigee-release/hybrid/apigee-hybrid-setup/1.2.0/apigeectl_linux_64.tar.gz\n ```\n\n **Mac 32 bit:** \n\n ```\n curl -LO \\\n https://storage.googleapis.com/apigee-release/hybrid/apigee-hybrid-setup/1.2.0/apigeectl_mac_32.tar.gz\n ```\n\n **Linux 32 bit** \n\n ```\n curl -LO \\\n https://storage.googleapis.com/apigee-release/hybrid/apigee-hybrid-setup/1.2.0/apigeectl_linux_32.tar.gz\n ```\n\n### Step 2: Reconfigure your installation directory\n\n1. Identify the base installation directory that was created when Apigee hybrid was [originally installed](/apigee/docs/hybrid/v1.2/install-download-install). The base directory is the directory in which the `$APIGEEGTL_HOME` directory resides. In the following example, the base directory is `/Users/myhome/hybrid`: \n\n ```\n echo $APIGEECTL_HOME\n /Users/myhome/hybrid/apigeectl\n ```\n2. Extract the downloaded gzip file contents into the Apigee hybrid base directory:\n\n ```\n tar xvzf filename.tar.gz -C path-to-base-directory\n ```\n3. `cd` to the base directory.\n4. The tar contents are, by default, expanded into a directory with the version and\n platform in its name. For example: `./apigeectl_1.2.0-f7b96a8_linux_64`.\n\n5. Rename the current `apigeectl` directory. For example, if the current version is 1.1.1, rename the `apigeectl` directory to `apigeectl_1.1.1`.\n6. Rename the newly extracted installation directory to `apigeectl`. This is now where the environment `$APIGEECTL_HOME` points to.\n\n### Step 3: Update your overrides file\n\n1. Make a copy of your overrides file, and be careful to save the old file in case you ever need to roll back. In the following steps, you will make required changes to the overrides file before applying it to the cluster. **NOTE:**To upgrade to version 1.2.0, you must make changes in your overrides file that are incompatible with previous versions. The override file changes described in the next step are required.\n2. Update your overrides file with the changes described below:\n\n Following is a **summary** of the\n configuration changes you must make to your overrides file. A complete example is given\n in the table following the summary. As you will see, the `envs[]`\n property has changed significantly from previous versions:\n - The property `envs[].hostAlias` has been removed and replaced by the new property `virtualhosts.hostAliases[]`. **NOTE:** If you used a single wildcard '\\*' for the environment host alias in a previous version, in version 1.2.0 you MUST use either a fully qualified DNS name or a subdomain wildcard in the virtual host alias configuration. For example: `*.mydomain.com`. The single wildcard character configuration `hostAliases['*']` is no longer supported.\n - You must add the new required configuration property `virtualhosts`.\n - You must move the `envs[].sslCertPath` and `envs[].sslKeyPath` properties from `envs` to `virtualhosts`.\n - You must add the `virtualhosts.routingRules` configuration stanza. The `virtualhosts.routingRules` property replaces the previous `envs[].paths` property. If you have `envs[].paths` in your overrides file, you must remove it. For more information on the virtual host configuration, see [Configure virtual hosts](/apigee/docs/hybrid/v1.2/base-path-routing).\n\n\n The table below illustrates the differences between a 1.1.1 overrides file and a version\n 1.2.0 file. The example is intended to highlight the kinds of changes you need to make for\n version 1.2.0:\n | **NOTE:** The code shown is for example purposes only.\n\n | **NOTE:** If you do not specify `envs[].paths` (as shown in the table above), you can omit the `virtualhosts[].routingRules.paths[]` property in the upgrade. By default, the path is \"/\". For example, if you want to use the default path of \"/\", you can configure the `virtualhosts[].routingRules` like this: \n |\n | ```text\n | virtualhosts:\n | - name: default\n | hostAliases: [\"api.example.com\"]\n | sslCertPath: ./certs/fullchain.pem\n | sslKeyPath: ./certs/privkey.pem\n | routingRules:\n | - env: test1\n | - name: prod\n | hostAliases: [\"api.example.com\"]\n | sslCertPath: ./certs/fullchain.pem\n | sslKeyPath: ./certs/privkey.pem\n | routingRules:\n | - env: test2\n | ```\n\n### Step 4: Apply the upgrade to the cluster\n\n1. If you enabled Apigee Connect in your version 1.1.1 installation, you must remove the deployment:\n 1. First, list the Apigee Deployments: \n\n ```\n kubectl -n namespace get ad\n ```\n 2. Delete the Apigee Connect deployment: \n\n ```\n kubectl -n namespace delete ad apigee-connect-name\n ```\n2. List the pods: \n\n ```\n kubectl get pods -n namespace\n ```\n3. Delete the `apigee-cps-setup` pod from the cluster. Use the pod's full name, which includes your organization name, as returned in the previous command. For example: \n\n ```\n kubectl -n namespace delete pod apigee-cps-setup-org\n ```\n4. Delete the `apigee-cps-create-user` pod in the same namespace: \n\n ```\n kubectl -n namespace delete pod apigee-cps-create-user\n ```\n5. Clean up completed jobs for the hybrid runtime namespace, where \u003cvar translate=\"no\"\u003enamespace\u003c/var\u003e is the namespace specified in your overrides file, if you specified a namespace. If not, the default namespace is `apigee`: \n\n ```\n kubectl delete job -n namespace \\\n $(kubectl get job -n namespace -o=jsonpath='{.items[?(@.status.succeeded==1)].metadata.name}')\n ```\n6. Clean up completed jobs for the `apigee-system` namespace: \n\n ```\n kubectl delete job -n apigee-system \\\n $(kubectl get job -n apigee-system -o=jsonpath='{.items[?(@.status.succeeded==1)].metadata.name}')\n ```\n7. Clean up completed jobs for the `istio-system` namespace: \n\n ```\n kubectl delete job -n istio-system \\\n $(kubectl get job -n istio-system -o=jsonpath='{.items[?(@.status.succeeded==1)].metadata.name}')\n ```\n8. `cd` to the `./hybrid-files` directory:\n9. Initialize `apigeectl` for the new version: \n\n ```\n $APIGEECTL_HOME/apigeectl init -f overrides/overrides-file.yaml\n ```\n10. Check to determine when the initialization is complete: \n\n ```\n $APIGEECTL_HOME/apigeectl check-ready -f overrides/overrides-file.yaml\n ```\n11. When `check-ready` replies with \"All containers are ready\", you can try a \"dry run\" install. Execute the `apply` command with the `--dry-run=true` flag. Doing a dry run lets you check for any errors before any changes are made to the cluster: \n\n ```\n $APIGEECTL_HOME/apigeectl apply -f overrides/overrides-file.yaml --dry-run=true\n ```\n12. If there are no errors, you can apply the [Apigee-specific\n runtime components](/apigee/docs/hybrid/v1.2/what-is-hybrid#about-the-runtime-plane) to the cluster: \n\n ```\n $APIGEECTL_HOME/apigeectl apply -f overrides/overrides-file.yaml\n ```\n13. Re-run `check-ready` to determine when the upgrade is complete.\n\nRolling back an upgrade\n-----------------------\n\n\nFollow these steps to roll back a previous upgrade:\n\n1. Clean up completed jobs for the hybrid runtime namespace, where \u003cvar translate=\"no\"\u003enamespace\u003c/var\u003e is the namespace specified in your overrides file, if you specified a namespace. If not, the default namespace is `apigee`: \n\n ```\n kubectl delete job -n namespace \\\n $(kubectl get job -n namespace -o=jsonpath='{.items[?(@.status.succeeded==1)].metadata.name}')\n ```\n2. Clean up completed jobs for the `apigee-system` namespace: \n\n ```\n kubectl delete job -n apigee-system \\\n $(kubectl get job -n apigee-system -o=jsonpath='{.items[?(@.status.succeeded==1)].metadata.name}')\n ```\n3. Clean up completed jobs for the `istio-system` namespace: \n\n ```\n kubectl delete job -n istio-system \\\n $(kubectl get job -n istio-system -o=jsonpath='{.items[?(@.status.succeeded==1)].metadata.name}')\n ```\n4. Delete the Apigee Operators deployment. This operation will not have any effect on your runtime traffic: \n\n ```\n kubectl -n apigee-system delete deployment apigee-controller-manager\n ```\n5. Change the `$APIGEECTL_HOME` variable to point to the directory that contains the original version of `apigeectl`. For example: \n\n ```\n export APIGEECTL_HOME=path-to-original-apigeectl-directory\n ```\n6. In the root directory of the installation you want to roll back to, run `apigeectl init` and then run `apigeectl apply`. Be sure to use the original overrides file for the version you wish to roll back to: \n\n `$APIGEECTL_HOME`/apigeectl init -f overrides/\u003cvar translate=\"no\"\u003eoriginal-overrides\u003c/var\u003e.yaml\n `$APIGEECTL_HOME`/apigeectl apply -f overrides/\u003cvar translate=\"no\"\u003eoriginal-overrides\u003c/var\u003e.yaml"]]
