Herramienta de migración de Helm de Apigee Hybrid

Esta herramienta de migración ayuda a migrar un clúster híbrido basado en apigeectl a un clúster híbrido basado en Helm. Esta herramienta no realiza ningún reemplazo real de ningún componente del clúster. Es idempotente y puede ejecutarse muchas veces en el mismo clúster, con la preparación de un subconjunto de componentes y organizaciones cada vez.

Puedes migrar todos los componentes de apigee a la vez y las operaciones de actualización de Helm se pueden realizar por componente después de que se ejecuta la herramienta.

Consulta Instala y administra Apigee Hybrid con gráficos de Helm para obtener información sobre cómo administrar clústeres híbridos que migraste a la administración de Helm con esta herramienta.

Requisitos previos

  • Versión 3.10+ de Helm.
  • Un archivo kubeconfig en funcionamiento que apunte a un clúster con una instalación de Apigee Hybrid 1.10 en funcionamiento.
  • Permisos para modificar los metadatos y las anotaciones en los recursos de Kubernetes de los componentes híbridos que deseas migrar.

Permiso

Esta herramienta admite las siguientes opciones en el tiempo de ejecución:

  • Personalización del espacio de nombres para los recursos apigee. Espacio de nombres predeterminado: apigee
  • Solo la migración de los componentes híbridos seleccionados. Predeterminado: se migran todos los componentes
  • Migración de una sola organización
  • Migración de un solo entorno
  • Migración de un solo grupo de organización (apigee-virtualhost)
  • Personalización de los nombres de versiones de Helm para organizaciones, entornos y grupos de entornos.

Limitaciones

  • Esta herramienta no admite la personalización de nombres de versiones de Helm para estos componentes híbridos: apigee-operator, apigee-datastore, apigee-redis, apigee-telemetry y apigee-ingress-manager.
  • Las personalizaciones interactivas hechas a los nombres de versión de Helm para organizaciones, entornos y grupos de entornos no persisten de forma automática entre ejecuciones. Puedes editar el archivo temporal y proporcionarlo como opción en ejecuciones posteriores.
  • El filtrado de entorno y grupo de entornos se realiza solo por nombre. En algunos casos, esto podría provocar que varios entornos y grupos de entornos se migren en clústeres multiorganizaciones.

    Por ejemplo, en un clúster multiorganización con organizaciones org1 y org2, si el entorno prod está presente en ambas organizaciones y solo se especifica --env=prod, se migrarán ambos entornos. Si deseas migrar un solo entorno, también debes especificar un filtro de organización --org=org1 o --org=org2.

Uso

Sintaxis

apigee-helm-migration-tool [--apigee-namespace=] [--components=] [--dry-run] [--env=org1] [--env-group=org2] [--org=baz] [--kubeconfig=] [-y] [-v] [-f /path/to/releaseNames.yaml]

Nombres de versiones de Helm generados

Cada gráfico de Helm que se implementa en un clúster debe tener un nombre de versión, que debe ser único dentro de un espacio de nombres. Los nombres de las versiones de Helm no tienen ninguna convención ni restricción de nombres relacionada con el nombre del gráfico. La herramienta de migración genera nombres de versión únicos de Helm para cada componente.

Gráfico Clúster de una sola organización Clúster multiorganización
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) Los nombres tienen el sufijo -env o -env-group si el nombre generado entra en conflicto con otro nombre generado. También tienen el sufijo -1 o -2 … si aún entran en conflicto.

Personaliza los nombres de versiones de Helm

