Ferramenta de migração do Helm do Apigee Hybrid

Version 1.10 

   Versões suportadas:

• v1.15 (mais recente)                        
• v1.14                        
• v1.13                         
• Lista de versões suportadas

   Versões não suportadas:

• v1.12                         
• v1.11                         
• v1.10                                      
• v1.9                                         
• v1.8                                         
• v1.7                                         
• v1.6                                         
• v1.5                                         
• v1.4                                         
• v1.3                                         
• v1.2                                         
• v1.1                                         

Pré-visualização — Apigee hybrid Helm migration tool

Esta funcionalidade está sujeita aos "Termos das Ofertas de Pré-DG" na secção Termos Gerais de Serviço dos Termos Específicos do Serviço. As funcionalidades de pré-DG estão disponíveis "tal como estão" e podem ter apoio técnico limitado. Para mais informações, consulte as descrições das fases de lançamento.

<0x0

Se estiver a usar o Apigee Hybrid v1.11, consulte a ferramenta de migração do Helm do Apigee Hybrid na documentação do Apigee Hybrid v1.11.

Aviso: esta ferramenta de migração é uma versão de pré-visualização para a versão 1.10 do Apigee Hybrid. Não a use para migrar os seus clusters de produção.

Esta ferramenta de migração ajuda a migrar um cluster híbrido baseado em apigeectl para um cluster híbrido baseado em Helm. Esta ferramenta não faz nenhuma substituição real de componentes do cluster. É idempotente e pode ser executado várias vezes no mesmo cluster, preparando um subconjunto de componentes e organizações de cada vez.

Importante: tem de executar esta ferramenta de migração antes de executar os comandos de atualização do Helm.

Pode migrar todos os componentes apigee de uma só vez e as operações de atualização do Helm podem ser feitas por componente após a execução da ferramenta.

Consulte o artigo Instalar e gerir o Apigee hybrid com gráficos Helm para ver informações sobre a gestão de clusters híbridos que migrou para a gestão do Helm com esta ferramenta.

Pré-requisitos

• Helm versão 3.10 ou superior.
• Um ficheiro kubeconfig funcional que aponta para um cluster com uma instalação híbrida do Apigee 1.10 funcional.
• Autorizações para modificar os metadados e as anotações nos recursos do Kubernetes dos componentes híbridos que quer migrar.

Âmbito

Esta ferramenta suporta as seguintes opções em tempo de execução:

• Personalização do espaço de nomes para recursos apigee. Espaço de nomes predefinido: apigee
• Migração apenas de componentes híbridos selecionados. Predefinição: todos os componentes são migrados
• Migração de uma única organização
• Migração de um único ambiente
• Migração apenas de um único grupo de ambientes (apigee-virtualhost)
• Personalização dos nomes de lançamentos do Helm para organizações, ambientes e grupos de ambientes.

Limitações

• Esta ferramenta não suporta a personalização dos nomes de lançamentos do Helm para estes componentes híbridos: apigee-operator, apigee-datastore, apigee-redis, apigee-telemetry e apigee-ingress-manager.
• As personalizações interativas feitas aos nomes de lançamentos do Helm para organizações, ambientes e grupos de ambientes não são automaticamente mantidas entre execuções. Pode editar o ficheiro temporário e fornecê-lo como uma opção em execuções posteriores.

• A filtragem de env e env-group é feita apenas por nome. Em alguns casos, isto pode resultar na migração de vários ambientes e grupos de ambientes em clusters de várias organizações.

  Por exemplo, num cluster multi-org com as orgs org1 e org2, se o ambiente prod estiver presente em ambas as orgs e apenas --env=prod for especificado, ambos os ambientes serão migrados. Se quiser migrar apenas um único ambiente, também tem de especificar um filtro org --org=org1 ou --org=org2.

Utilização

Sintaxe

apigee-helm-migration [--apigee-namespace=] [--components=] [--dry-run] [--env=org1] [--env-group=org2] [--org=baz] [--kubeconfig=] [-y] [-v] [-f /path/to/releaseNames.yaml]

