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]](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 -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:

  1. 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
    
  2. 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.

Directions

  1. Localize a ferramenta de migração.

    A ferramenta de migração é fornecida com apigeectl em /tools/migration/.

  2. 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
  3. 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:

  • Altere ingressGateways para apigeeIngressGateway. 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 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. 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