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.15 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]]⁽¹⁾`	`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 existirem 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:

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 v1.13 e mais recente é executado num único espaço de nomes do Kubernetes. Todos os componentes híbridos são executados neste namespace. 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

Localize a ferramenta de migração.

A ferramenta de migração está incluída no apigeectl em /tools/migration/.

Extraia os ficheiros comprimidos através de um dos seguintes comandos:

Mac:

tar -xzf apigee-helm-migration_1.0.2_mac_64.tar.gz

Linux:

tar -xzf apigee-helm-migration_1.0.2_linux_64.tar.gz

Windows:

tar -xzf apigee-helm-migration_1.0.2_windows_64.zip

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.

Alterações das propriedades de configuração

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

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
- Altere todas as propriedades ingressGateways que sejam globais para todos os gateways de entrada no seu cluster para propriedades apigeeIngressGateway. O ficheiro de substituições deve conter, pelo menos:
```
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.15.1"
```
- Certifique-se de que inclui ingressGateways.name. É necessário instanciar o gateway de entrada. Por exemplo:
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 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_NAMESPACE
  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_NAMESPACE cronjob apigee-cassandra-backup --patch-file ./migration-datastore-patch.yaml
kubectl patch -n APIGEE_NAMESPACE certificate apigee-cassandra-backup-tls --patch-file ./migration-datastore-patch.yaml --type merge
kubectl patch -n APIGEE_NAMESPACE secret apigee-cassandra-backup-svc-account --patch-file ./migration-datastore-patch.yaml
kubectl patch -n APIGEE_NAMESPACE secret apigee-cassandra-backup-key-file --patch-file ./migration-datastore-patch.yaml
kubectl patch -n APIGEE_NAMESPACE ServiceAccount apigee-cassandra-backup-sa --patch-file ./migration-datastore-patch.yaml
kubectl patch -n APIGEE_NAMESPACE job apigee-cassandra-restore --patch-file ./migration-datastore-patch.yaml
kubectl patch -n APIGEE_NAMESPACE certificate apigee-cassandra-restore-tls --patch-file ./migration-datastore-patch.yaml --type merge
kubectl patch -n APIGEE_NAMESPACE secret apigee-cassandra-restore-svc-account --patch-file ./migration-datastore-patch.yaml
kubectl patch -n APIGEE_NAMESPACE secret apigee-cassandra-restore-key-file --patch-file ./migration-datastore-patch.yaml
kubectl patch -n APIGEE_NAMESPACE 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