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
eapigee-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
eorg2
, se o envprod
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]](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 serão sufixados com |
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 paracustom-org
, a versão env comocustom-env
e a versão envgroup comocustom-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 componenteapigee-operator
sempre é executado no namespaceapigee-system
. A ferramenta de migração do Helm atualizará o componenteapigee-operator
no namespaceapigee-system
, independentemente do que você especificar com a flag--apigee-namespace
.apigee
: todos os componentes híbridos, excetoapigee-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.
Directions
-
Localize a ferramenta de migração.
A ferramenta de migração é fornecida com
apigeectl
em/tools/migration/
. -
Extraia os arquivos compactados usando 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
-
Mac:
-
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ãoapigee
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
edatastore
:./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 namespaceapigee
../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:
- Altere
ingressGateways
paraapigeeIngressGateway
. O arquivo de substituição precisa conter pelo menos: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"
Consulte
apigeeIngressGateway
- As propriedades para ativar a Identidade da carga de trabalho foram alteradas:
gcp.workloadIdentity.enabled
substituigcp.workloadIdentityEnabled
.- Se você estiver usando uma única conta de serviço para todos os componentes, especifique-a com o seguinte:
gcp.workloadIdentity.gsa
. Por 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. Por 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.
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.
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