Migrar a Apigee híbrida da apigeectl para o Helm

Essa ferramenta ajuda na migração de um cluster híbrido baseado em apigeectl para um cluster híbrido baseado em Helm. Essa ferramenta não realiza uma substituição real de nenhum componente do cluster. Ela é idempotente e pode ser executada várias vezes no mesmo cluster, preparando um subconjunto de componentes e organizações a cada vez.

É possível migrar todos os componentes apigee de uma só vez, e as operações de upgrade do Helm podem ser feitas por componente após a execução da ferramenta.

Consulte Como instalar e gerenciar a Apigee híbrida com gráficos do Helm para informações sobre como gerenciar clusters híbridos que você migrou para o gerenciamento do Helm com esta ferramenta.

Pré-requisitos

Helm versão v3.10+. Consulte Como instalar o Helm.
Um arquivo kubeconfig válido que aponta para um cluster com uma instalação funcional da Apigee híbrida 1.11.
Permissões para modificar os metadados e as anotações nos recursos do Kubernetes dos componentes híbridos que você quer migrar.

Escopo

Essa ferramenta oferece suporte às seguintes opções no tempo de execução:

Personalização do namespace para recursos apigee. Namespace padrão: apigee
Migração apenas de componentes híbridos selecionados. Padrão: todos os componentes são migrados
Migração de apenas uma organização
Migração de apenas um ambiente
Migração de apenas um único env-group (apigee-virtualhost)
Personalização de nomes de versão do Helm para organizações, envs e env-groups.

Limitações

Essa ferramenta não oferece suporte à personalização de nomes de versão do Helm para estes componentes híbridos: apigee-operator, apigee-datastore, apigee-redis, apigee-telemetry e apigee-ingress-manager.
As personalizações interativas feitas nos nomes de versão do Helm para organizações, envs e env-groups não permanecem automaticamente entre as execuções. É possível editar o arquivo temporário e fornecê-lo como uma opção em execuções posteriores.
A filtragem de ambiente e de grupo de ambiente é feita apenas pelo nome. Em alguns casos, isso pode resultar na migração de vários ambientes e grupos de ambientes em clusters de várias organizações.

Por exemplo, em um cluster de várias organizações com organizações org1 e org2, se o env prod estiver presente nas duas organizações e apenas --env=prod for especificado, os envs serão migrados. Se você quiser migrar apenas um ambiente, especifique também um filtro organizacional --org=org1 ou --org=org2.

Uso

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 versão gerados do Helm

Cada gráfico do Helm implantado em um cluster precisa ter um nome de versão, que precisa ser exclusivo dentro de um namespace. Os nomes de versão do Helm não têm nenhuma convenção de nomenclatura ou restrição relativa ao nome do gráfico. A ferramenta de migração gera nomes de versão exclusivos do Helm para cada componente.

Gráfico	Cluster de organização única	Cluster de 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]]⁽¹⁾`	`ORG_NAME-ENV_NAME[-env[-n]]`⁽¹⁾
`apigee-virtualhost (envgroup)`	`VH_NAME[-env-group[-n]]`⁽¹⁾	`ORG_NAME-VH_NAME[-env-group[-n]]`⁽¹⁾
⁽¹⁾ Os nomes serão sufixados com `-env` ou `-env-group` se o nome gerado estiver em conflito com outro nome gerado. Eles são sufixados com `-1` ou `-2 …` se ainda houver conflito.

Como personalizar nomes de versão do Helm

A ferramenta de migração permite a personalização interativa de nomes de versão do Helm. Para personalizar os nomes das versões do Helm de maneira não interativa:

Execute a ferramenta uma vez e saia no primeiro prompt para criar um arquivo temporário contendo os nomes de versão gerados automaticamente. Você verá uma linha como esta:
```
INFO: 21:32:56 using temp file for release names:  /tmp/apigee-helm-migration-1229129207-releaseNames
```
Mova ou copie e edite esse arquivo. É possível transmitir esse arquivo editado com a opção -f ao executar a ferramenta de migração. Os nomes das versões geradas automaticamente têm esta aparência:
```
orgs:
  example-apigee-org:
    helmReleaseName: example-apigee-org
    envs:
      prod:
        helmReleaseName: prod
    envGroups:
      prod-envgroup:
        helmReleaseName: prod-envgroup
```
Para personalizar os nomes de versão do Helm para um org, env ou envgroup, edite o campo helmReleaseName desse objeto. Por exemplo, para renomear a versão org para custom-org, a versão env como custom-env e a versão envgroup como custom-group, o arquivo resultante vai ficar assim:
```
orgs:
  example-apigee-org:
    helmReleaseName: custom-org
    envs:
      prod:
        helmReleaseName: custom-env
    envGroups:
      prod-envgroup:
        helmReleaseName: custom-group
