This page describes how to migrate an Apigee hybrid org from one
Kubernetes cluster to another. Some cases in which you might need to migrate
an org to another cluster are the following:
The data center hosting the existing cluster has no more capacity, or is
being decommissioned.
The cluster is running old infrastructure or an old version of Kubernetes, and you
want to migrate to a cluster with newer infrastructure.
You want to move orgs from multi-org clusters into separate clusters.
Note that there are risks and limitations when migrating an org to another hybrid cluster.
Read the details in the Limitations
section before performing a migration.
Limitations
The following limitations apply when migrating a hybrid org to another Kubernetes cluster:
There is a risk of data loss when moving org data to a new Kubernetes cluster.
You should back up the data for all orgs in the Kubernetes cluster, using the
hybrid backup
instructions, before migrating an org.
The maximum data size supported for org migration is 5GB across all keyspaces of an org,
excluding cache and quota.
Cache data will not be migrated. Hybrid rebuilds cache data.
Quota data will not be migrated. Hybrid resets quota data.
You can only migrate orgs to a Kubernetes cluster that contains no existing
hybrid deployment.
Migrating to a cluster with an existing hybrid deployment is not supported.
The org being migrated can only be moved to a new cluster with a single region deployment.
After the single region deployment is up and running, you can follow the region
expansion process, described in Multi-region
deployment, to expand to other regions.
The Cassandra cluster should be operating in good health across all regions.
Migrating an org
Follow the instructions below to migrate a hybrid org from one Kubernetes cluster to another:
If not already enabled, enable backups on the Kubernetes cluster containing the hybrid org
to be migrated. See
Cassandra backup overview
for information on hybrid backups.
Start a hybrid backup job using the following command:
The <backup job name> can be any valid container name.
Once the backup job is completed, use the instructions in the following sections of
Monitoring
backups to verify that the backup has successfully completed:
"Check the status of the backup job"
"Check the backup logs"
After verifying that the backup was successful, make a note of the ID number at the end
of the backup log.
For example, a successful backup log should contain a line like the following:
INFO: completed upload for 20230207004250
Make a note of the multi-digit number at the end of the line. You will need this number later.
Switch the Kubernetes context to the destination Kubernetes cluster:
where <destination cluster name> is the name of the destination Kubernetes
cluster.
Restore the backup data into the destination Kubernetes cluster using the instructions in
Restoring in a single region.
Use the overrides.yaml file for the org that is being migrated to the destination hybrid
deployment.
Remember to set the restore:snapshotTimestamp value to the multi-digit
number shown by the backup log in step 4. See
Restoring in a single region.
Once the restoration is complete, delete any org data, other than the data for the org being
migrated, from the destination Kubernetes cluster. Hybrid backup files contain the data for all
orgs, including ones you may not want to migrate. After the destination hybrid
deployment is restored, you need to remove any extra org data that was copied to the
deployment, using the following steps:
Verify that the current context is the correct context for the destination Kubernetes cluster:
Several of the steps in the procedure described in the previous section require the name of
the migrated org. To get the migrated org name, do the following:
Get the org name from the org's overrides.yaml file. Make sure to check the
overrides.yaml file for the org being migrated.
If the org name contains any dashes "-", replace all dashes "-" with underscores "_".
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Hard to understand","hardToUnderstand","thumb-down"],["Incorrect information or sample code","incorrectInformationOrSampleCode","thumb-down"],["Missing the information/samples I need","missingTheInformationSamplesINeed","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-08-29 UTC."],[[["\u003cp\u003eThis documentation outlines the process for migrating an Apigee hybrid organization from one Kubernetes cluster to another, covering reasons such as data center changes, infrastructure upgrades, and separating multi-org clusters.\u003c/p\u003e\n"],["\u003cp\u003eMigrating an org to a new Kubernetes cluster carries risks, including potential data loss, therefore requiring a backup of all org data prior to the migration, using the hybrid backup instructions.\u003c/p\u003e\n"],["\u003cp\u003eLimitations exist, such as a 5GB data size limit for migration, the inability to migrate cache and quota data, and the requirement that the destination cluster must have no pre-existing hybrid deployments.\u003c/p\u003e\n"],["\u003cp\u003eThe migration process involves backing up data in the source cluster, restoring it in the destination cluster, and then removing any unintended data, ensuring that only the migrated org's data remains.\u003c/p\u003e\n"],["\u003cp\u003eOnce the migration to the destination cluster is complete, the migrated org needs to be deleted from the original source cluster, making sure all the relevant org data is also properly removed.\u003c/p\u003e\n"]]],[],null,["# Migrating an org to another cluster\n\n| You are currently viewing version 1.9 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\nThis page describes how to migrate an Apigee hybrid org from one\nKubernetes cluster to another. Some cases in which you might need to migrate\nan org to another cluster are the following:\n\n- The data center hosting the existing cluster has no more capacity, or is being decommissioned.\n- The cluster is running old infrastructure or an old version of Kubernetes, and you want to migrate to a cluster with newer infrastructure.\n- You want to move orgs from multi-org clusters into separate clusters.\n\nNote that there are risks and limitations when migrating an org to another hybrid cluster.\nRead the details in the [Limitations](#limitations)\nsection before performing a migration.\n\nLimitations\n-----------\n\nThe following limitations apply when migrating a hybrid org to another Kubernetes cluster:\n\n- There is a risk of data loss when moving org data to a new Kubernetes cluster. You should back up the data for all orgs in the Kubernetes cluster, using the [hybrid backup\n instructions](/apigee/docs/hybrid/v1.9/cassandra-backup-overview), before migrating an org.\n- The maximum data size supported for org migration is 5GB across all keyspaces of an org, excluding cache and quota.\n- Cache data will not be migrated. Hybrid rebuilds cache data.\n- Quota data will not be migrated. Hybrid resets quota data.\n- You can only migrate orgs to a Kubernetes cluster that contains no existing hybrid deployment. Migrating to a cluster with an existing hybrid deployment is not supported.\n- The org being migrated can only be moved to a new cluster with a single region deployment. After the single region deployment is up and running, you can follow the region expansion process, described in [Multi-region\n deployment](/apigee/docs/hybrid/v1.9/multi-region), to expand to other regions.\n- The Cassandra cluster should be operating in good health across all regions.\n\nMigrating an org\n----------------\n\nFollow the instructions below to migrate a hybrid org from one Kubernetes cluster to another:\n\n1. If not already enabled, enable backups on the Kubernetes cluster containing the hybrid org to be migrated. See [Cassandra backup overview](/apigee/docs/hybrid/v1.9/cassandra-backup-overview) for information on hybrid backups.\n2. Start a hybrid backup job using the following command: \n\n ```\n kubectl create job -n apigee --from=cronjob/apigee-cassandra-backup \u003cbackup job name\u003e\n ```\n\n The `\u003cbackup job name\u003e` can be any valid container name.\n3. Once the backup job is completed, use the instructions in the following sections of [Monitoring\n backups](/apigee/docs/hybrid/v1.9/monitor-cassandra-backups) to verify that the backup has successfully completed:\n - \"Check the status of the backup job\"\n - \"Check the backup logs\"\n4. After verifying that the backup was successful, make a note of the ID number at the end of the backup log. For example, a successful backup log should contain a line like the following: \n\n ```\n INFO: completed upload for 20230207004250\n ```\n Make a note of the multi-digit number at the end of the line. You will need this number later.\n5. Switch the Kubernetes context to the destination Kubernetes cluster: \n\n ```\n kubectl config use-context \u003cdestination cluster name\u003e # \u003cdestination cluster name\u003e\n ```\n\n where `\u003cdestination cluster name\u003e` is the name of the destination Kubernetes\n cluster.\n6. Restore the backup data into the destination Kubernetes cluster using the instructions in [Restoring in a single region](https://cloud.google.com/apigee/docs/hybrid/v1.9/restore-cassandra-single-region).\n - Use the overrides.yaml file for the org that is being migrated to the destination hybrid deployment.\n - Remember to set the `restore:snapshotTimestamp` value to the multi-digit number shown by the backup log in step 4. See [Restoring in a single region](https://cloud.google.com/apigee/docs/hybrid/v1.9/restore-cassandra-single-region).\n7. Once the restoration is complete, delete any org data, other than the data for the org being migrated, from the destination Kubernetes cluster. Hybrid backup files contain the data for all orgs, including ones you may not want to migrate. After the destination hybrid deployment is restored, you need to remove any extra org data that was copied to the deployment, using the following steps:\n 1. Verify that the current context is the correct context for the destination Kubernetes cluster: \n\n ```\n kubectl config current-context\n ```\n 2. Exec into the `apigee-cassandra-default-0` pod: \n\n ```\n kubectl exec -it -n apigee apigee-cassandra-default-0 -- /bin/bash\n ```\n 3. Execute the following command: \n\n ```\n find /opt/apigee/data/apigee-cassandra/ -iname '*_hybrid' -not -iname '*\u003cmigrated org name\u003e*' -type d -maxdepth 2 -printf \"%f\\n\"\n ```\n\n See [Get the name of the migrated org](#get-the-name-of-the-migrated-org)\n for instructions on finding `\u003cmigrated org name\u003e`.\n\n Copy the list of all names that are shown in the\n output. You will need this list in step 7. f.\n 4. Exit the `apigee-cassandra-default-0` pod.\n 5. Create a Cassandra debug client pod using the instructions in [Create a client container for debugging](/apigee/docs/api-platform/troubleshoot/playbooks/cassandra/ts-cassandra#create-a-client-container-for-debugging). Move on to the next step after getting a `cqlsh` prompt.\n 6. Execute the following commands in the `cqlsh` prompt:\n -\n\n ```\n desc keyspaces;\n ```\n\n Make sure this command returns no errors.\n - For each name in the list created in step 7. c., run the following command: \n\n ```\n drop keyspace \u003cname\u003e\n ```\n 7. Exit the Cassandra debug client pod.\n 8. After executing the `cqlsh` commands, run the following commands on all Cassandra pods in the destination Kubernetes cluster:\n -\n\n ```\n kubectl exec -it -n apigee -- /bin/bash\n ```\n -\n\n ```\n find /opt/apigee/data/apigee-cassandra/ -iname '*_hybrid' -not -iname '*\u003cmigrated org name\u003e*' -type d -maxdepth 2\n ```\n\n See [Get the name of the migrated org](#get-the-name-of-the-migrated-org)\n for instructions on finding `\u003cmigrated org name\u003e`.\n -\n\n ```\n find /opt/apigee/data/apigee-cassandra/ -iname '*_hybrid' -not -iname '**' -type d -maxdepth 2 -exec rm -rf {} +\n ```\n 9. Exit the Cassandra pod.\n8. Switch the Kubernetes context to the source Kubernetes cluster: \n\n ```\n kubectl config use-context \u003csource cluster name\u003e\n ```\n\n where `\u003csource cluster name\u003e` is the name of the source Kubernetes cluster.\n9. Delete the migrated org from the source Kubernetes cluster. Be sure to use the `overrides.yaml` file for the org in the delete command:\n 1. Verify the current context is the correct context for the source Kubernetes cluster: \n\n ```\n kubectl config current-context\n ```\n 2.\n\n ```\n apigeectl delete --settings virtualhost -f \n ```\n 3.\n\n ```\n apigeectl delete --all-envs -f \u003coverrides.yaml\u003e\n ```\n 4.\n\n ```\n apigeectl delete -f \u003coverrides.yaml\u003e --org\n ```\n 5. Exec into the apigee-cassandra-default-0 pod: \n\n ```\n kubectl exec -it -n apigee apigee-cassandra-default-0 -- /bin/bash\n ```\n 6. Execute the following command: \n\n ```\n find /opt/apigee/data/apigee-cassandra/ -iname '*\u003cmigrated org name\u003e_hybrid' -type d -maxdepth 2 -printf \"%f\\n\"\n ```\n\n See [Get the name of the migrated org](#get-the-name-of-the-migrated-org)\n for instructions on finding `\u003cmigrated org name\u003e`.\n\n Copy the list of all the names that are shown in the output. You will need this list\n in step 9. j.\n 7. Exit the `apigee-cassandra-default-0` pod.\n 8. Create a Cassandra debug client pod using the instructions in [Create a client container for debugging](/apigee/docs/api-platform/troubleshoot/playbooks/cassandra/ts-cassandra#create-a-client-container-for-debugging). Move on to the next step after getting a `cqlsh` prompt.\n 9. Execute the following commands at the `cqlsh` prompt: \n\n ```\n desc keyspaces;\n ```\n\n Make sure this command returns no errors.\n 10. For each name in the list created in step 10. f., run the following command: \n\n ```\n drop keyspace \u003cname\u003e;\n ```\n 11. Exit the Cassandra debug client pod.\n After executing the `cqlsh` commands, run the following commands on all Cassandra pods in the source Kubernetes cluster:\n -\n\n ```\n kubectl exec -it -n apigee \u003ccassandra pod name\u003e -- /bin/bash\n ```\n -\n\n ```\n find /opt/apigee/data/apigee-cassandra/ -iname '*\u003cmigrated org name\u003e_hybrid' -type d -maxdepth 2\n ```\n\n See [Get the name of the migrated org](#get-the-name-of-the-migrated-org)\n for instructions on finding `\u003cmigrated org name\u003e`.\n -\n\n ```\n find /opt/apigee/data/apigee-cassandra/ -iname '*\u003cmigrated org name\u003e_hybrid' -type d -maxdepth 2 -exec rm -rf {} +\n ```\n 12. Exit the Cassandra pod.\n\n### Get the name of the migrated org\n\nSeveral of the steps in the procedure described in the previous section require the name of\nthe migrated org. To get the migrated org name, do the following:\n\n1. Get the org name from the org's overrides.yaml file. Make sure to check the overrides.yaml file for the org being migrated.\n2. If the org name contains any dashes \"-\", replace all dashes \"-\" with underscores \"_\"."]]
