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.10+.
-
Un archivo
kubeconfig
en funcionamiento que apunte a un clúster con una instalación de Apigee Hybrid 1.13 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
yapigee-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
yorg2
, si el entornoprod
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]](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 |
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 acustom-org
, la versión del entorno acustom-env
y la versión del grupo de entornos acustom-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 v1.13 y versiones posteriores se ejecutan en un solo espacio de nombres de Kubernetes. Todos los componentes híbridos 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
-
Ubica la herramienta de migración.
La herramienta de migración se empaqueta con
apigeectl
en/tools/migration/
. -
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
-
Mac:
-
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 predeterminadoapigee
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
ydatastore
:./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 nombresapigee
../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 propiedadesingressGateways
anulan la configuración deapigeeIngressGateway
para la puerta de enlace de entrada individual con nombre.Consulta
apigeeIngressGateway
- Cambia las propiedades
ingressGateways
que sean globales para todas las puertas de enlace de entrada de tu clúster a propiedadesapigeeIngressGateway
. Tu archivo de anulación debe contener al menos lo siguiente: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 necesario crear una instancia de tu puerta de enlace de entrada. Por ejemplo:
ingressGateways: name: INGRESS_GATEWAY_NAME
- Cambia las propiedades
- Han cambiado las propiedades para habilitar Workload Identity:
gcp.workloadIdentity.enabled
reemplaza agcp.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_NAMESPACE 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
- 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.
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