Como fazer upgrade do Anthos Service Mesh no GKE

Neste guia, explicamos como fazer upgrade do Anthos Service Mesh da versão 1.5.4+ or 1.6.4+ para a versão 1.6.14 no GKE. Para fazer upgrade do Anthos Service Mesh 1.4.5 ou mais recente, primeiro é necessário fazer o upgrade para o Anthos Service Mesh 1.5. Não há compatibilidade para fazer upgrade direto do Anthos Service Mesh 1.4 para 1.6.

Recomendamos um upgrade duplo do plano de controle, também conhecido como upgrade canário. Nele, as versões nova e anterior do plano de controle são executadas enquanto você testa a nova versão com uma pequena porcentagem das cargas de trabalho. Essa abordagem é mais segura do que um upgrade no local, em que a nova versão do plano de controle substitui a versão anterior. O upgrade do istio-ingressgateway é feito no local, portanto, você precisa planejar uma interrupção no cluster.

A reimplantação dos componentes do plano de controle do Anthos Service Mesh leva cerca de 5 a 10 minutos para ser concluída. Além disso, é necessário injetar novos proxies sidecar em todas as cargas de trabalho para que eles sejam atualizados com a versão atual do Anthos Service Mesh. O tempo necessário para atualizar os proxies sidecar depende de muitos fatores, como o número de pods, o número de nós, as configurações de escalonamento da implantação, os orçamentos de interrupção dos pods e outras definições de configuração. Uma estimativa aproximada do tempo necessário para atualizar os proxies sidecar é de 100 pods por minuto.

Como se preparar para o upgrade

Nesta seção, descrevemos os passos que você segue para se preparar para fazer upgrade do Anthos Service Mesh.

  1. Analise os Recursos compatíveis e este guia para conhecer os recursos e o processo de upgrade.

  2. Se você ativou recursos opcionais quando instalou a versão anterior do Anthos Service Mesh, precisa ativar os mesmos recursos ao fazer upgrade. Para ativar recursos opcionais, adicione sinalizações --set values ou especifique a sinalização -f com um arquivo YAML ao executar o comando istioctl install.

  3. Se você estiver instalando o Anthos Service Mesh em um cluster particular, abra a porta 15017 no firewall para que o webhook usado com a injeção automática de sidecar funcione corretamente. Para mais informações, consulte Como abrir uma porta em um cluster particular.

  4. Se você estiver fazendo upgrade do Anthos Service Mesh 1.5, siga estes passos caso precise reverter:

    1. Crie um diretório chamado asm-1-5.

    2. Faça o download do arquivo de instalação 1.5 para o diretório asm-1-5.

    3. Extraia o conteúdo do arquivo para o diretório asm-1-5.

    4. Verifique se você está no diretório raiz de instalação do Anthos Service Mesh 1.5.

    5. Faça o download do pacote kpt 1.5 e configure o istio-operator.yaml 1.5.

Como configurar o ambiente

Para instalações no Google Kubernetes Engine, siga os guias de instalação usando o Cloud Shell, uma interface de linha de comando no navegador para os recursos do Google Cloud ou no computador com Linux ou macOS:

Opção A: usar o Cloud Shell

O Cloud Shell provisiona uma máquina virtual (VM) g1-small do Compute Engine que executa um sistema operacional Linux baseado em Debian. Veja abaixo as vantagens de usar o Cloud Shell:

  • O Cloud Shell inclui as ferramentas de linha de comando gcloud, kubectl e helm necessárias.

  • O diretório $HOME do Cloud Shell tem 5 GB de espaço de armazenamento permanente.

  • É possível escolher os editores de texto:

    • Editor de código, que você acessa clicando em na parte superior da janela do Cloud Shell.

    • Emacs, Vim ou Nano, que você acessa na linha de comando do Cloud Shell.

