Como fazer upgrade do Anthos Service Mesh para a versão mais recente

Aviso: os comandos install_asm e istioctl install estão obsoletos com o lançamento do Anthos Service Mesh 1.11 e não terão suporte na versão 1.12. Atualize seus scripts e ferramentas para usar asmcli. Para mais informações, consulte Transição para asmcli.

Nesta página, explicamos como executar o script para fazer upgrade de qualquer versão e corrigir a versão 1.7.0 ou mais recente para o Anthos Service Mesh 1.11.8 em um cluster do GKE para uma malha que contenha um ou mais clusters que estão no mesmo projeto do Cloud.

Para fazer upgrade de onde os clusters estão em projetos diferentes, consulte o guia de vários projetos do GKE.

Nesta página, faremos upgrade do Anthos Service Mesh. Para informações sobre como executar o script para novas instalações e migrações a partir do Istio, consulte:

• Como instalar o Anthos Service Mesh
• Como migrar do Istio

Antes de começar

Antes de iniciar o upgrade, certifique-se de que você:

• revisou os requisitos;
• leu as notas de upgrade;
• registrou o cluster;
• instalou as ferramentas necessárias;
• fez o download do script.

O script requer que você tenha as permissões necessárias ou que você inclua as sinalizações --enable_all ou --enable_gcp_iam_roles para permitir que o script ative a permissão para você. Da mesma forma, para permitir que o script ative as APIs necessárias e atualize o cluster, especifique a sinalização --enable_all ou as sinalizações de ativação mais granulares.

Como se preparar para o upgrade

Se você tiver personalizado a instalação anterior, precisará das mesmas personalizações quando fizer upgrade para uma nova versão do Anthos Service Mesh ou migrar do Istio. Se você tiver personalizado a instalação adicionando a sinalização --set values em istioctl install, será necessário adicionar essas configurações a um arquivo YAML IstioOperator, chamado de arquivo de sobreposição. Especifique o arquivo de sobreposição usando a opção --custom_overlay com o nome de arquivo ao executar o script. O script transfere o arquivo de sobreposição para istioctl install.

Atenção: omitir o arquivo de sobreposição resulta em uma instalação bem-sucedida. Porém, a malha de serviço tem uma configuração diferente da pretendida porque os valores omitidos são redefinidos para os padrões quando o plano de controle e o gateway de entrada são reimplantados.

Observação: o upgrade no local usando istioctl upgrade não é compatível com o Anthos Service Mesh.

O script segue o processo de upgrade de revisão (chamado de upgrades "canário" na documentação do Istio). Com um upgrade baseado em revisão, o script instala uma nova versão do plano de controle com o plano de controle atual. Ao instalar a nova versão, o script inclui um rótulo revision que identifica o novo plano de controle.

Em seguida, você migra para a nova versão definindo o mesmo rótulo revision nas cargas de trabalho e realizando uma reinicialização gradual. Isso injeta os proxies novamente para que eles usem a nova versão e configuração do Anthos Service Mesh. Com essa abordagem, é possível monitorar o efeito do upgrade em uma pequena porcentagem das cargas de trabalho. Depois de testar o aplicativo, será possível migrar todo o tráfego para a nova versão. Essa abordagem é muito mais segura do que realizar um upgrade no local em que os novos componentes do plano de controle substituem a versão anterior.

Como fazer upgrade do Anthos Service Mesh

1. Defina as opções e especifique as sinalizações para executar o script. Você sempre incluirá as seguintes opções: project_id, cluster_name, cluster_location e mode.

   Observação: é possível usar --mode install para upgrades. Quando você usa --mode install em vez de --mode upgrade, install_asm permite o upgrade, independentemente da versão do plano de controle no cluster. A sinalização upgrade só permite um upgrade da versão secundária anterior ou de uma versão anterior do patch. Se você usar --mode install para um upgrade, especifique a mesma autoridade de certificação (CA) ativada no momento no cluster. Alterar a CA resultará em tempo de inatividade.

   Veja na seção a seguir exemplos típicos para executar o script. Consulte a barra de navegação à direita para ver uma lista dos exemplos. Para uma descrição completa dos argumentos do script, consulte Opção e sinalizações.

2. Para concluir a configuração do Anthos Service Mesh, você precisa ativar a injeção automática de arquivo secundário e implantar ou reimplantar cargas de trabalho.

