Referencia de asmcli

Descripció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:

  • Otorga los permisos de Identity and Access Management (IAM) necesarios en tu proyecto de Google Cloud.
  • Habilitar las APIs de Google necesarias en tu proyecto de Google Cloud
  • Configura una etiqueta en el clúster que identifique la malla.
  • Crea una cuenta de servicio que permita que los componentes del plano de datos, como el proxy de sidecar, accedan a los datos y recursos del proyecto de forma segura.
  • Registra el clúster en la flota si aún no está registrado.

Solo incluye la marca --enable_all cuando ejecutes asmcli para permitir que configure tu proyecto y clúster. Para obtener más información sobre las opciones y marcas 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 eres nuevo en Cloud Service Mesh y Istio, ve a Plataformas compatibles. La siguiente sección está diseñada para ayudar a Cloud Service Mesh existente a actualizar a 1.21.

Transición a asmcli

asmcli reemplaza a istioctl install y install_asm. Si bien aún puedes usar las herramientas heredadas en Cloud Service Mesh 1.11, daremos de baja y ya no serán compatibles con Cloud Service Mesh 1.12 ni versiones posteriores. Actualiza tus secuencias de comandos y herramientas para usar asmcli.

Todos los clústeres deben registrarse en un flota. Consulta Requisitos de las flotas para obtener más detalles.

Transición desde install_asm

Si estás familiarizado con install_asm, asmcli es similar, pero con las siguientes diferencias notables:

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

  • La mayoría de las opciones y marcas de asmcli se comportan de la misma manera que las para install_asm.

Transición desde istioctl install

Si estás familiarizado con istioctl install, si normalmente pasas un archivo YAML IstioOperator a través del 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 la malla de servicios de Cloud, nos referimos a estos archivos como archivos de superposición.

Plataformas compatibles

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

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

Referencia de asmcli

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

Opciones

Identifica el clúster Tienes las siguientes opciones para identificar el clúster:

Solo GKE.

-p|--project_id CLUSTER_PROJECT_ID
Es el ID del proyecto en el que se creó el clúster.
-n|--cluster_name CLUSTER_NAME
Es el nombre del clúster.
-l|--cluster_location CLUSTER_LOCATION
Es la zona (para los clústeres de zona única) o la región (para los clústeres regionales) en la que se creó el clúster.

Todas las plataformas

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

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

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

La autoridad certificadora (CA) que se usará para administrar certificados mutuos de TLS. Especificar mesh_ca para usar la autoridad certificadora de Cloud Service Mesh (autoridad certificadora de Cloud Service Mesh), gcp_cas usar Certificate Authority Service citadel para usar la AC de Istio Managed Cloud Service Mesh no es compatible con Istio de Google Cloud. Consulta los siguientes vínculos para obtener más información:

--channel CLOUD_SERVICE_MESH_CHANNEL

Usa --channel con un Canal de versiones de Cloud Service Mesh para aprovisionar la revisión del Plano de control asociada con ese canal de versiones. Por ejemplo, usa las etiquetas --channel rapid, --channel regular y --channel stable. Esta marca es obligatoria cuando se configuran ciertas funciones de Cloud Service Mesh en los clústeres de GKE Autopilot.

La opción --channel ya no es compatible con Cloud Service Mesh administrado, como se menciona en las Notas de la versión de CSM. El canal de versiones se determina en función del canal de versiones del clúster de GKE. Para obtener más información, consulta Canales de versiones de la malla de servicios de Cloud administrados.

--co|--custom_overlay OVERLAY_FILE
Usa --custom_overly con el nombre de un archivo YAML (denominado archivo de superposición) que contiene el recurso personalizado IstioOperator para configurar el plano de control en el clúster. Especificas un archivo de superposición para habilitar una función que no está habilitada de forma predeterminada. Cloud Service Mesh administrado no es compatible con la API de IstioOperator, por lo que no puedes usar --custom_overlay para configurar el plano de control administrado. asmcli debe poder ubicar el archivo de superposición, por lo que debe estar en el mismo directorio que asmcli o puedes especificar una ruta de acceso relativa. Para agregar 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 está registrado.
-k|--key_file FILE_PATH
Es 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 establecer la etiqueta topology.istio.io/network que se aplica al espacio de nombres istio-system. En GKE, --network_id usa el nombre de red del clúster de forma predeterminada. Para 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 un poco diferente:

  • Usa --custom_overlay cuando necesites cambiar la configuración en el archivo de superposición.

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

Para agregar varios archivos, especifica -o|--option y el nombre del 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 los parámetros de configuración necesarios para instalar Cloud Service Mesh. Especifica la marca --output-dir para especificar una ruta de acceso relativa a un directorio que se usará en su lugar. Una vez completado, el directorio especificado contiene los subdirectorios asm y istio-1.21.5-asm.7. El directorio asm contiene la configuración de la instalación. El directorio istio-1.21.5-asm.7 tiene el contenido extraído del archivo de instalación, que contiene istioctl, muestras y manifiestos. Si especificas --output-dir y el directorio ya contiene los archivos necesarios, la asmcli usará esos archivos en lugar de volver a descargarlos.