Para usar o Cloud Shell:

  1. Acesse o Console do Google Cloud.
  2. Selecione seu projeto do Google Cloud.
  3. Clique no botão Ativar Cloud Shell na parte superior da janela do console do Google Cloud.

    Console do Google Cloud Platform

    Uma sessão do Cloud Shell é aberta dentro de um novo frame na parte inferior do console do Google Cloud, e exibe um prompt de linha de comando.

    Sessão do Cloud Shell

  4. Atualize os componentes:

    gcloud components update
    

    O comando responde com uma saída semelhante a esta:

    ERROR: (gcloud.components.update)
    You cannot perform this action because the gcloud CLI component manager
    is disabled for this installation. You can run the following command
    to achieve the same result for this installation:
    
    sudo apt-get update && sudo apt-get --only-upgrade install ...
  5. Copie o comando longo e cole-o para atualizar os componentes.

  6. Verifique se o Git está no seu caminho para que kpt possa encontrá-lo.

Opção B: usar ferramentas de linha de comando localmente

Na máquina local, instale e inicialize a gcloud CLI.

Se a gcloud CLI já estiver instalada:

  1. Faça a autenticação com a gcloud CLI:

    gcloud auth login
    
  2. Atualize os componentes:

    gcloud components update
    
  3. Instale kubectl:

    gcloud components install kubectl
    
  4. Instale kpt:

    gcloud components install kpt
    
  5. Verifique se o Git está no seu caminho para que kpt possa encontrá-lo.

Como definir variáveis de ambiente

  1. Consiga o ID do projeto em que o cluster foi criado e o número do projeto host da frota.

    gcloud

    Execute este comando:

    gcloud projects list
    

    Console

    1. Acesse a página Painel no console do Google Cloud:

      Ir para a página "Painel"

    2. Clique na lista suspensa Selecionar de na parte superior da página. Na janela Selecionar de exibida, selecione seu projeto.

      O ID do projeto é exibido no card Informações do projeto do Painel.

  2. Crie uma variável de ambiente para o ID do projeto em que o cluster foi criado:

    export PROJECT_ID=YOUR_PROJECT_ID

  3. Crie uma variável de ambiente para o número do projeto host da frota:

    export FLEET_PROJECT_NUMBER=YOUR_FLEET_PROJECT_NUMBER

  4. Crie as variáveis de ambiente a seguir:

    • Defina o nome do cluster:

      export CLUSTER_NAME=YOUR_CLUSTER_NAME
    • Defina CLUSTER_LOCATION como a zona ou a região do cluster:

      export CLUSTER_LOCATION=YOUR_ZONE_OR_REGION

Se preferir, altere o ID da malha no cluster

Caso a malha de serviço contenha ou venha a conter vários clusters que estão em projetos diferentes, todos os clusters precisarão ter o mesmo ID da malha, que é baseado no número do projeto host da frota. O ID da malha definido no cluster precisa corresponder ao ID que você configurou para uso no Anthos Service Mesh.

Se você tiver somente um cluster, ou se a malha de serviço contiver (ou vir a conter) vários clusters que estão no mesmo projeto, pule as etapas a seguir e continue em Como configurar credenciais e permissões.

Para definir o novo rótulo do ID da malha no cluster:

  1. Crie uma variável de ambiente para o ID da malha:

    export MESH_ID="proj-${FLEET_PROJECT_NUMBER}"

  2. Se o cluster tiver rótulos existentes que você quer manter, inclua-os ao adicionar o rótulo mesh_id.

    1. Para ver se o cluster tem rótulos existentes:

      gcloud container clusters describe ${CLUSTER_NAME} \
        --project ${PROJECT_ID}

      Procure o campo resourceLabels na saída. Cada rótulo é armazenado em uma linha separada no campo resourceLabels. Por exemplo:

      resourceLabels:
        csm: ''
        env: dev
        release: stable

      Não é necessário preservar o mesh_id atual. Substitua-o pelo novo rótulo mesh_id.

      Para facilitar, é possível adicionar os rótulos a uma variável de ambiente. No exemplo a seguir, substitua YOUR_EXISTING_LABELS por uma lista separada por vírgulas dos rótulos existentes no seu cluster no formato KEY=VALUE. Por exemplo: env=dev,release=stable

      export EXISTING_LABELS="YOUR_EXISTING_LABELS"
    2. Defina o rótulo mesh_id:

      • Se o cluster tiver rótulos que você quer manter, atualize o cluster com o mesh_id e os rótulos existentes:

        gcloud container clusters update ${CLUSTER_NAME} \
          --project ${PROJECT_ID}
          --update-labels=mesh_id=${MESH_ID},${EXISTING_LABELS}
      • Se o cluster não tiver rótulos existentes, atualize o cluster somente com o novo rótulo mesh_id:

        gcloud container clusters update ${CLUSTER_NAME} \
          --project=${PROJECT_ID} \
          --update-labels=mesh_id=${MESH_ID}

