Referência

Esta página descreve os argumentos disponíveis para o script e fornece detalhes sobre as alterações que o script faz no seu projeto e no cluster do GKE.

Opções

-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 (para clusters de zona única) ou a região (para clusters regionais) em que o cluster foi criado.
-m|--mode {install|migrate|upgrade}

É possível usar --mode install para uma nova instalação, upgrade ou migração do Istio. Ao usar --mode install para upgrades ou migrações, install_asm permite o upgrade/migração, independentemente da versão do plano de controle no cluster. As sinalizações migrate e upgrade só permitem upgrades ou migrações da versão secundária anterior ou de uma versão de patch anterior.

Se você usar --mode install para upgrades ou migrações, especifique a mesma autoridade de certificação (CA, na sigla em inglês) ativada no momento no cluster. Alterar a CA resultará em tempo de inatividade. A sinalização --upgrade não permite alterar a CA, o que evita a inatividade não intencional.

Se você estiver migrando do Istio, será possível alterar a CA e ativar a autoridade de certificação do Anthos Service Mesh (Mesh CA, na sigla em inglês). Se não for possível programar o tempo de inatividade da migração para a CA da malha, ainda haverá um caminho para a CA da malha, mas serão necessárias outras etapas. Para mais detalhes, consulte Como migrar para a CA da malha.

-c|--ca {mesh_ca|citadel}

Para novas instalações, se você quiser usar a CA da malha, não é necessário incluir essa opção porque o padrão do script é a CA da malha. Para upgrades, não é necessário incluir essa opção porque o script não permite alterar a CA. Para migrações, especifique citadel ou mesh_ca. Se você puder programar o tempo de inatividade da migração, recomendamos que use mesh_ca. Para mais informações sobre qual CA usar, consulte Como escolher uma autoridade de certificação. Para outras opções que você precisa especificar ao usar a CA do Istio, consulte Opções para o certificado personalizado da CA do Istio.

--co|--custom_overlay YAML_FILE

O nome do arquivo YAML de recurso personalizado (CR) IstioOperator para ativar um recurso que não é ativado por padrão. O script precisa localizar o arquivo YAML. Portanto, ele precisa estar no mesmo diretório que o script 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

-o|--option OPTION_FILE

O nome de um arquivo YAML do pacote anthos-service-mesh que contém a resposta automática IstioOperator para ativar um recurso opcional. Ao incluir um desses arquivos, não é necessário fazer o download do pacote anthos-service-mesh primeiro nem especificar a extensão .yaml. Se você precisar modificar qualquer um dos arquivos, faça o download do pacote anthos-service-mesh, faça as alterações e use a opção --custom_overlay. 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 script criará um diretório temporário em que fará o download dos arquivos e das configurações necessárias para instalar o Anthos 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.11.8-asm.4. O diretório asm contém a configuração da instalação. O diretório istio-1.11.8-asm.4 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 script usará esses arquivos em vez de fazer o download deles novamente.

-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 script define o valor do rótulo de revisão com base na versão do Anthos Service Mesh, por exemplo: asm-1118-4. 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 e conter caracteres alfanuméricos minúsculos ou -, começar com um caractere alfabético e terminar com um caractere alfanumérico, como my-name' ou abc-123. 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 Anthos 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.

-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.

Opções do certificado personalizado do Citadel

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 script ative as APIs do Google necessárias, definapermissões do Identity and Access Management (IAM) obrigatórias e atualize o cluster. Se preferir, atualize o projeto e o cluster antes de executar o script conforme descrito nas seções Como configurar o projeto e Como configurar o cluster do guia de instalação de vários projetos. Todas essas sinalizações são incompatíveis com --only_validate, e o script termina com um erro nesse caso.

-e|--enable_all
Permita que o script execute todas as ações de ativação individuais descritas abaixo.
--enable_cluster_roles
Permita que o script tente vincular a conta de usuário ou de serviço do GCP que executa o script para o papel cluster-admin no cluster. O script determina a conta de usuário do comando gcloud config get core/account. Se você estiver executando o script localmente com uma conta de usuário, certifique-se de chamar o comando gcloud auth login antes de executar o script. 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 o script defina rótulos de cluster obrigatórios.
--enable_gcp_components

Permita que o script ative os seguintes serviços e componentes gerenciados necessários do Google Cloud:

--enable_gcp_apis

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

--enable_gcp_iam_roles

Permita que o script defina as permissões de IAM necessárias.

--enable_registration

Permita que o script registre o cluster para o projeto no qual ele 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 vm ou --option hub-meshca) que requer registro do cluster. Caso contrário, será necessário especificar essa sinalização separadamente.

Outras sinalizações

