Nesta página, descrevemos como migrar uma organização da Apigee híbrida de um
cluster do Kubernetes para outro. Veja a seguir alguns casos em que pode ser necessário migrar
uma organização para outro cluster:
O data center que hospeda o cluster atual não tem mais capacidade ou está
sendo desativado.
O cluster está executando uma infraestrutura ou uma versão antiga do Kubernetes e você
quer migrar para um cluster com infraestrutura mais recente.
Você quer mover as organizações de clusters de várias organizações para clusters separados.
A migração de uma organização para outro cluster híbrido tem riscos e limitações.
Leia os detalhes na seção Limitações
antes de executar uma migração.
Limitações
As limitações a seguir se aplicam à migração de uma organização híbrida para outro cluster do Kubernetes:
Há o risco de perda de dados ao mover dados da organização para um novo cluster do Kubernetes.
Faça o backup dos dados de todas as organizações do cluster do Kubernetes usando as
instruções de backup
híbrido antes de migrar uma organização.
O tamanho máximo de dados permitido para migração de uma organização é de 5GB em todos os keyspaces de uma organização,
exceto cache e cota.
Os dados em cache não serão migrados. O híbrido recria os dados do cache.
Os dados de cota não serão migrados. O híbrido redefine os dados de cota.
Só é possível migrar organizações para um cluster do Kubernetes que não contenha
implantação híbrida.
A migração para um cluster com uma implantação híbrida não é compatível.
A organização que está sendo migrada só pode ser movida para um novo cluster com uma única implantação de região.
Depois que a implantação de região única estiver funcionando, siga o processo de expansão de região,
descrito em Implantação multirregional,
para expandir para outras regiões.
O cluster do Cassandra deve funcionar bem em todas as regiões.
Como migrar uma organização
Siga as instruções abaixo para migrar uma organização híbrida de um cluster do Kubernetes para outro:
Se ainda não estiver ativado, ative os backups no cluster do Kubernetes que contém a
organização híbrida que será migrada. Consulte os
Aspectos gerais do backup do Cassandra
para receber informações sobre backups híbridos.
Inicie um job de backup híbrido usando o seguinte comando:
O <backup job name> pode ser qualquer nome de contêiner válido.
Quando o job de backup for concluído, use as instruções das seções a seguir de
Backups do
Monitoring para verificar se o backup foi concluído:
"Verifique o status da tarefa de backup"
"Verifique os registros de backup"
Depois de verificar se o backup foi concluído, anote o número de ID no final do
registro de backup.
Por exemplo, um registro de backup bem-sucedido deve conter uma linha como a seguinte:
INFO: completed upload for 20230207004250
Anote o número de vários dígitos no final da linha. Você precisará desse número mais tarde.
Alterne o contexto do Kubernetes para o cluster do Kubernetes de destino:
Use o arquivo overrides.yaml para a organização que será migrada para a implantação híbrida
de destino.
Lembre-se de definir o valor restore:snapshotTimestamp como o número de vários dígitos
mostrado pelo registro de backup na etapa 4. Consulte
Como restaurar em uma única região.
Quando a restauração for concluída, exclua todos os dados da organização do cluster de destino
do Kubernetes, exceto os dados da organização que está sendo migrada. Os arquivos de backup híbrido contêm os dados de todas as
organizações, incluindo as que você não quer migrar. Depois que a implantação híbrida
de destino for restaurada, será necessário remover todos os dados organizacionais extras que foram
copiados para a implantação seguindo estas etapas:
Verifique se o contexto atual é o contexto correto para o cluster de destino do Kubernetes:
Copie a lista com todos os nomes exibidos na
saída. Você precisará dessa lista na etapa 7. f.
Saia do pod apigee-cassandra-default-0.
Crie um pod cliente de depuração do Cassandra usando as instruções em
Criar um contêiner de cliente para depuração. Passe para a próxima etapa depois de receber uma
solicitação cqlsh.
Execute os seguintes comandos no prompt cqlsh:
desc keyspaces;
Verifique se esse comando não retorna erros.
Para cada nome da lista criada na etapa 7. c., execute o seguinte comando:
drop keyspace <name>
Saia do pod cliente de depuração do Cassandra.
Depois de executar os comandos cqlsh, execute os comandos a seguir em todos os pods do
Cassandra no cluster de destino do Kubernetes:
Copie a lista com todos os nomes exibidos na saída. Você precisará dessa lista
na etapa 9. j.
Saia do pod apigee-cassandra-default-0.
Crie um pod cliente de depuração do Cassandra usando as instruções em
Criar um contêiner de cliente para depuração. Passe para a próxima etapa
depois de receber uma solicitação cqlsh.
Execute os seguintes comandos no prompt cqlsh:
desc keyspaces;
Verifique se esse comando não retorna erros.
Para cada nome da lista criada na etapa 10, f.,
execute este comando:
drop keyspace <name>;
Saia do pod cliente de depuração do Cassandra.
Depois de executar os comandos cqlsh, execute os comandos a seguir em todos os pods do Cassandra
no cluster de origem do Kubernetes:
kubectl exec -it -n apigee <cassandra pod name> -- /bin/bash
find /opt/apigee/data/apigee-cassandra/ -iname '*<migrated org name>_hybrid' -type d -maxdepth 2
Várias das etapas do procedimento descrito na seção anterior exigem o nome da
organização migrada. Para encontrar o nome da organização migrada, faça o seguinte:
Receba o nome da organização do arquivo overrides.yaml da organização. Verifique o arquivo
overrides.yaml da organização que está sendo migrada.
Se o nome da organização contiver traços "-", substitua todos os traços "-" por sublinhados "_".
[[["Fácil de entender","easyToUnderstand","thumb-up"],["Meu problema foi resolvido","solvedMyProblem","thumb-up"],["Outro","otherUp","thumb-up"]],[["Difícil de entender","hardToUnderstand","thumb-down"],["Informações incorretas ou exemplo de código","incorrectInformationOrSampleCode","thumb-down"],["Não contém as informações/amostras de que eu preciso","missingTheInformationSamplesINeed","thumb-down"],["Problema na tradução","translationIssue","thumb-down"],["Outro","otherDown","thumb-down"]],["Última atualização 2025-08-28 UTC."],[[["\u003cp\u003eThis documentation outlines the process of migrating an Apigee hybrid organization from one Kubernetes cluster to another, covering reasons for migration such as data center decommissioning or infrastructure updates.\u003c/p\u003e\n"],["\u003cp\u003eMigrating an organization to a new Kubernetes cluster involves risks, including potential data loss, and limitations, such as a maximum data size of 5GB and no migration of cache or quota data.\u003c/p\u003e\n"],["\u003cp\u003eThe migration procedure involves backing up the org data in the source cluster, restoring it in the destination cluster, and then deleting the org data from the source cluster, including deleting the appropriate keyspaces.\u003c/p\u003e\n"],["\u003cp\u003eThe destination cluster must have no existing hybrid deployments, only supports single-region deployments initially, and the Cassandra cluster should be in good health.\u003c/p\u003e\n"],["\u003cp\u003eThe current version of this documentation is end-of-life, so it is highly recommended to upgrade to a newer version.\u003c/p\u003e\n"]]],[],null,["# Migrating an org to another cluster\n\n| You are currently viewing version 1.8 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.8/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.8/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.8/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.8/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.8/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.8/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 \"_\"."]]