--platform PLATFORM {gcp|multicloud}

La plataforma o el proveedor del clúster de Kubernetes. La configuración predeterminada es gcp (para clústeres de GKE). Para todas las demás plataformas, usa multicloud.

-r|--revision_name REVISION NAME

Una etiqueta de revisión es un par clave-valor que se configura en el plano de control. La clave de la etiqueta de revisión siempre es istio.io/rev. De predeterminada, asmcli establece el valor de la etiqueta de revisión según la La versión de Cloud Service Mesh, por ejemplo: asm-1215-7. Incluye esta opción si deseas anular el valor predeterminado y especificar el tuyo. El argumento REVISION NAME debe ser una etiqueta DNS-1035. Esto significa que el nombre debe cumplir con estos requisitos:

  • Contener 63 caracteres como máximo.
  • Contener solo caracteres alfanuméricos en minúscula o “-”.
  • Comenzar con un carácter alfabético
  • Terminar con un carácter alfanumérico

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

-s|--service_account ACCOUNT
El nombre de una cuenta de servicio que se usa para instalar Cloud Service Mesh. Si no se especifica, se usa la cuenta de usuario activa en la configuración de gcloud actual. Si necesitas cambiar la cuenta de usuario activa, ejecuta gcloud auth login.

Opciones para el certificado personalizado de la CA de Istio

Si especificaste --ca citadel y usas una CA personalizada, incluye las siguientes opciones:

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

Para obtener más información, consulta Conecta Certificados de CA existentes.

Marcas de habilitación

Las marcas que comienzan con --enable dejan que la asmcli habilite la API de Google, establece los permisos necesarios de administración de identidades y accesos (IAM) y actualiza el clúster. Si lo prefieres, puedes actualizar tu proyecto y clúster antes de ejecutar asmcli. Todas las marcas de habilitación son incompatibles con asmcli validate. Si especificas una marca de habilitación cuando ejecutas asmcli validate, el comando finaliza 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 la cuenta de servicio o usuario de Google Cloud que ejecuta asmcli al rol cluster-admin de 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, en el que GCP_EMAIL_ADDRESS es la cuenta que usas para acceder a Google Cloud.
--enable_cluster_labels
Permite que asmcli establezca las etiquetas de clúster requeridas.
--enable_gcp_components

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

--enable_gcp_apis

Permite que asmcli habilite todas las API de Google obligatorias.

--enable_gcp_iam_roles

Permite que asmcli establezca los permisos de IAM necesarios.

--enable_meshconfig_init

Permite que la secuencia de comandos inicialice el extremo de meshconfig en tu nombre. Implícito en --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 en Registra un clúster para registrarlo de forma manual. 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 de clústeres. De lo contrario, debes especificar esta marca por separado.

Otras marcas

--dry_run
Imprime comandos, pero no los ejecutes.
--fleet_id
Registra un clúster en una flota mediante el ID del proyecto host de la flota. Esta marca es obligatoria para clústeres que no son de Google Cloud. Cuando no se proporciona para los clústeres de Google Cloud, se establece de forma predeterminada como 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 si pasas las marcas --enable-registration y --fleet-id. No se puede cambiar esta configuración después de establecerla.
--managed
Obsoleta. Aprovisiona un plano de control remoto administrado 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, la secuencia de comandos se cerrará con error.
--only_enable
Sigue los pasos especificados para configurar el usuario o clúster actual, pero no instale nada.
--only_validate
Ejecuta la validación, pero no actualices el proyecto o el clúster y no instales Cloud Service Mesh. Esta marca no es compatible con las marcas de habilitación. asmcli finaliza con un error si especificas --only_validate con cualquier marca de habilitación.
--print_config
En lugar de instalar Cloud Service Mesh, imprime todos los YAML compilados en resultados estándar (stdout). Todos los demás resultados se escriben en error estándar (stderr), incluso si, por lo general, van con stdout. asmcli omite todas las validaciones y la configuración cuando especificas esta marca.
--disable_canonical_service
De forma predeterminada, asmcli implementa el controlador del servicio canónico en tu clúster. Si no deseas que asmcli implemente el controlador, especifica --disable_canonical_service. Para obtener más información, consulta Habilita o inhabilita el controlador del servicio canónico.
-h|--help
Muestra un mensaje de ayuda que describe las opciones y las marcas, y se cierra.
--use_managed_cni
Usa la CNI administrada. Si no se pasa esta marca, asmcli aplicará los manifiestos estáticos de la CNI.
--use_vpcsc
Si tu organización aplica Controles del servicio de VPC en tu proyecto, debes configurar Cloud Service Mesh administrado con la marca --use_vpcsc. De lo contrario, la instalación no pasará los controles de seguridad.
-v|--verbose
A medida que se ejecuta asmcli, imprime el comando que se 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 se cierra. Si no tienes la versión más reciente, puedes descargar la versión más reciente de asmcli_1.21.