referência do asmcli

Visão geral

O asmcli é uma ferramenta fornecida pelo Google que pode ser usada para instalar ou fazer upgrade do Cloud Service Mesh. Se você permitir, asmcli configurará o projeto e o cluster da seguinte maneira:

  • Conceda as permissões necessárias de gerenciamento de identidade e acesso (IAM, na sigla em inglês) no seu projeto do Google Cloud.
  • Ative as APIs do Google necessárias no seu projeto do Google Cloud.
  • Definir um identificador no cluster para reconhecer a malha
  • Crie uma conta de serviço que permita que os componentes do plano de dados, como o proxy sidecar, acessem com segurança os dados e os recursos do seu projeto.
  • Registre o cluster na frota se ele ainda não estiver registrado.

Basta incluir a sinalização --enable_all ao executar asmcli para permitir que ela configure o projeto e o cluster. Para mais informações sobre as opções e sinalizações do asmcli, consulte a referência do asmcli.

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

Se você não conhece o Cloud Service Mesh e o Istio, pule para Plataformas compatíveis. A próxima seção ajuda a fazer o upgrade do Cloud Service Mesh para 1.23.

Transição para asmcli

O asmcli substitui istioctl install e install_asm. Ainda que você possa usar as ferramentas legadas no Cloud Service Mesh 1.11, estamos descontinuando o uso delas e elas não serão mais compatíveis com o Cloud Service Mesh 1.12 e versões mais recentes. Atualize seus scripts e ferramentas para usar asmcli.

Todos os clusters precisam estar registrados em uma frota. Consulte os requisitos da frota para mais detalhes.

Transição de install_asm

Se você tem familiaridade com install_asm, asmcli é semelhante, mas com as seguintes diferenças notáveis:

  • Use asmcli install para novas instalações e upgrades. Não há uma opção --mode como com install_asm. Quando você executa asmcli install, ele verifica se há um plano de controle atual no cluster. Se não houver um plano de controle existente, o asmcli vai instalar o Cloud Service Mesh. Se o cluster tiver um plano de controle existente (um plano de controle do Cloud Service Mesh ou um plano de controle do Istio de código aberto):

  • A maioria das opções e sinalizações asmcli se comportam como as de install_asm.

Transição de istioctl install

Se você estiver familiarizado com istioctl install, se normalmente transmitir um arquivo YAML IstioOperator por meio do argumento de linha de comando -f para configurar o plano de controle, poderá transmitir o arquivo para asmcli usando a opção --custom_overlay. Na documentação do Cloud Service Mesh, nos referimos a esses arquivos como arquivos de sobreposição.

Plataformas compatíveis

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

No entanto, nem todos os recursos estão disponíveis nas plataformas fora do Google Cloud. Para detalhes, consulte Recursos compatíveis com o plano de controle no cluster.

Referência do asmcli

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

Opções

Identifique o cluster Você tem as seguintes opções para identificar o cluster:

Apenas GKE

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

Todas as plataformas

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

--ctx|--context KUBE_CONTEXT O contexto kubeconfig a ser usado. Se não especificado, asmcli usa o contexto padrão.

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

A autoridade de certificação (CA) a ser usada para gerenciar certificados TLS mútuos. Especifique mesh_ca para usar a autoridade certificadora do Cloud Service Mesh, gcp_cas para usar o Certificate Authority Service ou citadel para usar a AC do Istio. O Cloud Service Mesh gerenciado não é compatível com a CA do Istio. Para mais informações, consulte os links a seguir:

--channel CLOUD_SERVICE_MESH_CHANNEL

Use --channel com um canal de lançamento do Cloud Service Mesh específico para provisionar a revisão do plano de controle associada a esse canal. Por exemplo, --channel rapid, --channel regular e --channel stable. Essa flag é necessária ao configurar determinados recursos do Cloud Service Mesh em clusters do GKE Autopilot.

A opção --channel não é mais compatível com o Cloud Service Mesh gerenciado, conforme mencionado nas notas da versão do CSM. O canal de lançamento é determinado com base no canal de lançamento do cluster do GKE. Para mais informações, consulte Canais de lançamento do Cloud Service Mesh gerenciado.

