Referencia de asmcli

Nota: Esta guía solo admite Cloud Service Mesh con APIs de Istio y no admite APIs de Google Cloud . Para obtener más información, consulta la descripción general de Cloud Service Mesh.

Información general

asmcli es una herramienta proporcionada por Google que puedes usar para instalar o actualizar Cloud Service Mesh. Si lo permites, asmcli configurará tu proyecto y tu clúster de la siguiente manera:

• Concederte los permisos de gestión de identidades y accesos (IAM) necesarios en tuGoogle Cloud proyecto.
• Habilita las APIs de Google necesarias en tu Google Cloud proyecto.
• Define una etiqueta en el clúster que identifique la malla.
• Crea una cuenta de servicio que permita a los componentes del plano de datos, como el proxy sidecar, acceder de forma segura a los datos y recursos de tu proyecto.
• Registra el clúster en la flota si aún no lo has hecho.

Solo tienes que incluir la marca --enable_all al ejecutar asmcli para que configure tu proyecto y tu clúster. Para obtener más información sobre las opciones y las marcas de asmcli, consulta la referencia de asmcli.

A continuación, asmcli configura los archivos YAML con la información de tu proyecto y clúster. Estos archivos de configuración son necesarios para instalar el plano de control de Cloud Service Mesh.

Si no conoces Cloud Service Mesh e Istio, ve a la sección Plataformas compatibles. En la siguiente sección se explica cómo actualizar a 1.27si ya usas Cloud Service Mesh.

Cambiando a asmcli

El asmcli sustituye a istioctl install y install_asm. Aunque puedes seguir usando las herramientas antiguas en Cloud Service Mesh 1.11, vamos a dejar de ofrecerlas y ya no se admitirán en Cloud Service Mesh 1.12 ni en versiones posteriores. Actualiza tus secuencias de comandos y herramientas para usar asmcli.

Todos los clústeres deben registrarse en una flota. Para obtener más información, consulta los requisitos de la flota.

Cambiar de install_asm

Si ya conoces install_asm, asmcli es similar, pero con las siguientes diferencias notables:

• Utiliza asmcli install para las nuevas instalaciones y actualizaciones. No hay una opción --mode como en el caso de install_asm. Cuando ejecutas asmcli install, se comprueba si hay un plano de control en el clúster. Si no hay ningún plano de control, asmcli instala Cloud Service Mesh. Si el clúster tiene un plano de control (ya sea un plano de control de Cloud Service Mesh o un plano de control de Istio de código abierto):

  • Si la etiqueta de revisión del plano de control actual no coincide con la etiqueta de revisión del nuevo plano de control, asmcli realiza una actualización canary.

  • Si las etiquetas de revisión del plano de control son las mismas, asmcli realiza una actualización in situ.

• La mayoría de las asmcli opciones y las marcas se comportan igual que las de install_asm.

Cambiar de istioctl install

Si conoces istioctl install y normalmente pasas un archivo YAML de IstioOperator mediante el argumento de línea de comandos -f para configurar el plano de control, puedes pasar el archivo a asmcli mediante la opción --custom_overlay. En la documentación de Cloud Service Mesh, nos referimos a estos archivos como archivos de superposición.

Nota: De forma predeterminada, asmcli no instala una pasarela de entrada con el plano de control. En las implementaciones de producción, te recomendamos que instales las pasarelas por separado. Para obtener más información y consultar las prácticas recomendadas, consulta el artículo Instalar y actualizar gateways. Hemos proporcionado archivos de configuración de ejemplo de Deployment, Service, ServiceAccount y Role en el repositorio anthos-service-mesh para las dos pasarelas (de entrada y de salida) para que puedas empezar. Puedes implementarlas tal cual o personalizarlas según sea necesario.

Plataformas compatibles

Obsoleto: ya no se puede configurar Cloud Service Mesh con asmcli para el plano de control gestionado de GKE en Google Cloud . Para obtener más información, consulta las notas de la versión de Cloud Service Mesh. Para configurar Managed Cloud Service Mesh para GKE, sigue esta guía.

Las instalaciones de Cloud Service Mesh en la lista de plataformas admitidas se pueden configurar o actualizar mediante asmcli.