Nomes de lançamentos do Helm gerados

Cada gráfico Helm implementado num cluster tem de ter um nome de lançamento, que tem de ser exclusivo num espaço de nomes. Os nomes das versões do Helm não têm nenhuma convenção de nomenclatura nem restrição relativa ao nome do gráfico. A ferramenta de migração gera nomes de lançamentos do Helm exclusivos para cada componente.

Gráfico	Cluster de organização única	Cluster com várias organizações
apigee-operator	operator	operator
apigee-datastore	datastore	datastore
apigee-telemetry	telemetry	telemetry
apigee-redis	redis	redis
apigee-ingress-manager	ingress-manager	ingress-manager
apigee-org	ORG_NAME	ORG_NAME
apigee-env	ENV_NAME[-env[-n]]^(1)	ORG_NAME-ENV_NAME[-env[-n]]^(1)
apigee-virtualhost (envgroup)	VH_NAME[-env-group[-n]]^(1)	ORG_NAME-VH_NAME[-env-group[-n]]^(1)
^(1) Os nomes têm o sufixo -env ou -env-group se o nome gerado estiver em conflito com outro nome gerado. Se ainda houver conflitos, são adicionados os sufixos -1 ou -2 ….

Personalizar nomes de lançamentos do Helm

A ferramenta de migração permite a personalização interativa dos nomes de lançamentos do Helm. Se quiser personalizar os nomes de lançamentos do Helm de forma não interativa:

1. Execute a ferramenta uma vez e saia no primeiro comando para criar um ficheiro temporário com os nomes de lançamentos gerados automaticamente. Deve ver uma linha como:

   INFO: 21:32:56 using temp file for release names:  /tmp/apigee-helm-migration-1229129207-releaseNames

2. Mover ou copiar e, em seguida, editar este ficheiro. Pode transmitir este ficheiro editado com a opção -f quando executar a ferramenta de migração. Os nomes de lançamentos gerados automaticamente têm o seguinte aspeto:

   orgs:
     example-apigee-org:
       helmReleaseName: example-apigee-org
       envs:
         prod:
           helmReleaseName: prod
       envGroups:
         prod-envgroup:
           helmReleaseName: prod-envgroup

   Para personalizar os nomes de versões do Helm para uma organização, um ambiente ou um grupo de ambientes, edite o campo helmReleaseName desse objeto. Por exemplo, para mudar o nome da versão da organização para custom-org, o nome da versão do ambiente para custom-env e o nome da versão do grupo de ambientes para custom-group, o ficheiro resultante tem o seguinte aspeto:

   orgs:
     example-apigee-org:
       helmReleaseName: custom-org
       envs:
         prod:
           helmReleaseName: custom-env
       envGroups:
         prod-envgroup:
           helmReleaseName: custom-group

Usar espaços de nomes personalizados

O Apigee Hybrid é executado em dois espaços de nomes do Kubernetes:

• apigee-system: o componente apigee-operator é sempre executado no espaço de nomes apigee-system. A ferramenta de migração do Helm atualiza o componente apigee-operator no espaço de nomes apigee-system, independentemente do que especificar com a flag --apigee-namespace.
• apigee: todos os componentes híbridos, exceto apigee-operator, são executados neste espaço de nomes. apigee é o nome predefinido. Pode usar qualquer espaço de nomes personalizado para estes componentes.

  Se usar um espaço de nomes personalizado, tem de o especificar com a flag --apigee-namespace my_custom_namespace quando executar a ferramenta de migração do Helm.

  Também tem de adicionar a propriedade de nível superior namespace: my_custom_namespace ao ficheiro de substituições.

Indicações

