Esta página se ha traducido con Cloud Translation API.

Migrar 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 sustituye ningún componente del clúster. Es idempotente y se puede ejecutar muchas veces en el mismo clúster, preparando 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 componentes después de ejecutar la herramienta.

Consulta Instalar y gestionar Apigee hybrid con gráficos de Helm para obtener información sobre cómo gestionar los clústeres híbridos que hayas migrado a la gestión de Helm con esta herramienta.

Requisitos previos

Versión v3.14.2 o posterior de Helm.
Un archivo kubeconfig que apunte a un clúster con una instalación de Apigee hybrid 1.12 que funcione.
Permisos para modificar los metadatos y las anotaciones de los recursos de Kubernetes de los componentes híbridos que quieras migrar.

Ámbito

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

Personalización del espacio de nombres de los recursos de apigee. Espacio de nombres predeterminado: apigee
Migración solo de los componentes híbridos seleccionados. Valor 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 entornos (apigee-virtualhost)
Personalización de los nombres de las versiones de Helm para organizaciones, entornos y grupos de entornos.

Limitaciones

Esta herramienta no permite personalizar los nombres de las versiones de Helm de estos componentes híbridos: apigee-operator, apigee-datastore, apigee-redis, apigee-telemetry y apigee-ingress-manager.
Las personalizaciones interactivas que se hagan en los nombres de las versiones de Helm de las organizaciones, los entornos y los grupos de entornos no se conservarán automáticamente entre ejecuciones. Puedes editar el archivo temporal y proporcionarlo como opción en ejecuciones posteriores.
El filtrado de env y env-group se realiza solo por nombre. En algunos casos, esto podría provocar que se migren varios entornos y grupos de entornos en clústeres de varias organizaciones.

Por ejemplo, en un clúster de varias organizaciones con las 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 solo quieres migrar un 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 lanzamientos de Helm generados

Cada gráfico de Helm que se implemente en un clúster debe tener un nombre de lanzamiento, que debe ser único en un espacio de nombres. Los nombres de lanzamientos de Helm no tienen ninguna convención de nomenclatura ni restricción en relación con el nombre del gráfico. La herramienta de migración genera nombres únicos de lanzamientos de Helm para cada componente.

Gráfico	Clúster de una sola organización	Clúster de varias organizaciones
`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. Si siguen en conflicto, se les añade el sufijo `-1` o `-2 …`.

Personalizar los nombres de las versiones de Helm

La herramienta de migración permite personalizar de forma interactiva los nombres de las versiones de Helm. Si quieres personalizar los nombres de los lanzamientos de Helm de forma no interactiva, sigue estos pasos:

Ejecuta la herramienta una vez y sal en la primera petición para crear un archivo temporal que contenga los nombres de lanzamiento generados automáticamente. Debería aparecer una línea como esta:
```
INFO: 21:32:56 using temp file for release names:  /tmp/apigee-helm-migration-1229129207-releaseNames
```
Mueve o copia el archivo y, a continuación, edítalo. Puedes enviar este archivo editado con la opción -f cuando ejecutes la herramienta de migración. Los nombres de las versiones generados automáticamente tienen este formato:
```
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 de 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, el de la versión del entorno a custom-env y el de la versión del grupo de entornos a custom-group, el archivo resultante sería el siguiente:
```
orgs:
  example-apigee-org:
    helmReleaseName: custom-org
    envs:
      prod:
        helmReleaseName: custom-env
    envGroups:
      prod-envgroup:
        helmReleaseName: custom-group
```

Usar 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 espacio de nombres apigee-system. La herramienta de migración de Helm actualizará el componente apigee-operator en el espacio de nombres apigee-system, independientemente de 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 de Helm.

También debes añadir la propiedad de nivel superior namespace: my_custom_namespace al archivo de anulaciones.

Directions