Sin embargo, no todas las funciones están disponibles en las plataformas que no son de Google Cloud. Para obtener más información, consulta Funciones admitidas del plano de control en el clúster.

Referencia de asmcli

En esta sección se describen los argumentos disponibles para asmcli.

Nota: Ejecuta el comando ./asmcli -h -v para ver una lista completa de las marcas y opciones disponibles, así como sus descripciones.

Opciones

Identificar el clúster Para identificar el clúster, tienes las siguientes opciones:

Solo GKE

-p|--project_id CLUSTER_PROJECT_ID

El ID del proyecto en el que se creó el clúster.

-n|--cluster_name CLUSTER_NAME

El nombre del clúster.

-l|--cluster_location CLUSTER_LOCATION

La zona (en el caso de los clústeres de zona única) o la región (en el caso de los clústeres regionales) en la que se creó el clúster.

Todas las plataformas

--kubeconfig KUBECONFIG_FILE Ruta completa al archivo kubeconfig. La variable de entorno $PWD no funciona aquí.

--ctx|--context KUBE_CONTEXT El contexto de kubeconfig que se va a usar. Si no se especifica, asmcli usa el contexto predeterminado.

Advertencia: Utiliza solo archivos kubeconfig de fuentes de confianza. Si se usa un archivo kubeconfig especialmente diseñado, se podría ejecutar código malicioso o se podrían exponer archivos. Si debes usar un archivo kubeconfig que no sea de confianza, inspecciónalo primero con cuidado, como harías con un script de shell.

-c|--ca {mesh_ca|gcp_cas|citadel}

La autoridad de certificación que se va a usar para gestionar los certificados TLS mutuo. Especifica mesh_ca para usar la autoridad de certificación de Cloud Service Mesh, gcp_cas para usar Servicio de Autoridades de Certificación o citadel para usar la AC de Istio. Managed Cloud Service Mesh no admite la CA de Istio. Consulta la siguiente información adicional:

• Elegir una autoridad de certificación
• Opciones de certificado personalizado de la AC de Istio
• Configurar Cloud Service Mesh para usar el Servicio de AC

--channel CLOUD_SERVICE_MESH_CHANNEL

Usa --channel con un canal de lanzamiento de Cloud Service Mesh específico para aprovisionar la revisión del plano de control asociada a ese canal de lanzamiento. Por ejemplo, --channel rapid, --channel regular y --channel stable. Esta marca es obligatoria al configurar determinadas funciones de Cloud Service Mesh en clústeres de Autopilot de GKE.

La opción --channel ya no se admite en la malla de servicios de Cloud gestionada, tal como se indica en las notas de la versión de CSM. El canal de lanzamiento se determina en función del canal de lanzamiento de tu clúster de GKE. Para obtener más información, consulta Canales de lanzamiento de Managed Cloud Service Mesh.

--co|--custom_overlay OVERLAY_FILE

Usa --custom_overly con el nombre de un archivo YAML (denominado archivo de superposición) que contenga el recurso personalizado IstioOperator para configurar el plano de control del clúster. Especifica un archivo de superposición para habilitar una función que no está habilitada de forma predeterminada. Managed Cloud Service Mesh no admite la API IstioOperator, por lo que no puedes usar --custom_overlay para configurar el plano de control gestionado. asmcli debe poder localizar el archivo de superposición, por lo que debe estar en el mismo directorio que asmcli o puedes especificar una ruta relativa. Para añadir varios archivos, especifica --co|--custom_overlay y el nombre del archivo. Por ejemplo: --co overlay_file1.yaml --co overlay_file2.yaml --co overlay_file3.yaml

--hub-registration-extra-flags HUB_REGISTRATION_EXTRA_FLAGS

Si usas clústeres de Amazon EKS adjuntos, usa --hub-registration-extra-flags para registrar el clúster en la flota si aún no lo has hecho.

-k|--key_file FILE_PATH

El archivo de claves de una cuenta de servicio. Omite esta opción si no usas una cuenta de servicio.

--network_id NETWORK_ID

Usa --network_id para definir la etiqueta topology.istio.io/network aplicada al espacio de nombres istio-system. En GKE, --network_id tiene como valor predeterminado el nombre de la red del clúster. En otros entornos, se usará default.