Como configurar credenciais e permissões

  1. Consiga as credenciais de autenticação para interagir com o cluster:

    gcloud container clusters get-credentials ${CLUSTER_NAME} \
        --project=${PROJECT_ID}
    
  2. Conceda permissões de administrador de cluster ao usuário atual. Você precisa dessas permissões para criar as regras necessárias de controle de acesso baseado em papéis (RBAC, na sigla em inglês) para o Anthos Service Mesh:

    kubectl create clusterrolebinding cluster-admin-binding \
      --clusterrole=cluster-admin \
      --user="$(gcloud config get-value core/account)"

Se você observar o erro "cluster-admin-binding" already exists, poderá ignorá-lo com segurança e continuar com o cluster-admin-binding atual.

Como fazer o download do arquivo de instalação

    Linux

  1. Faça o download do arquivo de instalação do Anthos Service Mesh no diretório de trabalho atual:
    curl -LO https://storage.googleapis.com/gke-release/asm/istio-1.6.14-asm.2-linux-amd64.tar.gz
  2. Faça o download do arquivo de assinatura e use openssl para verificar a assinatura:
    curl -LO https://storage.googleapis.com/gke-release/asm/istio-1.6.14-asm.2-linux-amd64.tar.gz.1.sig
    openssl dgst -verify /dev/stdin -signature istio-1.6.14-asm.2-linux-amd64.tar.gz.1.sig istio-1.6.14-asm.2-linux-amd64.tar.gz <<'EOF'
    -----BEGIN PUBLIC KEY-----
    MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEWZrGCUaJJr1H8a36sG4UUoXvlXvZ
    wQfk16sxprI2gOJ2vFFggdq3ixF2h4qNBt0kI7ciDhgpwS8t+/960IsIgw==
    -----END PUBLIC KEY-----
    EOF

    A saída esperada é Verified OK.

  3. Extraia o conteúdo do arquivo em qualquer local no sistema. Por exemplo, para extrair o conteúdo para o diretório de trabalho atual:
    tar xzf istio-1.6.14-asm.2-linux-amd64.tar.gz

    O comando cria um diretório de instalação no seu diretório de trabalho atual chamado istio-1.6.14-asm.2, que contém:

    • Exemplos de aplicativos no diretório samples.
    • A ferramenta de linha de comando istioctl usada para instalar o Anthos Service Mesh está no diretório bin.
    • Os perfis de configuração do Anthos Service Mesh estão no diretório manifests/profiles.

  4. macOS

  5. Faça o download do arquivo de instalação do Anthos Service Mesh no diretório de trabalho atual:
    curl -LO https://storage.googleapis.com/gke-release/asm/istio-1.6.14-asm.2-osx.tar.gz
  6. Faça o download do arquivo de assinatura e use openssl para verificar a assinatura:
    curl -LO https://storage.googleapis.com/gke-release/asm/istio-1.6.14-asm.2-osx.tar.gz.1.sig
    openssl dgst -sha256 -verify /dev/stdin -signature istio-1.6.14-asm.2-osx.tar.gz.1.sig istio-1.6.14-asm.2-osx.tar.gz <<'EOF'
    -----BEGIN PUBLIC KEY-----
    MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEWZrGCUaJJr1H8a36sG4UUoXvlXvZ
    wQfk16sxprI2gOJ2vFFggdq3ixF2h4qNBt0kI7ciDhgpwS8t+/960IsIgw==
    -----END PUBLIC KEY-----
    EOF

    A saída esperada é Verified OK.

  7. Extraia o conteúdo do arquivo em qualquer local no sistema. Por exemplo, para extrair o conteúdo para o diretório de trabalho atual:
    tar xzf istio-1.6.14-asm.2-osx.tar.gz

    O comando cria um diretório de instalação no seu diretório de trabalho atual chamado istio-1.6.14-asm.2, que contém:

    • Exemplos de aplicativos no diretório samples.
    • A ferramenta de linha de comando istioctl usada para instalar o Anthos Service Mesh está no diretório bin.
    • Os perfis de configuração do Anthos Service Mesh estão no diretório manifests/profiles.

  8. Windows

  9. Faça o download do arquivo de instalação do Anthos Service Mesh no diretório de trabalho atual:
    curl -LO https://storage.googleapis.com/gke-release/asm/istio-1.6.14-asm.2-win.zip
  10. Faça o download do arquivo de assinatura e use openssl para verificar a assinatura:
    curl -LO https://storage.googleapis.com/gke-release/asm/istio-1.6.14-asm.2-win.zip.1.sig
    openssl dgst -verify - -signature istio-1.6.14-asm.2-win.zip.1.sig istio-1.6.14-asm.2-win.zip <<'EOF'
    -----BEGIN PUBLIC KEY-----
    MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEWZrGCUaJJr1H8a36sG4UUoXvlXvZ
    wQfk16sxprI2gOJ2vFFggdq3ixF2h4qNBt0kI7ciDhgpwS8t+/960IsIgw==
    -----END PUBLIC KEY-----
    EOF

    A saída esperada é Verified OK.

  11. Extraia o conteúdo do arquivo em qualquer local no sistema. Por exemplo, para extrair o conteúdo para o diretório de trabalho atual:
    tar xzf istio-1.6.14-asm.2-win.zip

    O comando cria um diretório de instalação no seu diretório de trabalho atual chamado istio-1.6.14-asm.2, que contém:

    • Exemplos de aplicativos no diretório samples.
    • A ferramenta de linha de comando istioctl usada para instalar o Anthos Service Mesh está no diretório bin.
    • Os perfis de configuração do Anthos Service Mesh estão no diretório manifests/profiles.

  12. Verifique se você está no diretório raiz da instalação do Anthos Service Mesh.
    cd istio-1.6.14-asm.2
  13. Para facilitar, adicione as ferramentas ao diretório /bin/bin do seu PATH.
    export PATH=$PWD/bin:$PATH