Exemplos

Esta seção mostra exemplos de como executar o script para upgrades e alguns argumentos adicionais que podem ser úteis. Consulte a barra de navegação à direita para ver uma lista dos exemplos.

Somente validar

Veja no exemplo a seguir a execução do script com a opção --only_validate. Com essa opção, o script não faz alterações no projeto nem no cluster, assim como não instala o Anthos Service Mesh. Quando você especifica --only_validate, o script falha se você inclui qualquer uma das sinalizações --enable_*.

O script confirma que:

• Seu ambiente tem as ferramentas necessárias.
• Você tem a permissão necessária no projeto especificado.
• O cluster atende aos requisitos mínimos.
• O projeto tem todas as APIs do Google necessárias ativadas.

Por padrão, o script faz o download e extrai o arquivo de instalação e faz o download do pacote de configuração asm (em inglês) do GitHub para um diretório temporário. Antes de sair, o script gera uma mensagem que fornece o nome do diretório temporário. É possível especificar um diretório para os downloads com a opção --output_dir DIR_PATH. A opção --output_dir facilita o uso da ferramenta de linha de comando istioctl, se for necessário usá-la. Além disso, os arquivos de configuração para ativar recursos opcionais estão incluídos no diretório asm/istio/options.

Execute o seguinte comando para validar a configuração e fazer o download do arquivo de instalação e do pacote asm para o diretório OUTPUT_DIR:

./install_asm \
  --project_id PROJECT_ID \
  --cluster_name CLUSTER_NAME \
  --cluster_location CLUSTER_LOCATION \
  --mode install \
  --output_dir DIR_PATH \
  --only_validate

Em caso de sucesso, o script gera o seguinte:

./install_asm \
install_asm: Setting up necessary files...
install_asm: Creating temp directory...
install_asm: Generating a new kubeconfig...
install_asm: Checking installation tool dependencies...
install_asm: Downloading ASM..
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100 57.0M  100 57.0M    0     0  30.6M      0  0:00:01  0:00:01 --:--:-- 30.6M
install_asm: Downloading ASM kpt package...
fetching package /asm from https://github.com/GoogleCloudPlatform/anthos-service-mesh-packages to asm
install_asm: Checking for project PROJECT_ID...
install_asm: Confirming cluster information...
install_asm: Confirming node pool requirements...
install_asm: Fetching/writing GCP credentials to kubeconfig file...
Fetching cluster endpoint and auth data.
kubeconfig entry generated for cluster-1.
install_asm: Checking Istio installations...
install_asm: Checking required APIs...
install_asm: Successfully validated all requirements to install ASM from this computer.

Se um dos testes falhar na validação, o script exibirá uma mensagem de erro. Por exemplo, se seu projeto não tiver todas as APIs do Google necessárias ativadas, você verá o seguinte erro:

ERROR: One or more APIs are not enabled. Please enable them and retry, or run
the script with the '--enable_gcp_apis' flag to allow the script to enable them
on your behalf.

Se você recebeu uma mensagem de erro sobre a necessidade de executar o script com uma sinalização de ativação, terá as seguintes opções:

• Inclua a sinalização específica da mensagem de erro ou a sinalização --enable_all ao executar o script para realizar a instalação real (ou seja, sem --only_validate).

• Se preferir, atualize o projeto e o cluster antes de executar o script, conforme descrito em Como instalar o Anthos Service Mesh no GKE.

Observe que install_asm não permite nenhuma sinalização de ativação com --only_validate.

Upgrade

O comando a seguir executa o script para fazer upgrade. O script não permite que você mude para outra CA. Portanto, não é necessário incluir a opção ca.

Cuidado: se você tiver personalizado a instalação anterior, precisará especificar os arquivos de configuração IstioOperator usando a opção --custom_overlay. para criar um anexo da VLAN de monitoramento. A omissão do arquivo de configuração redefine o Anthos Service Mesh de volta para os valores padrão.

./install_asm \
  --project_id  PROJECT_ID \
  --cluster_name CLUSTER_NAME \
  --cluster_location CLUSTER_LOCATION \
  --mode install \
  --enable_all

Como fazer upgrade com um arquivo de sobreposição