-o|--option OVERLAY_FILE

El nombre del archivo de superposición (sin la extensión .yaml) que asmcli descarga del repositorio anthos-service-mesh para habilitar una función opcional. Necesitas conexión a Internet para usar --option. Las opciones --option y --custom_overlay son similares, pero tienen un comportamiento ligeramente diferente:

• Usa --custom_overlay cuando necesites cambiar los ajustes del archivo de superposición.

• Usa --option para habilitar una función que no requiera cambios en el archivo de superposición. Por ejemplo, para configurar políticas de auditoría para tus servicios.

Para añadir varios archivos, especifica -o|--option y el nombre de archivo. Por ejemplo: -o option_file1 -o option_file2 -o option_file3

-D|--output_dir DIR_PATH

Si no se especifica, asmcli crea un directorio temporal en el que descarga los archivos y las configuraciones necesarios para instalar Cloud Service Mesh. Especifica la marca --output-dir para indicar una ruta relativa a un directorio que quieras usar. Una vez completado el proceso, el directorio especificado contendrá los subdirectorios asm y istio-1.27.1-asm.5. El directorio asm contiene la configuración de la instalación. El directorio istio-1.27.1-asm.5 contiene el contenido extraído del archivo de instalación, que incluye istioctl, muestras y manifiestos. Si especifica --output-dir y el directorio ya contiene los archivos necesarios, asmcli usa esos archivos en lugar de descargarlos de nuevo.

--platform PLATFORM {gcp|multicloud}

La plataforma o el proveedor del clúster de Kubernetes. El valor predeterminado es gcp (en el caso de los clústeres de GKE). Para usarlo en otras plataformas, multicloud.

-r|--revision_name REVISION NAME

Una etiqueta de revisión es un par clave-valor que se define en el plano de control. La clave de la etiqueta de revisión siempre es istio.io/rev. De forma predeterminada, asmcli define el valor de la etiqueta de revisión en función de la versión de Cloud Service Mesh. Por ejemplo, asm-1271-5. Incluye esta opción si quieres anular el valor predeterminado y especificar el tuyo. El argumento REVISION NAME debe ser una etiqueta DNS-1035. Esto significa que el nombre debe:

• Contener como máximo 63 caracteres
• Contener únicamente caracteres alfanuméricos en minúscula o guiones ("-")
• Empezar por un carácter alfabético
• terminar con un carácter alfanumérico

La expresión regular que se usa para la validación es: '[a-z]([-a-z0-9]*[a-z0-9])?'

-s|--service_account ACCOUNT

Nombre de una cuenta de servicio que se usa para instalar Cloud Service Mesh. Si no se especifica, se usará la cuenta de usuario activa en la configuración actual de gcloud. Si necesitas cambiar la cuenta de usuario activa, ejecuta gcloud auth login.

Opciones para el certificado personalizado de la AC de Istio

Si ha especificado --ca citadel y está usando una CA personalizada, incluya las siguientes opciones:

• --ca_cert FILE_PATH: el certificado intermedio
• --ca_key FILE_PATH: la clave del certificado intermedio
• --root_cert FILE_PATH: el certificado raíz
• --cert_chain FILE_PATH: la cadena de certificados

Para obtener más información, consulta Conectar certificados de CA.

Enablement flags

Las marcas que empiezan por --enable permiten a asmcli habilitar las APIs de Google necesarias, definir los permisos de gestión de identidades y accesos (IAM) necesarios y actualizar el clúster. Si lo prefieres, puedes actualizar el proyecto y el clúster antes de ejecutar asmcli. Todas las marcas de habilitación son incompatibles con asmcli validate. Si especifica un indicador de habilitación al ejecutar asmcli validate, el comando finalizará con un error.

-e|--enable_all

Permite que asmcli realice todas las acciones de habilitación individuales que se describen a continuación.

--enable_cluster_roles

