Referência da asmcli

Vista geral

O asmcli é uma ferramenta fornecida pela Google que pode usar para instalar ou atualizar o Cloud Service Mesh. Se o permitir, o asmcli vai configurar o seu projeto e cluster da seguinte forma:

  • Conceder-lhe as autorizações da gestão de identidade e de acesso (IAM) necessárias no seu Google Cloud projeto.
  • Ative as APIs Google necessárias no seu Google Cloud projeto.
  • Defina uma etiqueta no cluster que identifique a malha.
  • Crie uma conta de serviço que permita que os componentes do plano de dados, como o proxy sidecar, acedam de forma segura aos dados e recursos do seu projeto.
  • Registe o cluster na frota, se ainda não estiver registado.

Basta incluir a flag --enable_all quando executar asmcli para permitir que configure o seu projeto e cluster. Para mais informações sobre as asmcliopções e as flags, consulte a asmcli referência.

Em seguida, asmcli configura os ficheiros YAML com as informações do projeto e do cluster. Estes ficheiros de configuração são necessários para instalar o plano de controlo do Cloud Service Mesh.

Se não conhece o Cloud Service Mesh nem o Istio, avance para a secção Plataformas suportadas. A secção seguinte destina-se a ajudar os utilizadores do Cloud Service Mesh a atualizarem para o 1.21.

A fazer a transição para asmcli

O asmcli substitui istioctl install e install_asm. Embora ainda possa usar as ferramentas antigas no Cloud Service Mesh 1.11, vamos descontinuá-las e deixarão de ser suportadas no Cloud Service Mesh 1.12 e posterior. Atualize os seus scripts e ferramentas para usar asmcli.

Todos os clusters têm de estar registados numa frota. Consulte os requisitos da frota para ver detalhes.

Transição de install_asm

Se conhece o install_asm, o asmcli é semelhante, mas com as seguintes diferenças notáveis:

  • Usa o asmcli install para novas instalações e atualizações. Não existe uma opção --mode como com o install_asm. Quando executa asmcli install, verifica se existe um plano de controlo no cluster. Se não existir um plano de controlo, o asmcli instala o Cloud Service Mesh. Se o cluster tiver um plano de controlo existente (um plano de controlo do Cloud Service Mesh ou um plano de controlo do Istio de código aberto):

  • A maioria das asmcli opções e flags comporta-se da mesma forma que as do install_asm.

Transição de istioctl install

Se estiver familiarizado com o istioctl install, se normalmente transmitir um ficheiro YAML IstioOperator através do argumento da linha de comandos -f para configurar o plano de controlo, pode transmitir o ficheiro para asmcli através da opção --custom_overlay. Na documentação do Cloud Service Mesh, referimo-nos a estes ficheiros como ficheiros de sobreposição.

Plataformas suportadas

As instalações do Cloud Service Mesh na lista de plataformas suportadas podem ser configuradas ou atualizadas por asmcli.

No entanto, nem todas as funcionalidades estão disponíveis nas plataformas fora do Google Cloud. Para ver detalhes, consulte o artigo Funcionalidades suportadas do plano de controlo no cluster.

asmcli referência

Esta secção descreve os argumentos disponíveis para asmcli.

Opções

Identifique o cluster Tem as seguintes opções para identificar o cluster:

Apenas GKE

-p|--project_id CLUSTER_PROJECT_ID
O ID do projeto no qual o cluster foi criado.
-n|--cluster_name CLUSTER_NAME
O nome do cluster.
-l|--cluster_location CLUSTER_LOCATION
A zona (para clusters de zona única) ou a região (para clusters regionais) em que o cluster foi criado.

Todas as plataformas

--kubeconfig KUBECONFIG_FILE O caminho completo para o ficheiro kubeconfig. A variável de ambiente $PWD não funciona aqui.

--ctx|--context KUBE_CONTEXT O contexto kubeconfig a usar. Se não for especificado, asmcli usa o contexto predefinido.

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

A autoridade de certificação (AC) a usar para gerir os certificados de TLS mútuo. Especifique mesh_ca para usar a autoridade de certificação do Cloud Service Mesh (autoridade de certificação do Cloud Service Mesh), gcp_cas para usar o serviço de autoridade de certificação ou citadel para usar a AC do Istio. O Managed Cloud Service Mesh não suporta a AC do Istio. Consulte o seguinte para ver informações adicionais:

--channel CLOUD_SERVICE_MESH_CHANNEL

Use o --channel com um canal de lançamento do Cloud Service Mesh específico para aprovisionar a revisão do plano de controlo associada a esse canal de lançamento. Por exemplo, --channel rapid, --channel regular e --channel stable. Esta flag é necessária quando configura determinadas funcionalidades da malha de serviços na nuvem em clusters do GKE Autopilot.

