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}
Digite install se você estiver fazendo uma nova instalação do Anthos Service Mesh. Digite migrate se você estiver migrando do Istio. Insira upgrade para atualizar uma instalação atual do Anthos Service Mesh para uma nova versão.
-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 conhecer outras opções que você precisa especificar ao usar o Citadel, consulte Opções para um certificado personalizado para o Citadel.
--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
-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.
-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 designar um diretório existente a ser usado. Após a conclusão, o diretório especificado conterá os subdiretórios asm e istio-1.8.6-asm.8. O diretório asm contém a configuração da instalação. O diretório istio-1.8.6-asm.8 tem o conteúdo extraído do arquivo de instalação, que contém istioctl, amostras e manifestos.

Opções do certificado personalizado do Citadel

Se você especificou 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-value 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 não está incluído em --enable_all. Especifique essa sinalização separadamente.

Outras sinalizações

-v|--verbose
Mostra comandos antes e depois da execução.
--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.
--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.8.

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.8.6, você usa a versão do script install_asm na ramificação release-1.8-asm. Para uma explicação do processo de controle de versão e lançamento, consulte Controle de versões/lançamento.

Validação

validate_args() {
  if [[ "${MODE}" == "install" && -z "${CA}" ]]; then
    CA="mesh_ca"
  fi

  if is_managed; then
    if [[ "${MODE}" != "install" ]]; then
      fatal "Migrate and upgrade are incompatible with managed control plane."
    fi

    if [[ "${CA}" == "citadel" ]]; then
      fatal "Citadel is not supported with managed control plane."
    fi

    if [[ "${CA}" == "gcp_cas" ]]; then
      fatal "Google Certificate Authority Service integration is not supported with managed control plane."
    fi

    if [[ "${CUSTOM_CA}" -eq 1 ]]; then
      fatal "Specifying a custom CA with managed control plane is not supported."
    fi
  fi

  local MISSING_ARGS=0
  while read -r REQUIRED_ARG; do
    if [[ -z "${!REQUIRED_ARG}" ]]; then
      MISSING_ARGS=1
      warn "Missing value for ${REQUIRED_ARG}"
    fi
    readonly "${REQUIRED_ARG}"
  done <<EOF
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
}

As funções validate_args e validate_dependencies:

  • Verifique se todas as ferramentas necessárias estão instaladas.
  • Verifique se o nome e o local do cluster, além do ID do projeto que você inseriu como valores de parâmetro são válidos.
  • Garante que o cluster atenda ao tipo de máquina e ao número de nós mínimo necessário.

Configurar o projeto

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

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

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-186-8 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