Permite que asmcli intente vincular el Google Cloud usuario o la cuenta de servicio que ejecuta asmcli al rol cluster-admin en tu clúster. asmcli determina la cuenta de usuario a partir del comando gcloud config get core/account. Si ejecutas asmcli de forma local con una cuenta de usuario, asegúrate de llamar al comando gcloud auth login antes de ejecutar asmcli. Si necesitas cambiar la cuenta de usuario, ejecuta el comando gcloud config set core/account GCP_EMAIL_ADDRESS donde GCP_EMAIL_ADDRESS es la cuenta que usas para iniciar sesión en Google Cloud.

--enable_cluster_labels

Permitir que asmcli defina las etiquetas de clúster

obligatorias.

--enable_gcp_components

Permite que asmcli habilite los siguientes servicios y componentes Google Cloud gestionados obligatorios:

• Workload Identity, que permite a las aplicaciones de GKE acceder de forma segura a los servicios de Google Cloud.

• Cloud Monitoring y Cloud Logging en GKE.

--enable_gcp_apis

Permite que asmcli habilite todas las APIs de Google necesarias.

--enable_gcp_iam_roles

Permite que asmcli establezca los permisos de gestión de identidades y accesos necesarios.

--enable_meshconfig_init

Permite que la secuencia de comandos inicialice el endpoint meshconfig en tu nombre. Implícito por --enable_gcp_components y --managed.

--enable_namespace_creation

Permite que asmcli cree el espacio de nombres raíz istio-system.

--enable_registration

Permite que asmcli registre el clúster en el proyecto en el que se encuentra. Si no incluyes esta marca, sigue los pasos que se indican en Registrar un clúster para registrarlo manualmente. Ten en cuenta que, a diferencia de las otras marcas de habilitación, --enable_registration solo se incluye en --enable_all cuando especificas una opción (como --option hub-meshca) que requiere el registro del clúster. De lo contrario, tendrás que especificar este valor por separado.

Otras marcas

--dry_run

Imprime los comandos, pero no los ejecuta.

--fleet_id

Registra un clúster en una flota con el ID del proyecto host de la flota. Esta marca es obligatoria para los clústeres que no sean deGoogle Cloud . Si no se proporciona para los clústeres deGoogle Cloud , se utiliza de forma predeterminada el ID del proyecto del clúster. Puedes ejecutar asmcli install junto con --fleet_id antes de la instalación o como parte de la instalación pasando las marcas --enable-registration y --fleet-id. Este ajuste no se puede cambiar una vez que se haya configurado.

--managed

Obsoleta. Aprovisiona un plano de control gestionado remoto en lugar de instalar uno en el clúster.

--offline

Realiza una instalación sin conexión con el paquete descargado previamente en el directorio de salida. Si no se especifica el directorio o no contiene los archivos necesarios, el script se cerrará con un error.

--only_enable

Realiza los pasos especificados para configurar el usuario o clúster actual, pero no instala nada.

--only_validate

Ejecuta la validación, pero no actualices el proyecto ni el clúster, y no instales Cloud Service Mesh. Esta marca no es compatible con las marcas de habilitación. asmcli termina con un error si especificas --only_validate con cualquier marca de habilitación.

--print_config

En lugar de instalar Cloud Service Mesh, imprime todo el YAML compilado en la salida estándar (stdout). El resto de la salida se escribe en el error estándar (stderr), aunque normalmente se escribiría en stdout. asmcli omite todas las validaciones y la configuración cuando especificas esta marca.

--disable_canonical_service

Obsoleta. El controlador del servicio canónico gestionado siempre se aprovisiona.

-h|--help

Muestra un mensaje de ayuda que describe las opciones y las marcas, y sale.

--use_managed_cni

Usa el CNI gestionado. Si no se pasa esta marca, asmcli aplicará los manifiestos de CNI estáticos.

--use_vpcsc

Si tu organización aplica Controles de Servicio de VPC en tu proyecto, debes configurar Cloud Service Mesh gestionado con la marca --use_vpcsc. De lo contrario, la instalación no superará los controles de seguridad.

-v|--verbose

Mientras se ejecuta asmcli, imprime el comando que ejecutará a continuación. Con la marca --verbose, asmcli también imprime el comando después de la ejecución.

--version

Imprime la versión de asmcli y sale. Si no tienes la versión más reciente, puedes descargar la versión más reciente de asmcli_1.27.