```

Como usar namespaces personalizados

A Apigee híbrida é executada em dois namespaces do Kubernetes:

apigee-system: o componente apigee-operator sempre é executado no namespace apigee-system. A ferramenta de migração do Helm atualizará o componente apigee-operator no namespace apigee-system, independentemente do que você especificar com a flag --apigee-namespace.
apigee: todos os componentes híbridos, exceto apigee-operator, são executados nesse namespace. apigee é o nome padrão. Você pode usar qualquer namespace personalizado para esses componentes.
Se você usar um namespace personalizado, especifique-o com a flag --apigee-namespace my_custom_namespace ao executar a ferramenta de migração Helm.

Também é preciso adicionar a propriedade de nível superior namespace: my_custom_namespace ao arquivo de modificações.

Rotas

Faça o download da ferramenta de migração.
Linux
1. Armazene o número da versão mais recente em uma variável usando o 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 usando o seguinte comando: Se você quiser usar uma versão diferente, salve-a em uma variável de ambiente.
  echo $VERSION
  Exemplo:
  1.0.5
3. Faça o download do pacote de lançamento do seu sistema operacional usando o 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 arquivos compactados usando o seguinte comando:
  tar -xzf apigee-helm-migration_linux_64.tar.gz
Mac OS
1. Armazene o número da versão mais recente em uma variável usando o 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 usando o seguinte comando: Se você quiser usar uma versão diferente, salve-a em uma variável de ambiente.
  echo $VERSION
  Exemplo:
  1.0.5
3. Faça o download do pacote de lançamento do seu sistema operacional usando o 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 arquivos compactados usando o seguinte comando:
  tar -xzf apigee-helm-migration_mac_64.tar.gz
Windows
1. Armazene o número da versão mais recente em uma variável usando o 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 usando o seguinte comando: Se você quiser usar uma versão diferente, salve-a em uma variável de ambiente.
  echo %VERSION%
  Exemplo:
  1.0.5
3. Faça o download do pacote de lançamento do seu sistema operacional usando o 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 arquivos compactados usando o seguinte comando:
  tar xzvf apigee-helm-migration_windows_64.tar.gz

Execute a ferramenta de migração. Se as opções padrão forem aceitáveis, basta executar a ferramenta sem nenhum argumento e aprovar a solicitação se os nomes de versão do Helm gerados forem satisfatórios. Confira alguns exemplos de situações abaixo:

Uma instalação simples que usa o kubeconfig (~/.kube/config), o namespace padrão apigee e os nomes de versão padrão do Helm.

O comando a seguir é suficiente para a maioria das instalações, se não para todas. As operações de upgrade do Helm podem ser feitas por componente após a execução da ferramenta.
```
./apigee-helm-migration
```
Como migrar todos os componentes usando um namespace personalizado:
```
./apigee-helm-migration --apigee-namespace my_custom_namespace
```

Migrando 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!

Direcionar para um arquivo kubeconfig específico e especificar um nome diferente para o namespace apigee.
```
./apigee-helm-migration --kubeconfig /abs/path/to/kubeconf --namespace org1_namespace
```
Migrar todos os componentes, mas apenas uma organização:
```
./apigee-helm-migration --org=some-test-org
```

Veja a seguir um exemplo de saída 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!

Erros possíveis:

Erro ao analisar o arquivo de nomes de versão: verifique o transmitido no arquivo de nomes de versão.
Recursos não encontrados: verifique se a Apigee híbrida está totalmente instalada e se você tem permissões para acessar os recursos apigee.

Mudanças nas propriedades de configuração

Faça as seguintes alterações nos arquivos de substituição:

A Apigee híbrida gerenciada com o Helm usa propriedades apigeeIngressGateway para configurar todos os gateways de entrada da Apigee no cluster. As propriedades ingressGateways substituem as configurações em apigeeIngressGateway para o gateway de entrada nomeado individual.
Consulte apigeeIngressGateway
- Crie uma estrofe apigeeIngressGateway adicional no arquivo de substituições para todas as propriedades ingressGateways que são globais para todos os gateways de entrada no cluster. Exemplo:
```
apigeeIngressGateway:
  image:
    url: "PATH_TO_REPOSITORY/apigee-asm-ingress"
    tag: "TAG"
