Référence asmcli

{version_1.0.1 d

Présentation

asmcli est un outil fourni par Google que vous pouvez utiliser pour installer ou mettre à niveau Cloud Service Mesh. Si vous le permettez, asmcli configurera votre projet et votre cluster comme suit :

  • Accordez les autorisations IAM (gestion de l'authentification et des accès) requises sur votre projet Google Cloud.
  • Activer les API Google requises sur votre projet Google Cloud
  • définissant une étiquette sur le cluster qui identifie le réseau maillé ;
  • Créez un compte de service permettant aux composants du plan de données, tels que le proxy side-car, d'accéder en toute sécurité aux données et aux ressources de votre projet.
  • Enregistrer le cluster dans le parc si ce n'est déjà fait.

Il vous suffit d'inclure l'indicateur --enable_all lorsque vous exécutez asmcli pour lui permettre de configurer votre projet et votre cluster. Pour en savoir plus sur les options asmcli, consultez la documentation de référence sur asmcli.

Ensuite, asmcli configure les fichiers YAML avec les informations de votre projet et de votre cluster. Ces fichiers de configuration sont nécessaires pour installer le plan de contrôle Cloud Service Mesh.

Si vous débutez avec Cloud Service Mesh et Istio, passez directement à la section Plates-formes compatibles. La section suivante est destinée à faciliter la mise à niveau de Cloud Service Mesh existant vers .

Passer à asmcli

asmcli remplace istioctl install et install_asm. Bien que vous puissiez toujours utiliser les anciens outils dans Cloud Service Mesh 1.11, nous les abandonnons et ne seront plus compatibles avec Cloud Service Mesh 1.12 et les versions ultérieures. Veuillez mettre à jour vos scripts et vos outils pour qu'ils utilisent asmcli.

Tous les clusters doivent être enregistrés dans un parc. Pour en savoir plus, consultez la section Exigences concernant le parc.

Effectuer la transition depuis install_asm

Si vous connaissez install_asm, asmcli est similaire, mais présente les différences notables suivantes :

  • Vous utilisez asmcli install pour les nouvelles installations et les mises à niveau. Aucune option --mode n'existe, comme avec install_asm. Lorsque vous exécutez asmcli install, il vérifie s'il existe un plan de contrôle sur le cluster. En l'absence de plan de contrôle existant, asmcli installe Cloud Service Mesh. Si le cluster dispose d'un plan de contrôle existant (un plan de contrôle Cloud Service Mesh ou un plan de contrôle Istio Open Source):

  • La plupart des options et indicateurs asmcli se comportent de la même manière que ceux de install_asm.

Effectuer la transition depuis istioctl install

Si vous connaissez bien istioctl install, si vous transmettez normalement un fichier YAML IstioOperator via l'argument de ligne de commande -f pour configurer le plan de contrôle, vous pouvez transmettre le fichier à asmcli à l'aide de l'option --custom_overlay. Dans la documentation de Cloud Service Mesh, ces fichiers sont appelés fichiers de superposition.

Plates-formes compatibles

Les installations Cloud Service Mesh figurant sur la liste des plates-formes compatibles peuvent être configurées ou mises à niveau par asmcli.

Cependant, toutes les fonctionnalités ne sont pas disponibles sur les plates-formes externes à Google Cloud. Pour en savoir plus, consultez la page Fonctionnalités compatibles avec le plan de contrôle au sein du cluster.

Référence asmcli

Cette section décrit les arguments disponibles pour asmcli.

Options

Identifier le cluster Vous disposez des options suivantes pour identifier le cluster :

Limitation à GKE

-p|--project_id CLUSTER_PROJECT_ID
ID du projet dans lequel le cluster a été créé.
-n|--cluster_name CLUSTER_NAME
Nom du cluster.
-l|--cluster_location CLUSTER_LOCATION
Zone (pour les clusters à zone unique) ou région (pour les clusters régionaux) dans laquelle le cluster a été créé.

Toutes les plates-formes

--kubeconfig KUBECONFIG_FILE Chemin d'accès complet au fichier kubeconfig. La variable d'environnement $PWD ne fonctionne pas ici.

--ctx|--context KUBE_CONTEXT Contexte kubeconfig à utiliser. Si cette option n'est pas spécifiée, asmcli utilise le contexte par défaut.

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

Autorité de certification à utiliser pour gérer les certificats TLS mutuels. Spécifiez mesh_ca pour utiliser l'autorité de certification Cloud Service Mesh (autorité de certification Cloud Service Mesh), gcp_cas pour utiliser Certificate Authority Service ou citadel pour utiliser l'autorité de certification Istio. Managed Cloud Service Mesh n'est pas compatible avec l'autorité de certification Istio. Pour en savoir plus, consultez les pages suivantes :

--channel ANTHOS_SERVICE_MESH_CHANNEL

Utilisez --channel avec un canal de publication Cloud Service Mesh spécifique pour provisionner la révision du plan de contrôle associée à ce version disponible. Par exemple, --channel rapid, --channel regular et --channel stable. Cette option est requise lors de la configuration de certaines fonctionnalités de Cloud Service Mesh sur des clusters GKE Autopilot.

--co|--custom_overlay OVERLAY_FILE

Utilisez --custom_overly avec le nom d'un fichier YAML (appelé fichier superposé) contenant la ressource personnalisée IstioOperator pour configurer le plan de contrôle au sein du cluster. Vous spécifiez un fichier superposé pour activer une fonctionnalité qui n'est pas activée par défaut. Le service géré Cloud Service Mesh n'est pas compatible avec l'API IstioOperator. Vous ne pouvez donc pas utiliser --custom_overlay pour configurer le plan de contrôle géré. asmcli doit pouvoir localiser le fichier superposé. Il doit donc se trouver dans le même répertoire que asmcli, ou vous pouvez spécifier un chemin d'accès relatif. Pour ajouter plusieurs fichiers, spécifiez --co|--custom_overlay et le nom du fichier, par exemple : --co overlay_file1.yaml --co overlay_file2.yaml --co overlay_file3.yaml

--hub-registration-extra-flags HUB_REGISTRATION_EXTRA_FLAGS

Si vous utilisez des clusters Amazon EKS associés, enregistrez le cluster à l'aide de --hub-registration-extra-flags si le parc n'est pas déjà enregistré.

-k|--key_file FILE_PATH

Fichier de clé d'un compte de service. Ne renseignez pas cette option si vous n'utilisez pas de compte de service.

--network_id NETWORK_ID

Utilisez --network_id pour définir le libellé topology.istio.io/network appliqué à l'espace de noms istio-system. Pour GKE, --network_id utilise par défaut le nom du réseau du cluster. Pour les autres environnements, la valeur default est utilisée.

-o|--option OVERLAY_FILE

Nom du fichier superposé (sans l'extension .yaml) téléchargé par asmcli à partir du dépôt anthos-service-mesh pour activer une fonctionnalité facultative. Vous devez disposer d'une connexion Internet pour utiliser --option. Les options --option et --custom_overlay sont similaires, mais elles présentent un comportement légèrement différent :

  • Utilisez --custom_overlay lorsque vous devez modifier les paramètres dans le fichier superposé.

  • Utilisez --option pour activer une fonctionnalité qui ne nécessite pas d'apporter des modifications au fichier superposé, par exemple, pour configurer des règles d'audit pour vos services.

Pour ajouter plusieurs fichiers, spécifiez -o|--option et le nom du fichier, par exemple : -o option_file1 -o option_file2 -o option_file3

-D|--output_dir DIR_PATH

S'il n'est pas spécifié, asmcli crée un répertoire temporaire dans lequel il télécharge les fichiers et les configurations nécessaires à l'installation de Cloud Service Mesh. Spécifiez l'option --output-dir pour spécifier un chemin d'accès relatif vers un répertoire à utiliser à la place. Une fois l'opération terminée, le répertoire spécifié contient les sous-répertoires asm et . Le répertoire asm contient la configuration pour l'installation. Le répertoire contient le contenu extrait du fichier d'installation, qui contient istioctl, des exemples et des fichiers manifestes. Si vous spécifiez --output-dir et que le répertoire contient déjà les fichiers nécessaires, asmcli utilise ces fichiers au lieu de les télécharger à nouveau.

--platform PLATFORM {gcp|multicloud}

Plate-forme ou fournisseur du cluster Kubernetes. La valeur par défaut est gcp (pour les clusters GKE). Pour toutes les autres plates-formes, multicloud.

-r|--revision_name REVISION NAME

Un libellé de révision est une paire clé-valeur définie sur le plan de contrôle. La clé du libellé de révision est toujours istio.io/rev. Par défaut, asmcli définit la valeur du libellé de révision en fonction de la version de Cloud Service Mesh, par exemple: . Incluez cette option si vous souhaitez remplacer la valeur par défaut et spécifier la vôtre. L'argument REVISION NAME doit être un libellé DNS-1035. Cela signifie que le nom doit :

  • contenir au maximum 63 caractères ;
  • contenir uniquement des caractères alphanumériques en minuscules ou "-" ;
  • commencer par un caractère alphabétique ;
  • se terminer par un caractère alphanumérique.

L'expression régulière utilisée pour la validation est la suivante : '[a-z]([-a-z0-9]*[a-z0-9])?'

-s|--service_account ACCOUNT
Nom d'un compte de service utilisé pour installer Cloud Service Mesh. S'il n'est pas spécifié, le compte utilisateur actif dans la configuration gcloud actuelle est utilisé. Si vous devez modifier le compte utilisateur actif, exécutez la commande gcloud auth login.

Options pour le certificat personnalisé Istio CA

Si vous avez spécifié --ca citadel et que vous utilisez une autorité de certification personnalisée, incluez les options suivantes :

  • --ca_cert FILE_PATH : le certificat intermédiaire
  • --ca_key FILE_PATH : la clé du certificat intermédiaire
  • --root_cert FILE_PATH : le certificat racine
  • --cert_chain FILE_PATH : la chaîne de certificats

Pour en savoir plus, consultez la page Connecter des certificats CA existants.

Options d'activation

Les options commençant par --enable permettent à asmcli d'activer les API Google nécessaires, de définir les autorisations IAM (Identity and Access Management) requises et de mettre à jour votre cluster. Si vous préférez, vous pouvez mettre à jour votre projet et votre cluster vous-même avant d'exécuter asmcli. Toutes les options d'activation sont incompatibles avec asmcli validate. Si vous spécifiez une option d'activation lorsque vous exécutez asmcli validate, la commande se termine par une erreur.

-e|--enable_all
Autorise asmcli à effectuer toutes les actions d'activation individuelles décrites ci-dessous.
--enable_cluster_roles
Autorise asmcli à tenter de lier l'utilisateur ou le compte de service Google Cloud qui exécute asmcli au rôle cluster-admin sur le cluster. asmcli identifie le compte utilisateur à l'aide de la commande gcloud config get core/account. Si vous exécutez asmcli en local avec un compte utilisateur, veillez à appeler la commande gcloud auth login avant d'exécuter asmcli. Si vous devez modifier le compte utilisateur, exécutez la commande gcloud config set core/account GCP_EMAIL_ADDRESS, où GCP_EMAIL_ADDRESS correspond au compte que vous utilisez pour vous connecter à Google Cloud.
--enable_cluster_labels
Autorise asmcli à définir les libellés de cluster requis.
--enable_gcp_components

Autorise asmcli à activer les services gérés et composants Google Cloud requis suivants :

--enable_gcp_apis

Autorise asmcli à activer toutes les API Google requises.

--enable_gcp_iam_roles

Autorise asmcli à définir les autorisations IAM requises.

--enable_meshconfig_init

Autorisez le script à initialiser le point de terminaison meshconfig en votre nom. Implications par --enable_gcp_components et --managed.

--enable_namespace_creation

Autorisez asmcli à créer l'espace de noms racine istio-system.

--enable_registration

Autorise asmcli à enregistrer le cluster dans le projet dans lequel il se trouve. Si vous n'incluez pas cette option, suivez les étapes décrites dans la section Enregistrer un cluster pour enregistrer manuellement le cluster. Notez que, contrairement aux autres options d'activation, --enable_registration n'est inclus dans --enable_all que lorsque vous spécifiez une option (par exemple, --option hub-meshca) nécessitant l'enregistrement du cluster. Sinon, vous devez spécifier cette option séparément.

Autres options

--dry_run
Imprimer les commandes, mais ne pas les exécuter.
--fleet_id
Enregistre un cluster dans un parc à l'aide de l'ID de projet hôte du parc Cette option est requise pour les clusters autres que Google Cloud. Lorsqu'elle n'est pas fournie pour les clusters Google Cloud, elle utilise par défaut l'ID de projet du cluster. Vous pouvez exécuter asmcli install avec --fleet_id avant l'installation ou pendant l'installation en transmettant les options --enable-registration et --fleet-id. Ce paramètre ne peut plus être modifié une fois configuré.
--managed
Provisionnez un plan de contrôle géré à distance au lieu d'en installer un en cluster.
--offline
Effectuez une installation hors connexion à l'aide du package prétéléchargé dans le répertoire de sortie. Si le répertoire n'est pas spécifié ou ne contient pas les fichiers requis, le script se terminera avec une erreur.
--only_enable
Suivez la procédure spécifiée pour configurer l'utilisateur/le cluster actuel, mais cela n'installe rien.
--only_validate
Exécutez la validation, mais ne mettez pas à jour le projet ou le cluster, et n'installez pas Cloud Service Mesh. Cette option n'est pas compatible avec les options d'activation. asmcli se termine par une erreur si vous spécifiez --only_validate avec une option d'activation.
--print_config
Au lieu d'installer Cloud Service Mesh, imprimez tout le fichier YAML compilé sur la sortie standard (stdout). Toutes les autres sorties sont générées pour les erreurs standards (stderr), même si elles se rendent normalement dans stdout. asmcli ignore toutes les validations et la configuration lorsque vous spécifiez cette option.
--disable_canonical_service
Par défaut, asmcli déploie le contrôleur de service canonique sur votre cluster. Si vous ne souhaitez pas que asmcli déploie le contrôleur, spécifiez --disable_canonical_service. Pour en savoir plus, consultez la page Activer et désactiver le contrôleur de service canonique.
-h|--help
Affiche un message d'aide décrivant les options, puis ferme.
--use_managed_cni
Utiliser l'interface CNI gérée Si cet indicateur n'est pas transmis, asmcli appliquera les fichiers manifestes CNI statiques.
--use_vpcsc
Si votre organisation applique VPC Service Controls pour votre projet, vous devez configurer le service géré Cloud Service Mesh avec l'option --use_vpcsc. Sinon, l'installation ne sera pas en mesure d'effectuer les contrôles de sécurité.
-v|--verbose
Lorsque asmcli s'exécute, il imprime la commande qu'il exécutera ensuite. Avec l'option --verbose, asmcli imprime également la commande après l'exécution.
--version
Imprimez la version de asmcli, puis quittez. Si vous ne disposez pas de la version la plus récente, vous pouvez télécharger la version la plus récente de .