Um arquivo de sobreposição é um arquivo YAML contendo um recurso personalizado (CR) IstioOperator que você passa para install_asm para configurar o plano de controle. É possível substituir a configuração do plano de controle padrão e ativar um recurso opcional transmitindo o arquivo YAML para install_asm. É possível usar mais camadas, e cada arquivo de sobreposição substitui a configuração nas camadas anteriores.

Se você especificar mais de uma CR em um arquivo YAML, install_asm divide o arquivo em vários arquivos YAML temporários, um para cada resposta automática. O script divide as respostas em arquivos separados porque istioctl install só aplica a primeira resposta automática em um arquivo YAML contendo mais de uma resposta automática.

O exemplo a seguir faz um upgrade e inclui um arquivo de sobreposição para personalizar a configuração do plano de controle. No comando a seguir, altere OVERLAY_FILE para o nome do arquivo YAML.

./install_asm \
  --project_id PROJECT_ID \
  --cluster_name CLUSTER_NAME \
  --cluster_location CLUSTER_LOCATION \
  --mode install \
  --enable_all \
  --custom_overlay OVERLAY_FILE

Como fazer upgrade com uma opção

O exemplo a seguir faz um upgrade e inclui o arquivo egressgateways.yaml do pacote anthos-service-mesh (em inglês), que ativa um gateway de saída. Não inclua a extensão .yaml. O script recupera o arquivo, então não é necessário fazer o download do pacote asm primeiro.

./install_asm \
  --project_id PROJECT_ID \
  --cluster_name CLUSTER_NAME \
  --cluster_location CLUSTER_LOCATION \
  --mode install \
  --enable_all \
  --option egressgateways

É possível usar --option para ativar um recurso opcional. Se você precisar fazer modificações em qualquer um dos arquivos no diretório asm/istio/options no pacote asm, faça o download do pacote asm, faça suas alterações e inclua o arquivo usando --custom_overlay.

Para fazer o download do pacote asm para o diretório de trabalho atual, faça modificações nos arquivos:

kpt pkg get \
https://github.com/GoogleCloudPlatform/anthos-service-mesh-packages.git/asm@release-1.11 asm

Se você executou o exemplo Apenas validar em que especificou a opção --output_dir, os arquivos de configuração estão no diretório de saída especificado em asm/istio/options.

Como implantar e reimplantar cargas de trabalho

A instalação (ou upgrade) só vai ser concluída quando você ativar a injeção automática de proxy sidecar (injeção automática). As migrações do OSS Istio e os upgrades seguem o processo de upgrade baseado em revisão (chamado de "upgrades canário" na documentação do Istio). Com um upgrade baseado em revisão, a nova versão do plano de controle é instalada com o plano de controle existente. Depois, transfira parte das cargas de trabalho para a nova versão. Isso permite monitorar o efeito do upgrade com uma pequena porcentagem das cargas de trabalho antes de migrar todo o tráfego para a nova versão.

O script define um rótulo de revisão no formato istio.io/rev=asm-1118-4 em istiod. Para ativar a injeção automática, adicione um rótulo de revisão correspondente aos namespaces. O rótulo de revisão é usado pelo webhook do injetor automático de arquivos secundários para associar os arquivos secundários injetados a uma revisão istiod específica. Depois de adicionar o rótulo, reinicie os pods no namespace para que os arquivos secundários sejam injetados.

1. Consiga o rótulo de revisão em istiod e o istio-ingressgateway.

   kubectl get pod -n istio-system -L istio.io/rev
   

   A saída deste comando é semelhante a:

   NAME                                             READY   STATUS    RESTARTS   AGE   REV
   istio-ingressgateway-65d884685d-6hrdk            1/1     Running   0          67m
   istio-ingressgateway-65d884685d-94wgz            1/1     Running   0          67m
   istio-ingressgateway-asm-182-2-8b5fc8767-gk6hb   1/1     Running   0          5s    asm-1118-4
   istio-ingressgateway-asm-182-2-8b5fc8767-hn4w2   1/1     Running   0          20s   asm-1118-4
   istiod-asm-176-1-67998f4b55-lrzpz                1/1     Running   0          68m   asm-1107-1
   istiod-asm-176-1-67998f4b55-r76kr                1/1     Running   0          68m   asm-1107-1
   istiod-asm-182-2-5cd96f88f6-n7tj9                1/1     Running   0          27s   asm-1118-4
   istiod-asm-182-2-5cd96f88f6-wm68b                1/1     Running   0          27s   asm-1118-4

   1. Na saída, na coluna REV, anote o valor do rótulo de revisão da nova versão. Neste exemplo, o valor é asm-1118-4.

   2. Observe também o valor no rótulo de revisão da versão istiod antiga. Você precisará dele para excluir a versão antiga do istiod ao terminar de mover as cargas de trabalho para a nova versão. No exemplo de saída, o valor do rótulo de revisão da versão antiga é asm-1107-1.

