Documentation de référence sur asmcli
Présentation
Le 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.
- Activez les API Google requises sur votre projet Google Cloud.
- Définir un libellé 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 à l'installation de Cloud Service Mesh
plan de contrôle.
Si vous débutez avec Cloud Service Mesh et Istio, passez à la section Plates-formes compatibles. La section suivante vise à aider Cloud Service Mesh à passer à 1.21.
Passer à asmcli
asmcli
remplace istioctl install
et install_asm
. Bien que vous puissiez toujours utiliser les anciens outils de Cloud Service Mesh 1.11, nous les abandonnons et ils ne seront plus compatibles avec Cloud Service Mesh 1.12 et versions ultérieures.
Veuillez mettre à jour vos scripts et vos outils pour qu'ils utilisent asmcli
.
Tous les clusters doivent être enregistrés sur 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 avecinstall_asm
. Lorsque vous exécutezasmcli install
, il vérifie s'il existe un plan de contrôle sur le cluster. S'il n'existe aucun plan de contrôle,asmcli
installe Cloud Service Mesh. Si le cluster comporte un un plan de contrôle existant (un plan de contrôle Cloud Service Mesh ou un plan de contrôle plan de contrôle Istio):Si le libellé de révision sur le plan de contrôle existant ne correspond pas au libellé de révision du nouveau plan de contrôle,
asmcli
procède à une mise à niveau Canary.Si les libellés de révision du plan de contrôle sont identiques,
asmcli
effectue une mise à niveau sur place.
La plupart des options et indicateurs
asmcli
se comportent de la même manière que ceux deinstall_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 Cloud Service Mesh, ces fichiers sont appelés fichiers de superposition.
Plates-formes compatibles
Les installations Cloud Service Mesh de la liste des plates-formes compatibles peuvent être configurées ou mises à niveau par asmcli
.
Cependant, certaines fonctionnalités ne sont pas disponibles sur les plates-formes en dehors de 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,gcp_cas
pour utiliser Certificate Authority Service oucitadel
pour utiliser l'autorité de certification Istio. Cloud Service Mesh géré n'est pas compatible avec Istio CA. Pour en savoir plus, consultez les pages suivantes :--channel CLOUD_SERVICE_MESH_CHANNEL
Utiliser
--channel
avec un élément Version disponible de Cloud Service Mesh 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 Cloud Service Mesh sur les clusters GKE Autopilot.
L'option --channel
n'est plus disponible pour Managed Cloud Service Mesh car
mentionnées dans les notes de version CSM.
Le canal de publication est déterminé en fonction du canal de publication de votre cluster GKE.
Pour en savoir plus, consultez la page Canaux de publication gérés pour Cloud Service Mesh.
--co|--custom_overlay OVERLAY_FILE
- Utilisez
--custom_overly
avec le nom d'un fichier YAML (appelé fichier superposé) contenant la ressource personnaliséeIstioOperator
pour configurer le plan de contrôle au sein du cluster. Vous spécifiez un fichier de superposition à activer une fonctionnalité qui n'est pas activé par défaut. Cloud Service Mesh géré n'est pas compatible avec l'APIIstioOperator
. Vous ne pouvez donc pas utiliser--custom_overlay
pour configurer le plan de contrôle géré.asmcli
doit pouvoir localiser le fichier de superposition. doit se trouver dans le même répertoire queasmcli
, ou vous pouvez spécifier un chemin 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 nomsistio-system
. Pour GKE,--network_id
utilise par défaut le nom du réseau du cluster. Pour les autres environnements, la valeurdefault
est utilisée. -o|--option OVERLAY_FILE
Nom du fichier superposé (sans l'extension
.yaml
) téléchargé parasmcli
à partir du dépôtanthos-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épertoiresasm
etistio-1.21.5-asm.7
. Le répertoireasm
contient la configuration pour l'installation. Le répertoireistio-1.21.5-asm.7
contient le contenu extrait du fichier d'installation, qui contientistioctl
, 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 les plates-formes utilisées,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 :asm-1215-7
. Incluez cette option si vous souhaitez remplacer la valeur par défaut et spécifier la vôtre. L'argumentREVISION 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écuteasmcli
au rôlecluster-admin
sur le cluster.asmcli
identifie le compte utilisateur à l'aide de la commandegcloud config get core/account
. Si vous exécutezasmcli
en local avec un compte utilisateur, veillez à appeler la commandegcloud auth login
avant d'exécuterasmcli
. Si vous devez modifier le compte utilisateur, exécutez la commandegcloud 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 :Workload Identity, qui permet aux applications GKE d'accéder en toute sécurité aux services Google Cloud
--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. Implied par
--enable_gcp_components
et--managed
.--enable_namespace_creation
Autorisez
asmcli
à créer l'espace de noms racineistio-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
- Imprime les commandes, mais ne les exécute pas.
--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
- Obsolète. 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 s'arrête 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 ni 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é en 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 à votre cluster. Si vous ne souhaitez pas queasmcli
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
- Utilisez le CNI géré. Si cet indicateur n'est pas transmis,
asmcli
appliquera les fichiers manifestes CNI statiques. --use_vpcsc
- Si votre organisation impose
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 deasmcli_1.21
.