Migra Apigee Hybrid a Helm desde apigeectl

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 de Helm v3.14.2+.
Un archivo kubeconfig en funcionamiento que apunte a un clúster con una instalación de Apigee Hybrid 1.12 en funcionamiento.
Permisos para modificar los metadatos y las anotaciones en los recursos de Kubernetes de los componentes híbridos que deseas migrar.

Alcance

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 [--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]]⁽¹⁾`	`ORG_NAME-ENV_NAME[-env[-n]]`⁽¹⁾
`apigee-virtualhost (envgroup)`	`VH_NAME[-env-group[-n]]`⁽¹⁾	`ORG_NAME-VH_NAME[-env-group[-n]]`⁽¹⁾
⁽¹⁾ 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:

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

Descarga la herramienta de migración.
Linux
1. Almacena el número de la versión más reciente en una variable con el siguiente comando:
  export VERSION=$(curl -s "https://storage.googleapis.com/apigee-release/hybrid/apigee-migration-tool/current-version.txt?ignoreCache=1")
2. Verifica que la variable se haya propagado con un número de versión mediante el siguiente comando. Si quieres usar una versión diferente, puedes guardarla en una variable de entorno.
  echo $VERSION
  Por ejemplo:
  echo $VERSION 1.0.5
3. Descarga el paquete de lanzamientos para tu sistema operativo con el siguiente comando:
  curl -LO https://storage.googleapis.com/apigee-release/hybrid/apigee-migration-tool/${VERSION}/apigee-helm-migration_linux_64.tar.gz
4. Extrae los archivos comprimidos con el siguiente comando:
  tar -xzf apigee-helm-migration_linux_64.tar.gz
macOS
1. Almacena el número de la versión más reciente en una variable con el siguiente comando:
  export VERSION=$(curl -s "https://storage.googleapis.com/apigee-release/hybrid/apigee-migration-tool/current-version.txt?ignoreCache=1")
2. Verifica que la variable se haya propagado con un número de versión mediante el siguiente comando. Si quieres usar una versión diferente, puedes guardarla en una variable de entorno.
  echo $VERSION
  Por ejemplo:
  echo $VERSION 1.0.5
3. Descarga el paquete de lanzamientos para tu sistema operativo con el siguiente comando:
  curl -LO https://storage.googleapis.com/apigee-release/hybrid/apigee-migration-tool/${VERSION}/apigee-helm-migration_mac_64.tar.gz
4. Extrae los archivos comprimidos con el siguiente comando:
  tar -xzf apigee-helm-migration_mac_64.tar.gz
Windows
1. Almacena el número de la versión más reciente en una variable con el siguiente 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. Verifica que la variable se haya propagado con un número de versión mediante el siguiente comando. Si quieres usar una versión diferente, puedes guardarla en una variable de entorno.
  echo %VERSION%
  Por ejemplo:
  echo %VERSION% 1.0.5
3. Descarga el paquete de lanzamientos para tu sistema operativo con el siguiente comando:
  curl -LO https://storage.googleapis.com/apigee-release/hybrid/apigee-migration-tool/%VERSION%/apigee-helm-migration_windows_64.tar.gz
4. Extrae los archivos comprimidos con el siguiente comando:
  tar xzvf apigee-helm-migration_windows_64.tar.gz

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:

Para las actualizaciones de varias organizaciones, se recomienda ejecutar apigee-helm-migration sin opciones para actualizar todos los componentes de la organización y el entorno.

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

Migra todos los componentes mediante un espacio de nombres personalizado:
```
./apigee-helm-migration --apigee-namespace my_custom_namespace
```

Migra solo los componentes operator y 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!

Apuntan a un archivo kubeconfig específico y especifican un nombre diferente para el espacio de nombres apigee.
```
./apigee-helm-migration --kubeconfig /abs/path/to/kubeconf --namespace org1_namespace
```
Migra todos los componentes, pero solo una organización:
```
./apigee-helm-migration --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.

Cambios en las propiedades de configuración

Realiza los siguientes cambios en tus archivos de anulaciones:

Apigee Hybrid administrado con Helm usa propiedades apigeeIngressGateway para configurar todas las puertas de enlace de entrada de Apigee en tu clúster. Las propiedades ingressGateways anulan la configuración de apigeeIngressGateway para la puerta de enlace de entrada individual con nombre.
Consulta apigeeIngressGateway
- Crea una estrofa apigeeIngressGateway adicional en tu archivo de anulaciones para cualquier propiedad ingressGateways que sea global para todas las puertas de enlace de entrada de tu clúster. Por ejemplo:
```
apigeeIngressGateway:
  image:
    url: "PATH_TO_REPOSITORY/apigee-asm-ingress"
    tag: "TAG"
```
  Por ejemplo:
```
apigeeIngressGateway:
  image:
    url: "gcr.io/apigee-release/hybrid/apigee-asm-ingress"
    tag: "1.17.8-asm.20-distroless"
```
- Asegúrate de incluir ingressGateways.name: Es obligatorio crear una instancia de tu puerta de enlace de entrada. Por ejemplo:
Han cambiado las propiedades para habilitar Workload Identity:
- gcp.workloadIdentity.enabled reemplaza a gcp.workloadIdentityEnabled.
- Si usas una sola cuenta de servicio para todos los componentes, puedes especificarla con: gcp.workloadIdentity.gsa. Por ejemplo:
```
gcp:
  workloadIdentity:
    enabled: true
    gsa: "apigee-non-prod@my-hybrid-project.iam.gserviceaccount.com"
```
- Si usas una cuenta de servicio independiente para cada componente (el estándar de la mayoría de las instalaciones de producción), especifica la cuenta de servicio con la propiedad gsa del componente. Por ejemplo:
```
logger:
  gsa: "apigee-logger@my-hybrid-project.iam.gserviceaccount.com"
```
Consulta: gcp.workloadIdentity.enabled, gcp.federatedWorkloadIdentity.enabled, Habilita Workload Identity en GKE o Habilita la federación de identidades para cargas de trabajo en AKS y EKS

Soluciona problemas

Existe un problema conocido con la herramienta de migración de Helm en la versión híbrida v1.12. Hasta que el problema se resuelva, la copia de seguridad y restablecimiento de Cassandra requerirá pasos adicionales.

Puedes seguir estos pasos:

Antes o después de ejecutar la herramienta de migración
Antes de instalar gráficos de Helm

Para instalar el parche de la solución alternativa, sigue estos pasos:

Asegúrate de que tu kubeconfig actual apunte al clúster que deseas migrar. Puedes seguir estos pasos desde cualquier directorio.

Crea un archivo llamado migration-operator-patch.yaml con el siguiente contenido:

# 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

Crea un archivo migration-datastore-patch.yaml con el siguiente contenido:

# 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

Ejecuta los siguientes comandos de 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: Puedes ignorar los errores not found.

Limpia los archivos de parche con los siguientes comandos:

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

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.

Importante: Cuando sigues las instrucciones de tu clúster migrado, debes omitir la marca ‑‑atomic de cualquier comando de Helm para evitar borrar recursos por accidente si el comando helm upgrade falla.

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