2. Alterne istio-ingressgateway para a nova revisão. No comando a seguir, altere REVISION para o valor que corresponda ao rótulo de revisão da nova versão.

   kubectl patch service -n istio-system istio-ingressgateway --type='json' -p='[{"op": "replace", "path": "/spec/selector/service.istio.io~1canonical-revision", "value": "REVISION"}]'

   Resposta esperada: service/istio-ingressgateway patched

3. Adicione o rótulo de revisão a um namespace e remova o rótulo istio-injection, se ele existir. No comando a seguir, altere REVISION para o valor que corresponda à nova revisão de istiod.

   kubectl label namespace NAMESPACE istio.io/rev=REVISION istio-injection- --overwrite

   Se vir "istio-injection not found" na saída, poderá ignorá-la. Isso significa que o namespace não tinha o rótulo istio-injection anteriormente. Como a injeção automática falha se um namespace tiver o istio-injection e o rótulo de revisão, todos os comandos kubectl label na documentação do Anthos Service Mesh incluem a remoção do rótulo istio-injection

4. Reinicie os pods para acionar a nova injeção:

   kubectl rollout restart deployment -n NAMESPACE

5. Teste o aplicativo para verificar se as cargas de trabalho estão funcionando corretamente.

6. Se você tiver cargas de trabalho em outros namespaces, repita as etapas para rotular o namespace e reiniciar os pods.