Como preparar arquivos de configuração de recursos

Ao executar o comando istioctl install, especifique -f istio-operator.yaml na linha de comando. Esse arquivo contém informações sobre o projeto e o cluster exigidos pelo Anthos Service Mesh. Faça o download de um pacote que contenha istio-operator.yaml e outros arquivos de configuração de recursos para que seja possível definir as informações do projeto e do cluster.

Para começar, escolha um pacote para fazer o download com base na autoridade de certificação (CA, na sigla em inglês) que você quer usar:

  • asm: Este pacote ativa o Mesh CA, que recomendamos para novas instalações.

  • asm-citadel: você tem a opção de ativar o Citadel como o CA. Antes de escolher esse pacote, consulte Como escolher uma autoridade de certificação para mais informações.

Para preparar os arquivos de configuração de recursos, siga estas etapas:

  1. Crie um novo diretório para os arquivos de configuração do recurso do pacote Anthos Service Mesh. Recomendamos que você use o nome do cluster como o nome do diretório.

  2. Altere para o diretório em que você quer fazer o download do pacote do Anthos Service Mesh.

  3. Faça o download do pacote que você quer usar com base na CA.

    CA da malha

    Faça o download do pacote asm, que ativa a CA da malha:

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

    Citadel

    Faça o download do pacote asm-citadel, que ativa o Citadel como a CA:

    kpt pkg get \
    https://github.com/GoogleCloudPlatform/anthos-service-mesh-packages.git/asm-citadel@release-1.6-asm asm
    
  4. Defina o ID do projeto em que o cluster foi criado:

    kpt cfg set asm gcloud.core.project ${PROJECT_ID}
    
  5. Defina o número do projeto host da frota:

    kpt cfg set asm gcloud.project.environProjectNumber ${FLEET_PROJECT_NUMBER}
    
  6. Defina o nome do cluster:

    kpt cfg set asm gcloud.container.cluster ${CLUSTER_NAME}
    
  7. Defina a zona ou a região padrão:

    kpt cfg set asm gcloud.compute.location ${CLUSTER_LOCATION}
    
  8. Defina o perfil de configuração que você planeja usar:

    • Se todos os clusters estiverem no mesmo projeto, defina o perfil asm-gcp:

      kpt cfg set asm anthos.servicemesh.profile asm-gcp
      
    • Se a malha de serviço contiver ou tiver vários clusters que estão em projetos diferentes, defina o perfil asm-gcp-multiproject (Beta):

      kpt cfg set asm anthos.servicemesh.profile asm-gcp-multiproject
      
  9. Se você definir o perfil asm-gcp-multiproject e fizer o download do pacote asm, que ativa o CA da CA, será necessário configurar os aliases de domínio de confiança para os outros projetos que formam a malha de serviço de cluster/vários projetos. Caso contrário, pule esta etapa.

    1. Encontre o ID do projeto de todos os clusters que estarão na malha de vários clusters/vários projetos.

    2. Para o ID do projeto de cada cluster, defina os aliases do domínio de confiança. Por exemplo, se você tiver clusters em três projetos, execute o seguinte comando e substitua PROJECT_ID_1, PROJECT_ID_2 e PROJECT_ID_3 pelo ID do projeto de cada cluster.

      kpt cfg set asm anthos.servicemesh.trustDomainAliases PROJECT_ID_1.svc.id.goog PROJECT_ID_2.svc.id.goog PROJECT_ID_3.svc.id.goog

      Ao configurar os clusters nos outros projetos, é possível usar o mesmo comando.

      Os aliases de domínio de confiança permitem que a CA da malha autentique cargas de trabalho em clusters em outros projetos. Além de definir os aliases de domínio de confiança, depois de instalar o Anthos Service Mesh, você precisa ativar o balanceamento de carga entre clusters.

  10. Gere os valores dos setters kpt:

      kpt cfg list-setters asm
    

    Na saída do comando, verifique se os valores dos setters a seguir estão corretos:

    • gcloud.compute.location
    • gcloud.container.cluster
    • gcloud.core.project
    • gcloud.project.environProjectNumber