A opção --channel já não é suportada para a malha de serviços na nuvem gerida, conforme mencionado nas notas de lançamento do CSM. O canal de lançamento é determinado com base no canal de lançamento do cluster do GKE. Para mais informações, consulte o artigo Canais de lançamento da malha de serviços na nuvem gerida.

--co|--custom_overlay OVERLAY_FILE
Use --custom_overly com o nome de um ficheiro YAML (denominado ficheiro de sobreposição) que contenha o recurso personalizado IstioOperator para configurar o plano de controlo no cluster. Especifica um ficheiro de sobreposição para ativar uma funcionalidade que não está ativada por predefinição. O Managed Cloud Service Mesh não suporta a API IstioOperator, pelo que não pode usar o --custom_overlay para configurar o plano de controlo gerido. asmcli tem de conseguir localizar o ficheiro de sobreposição. Por isso, tem de estar no mesmo diretório que asmcli ou pode especificar um caminho relativo. Para adicionar vários ficheiros, especifique --co|--custom_overlay e o nome do ficheiro, por exemplo: --co overlay_file1.yaml --co overlay_file2.yaml --co overlay_file3.yaml
--hub-registration-extra-flags HUB_REGISTRATION_EXTRA_FLAGS
Se usar clusters do Amazon EKS anexados, use --hub-registration-extra-flags para registar o cluster na frota se ainda não estiver registado.
-k|--key_file FILE_PATH
O ficheiro de chave de uma conta de serviço. Omita esta opção se não estiver a usar uma conta de serviço.
--network_id NETWORK_ID
Use --network_id para definir a etiqueta topology.istio.io/network aplicada ao espaço de nomes istio-system. Para o GKE, a predefinição de --network_id é o nome da rede do cluster. Para outros ambientes, é usado o default.
-o|--option OVERLAY_FILE

O nome do ficheiro de sobreposição (sem a extensão .yaml) que asmcli é transferido do repositório anthos-service-mesh para ativar uma funcionalidade opcional. Precisa de uma ligação à Internet para usar o --option. As opções --option e --custom_overlay são semelhantes, mas têm um comportamento ligeiramente diferente:

Para adicionar vários ficheiros, especifique -o|--option e o nome do ficheiro, por exemplo: -o option_file1 -o option_file2 -o option_file3

-D|--output_dir DIR_PATH

Se não for especificado, asmcli cria um diretório temporário onde transfere ficheiros e configurações necessários para instalar o Cloud Service Mesh. Especifique o sinalizador --output-dir para especificar um caminho relativo para um diretório a usar em alternativa. Após a conclusão, o diretório especificado contém os subdiretórios asm e istio-1.21.5-asm.34. O diretório asm contém a configuração para a instalação. O diretório istio-1.21.5-asm.34 contém os conteúdos extraídos do ficheiro de instalação, que contém istioctl, exemplos e manifestos. Se especificar --output-dir e o diretório já contiver os ficheiros necessários, asmcli usa esses ficheiros em vez de os transferir novamente.

--platform PLATFORM {gcp|multicloud}

A plataforma ou o fornecedor do cluster do Kubernetes. A predefinição é gcp (para clusters do GKE). Para todas as outras plataformas, multicloud.

-r|--revision_name REVISION NAME

Uma etiqueta de revisão é um par de chave-valor que é definido no plano de controlo. A chave da etiqueta de revisão é sempre istio.io/rev. Por predefinição, asmcli define o valor da etiqueta de revisão com base na versão do Cloud Service Mesh, por exemplo: asm-1215-34. Inclua esta opção se quiser substituir o valor predefinido e especificar o seu próprio valor. O argumento REVISION NAME tem de ser uma etiqueta DNS-1035. Isto significa que o nome tem de:

  • Conter, no máximo, 63 carateres
  • conter apenas carateres alfanuméricos minúsculos ou "-"
  • Começar com um caráter alfabético
  • Terminar com um caráter alfanumérico

A regex usada para validação é: '[a-z]([-a-z0-9]*[a-z0-9])?'

-s|--service_account ACCOUNT
O nome de uma conta de serviço usada para instalar o Cloud Service Mesh. Se não for especificado, é usada a conta de utilizador ativa na configuração atual do gcloud. Se precisar de alterar a conta de utilizador ativa, execute o comando gcloud auth login.

Opções para o certificado personalizado da AC do Istio

Se especificou --ca citadel e estiver a usar uma AC personalizada, inclua as seguintes opções:

  • --ca_cert FILE_PATH: O certificado intermédio
  • --ca_key FILE_PATH: a chave do certificado intermédio
  • --root_cert FILE_PATH: o certificado de raiz
  • --cert_chain FILE_PATH: a cadeia de certificados

Para mais informações, consulte o artigo Inserir certificados de AC existentes.