7. Se você achar que seu aplicativo está funcionando conforme esperado, continue com as etapas para concluir a transição para a nova versão de istiod. Se houver um problema com o aplicativo, siga as etapas para reverter.

   Concluir a transição

   Se o aplicativo estiver funcionando corretamente, remova o plano de controle antigo para concluir a transição para a nova versão.

   1. Altere para o diretório em que os arquivos do repositório anthos-service-mesh do GitHub estão localizados.

   2. Configure o webhook de validação para usar o novo plano de controle.

      kubectl apply -f asm/istio/istiod-service.yaml
      

   3. Exclua a implantação istio-ingressgateway antiga. O comando executado depende se você está migrando do Istio ou fazendo upgrade de uma versão anterior do Anthos Service Mesh:

      Migrate

      Se você tiver migrado do Istio, o istio-ingressgateway antigo não terá um rótulo de revisão.

      kubectl delete deploy/istio-ingressgateway -n istio-system
      

      Fazer upgrade

      Se você tiver feito upgrade de uma versão anterior do Anthos Service Mesh, no comando a seguir, substitua OLD_REVISION pelo rótulo de revisão da versão anterior do istio-ingressgateway.

      kubectl delete deploy -l app=istio-ingressgateway,istio.io/rev=OLD_REVISION -n istio-system --ignore-not-found=true
      

   4. Exclua a versão antiga de istiod. O comando usado depende de se você está migrando do Istio ou fazendo upgrade de uma versão anterior do Anthos Service Mesh.

      Migrate

      Se você tiver migrado do Istio, o istio-ingressgateway antigo não terá um rótulo de revisão.

      kubectl delete Service,Deployment,HorizontalPodAutoscaler,PodDisruptionBudget istiod -n istio-system --ignore-not-found=true
      

      Fazer upgrade

      Se você fez upgrade de uma versão anterior do Anthos Service Mesh, no comando a seguir, verifique se OLD_REVISION corresponde ao rótulo de revisão da versão anterior de istiod.

      kubectl delete Service,Deployment,HorizontalPodAutoscaler,PodDisruptionBudget istiod-OLD_REVISION -n istio-system --ignore-not-found=true
      

   5. Remova a versão antiga da configuração de IstioOperator.

      kubectl delete IstioOperator installed-state-OLD_REVISION -n istio-system
      

      A saída esperada terá esta aparência:

      istiooperator.install.istio.io "installed-state-OLD_REVISION" deleted

   Reversão

   Se você encontrar um problema ao testar seu aplicativo com a nova versão de istiod, siga estas etapas para reverter para a versão anterior:

   1. Volte para a versão antiga de istio-ingressgateway. No comando a seguir, substitua OLD_REVISION pela revisão antiga.

      kubectl patch service -n istio-system istio-ingressgateway --type='json' -p='[{"op": "replace", "path": "/spec/selector/service.istio.io~1canonical-revision", "value": "OLD_REVISION"}]'
      

   2. Altere o nome do seu namespace para ativar a injeção automática com a versão anterior do istiod. O comando usado depende de você ter usado um rótulo de revisão ou istio-injection=enabled com a versão anterior.

      • Se você usou um rótulo de revisão para a injeção automática, faça o seguinte:

        kubectl label namespace NAMESPACE istio.io/rev=OLD_REVISION --overwrite
        

      • Se você usou istio-injection=enabled:

        kubectl label namespace NAMESPACE istio.io/rev- istio-injection=enabled --overwrite
        

      Resposta esperada:

      namespace/NAMESPACE labeled

   3. Confirme se o rótulo de revisão no namespace corresponde ao rótulo de revisão na versão anterior de istiod:

      kubectl get ns NAMESPACE --show-labels
      

   4. Reinicie os pods para acionar a nova injeção de modo que os proxies tenham a versão do Istio:

      kubectl rollout restart deployment -n NAMESPACE
      

   5. Remova a nova implantação istio-ingressgateway. Verifique se o valor de REVISION no comando a seguir está correto.

      kubectl delete deploy -l app=istio-ingressgateway,istio.io/rev=REVISION -n istio-system --ignore-not-found=true
      

   6. Remova a nova versão de istiod. Verifique se o valor de REVISION no comando a seguir está correto.

      kubectl delete Service,Deployment,HorizontalPodAutoscaler,PodDisruptionBudget istiod-REVISION -n istio-system --ignore-not-found=true
      

   7. Remova a nova versão da configuração IstioOperator.

      kubectl delete IstioOperator installed-state-REVISION -n istio-system
      

      A saída esperada será assim:

      istiooperator.install.istio.io "installed-state-REVISION" deleted

   8. Se você não incluiu a sinalização --disable_canonical_service, o script ativou o controlador de serviço canônico. É recomendável deixá-la ativada, mas, se você precisar desativá-la, consulte Como ativar e desativar o controlador de serviço canônico.

Como visualizar os painéis do Anthos Service Mesh

Depois de implantar as cargas de trabalho no seu cluster com os proxies sidecar injetados, é possível explorar as páginas do Anthos Service Mesh no Console do Cloud para ver todos os recursos de observação que o Anthos Service Mesh oferece. Observe que leva cerca de um ou dois minutos para que os dados de telemetria sejam exibidos no Console do Cloud após a implantação das cargas de trabalho.

O acesso ao Anthos Service Mesh no Console do Cloud é controlado pelo Gerenciamento de identidade e acesso (IAM). Para acessar as páginas do Anthos Service Mesh, um proprietário do projeto precisa conceder aos usuários o papel de Editor ou Visualizador de projeto ou os papéis mais restritivos descritos em Como controlar o acesso ao Anthos Service Mesh no Console do Cloud.

1. No Console do Google Cloud, acesse Anthos Service Mesh.

   Acesse o Anthos Service Mesh

2. Selecione o projeto do Cloud na lista suspensa na barra de menus.

3. Se você tiver mais de uma malha de serviço, selecione a malha na lista suspensa Service Mesh.

Para saber mais, consulte Como explorar o Anthos Service Mesh no Console do Cloud.

Além das páginas do Anthos Service Mesh, as métricas relacionadas aos seus serviços, como o número de solicitações recebidas por um serviço específico, são enviadas para o Cloud Monitoring, onde elas aparecem o Metrics Explorer.

Para ver métricas:

1. No Console do Google Cloud, acesse a página Monitoring.

   Acessar Monitoring

2. Selecione Recursos > Metrics Explorer.

Veja uma lista completa de métricas em Métricas do Istio na documentação do Cloud Monitoring.

A seguir

• Implantar o aplicativo de amostra Online Boutique
• Como configurar uma malha de vários clusters