1. Transfira a ferramenta de migração.

   Linux

   1. Armazene o número da versão mais recente numa variável através do seguinte comando:

      export VERSION=$(curl -s "https://storage.googleapis.com/apigee-release/hybrid/apigee-migration-tool/current-version.txt?ignoreCache=1")

   2. Verifique se a variável foi preenchida com um número de versão através do seguinte comando. Se quiser usar uma versão diferente, pode guardá-la numa variável de ambiente.

      echo $VERSION

      Por exemplo:

      echo $VERSION
      1.0.5

   3. Transfira o pacote de lançamento para o seu sistema operativo através do seguinte comando:

      curl -LO https://storage.googleapis.com/apigee-release/hybrid/apigee-migration-tool/${VERSION}/apigee-helm-migration_linux_64.tar.gz

   4. Extraia os ficheiros comprimidos através do seguinte comando:

      tar -xzf apigee-helm-migration_linux_64.tar.gz

   Mac OS

   1. Armazene o número da versão mais recente numa variável através do seguinte comando:

      export VERSION=$(curl -s "https://storage.googleapis.com/apigee-release/hybrid/apigee-migration-tool/current-version.txt?ignoreCache=1")

   2. Verifique se a variável foi preenchida com um número de versão através do seguinte comando. Se quiser usar uma versão diferente, pode guardá-la numa variável de ambiente.

      echo $VERSION

      Por exemplo:

      echo $VERSION
      1.0.5

   3. Transfira o pacote de lançamento para o seu sistema operativo através do seguinte comando:

      curl -LO https://storage.googleapis.com/apigee-release/hybrid/apigee-migration-tool/${VERSION}/apigee-helm-migration_mac_64.tar.gz

   4. Extraia os ficheiros comprimidos através do seguinte comando:

      tar -xzf apigee-helm-migration_mac_64.tar.gz

   Windows

   1. Armazene o número da versão mais recente numa variável através do seguinte comando:

      for /f "tokens=*" %a in ('curl -s https://storage.googleapis.com/apigee-release/hybrid/apigee-migration-tool/current-version.txt') do set VERSION=%a

   2. Verifique se a variável foi preenchida com um número de versão através do seguinte comando. Se quiser usar uma versão diferente, pode guardá-la numa variável de ambiente.

      echo %VERSION%

      Por exemplo:

      echo %VERSION%
      1.0.5

   3. Transfira o pacote de lançamento para o seu sistema operativo através do seguinte comando:

      curl -LO https://storage.googleapis.com/apigee-release/hybrid/apigee-migration-tool/%VERSION%/apigee-helm-migration_windows_64.tar.gz

   4. Extraia os ficheiros comprimidos através do seguinte comando:

      tar xzvf apigee-helm-migration_windows_64.tar.gz