--co|--custom_overlay OVERLAY_FILE
Use --custom_overly com o nome de um arquivo YAML (chamado de arquivo de sobreposição) que contém o recurso personalizado IstioOperator para configurar o plano de controle no cluster. Especifique um arquivo de sobreposição para ativar um recurso que não está ativado por padrão. O Cloud Service Mesh gerenciado não é compatível com a API IstioOperator. Portanto, não é possível usar --custom_overlay para configurar o plano de controle gerenciado. asmcli precisa conseguir localizar o arquivo de sobreposição. Por isso, ele precisa estar no mesmo diretório que asmcli ou você pode especificar um caminho relativo. Para adicionar vários arquivos, especifique --co|--custom_overlay e o nome do arquivo. Por exemplo: --co overlay_file1.yaml --co overlay_file2.yaml --co overlay_file3.yaml
--hub-registration-extra-flags HUB_REGISTRATION_EXTRA_FLAGS
Se estiver usando clusters do Amazon EKS anexados, use --hub-registration-extra-flags para registrar o cluster para a frota, caso ainda não esteja registrado.
-k|--key_file FILE_PATH
O arquivo de chave de uma conta de serviço. Omita essa opção se não estiver usando uma conta de serviço.
--network_id NETWORK_ID
Use --network_id para definir o rótulo topology.istio.io/network aplicado ao namespace istio-system. Para o GKE, --network_id tem como padrão o nome da rede do cluster. Para outros ambientes, default será usado.
-o|--option OVERLAY_FILE

O nome do arquivo de sobreposição (sem a extensão .yaml) que asmcli faz o download do repositório anthos-service-mesh para ativar um recurso opcional. Você precisa de conectividade com a Internet para usar o --option. As opções --option e --custom_overlay são semelhantes, mas têm comportamentos um pouco diferentes:

  • Use --custom_overlay quando precisar alterar as configurações no arquivo de sobreposição.

  • Use --option para ativar um recurso que não exija alterações no arquivo de sobreposição, por exemplo, para configurar políticas de auditoria dos serviços.

Para adicionar vários arquivos, especifique -o|--option e o nome do arquivo. Por exemplo: -o option_file1 -o option_file2 -o option_file3

-D|--output_dir DIR_PATH

Se não for especificado, o asmcli vai criar um diretório temporário em que fará o download dos arquivos e das configurações necessárias para instalar o Cloud Service Mesh. Especifique a sinalização --output-dir para especificar um caminho relativo para um diretório a ser usado. Após a conclusão, o diretório especificado conterá os subdiretórios asm e istio-1.23.3-asm.1. O diretório asm contém a configuração da instalação. O diretório istio-1.23.3-asm.1 contém o conteúdo extraído do arquivo de instalação, que contém istioctl, amostras e manifestos. Se você especificar --output-dir e o diretório já contiver os arquivos necessários, o asmcli usará esses arquivos em vez de fazer o download deles novamente.

--platform PLATFORM {gcp|multicloud}

A plataforma ou o provedor do cluster do Kubernetes. O padrão é gcp (para clusters do GKE). Para todas as outras plataformas, use multicloud.

-r|--revision_name REVISION NAME

Um rótulo de revisão é um par de chave-valor definido no plano de controle. A chave do rótulo de revisão é sempre istio.io/rev. Por padrão, o asmcli define o valor do rótulo de revisão com base na versão do Cloud Service Mesh, por exemplo: asm-1233-2. Inclua essa opção se quiser modificar o valor padrão e especificar seu próprio valor. O argumento REVISION NAME precisa ser um rótulo DNS-1035. Isso significa que o nome precisa:

  • conter no máximo 63 caracteres
  • conter apenas caracteres alfanuméricos minúsculos ou '-'
  • começam com um caractere alfabético
  • terminar com um caractere alfanumérico.

O regex usado 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, a conta de usuário ativa na configuração de gcloud atual será usada. Se você precisar alterar a conta de usuário ativa, execute gcloud auth login.

Opções para o certificado personalizado de CA do Istio

Se você especificou --ca citadel e está usando uma CA personalizada, inclua as seguintes opções:

  • --ca_cert FILE_PATH: o certificado intermediário
  • --ca_key FILE_PATH: a chave do certificado intermediário.
  • --root_cert FILE_PATH: o certificado raiz
  • --cert_chain FILE_PATH: a cadeia de certificados

Para ver mais informações, consulte Como conectar certificados de CA existentes.

Sinalizações de ativação