```
  Exemplo:
```
apigeeIngressGateway:
  image:
    url: "gcr.io/apigee-release/hybrid/apigee-asm-ingress"
    tag: "1.17.8-asm.20-distroless"
```
- Não se esqueça de incluir os seguintes dados ingressGateways.name. É necessário instanciar o gateway de entrada. Exemplo:
As propriedades para ativar a Identidade da carga de trabalho foram alteradas:
- gcp.workloadIdentity.enabled substitui gcp.workloadIdentityEnabled.
- Se você estiver usando uma única conta de serviço para todos os componentes, especifique-a com o seguinte: gcp.workloadIdentity.gsa. Exemplo:
```
gcp:
  workloadIdentity:
    enabled: true
    gsa: "apigee-non-prod@my-hybrid-project.iam.gserviceaccount.com"
```
- Se você estiver usando uma conta de serviço distinta para cada componente (o padrão para a maioria das instalações de produção), especifique a conta de serviço com a propriedade gsa do componente. Exemplo:
```
logger:
  gsa: "apigee-logger@my-hybrid-project.iam.gserviceaccount.com"
```
Consulte: gcp.workloadIdentity.enabled e Como ativar a Identidade da carga de trabalho com o Helm.

Solução de problemas

Há um problema conhecido com a ferramenta de migração Helm na versão híbrida v1.11. Até que o problema seja resolvido, o backup e a restauração do Cassandra exigem etapas adicionais.

Siga estas etapas:

Antes ou depois de executar a ferramenta de migração
Antes de instalar gráficos do Helm

Para instalar o patch como solução alternativa:

Verifique se o kubeconfig atual está apontando para o cluster que você quer migrar. É possível executar essas etapas em qualquer diretório.

Crie um arquivo chamado migration-operator-patch.yaml com o seguinte conteúdo:

# migration-operator-patch.yaml
metadata:
  annotations:
    meta.helm.sh/release-name: operator
    meta.helm.sh/release-namespace: apigee-system
  labels:
    app.kubernetes.io/managed-by: Helm

Crie um arquivo chamado migration-datastore-patch.yaml com o conteúdo a seguir.

# migration-datastore-patch.yaml
metadata:
  annotations:
    meta.helm.sh/release-name: datastore
    meta.helm.sh/release-namespace: apigee
  labels:
    app.kubernetes.io/managed-by: Helm

Execute os comandos kubectl a seguir:

kubectl patch clusterrole apigee-cassandra-backup --patch-file ./migration-operator-patch.yaml
kubectl patch clusterrole apigee-cassandra-restore --patch-file ./migration-operator-patch.yaml
kubectl patch clusterrolebinding apigee-cassandra-backup --patch-file ./migration-operator-patch.yaml
kubectl patch clusterrolebinding apigee-cassandra-restore --patch-file ./migration-operator-patch.yaml
kubectl patch -n apigee cronjob apigee-cassandra-backup --patch-file ./migration-datastore-patch.yaml
kubectl patch -n apigee certificate apigee-cassandra-backup-tls --patch-file ./migration-datastore-patch.yaml --type merge
kubectl patch -n apigee secret apigee-cassandra-backup-svc-account --patch-file ./migration-datastore-patch.yaml
kubectl patch -n apigee secret apigee-cassandra-backup-key-file --patch-file ./migration-datastore-patch.yaml
kubectl patch -n apigee ServiceAccount apigee-cassandra-backup-sa --patch-file ./migration-datastore-patch.yaml
kubectl patch -n apigee job apigee-cassandra-restore --patch-file ./migration-datastore-patch.yaml
kubectl patch -n apigee certificate apigee-cassandra-restore-tls --patch-file ./migration-datastore-patch.yaml --type merge
kubectl patch -n apigee secret apigee-cassandra-restore-svc-account --patch-file ./migration-datastore-patch.yaml
kubectl patch -n apigee secret apigee-cassandra-restore-key-file --patch-file ./migration-datastore-patch.yaml
kubectl patch -n apigee ServiceAccount apigee-cassandra-restore-sa --patch-file ./migration-datastore-patch.yaml

Observação: ignore quaisquer erros not found.

Limpe os arquivos de patch usando os seguintes comandos:

rm migration-operator-patch.yaml
rm migration-datastore-patch.yaml

Próxima etapa

Continue a instalação dos gráficos da Apigee híbrida do Helm com as instruções em Como instalar e gerenciar a Apigee híbrida com gráficos do Helm.

Importante: ao seguir as instruções sobre o cluster migrado, omita a flag ‑‑atomic de qualquer comando Helm para evitar a exclusão acidental de recursos se o comando helm upgrade falhar de dois minutos.

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