La herramienta de migración permite la personalización interactiva de los nombres de las versiones de Helm. Si deseas personalizar los nombres de las versiones de Helm no interactivas, haz lo siguiente:

  1. Ejecuta la herramienta una vez y sal del primer mensaje para crear un archivo temporal que contenga los nombres de las versiones generados de forma automática. Deberías ver una línea como la que se muestra a continuación:
    INFO: 21:32:56 using temp file for release names:  /tmp/apigee-helm-migration-1229129207-releaseNames
    
  2. Mueve o copia y, luego, edita este archivo. Puedes pasar este archivo editado con la opción -f cuando ejecutes la herramienta de migración. Los nombres de las versiones generados de forma automática se ven de la siguiente manera:

    orgs:
      example-apigee-org:
        helmReleaseName: example-apigee-org
        envs:
          prod:
            helmReleaseName: prod
        envGroups:
          prod-envgroup:
            helmReleaseName: prod-envgroup
    

    Para personalizar los nombres de las versiones de Helm para una organización, un entorno o un grupo de entornos, edita el campo helmReleaseName de ese objeto. Por ejemplo, para cambiar el nombre de la versión de la organización a custom-org, la versión del entorno a custom-env y la versión del grupo de entornos a custom-group, el archivo resultante se ve de la siguiente manera:

    orgs:
      example-apigee-org:
        helmReleaseName: custom-org
        envs:
          prod:
            helmReleaseName: custom-env
        envGroups:
          prod-envgroup:
            helmReleaseName: custom-group
    

Usa espacios de nombres personalizados

Apigee Hybrid se ejecuta en dos espacios de nombres de Kubernetes:

  • apigee-system: El componente apigee-operator siempre se ejecuta en el apigee-systemespacio de nombres. La herramienta de migración de Helm actualizará el componente apigee-operator en el espacio de nombres apigee-system, sin importar lo que especifiques con la marca --apigee-namespace.
  • apigee: Todos los componentes híbridos, excepto apigee-operator, se ejecutan en este espacio de nombres. apigee es el nombre predeterminado. Puedes usar cualquier espacio de nombres personalizado para estos componentes.

    Si usas un espacio de nombres personalizado, debes especificarlo con la marca --apigee-namespace my_custom_namespace cuando ejecutes la herramienta de migración Helm.

    También debes agregar la propiedad de nivel superior namespace: my_custom_namespace a tu archivo de anulaciones.

Instrucciones

  1. Ubica la herramienta de migración.

    La herramienta de migración se empaqueta con apigeectl a partir de la versión 1.10.3, en /tools/migration/.

  2. Extrae los archivos comprimidos con uno de los siguientes 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. Ejecuta la herramienta de migración. Si las opciones predeterminadas son aceptables, es suficiente ejecutar la herramienta sin argumentos y aprobar el mensaje si los nombres de las versiones de Helm generados son satisfactorios. A continuación, se muestran algunas situaciones de ejemplo:
    • Una instalación simple, con el kubeconfig (~/.kube/config) predeterminado, el espacio de nombres predeterminado apigee y los nombres de versiones predeterminados de Helm.

      El siguiente comando debería ser suficiente para la mayoría de las instalaciones, si no todas. Las operaciones de actualización de Helm se pueden realizar por componente después de ejecutar la herramienta.

      ./apigee-helm-migration-tool
      
    • Migra todos los componentes mediante un espacio de nombres personalizado:
      ./apigee-helm-migration-tool --apigee-namespace my_custom_namespace
      
    • Migra solo los componentes operator y datastore:

      ./apigee-helm-migration-tool --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!
      
    • Apuntan a un archivo kubeconfig específico y especifican un nombre diferente para el espacio de nombres apigee.

      ./apigee-helm-migration-tool --kubeconfig /abs/path/to/kubeconf --namespace org1_namespace
      
    • Migra todos los componentes, pero solo una organización:

      ./apigee-helm-migration-tool --org=some-test-org
      

    A continuación, se muestra un resultado de ejemplo de una migración correcta:

    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!
    

    Posibles errores:

    • Se produjo un error cuando se analizaba el archivo de nombres de la versión: verifica el archivo de nombres de las versiones que se pasó.
    • No se encontraron los recursos: verifica que Apigee Hybrid esté completamente instalado y que tengas permisos para acceder a los recursos de apigee.

Próximo paso

Continúa la instalación de los gráficos de Helm de Apigee Hybrid con las instrucciones en Instala y administra Apigee Hybrid con gráficos de Helm.

Resultado de -help

./apigee-helm-migration-tool --help
Usage of ./apigee-helm-migration-tool:
  -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