Esta página foi traduzida pela API Cloud Translation.

Migre o Apigee Hybrid para o Helm a partir do apigeectl

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.

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

Versão do Helm v3.14.2 ou superior.
Um ficheiro kubeconfig funcional que aponta para um cluster com uma instalação do Apigee Hybrid 1.12 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 de organização --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 Helm Chart 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]]⁽¹⁾`	`ORG_NAME-ENV_NAME[-env[-n]]`⁽¹⁾
`apigee-virtualhost (envgroup)`	`VH_NAME[-env-group[-n]]`⁽¹⁾	`ORG_NAME-VH_NAME[-env-group[-n]]`⁽¹⁾
⁽¹⁾ 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 das versões do Helm de forma não interativa:

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
```
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

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

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:

Para atualizações de várias organizações, recomendamos que execute o comando apigee-helm-migration sem opções para atualizar todos os componentes da organização e do ambiente.

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.

Alterações às propriedades de configuração

Faça as seguintes alterações nos ficheiros de substituições:

Use metrics.appStackdriverExporter.* em vez de metrics.aggregator.*.
O Apigee Hybrid gerido com o Helm usa propriedades apigeeIngressGateway para configurar todos os gateways de entrada do Apigee no seu cluster. As propriedades ingressGateways substituem as definições em apigeeIngressGateway para o gateway de entrada nomeado individual.
Consulte apigeeIngressGateway
- Crie uma secção apigeeIngressGateway adicional no ficheiro de substituições para quaisquer propriedades ingressGateways que sejam globais para todos os gateways de entrada no cluster. Por exemplo:
```
apigeeIngressGateway:
  image:
    url: "PATH_TO_REPOSITORY/apigee-asm-ingress"
    tag: "TAG"
```
  Por exemplo:
```
apigeeIngressGateway:
  image:
    url: "gcr.io/apigee-release/hybrid/apigee-asm-ingress"
    tag: "1.17.8-asm.20-distroless"
```
- Certifique-se de que inclui ingressGateways.name. É necessário instanciar o gateway de entrada. Por exemplo:

Nota: ingressGateways é uma coleção de instâncias ingressGateway individuais. Faz a gestão da configuração das instâncias ingressGateway. Use ingressGateways no ficheiro de substituições.

As propriedades para ativar o Workload Identity foram alteradas:
- gcp.workloadIdentity.enabled substitui gcp.workloadIdentityEnabled.
- Se estiver a usar uma única conta de serviço para todos os componentes, pode especificá-la com: gcp.workloadIdentity.gsa. Por exemplo:
```
gcp:
  workloadIdentity:
    enabled: true
    gsa: "apigee-non-prod@my-hybrid-project.iam.gserviceaccount.com"
```
- Se estiver a usar uma conta de serviço separada 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. Por exemplo:
```
logger:
  gsa: "apigee-logger@my-hybrid-project.iam.gserviceaccount.com"
```
Veja: gcp.workloadIdentity.enabled, gcp.federatedWorkloadIdentity.enabled, Ativar a identidade da carga de trabalho no GKE ou Ativar a federação de identidades da carga de trabalho no AKS e no EKS.

Resolução de problemas

Existe um problema conhecido com a ferramenta de migração do Helm na versão híbrida 1.12. Até o problema ser resolvido, a cópia de segurança e o restauro do Cassandra requerem passos adicionais.

Pode seguir estes passos:

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

Para instalar o patch para a solução alternativa:

Certifique-se de que o seu kubeconfig atual está a apontar para o cluster que quer migrar. Pode realizar estes passos a partir de qualquer diretório.

Crie um ficheiro denominado 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 ficheiro denominado migration-datastore-patch.yaml com o seguinte conteúdo:

# 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 seguintes comandos kubectl:

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

Nota: pode ignorar quaisquer erros not found.

Limpe os ficheiros de patch com os seguintes comandos:

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

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