As sinalizações que começam com --enable permitem que o asmcli ative as APIs do Google, defina as permissões Identity and Access Management (IAM) obrigatórias e atualize o cluster. Se preferir, atualize o projeto e o cluster antes de executar o asmcli. Todas as sinalizações de ativação são incompatíveis com asmcli validate. Se você especificar uma sinalização de ativação ao executar asmcli validate, o comando terminará com um erro.

-e|--enable_all
Permita que asmcli execute todas as ações de ativação individuais descritas abaixo.
--enable_cluster_roles
Permita que asmcli tente vincular a conta de usuário ou serviço do Google Cloud que está executando asmcli ao papel cluster-admin no cluster. asmcli determina a conta de usuário do comando gcloud config get core/account. Se você estiver executando asmcli localmente com uma conta de usuário, lembre-se de chamar o comando gcloud auth login antes de executar asmcli. Se você precisar alterar a conta de usuário, execute o comando gcloud config set core/account GCP_EMAIL_ADDRESS em que GCP_EMAIL_ADDRESS é a conta que você usa para fazer login no Google Cloud.
--enable_cluster_labels
Permita que asmcli defina os rótulos de cluster necessários.
--enable_gcp_components

Permita que asmcli ative os seguintes serviços e componentes gerenciados do Google Cloud:

--enable_gcp_apis

Permitir que asmcli ative todas as APIs necessárias do Google.

--enable_gcp_iam_roles

Permita que asmcli defina as permissões do IAM necessárias.

--enable_meshconfig_init

Permita que o script inicialize o endpoint meshconfig em seu nome. Implícito por --enable_gcp_components e --managed.

--enable_namespace_creation

Permita que asmcli crie o namespace istio-system raiz.

--enable_registration

Permitir que asmcli registre o cluster no projeto em que o cluster está. Se não incluir essa sinalização, siga as etapas em Como registrar um cluster e registre-o manualmente. Observe que, ao contrário das outras sinalizações de ativação, --enable_registration é incluído apenas em --enable_all quando você especifica uma opção (como --option hub-meshca) que requer registro do cluster. Caso contrário, será necessário especificar essa sinalização separadamente.

Outras sinalizações

--dry_run
Imprima comandos, mas não os execute.
--fleet_id
Registre um cluster em uma frota usando o ID do projeto host da frota. Essa sinalização é necessária para clusters que não são do Google Cloud. Quando não fornecido para clusters do Google Cloud, o padrão é o ID do projeto do cluster. Execute asmcli install com --fleet_id antes da instalação ou como parte da instalação transmitindo as sinalizações --enable-registration e --fleet-id. Não será possível mudar essa configuração depois.
--managed
Obsoleto. Provisione um plano de controle remoto gerenciado em vez de instalar um no cluster.
--offline
Execute uma instalação off-line usando o pacote pré-baixado no diretório de saída. Se o diretório não for especificado ou não tiver os arquivos necessários, o script será encerrado com erro.
--only_enable
Execute as etapas especificadas para configurar o usuário/cluster atual, mas não instala nada.
--only_validate
Execute a validação, mas não atualize o projeto ou o cluster, nem instale o Cloud Service Mesh. Essa sinalização é incompatível com as sinalizações de ativação. asmcli terminará com um erro se você 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). Todas as outras saídas são gravadas no erro padrão (stderr), mesmo que você normalmente acesse stdout. asmcli ignora todas as validações e configurações quando você especifica essa sinalização.
--disable_canonical_service
Por padrão, asmcli implanta o controlador de serviço canônico no cluster. Se você não quiser que asmcli implante o controlador, especifique --disable_canonical_service. Para mais informações, consulte Como ativar e desativar o controlador de serviço canônico.
-h|--help
Mostra uma mensagem de ajuda que descreve as opções e sinalizações, e depois sai.
--use_managed_cni
Use a CNI gerenciada. Se essa sinalização não for transmitida, asmcli aplicará os manifestos CNI estáticos.
--use_vpcsc
Se a organização aplicar o VPC Service Controls ao projeto, é necessário configurar o Cloud Service Mesh gerenciado com a flag --use_vpcsc. Caso contrário, a instalação não vai ter os controles de segurança.
-v|--verbose
À medida que asmcli é executado, ele imprime o comando que será executado em seguida. Com a sinalização --verbose, asmcli também imprime o comando após a execução.
--version
Imprime a versão de asmcli e sai. Se você não tiver a versão mais recente, poderá fazer o download da versão mais recente do asmcli_1.23.