referência do asmcli

Visão geral

O asmcli é uma ferramenta oferecida pelo Google que você pode usar para instalar ou e 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ê ainda não conhece o Cloud Service Mesh e o Istio, avance 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 ser registrados 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 plano de controle, o asmcli instala 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

instalações do Cloud Service Mesh na lista de É possível configurar plataformas compatíveis ou atualizado 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 de 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. Especificar mesh_ca para usar a autoridade certificadora do Cloud Service Mesh (autoridade de certificação do Cloud Service Mesh), gcp_cas usar o Certificate Authority Service; ou citadel para usar a CA do Istio. O Cloud Service Mesh gerenciado não é compatível com o Istio no Canadá. 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 sinalização é necessária ao configurar determinados recursos do Cloud Service Mesh em clusters do Autopilot do GKE.

A opção --channel não é mais compatível com o Cloud Service Mesh gerenciado como 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 gerenciados do Cloud Service Mesh.

--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 a ser configurado plano de controle no cluster. Você especifica um arquivo de sobreposição 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 deve ser capaz de localizar o arquivo de sobreposição. Portanto, precisa estar no mesmo diretório que asmcli, ou é possível especificar 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, asmcli criará um diretório temporário em que faz o download dos arquivos e configurações necessários 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.2-asm.2. O diretório asm contém a configuração da instalação. O diretório istio-1.23.2-asm.2 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-1232-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
Executar a validação, mas não atualizar o projeto ou cluster e não instalar do 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, o asmcli implanta a Controlador de serviço canônico ao 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 sua organização aplicar VPC Service Controls para seu projeto, é preciso configurar o Cloud Service Mesh gerenciado com a sinalização --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.