Sinalizações de ativação

As flags que começam com --enable permitem que asmcli ative as APIs Google necessárias, defina as autorizações de gestão de identidade e de acesso (IAM) necessárias e atualize o cluster. Se preferir, pode atualizar o projeto e o cluster antes de executar asmcli. Todas as flags de ativação são incompatíveis com asmcli validate. Se especificar uma flag de ativação quando executar o comando asmcli validate, o comando termina com um erro.

-e|--enable_all
Permitir que asmcli realize todas as ações de ativação individuais descritas abaixo.
--enable_cluster_roles
Permitir que o asmcli tente associar o utilizador ou a conta de serviço que executa o asmcli à função cluster-admin no seu cluster. Google Cloud asmcli determina a conta de utilizador a partir do comando gcloud config get core/account. Se estiver a executar o asmcli localmente com uma conta de utilizador, certifique-se de que chama o comando gcloud auth login antes de executar o asmcli. Se precisar de alterar a conta de utilizador, execute o comando gcloud config set core/account GCP_EMAIL_ADDRESS, em que GCP_EMAIL_ADDRESS é a conta que usa para iniciar sessão no Google Cloud.
--enable_cluster_labels
Permitir que asmcli defina etiquetas de cluster necessárias.
--enable_gcp_components

Permita que asmcli ative os seguintes serviços e componentes geridos Google Cloud obrigatórios:

--enable_gcp_apis

Permita que o asmcli ative todas as APIs Google necessárias.

--enable_gcp_iam_roles

Permita que o asmcli defina as autorizações de IAM necessárias.

--enable_meshconfig_init

Permitir que o script inicialize o ponto final meshconfig em seu nome. Implícito por --enable_gcp_components e --managed.

--enable_namespace_creation

Permitir que o asmcli crie o espaço de nomes istio-system raiz.

--enable_registration

Permita que o asmcli registe o cluster no projeto em que o cluster se encontra. Se não incluir esta flag, siga os passos em Registar um cluster para registar manualmente o cluster. Tenha em atenção que, ao contrário das outras flags de ativação, a flag --enable_registration só é incluída em --enable_all quando especifica uma opção (como --option hub-meshca) que requer o registo do cluster. Caso contrário, tem de especificar esta flag separadamente.

Outras sinalizações

--dry_run
Imprimir comandos, mas não os executar.
--fleet_id
Registe um cluster numa frota através do ID do projeto anfitrião da frota. Esta flag é obrigatória para clusters que não sejam do tipoGoogle Cloud . Quando não é fornecido para Google Cloud clusters, a predefinição é o ID do projeto do cluster. Pode executar asmcli install juntamente com --fleet_id antes da instalação ou como parte da instalação transmitindo as flags --enable-registration e --fleet-id. Não é possível alterar esta definição depois de configurada.
--managed
Descontinuado. Aprovisionar um painel de controlo gerido remotamente em vez de instalar um no cluster.
--offline
Faça uma instalação offline usando o pacote pré-transferido no diretório de saída. Se o diretório não for especificado ou não contiver os ficheiros necessários, o script é terminado com um erro.
--only_enable
Executa os passos especificados para configurar o utilizador/cluster atual, mas não instala nada.
--only_validate
Executar a validação, mas não atualizar o projeto nem o cluster, e não instalar o Cloud Service Mesh. Esta flag é incompatível com as flags de ativação. asmcli termina com um erro se especificar --only_validate com qualquer sinalização de ativação.
--print_config
Em vez de instalar o Cloud Service Mesh, imprima todo o YAML compilado para a saída padrão (stdout). Toda a outra saída é escrita no erro padrão (stderr), mesmo que normalmente fosse para stdout. asmcli ignora todas as validações e a configuração quando especifica este sinalizador.
--disable_canonical_service
Por predefinição, o asmcli implementa o controlador de serviços canónico no seu cluster. Se não quiser que o asmcli implemente o controlador, especifique --disable_canonical_service. Para mais informações, consulte o artigo Ativar e desativar o controlador de serviços canónico.
-h|--help
Mostrar uma mensagem de ajuda que descreve as opções e as flags, e sair.
--use_managed_cni
Use a CNI gerida. Se esta flag não for transmitida, o asmcli aplica os manifestos CNI estáticos.
--use_vpcsc
Se a sua organização aplicar os VPC Service Controls ao seu projeto, tem de configurar o Cloud Service Mesh gerido com a flag --use_vpcsc. Caso contrário, a instalação falha os controlos de segurança.
-v|--verbose
À medida que o asmcli é executado, imprime o comando que vai executar a seguir. Com a flag --verbose, asmcli também imprime o comando após a execução.
--version
Imprima a versão de asmcli e saia. Se não tiver a versão mais recente, pode transferir a versão mais recente do asmcli_1.21.