Como fazer upgrade do Anthos Service Mesh

Para instalar uma nova versão do Anthos Service Mesh, recomendamos seguir o processo de upgrade do plano de controle duplo, chamado de "upgrade canário" na documentação do Istio. Com um upgrade do plano de controle duplo, você instala uma nova versão do plano de controle junto com o plano atual. Ao instalar a nova versão, inclua uma etiqueta revision que identifique a versão do novo plano de controle. Cada revisão é uma implementação completa do plano de controle do Anthos Service Mesh com implantação e serviço próprios.

Em seguida, você migra para a nova versão definindo a mesma etiqueta revision em suas cargas de trabalho para apontar para o novo plano de controle e realizando uma reinicialização gradual para reinjetar os proxies com a nova versã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, é possível migrar todo o tráfego para a nova versão. Essa abordagem é muito mais segura do que fazer um upgrade no local em que um novo plano de controle substitui a versão anterior do plano de controle.

Como atualizar o plano de controle

Execute o comando a seguir para implantar o novo plano de controle usando o perfil de configuração definido no arquivo istio-operator.yaml. Se você quiser ativar um recurso opcional compatível, inclua -f e o nome de arquivo YAML na linha de comando a seguir. Para ver mais informações, consulte Como ativar recursos opcionais.

  istioctl install \
    -f asm/cluster/istio-operator.yaml \
    --set revision=asm-1614-2