2. Execute a ferramenta de migração. Se as opções predefinidas forem aceitáveis, é suficiente executar a ferramenta sem argumentos e aprovar o comando se os nomes de lançamento do Helm gerados forem satisfatórios. Seguem-se alguns cenários de exemplo:

   • Uma instalação simples, usando o kubeconfig predefinido (~/.kube/config), o espaço de nomes apigee predefinido e os nomes de lançamento do Helm predefinidos.

     O comando seguinte deve ser suficiente para a maioria, se não todas, as instalações. As operações de atualização do Helm podem ser feitas por componente após a execução da ferramenta.

     ./apigee-helm-migration
     

   • Migrar todos os componentes com um espaço de nomes personalizado:

     ./apigee-helm-migration --apigee-namespace my_custom_namespace
     

   • Migrar apenas os componentes operator e datastore:

     ./apigee-helm-migration --components operator,datastore
     

       INFO: 00:22:48 using kubeconfig file  /usr/local/google/home/example/.kube/config
       INFO: 00:22:48 namespace for apigee resources:
       INFO: 00:22:48 	 apigee
       INFO: 00:22:48 processing all organizations in cluster
       INFO: 00:22:48 Components to migrate:
       INFO: 00:22:48 	 operator,datastore
       INFO: 00:22:48 dry-run:
       INFO: 00:22:48 	 false
       Continue with patching apigee resources for Helm migration? [y/n]: y
       INFO: 00:22:52 Processing component:  operator
       INFO: 00:22:54 Processing component:  datastore
       INFO: 00:22:55 Migration successful!

   • Apontando para um ficheiro kubeconfig específico e especificando um nome diferente para o espaço de nomes apigee.

     ./apigee-helm-migration --kubeconfig /abs/path/to/kubeconf --namespace org1_namespace
     

   • Migrar todos os componentes, mas apenas uma única organização:

     ./apigee-helm-migration --org=some-test-org
     

   Segue-se um exemplo de resultado de uma migração bem-sucedida:

   INFO: 21:32:55 using kubeconfig file  /usr/local/google/home/example/.kube/config
   INFO: 21:32:55 namespace for apigee resources:
   INFO: 21:32:55 	 apigee
   INFO: 21:32:55 processing all organizations in cluster
   INFO: 21:32:55 processing all components
   INFO: 21:32:55 dry-run:
   INFO: 21:32:55 	 false
   INFO: 21:32:55 cluster Apigee information:
   INFO: 21:32:55 Apigee Organizations found:
   INFO: 21:32:56 	 example-hybrid-dev
   INFO: 21:32:56 Apigee Environments found (org: env):
   INFO: 21:32:56 	 example-hybrid-dev : prod
   INFO: 21:32:56 Apigee EnvGroups(apigeerouteconfigs) found (org: envGroup):
   INFO: 21:32:56 	 example-hybrid-dev : prod-envgroup
   INFO: 21:32:56 using temp file for release names:  /tmp/apigee-helm-migration-1229129207-releaseNames
   INFO: 21:32:56 Helm release names for Apigee orgs/envs/envgroups:
   orgs:
   example-hybrid-dev:
   helmReleaseName: example-hybrid-dev
   envs:
     prod:
       helmReleaseName: prod
   envGroups:
     prod-envgroup:
       helmReleaseName: prod-envgroup
   Make changes to the release names for Apigee orgs/env/envgroups? [y/n]: n
   Continue with patching apigee resources for Helm migration? [y/n]: y
   INFO: 21:32:59 Processing component:  operator
   INFO: 21:33:01 Processing component:  datastore
   INFO: 21:33:01 Processing component:  redis
   INFO: 21:33:02 Processing component:  ingress-manager
   INFO: 21:33:02 Processing component:  telemetry
   INFO: 21:33:03 Processing component:  orgs
   INFO: 21:33:05 Processing component:  envs
   INFO: 21:33:06 Processing component:  env-groups
   INFO: 21:33:07 Migration successful!

   Potenciais erros:

   • Erro ao analisar o ficheiro de nomes de lançamentos: verifique o ficheiro de nomes de lançamentos transmitido.
   • Recursos não encontrados: verifique se o Apigee hybrid está totalmente instalado e se tem autorizações para aceder aos recursos apigee.

Passo seguinte

Continue a instalação dos gráficos Helm do Apigee Hybrid com as instruções em Instalar e gerir o Apigee Hybrid com gráficos Helm.

Importante: quando seguir as instruções para o cluster migrado, tem de omitir a flag ‑‑atomic de todos os comandos Helm para evitar a eliminação acidental de recursos se o comando helm upgrade falhar.

Resultado de -help

./apigee-helm-migration --help

Usage of ./apigee-helm-migration:
  -apigee-namespace string
      namespace used for apigee resources (default "apigee")
  -components string
      CSV of components to migrate. If empty then all components are migrated. Valid values are: operator,datastore,redis,ingress-manager,telemetry,orgs,envs,env-groups
  -dry-run
      perform a dry-run
  -env string
      restrict migration to a singular supplied env. If empty then all envs detected in the cluster are migrated
  -env-group string
      restrict migration to a singular supplied envGroup. If empty then all envGroups detected in the cluster are migrated
  -kubeconfig string
      (optional) absolute path to the kubeconfig file (default "/usr/local/google/home/example/.kube/config")
  -org string
      restrict migration to a singular supplied org. If empty then all orgs detected in the cluster are migrated
  -v	Increased logging verbosity
  -y	don't prompt for confirmation or for configuration of Helm releases