Descarga la herramienta de migración.
Linux
1. Almacena el número de la última versión 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. Comprueba que la variable se haya rellenado con un número de versión mediante el siguiente comando. Si quieres usar otra versión, puedes guardarla en una variable de entorno.
  echo $VERSION
  Por ejemplo:
  echo $VERSION 1.0.5
3. Descarga el paquete de lanzamiento de 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 última versión 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. Comprueba que la variable se haya rellenado con un número de versión mediante el siguiente comando. Si quieres usar otra versión, puedes guardarla en una variable de entorno.
  echo $VERSION
  Por ejemplo:
  echo $VERSION 1.0.5
3. Descarga el paquete de lanzamiento de 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 última versión 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. Comprueba que la variable se haya rellenado con un número de versión mediante el siguiente comando. Si quieres usar otra versión, puedes guardarla en una variable de entorno.
  echo %VERSION%
  Por ejemplo:
  echo %VERSION% 1.0.5
3. Descarga el paquete de lanzamiento de 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, basta con ejecutar la herramienta sin ningún argumento y aprobar la petición si los nombres de lanzamiento de Helm generados son satisfactorios. A continuación, se muestran algunos ejemplos:

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

Una instalación sencilla que usa el kubeconfig (~/.kube/config) predeterminado, el espacio de nombres apigee predeterminado y los nombres de lanzamiento de Helm predeterminados.

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

Migrar todos los componentes que usan un espacio de nombres personalizado:
```
./apigee-helm-migration --apigee-namespace my_custom_namespace
```

Migrar 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!

Señalar un archivo kubeconfig específico y especificar otro nombre para el espacio de nombres apigee.
```
./apigee-helm-migration --kubeconfig /abs/path/to/kubeconf --namespace org1_namespace
```
Migrar todos los componentes, pero solo una organización:
```
./apigee-helm-migration --org=some-test-org
```

A continuación, se muestra un ejemplo de resultado 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:

Error al analizar el archivo de nombres de lanzamientos: compruebe el archivo de nombres de lanzamientos que se ha proporcionado.
No se han encontrado recursos: comprueba que Apigee hybrid esté instalado por completo y que tengas permisos para acceder a los recursos de apigee.

Cambios en las propiedades de configuración

Haz los siguientes cambios en tus archivos de anulaciones:

Usa metrics.appStackdriverExporter.* en lugar de metrics.aggregator.*.
Apigee Hybrid gestionado con Helm usa las propiedades de apigeeIngressGateway para configurar todas las pasarelas de entrada de Apigee de tu clúster. Las propiedades de ingressGateways anulan los ajustes de apigeeIngressGateway de la pasarela de entrada con nombre.
Consulta apigeeIngressGateway.
- Crea una sección apigeeIngressGateway adicional en el archivo de anulaciones para las propiedades ingressGateways que sean globales para todas las pasarelas 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 pasarela de entrada. Por ejemplo:

Nota: ingressGateways es una colección de instancias de ingressGateway individuales. Gestiona la configuración de las instancias ingressGateway. Usa ingressGateways en tu archivo de anulaciones.

Las propiedades para habilitar Workload Identity han cambiado:
- gcp.workloadIdentity.enabled sustituye 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 en 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, Habilitar Workload Identity en GKE o Habilitar Workload Identity Federation en AKS y EKS.

Solución de problemas

Hay un problema conocido con la herramienta de migración de Helm en la versión híbrida 1.12. Hasta que se resuelva el problema, la copia de seguridad y restauración de Cassandra requiere pasos adicionales.

Para hacerlo, sigue 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 quieras 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 llamado 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 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

Paso siguiente

Continúa con la instalación de los gráficos de Helm de Apigee Hybrid siguiendo las instrucciones de Instalar y gestionar Apigee Hybrid con gráficos de Helm.

Importante: Cuando sigas las instrucciones de tu clúster migrado, debes omitir la marca ‑‑atomic de cualquier comando de Helm para evitar que se eliminen recursos por error si falla el comando helm upgrade.

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