O argumento --set revision adiciona um rótulo istio.io/rev ao istiod. Depois de executar o comando, você tem duas implantações e dois serviços de plano de controle sendo executados lado a lado:

kubectl get pods -n istio-system

Exemplo de saída:

NAME                                        READY   STATUS    RESTARTS   AGE
istio-ingressgateway-c56675fcd-86zdn        1/1     Running   0          2m9s
istio-ingressgateway-c56675fcd-vn4nv        1/1     Running   0          2m21s
istiod-asm-1614-2-6d5cfd4b89-xztlr           1/1     Running   0          3m44s
istiod-fb7f746f4-wcntn                      1/1     Running   0          50m

Como reimplantar cargas de trabalho

A instalação da nova revisão não afeta os proxies sidecar atuais. Para fazer upgrade, configure-os para que direcionem para o novo plano de controle. Isso é controlado durante a injeção do sidecar com base no rótulo de namespace istio.io/rev.

  1. Atualize as cargas de trabalho que serão injetadas com a nova versão do Anthos Service Mesh:

    kubectl label namespace NAMESPACE istio-injection- istio.io/rev=asm-1614-2 --overwrite

    O rótulo istio-injection precisa ser removido porque tem precedência sobre o rótulo istio.io/rev.

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

    kubectl rollout restart deployment -n NAMESPACE
  3. Verifique se os pods estão configurados de modo que apontem para o plano de controle istiod-asm-1614-2:

    kubectl get pods -n NAMESPACE -l istio.io/rev=asm-1614-2

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

  5. Se você tiver cargas de trabalho em outros namespaces, repita os passos anteriores para cada namespace.

  6. Se o aplicativo funcionar como esperado, pule para Concluir o upgrade. Caso contrário, execute os passos a seguir para voltar à versão anterior.

    1. Atualize as cargas de trabalho a serem injetadas com a versão anterior do plano de controle:

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

    2. Reinicie os pods para acionar a reinjeção para que os proxies tenham a versão anterior:

       kubectl rollout restart deployment -n NAMESPACE

    3. Reverta os componentes do plano de controle:

      Reverter para a versão 1.6 anterior

      1. Reimplante a versão anterior do istio-ingressgateway:

        kubectl -n istio-system rollout undo deploy istio-ingressgateway
        
      2. Remova o novo plano de controle:

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

      Reverter para a versão 1.5

      1. Mude para o diretório em que você fez o download do arquivo de instalação do Anthos Service Mesh 1.5.

      2. Reinstale a versão anterior do Anthos Service Mesh. No comando a seguir, se você tiver ativado recursos opcionais, inclua as sinalizações --set values ou -f aplicáveis com o nome do arquivo YAML.

        bin/istioctl install \
        -f asm/cluster/istio-operator.yaml

Conclua o upgrade

Se o aplicativo estiver funcionando conforme o esperado, siga os passos a seguir para concluir o upgrade:

  1. Remova o plano de controle antigo:

    kubectl delete Service,Deployment,HorizontalPodAutoscaler,PodDisruptionBudget istiod -n istio-system --ignore-not-found=true
    
  2. Execute o seguinte comando para implantar o controlador de serviço canônico:

    kubectl apply -f asm/canonical-service/controller.yaml

    O comando implanta o controlador de serviço canônico no cluster. O controlador de serviço canônico agrupa cargas de trabalho pertencentes ao mesmo serviço lógico, e é necessário desbloquear funcionalidades extras no painel de Serviços no console do Google Cloud. Para mais informações, consulte Como ativar e desativar o controlador de serviço canônico.

A seguir