--dry_run
Mostra comandos, mas não os executa.
--only_validate
Execute a validação, mas não atualize o projeto ou o cluster, nem instale o Anthos Service Mesh. Essa sinalização é incompatível com as sinalizações de ativação. O script termina com um erro se você especifica --only_validate com qualquer sinalização de ativação.
--print_config
Em vez de instalar o Anthos 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. O script ignora todas as validações e a configuração quando você especifica essa sinalização.
--disable_canonical_service
Por padrão, o script implanta o controlador de serviço canônico no cluster. Se você não quiser que o script 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
Mostrar uma mensagem de ajuda com a descrição das opções, sinalizações e saídas.
-v|--verbose
À medida que o script é executado, se imprimir o comando que ele executará em seguida. Com a sinalização --verbose, o script também imprime o comando após a execução.
--version
Imprime a versão de install_asm e sai. Se o comando não gerar uma versão, faça o download da versão mais recente de install_asm_1.11.

Como entender o script

É possível fazer o download do script a partir de um local seguro do Cloud Source Repositories, mas o script também estará disponível no GitHub para que você possa ver o que ele faz antes de iniciar o download. O script valida que seu projeto e cluster atendam aos requisitos do Anthos Service Mesh e automatiza todas as etapas que você faria manualmente para configurar seu projeto e cluster e, em seguida, instala o Anthos Service Mesh usando o comando istioctl install.

Com o Anthos Service Mesh 1.11.8, você usa a versão do script install_asm na ramificação release-1.11. Para uma explicação do processo de controle de versão e lançamento, consulte Controle de versões/lançamento.

Validação

validate_dependencies() {
  validate_node_pool
  validate_k8s
  validate_expected_control_plane

  if [[ "${MODE}" = "migrate" ]]; then
    validate_istio_version
  elif [[ "${MODE}" = "upgrade" ]]; then
    validate_asm_version
    validate_ca_consistency
  fi
}

O script install_asm verifica se:

  • O ID do projeto, o nome do cluster e o local do cluster que você inseriu como valores de parâmetro são válidos.
  • O cluster atende ao tipo de máquina mínimo necessário e ao número de nós.

Configurar o projeto

Funções exigidas

Se você incluiu a sinalização --enable_all ou --enable_gcp_iam_roles, o script define as permissões do IAM necessárias.

required_iam_roles() {
  # meshconfig.admin - required for init, stackdriver, UI elements, etc.
  # servicemanagement.admin/serviceusage.serviceUsageAdmin - enables APIs
  if can_modify_gcp_components || \
     can_modify_cluster_labels || \
     can_modify_cluster_roles; then
    echo roles/container.admin
  fi
  if can_modify_gcp_components; then
    echo roles/meshconfig.admin
  fi
  if can_modify_gcp_apis; then
    echo roles/servicemanagement.admin
    echo roles/serviceusage.serviceUsageAdmin
  fi
  if can_modify_gcp_iam_roles; then
    echo roles/resourcemanager.projectIamAdmin
  fi
  if is_sa; then
    echo roles/iam.serviceAccountAdmin
  fi
  if can_register_cluster; then
    echo roles/gkehub.admin
  fi
  if [[ "${CA}" = "gcp_cas" ]]; then
    echo roles/privateca.admin
  fi
  if [[ "${_CI_I_AM_A_TEST_ROBOT}" -eq 1 ]]; then
    echo roles/compute.admin
    echo roles/iam.serviceAccountKeyAdmin
  fi
}

APIs do Google obrigatórias

Se você incluiu a sinalização --enable_all ou --enable_apis, o script ativará as APIs necessárias:

required_apis() {
    cat << EOF
container.googleapis.com
monitoring.googleapis.com
logging.googleapis.com
cloudtrace.googleapis.com
meshtelemetry.googleapis.com
meshconfig.googleapis.com
iamcredentials.googleapis.com
gkeconnect.googleapis.com
gkehub.googleapis.com
cloudresourcemanager.googleapis.com
stackdriver.googleapis.com
EOF
  case "${CA}" in
   mesh_ca)
     echo meshca.googleapis.com
     ;;
   gcp_cas)
     echo privateca.googleapis.com
     ;;
    *);;
  esac

  if [[ "${_CI_I_AM_A_TEST_ROBOT}" -eq 1 ]]; then
    echo compute.googleapis.com
  fi
}

Como configurar o cluster

O script fará as seguintes atualizações no cluster se você tiver incluído a sinalização --enable_all ou uma das sinalizações de ativação mais granulares listadas abaixo:

Atualização do cluster Sinalização
Ativa a Identidade da carga de trabalho, que permite que os aplicativos do GKE acessem os serviços do Google Cloud com segurança. --enable_gcp_components
Ativa o Cloud Monitoring e o Cloud Logging no GKE. --enable_gcp_components
Define o rótulo mesh_id no cluster, que é necessário para que as métricas sejam exibidas nas páginas do Anthos Service Mesh no console do Google Cloud. --enable_cluster_labels
Define um rótulo como asmv=asm-1118-4 para que você saiba que o cluster foi modificado pelo script. --enable_cluster_labels
Vincula o usuário da GCP ou a conta de serviço que executa o script ao papel de administrador do cluster no cluster. --enable_cluster_roles

A seguir