Atualizações de configuração para modernização

Neste documento, descrevemos as atualizações de configuração que você precisa fazer nos clusters gerenciados do Cloud Service Mesh se sinalizados pelas verificações de compatibilidade antes de modernizar do plano de controle ISTIOD descontinuado para o plano de controle TRAFFIC_DIRECTOR antes do prazo de fim do suporte.

Veja a seguir uma lista de possíveis atualizações de configuração necessárias para preparar o cluster para a modernização. Consulte cada seção para ver as instruções de atualização:

• Multicluster
• Ativar a Federação de Identidade da Carga de Trabalho para GKE
• Ativar a CNI gerenciada
• Uso de binários não padrão no Sidecar
• Migrar para o gateway de entrada do Istio
• Modernizar as configurações do compressor EnvoyFilter
• Ativar grupos de endpoints de rede da Internet
• Permissões de VPC compartilhada
• Configuração do plano de controle ausente

Para mais informações sobre o fluxo de trabalho de modernização, consulte a página Modernização do plano de controle gerenciado.

Migrar de secrets do Istio para multicluster_mode

Os secrets de vários clusters não são compatíveis quando um cluster está usando o plano de controle TRAFFIC_DIRECTOR. Neste documento, descrevemos como modernizar o uso de secrets de vários clusters do Istio para usar o multicluster_mode.

Visão geral de secrets do Istio x API declarativa

A descoberta de endpoints multicluster do Istio de código aberto funciona usando istioctl ou outras ferramentas para criar um secret do Kubernetes em um cluster. Essa secret permite que um cluster faça o balanceamento de carga do tráfego para outro cluster na malha. O plano de controle do ISTIOD lê esse secret e começa a rotear o tráfego para o outro cluster.

O Cloud Service Mesh tem uma API declarativa para controlar o tráfego de vários clusters em vez de criar diretamente secrets do Istio. Essa API trata os secrets do Istio como um detalhe de implementação e é mais confiável do que criar secrets do Istio manualmente. Os recursos futuros do Cloud Service Mesh vão depender da API declarativa, e não será possível usar esses novos recursos diretamente com secrets do Istio. A API declarativa é o único caminho compatível.

Se você estiver usando secrets do Istio, migre para a API declarativa assim que possível. A configuração multicluster_mode direciona cada cluster para direcionar o tráfego para todos os outros clusters na malha. O uso de secrets permite uma configuração mais flexível, permitindo que você configure para cada cluster para qual outro cluster ele deve direcionar o tráfego na malha. Para uma lista completa das diferenças entre os recursos compatíveis da API declarativa e os secrets do Istio, consulte Recursos compatíveis com as APIs do Istio.

Importante:com a API declarativa, um cluster inteiro é ativado para a descoberta de endpoints por vez. Isso significa que cada cluster com "multicluster_mode=connected" vai descobrir endpoints para todos os outros clusters na frota que também têm "multicluster_mode=connected".

Migrar de secrets do Istio para a API declarativa

Se você provisionou o Cloud Service Mesh usando o gerenciamento automático com a API de recursos da frota, não é necessário seguir estas instruções. Estas etapas só se aplicam se você tiver feito a integração usando asmcli --managed.

Esse processo altera os secrets que apontam para um cluster. Durante esse processo, os endpoints são removidos e adicionados novamente. Entre a remoção e a adição dos endpoints, o tráfego vai voltar brevemente ao roteamento local em vez de fazer o balanceamento de carga para outros clusters. Para mais informações, consulte o problema no GitHub.

Para deixar de usar os secrets do Istio e passar a usar a API declarativa, siga estas etapas. Siga estas etapas ao mesmo tempo ou em rápida sucessão:

1. Ative a API declarativa para cada cluster na frota em que você quer ativar a descoberta de endpoints de vários clusters definindo multicluster_mode=connected. Defina explicitamente multicluster_mode=disconnected se você não quiser que o cluster seja detectável.

   Use o comando a seguir para ativar um cluster para descoberta de endpoints de vários clusters:

    kubectl patch configmap/asm-options -n istio-system --type merge -p '{"data":{"multicluster_mode":"connected"}}'
   

   Use o comando a seguir para desativar a descoberta de endpoints em um cluster:

    kubectl patch configmap/asm-options -n istio-system --type merge -p '{"data":{"multicluster_mode":"disconnected"}}'
   

2. Exclua os secrets antigos.

   Depois de definir multicluster_mode=connected nos clusters, cada um deles terá um novo secret gerado para todos os outros clusters que também tiverem multicluster_mode=connected definido. O secret é colocado no namespace istio-system e tem o seguinte formato:

   istio-remote-secret-projects-PROJECT_NAME-locations-LOCATION-memberships-MEMBERSHIPS
   

   Cada secret também terá o rótulo istio.io/owned-by: mesh.googleapis.com aplicado.

   Depois que os novos secrets forem criados, você poderá excluir os secrets criados manualmente com istioctl create-remote-secret:

   kubectl delete secret SECRET_NAME -n istio-system
   

Depois de migrar, verifique as métricas de solicitação para garantir que elas sejam roteadas conforme esperado.

Ativar a Federação de Identidade da Carga de Trabalho para GKE

A federação de identidade da carga de trabalho é o método seguro recomendado para cargas de trabalho do Google Kubernetes Engine. Isso permite o acesso a serviços do Google Cloud , como o Compute Engine, o BigQuery e as APIs de machine learning. A federação de identidade da carga de trabalho não requer configuração manual ou métodos menos seguros, como arquivos de chave de conta de serviço, porque usa políticas do IAM. Para mais detalhes sobre a Federação de Identidade da Carga de Trabalho, consulte Como funciona a Federação de Identidade da Carga de Trabalho para GKE.

A seção a seguir descreve como ativar a federação de identidade da carga de trabalho.

Ativar a federação de identidade da carga de trabalho em clusters

1. Verifique se a federação de identidade da carga de trabalho está ativada para o cluster. Para isso, verifique se o cluster do GKE tem um conjunto de pools da federação de identidade da carga de trabalho configurado, o que é essencial para a validação de credenciais do IAM.

   Use o comando a seguir para verificar o pool de Identidade da carga de trabalho definido para um cluster:

   gcloud container clusters describe CLUSTER_NAME \
     --format="value(workloadIdentityConfig.workloadPool)"
   

   Substitua CLUSTER_NAME pelo nome do cluster do GKE. Se você ainda não tiver especificado uma zona ou região padrão para gcloud, talvez seja necessário especificar uma flag --region ou --zone ao executar este comando.

2. Se a saída estiver vazia, siga as instruções em Atualizar um cluster para ativar a Identidade da carga de trabalho em clusters do GKE.

Ativar a federação de identidade da carga de trabalho em pools de nós

Depois que a federação de identidade da carga de trabalho for ativada em um cluster, os pools de nós precisarão ser configurados para usar o servidor de metadados do GKE.

1. Liste todos os pools de nós de um cluster Standard. Execute o comando gcloud container node-pools list:

   gcloud container node-pools list --cluster CLUSTER_NAME
   

   Substitua CLUSTER_NAME pelo nome do cluster do GKE. Se você ainda não tiver especificado uma zona ou região padrão para gcloud, talvez seja necessário especificar uma flag --region ou --zone ao executar este comando.

2. Verifique se cada pool de nós está usando o servidor de metadados do GKE:

   gcloud container node-pools describe NODEPOOL_NAME \
       --cluster=CLUSTER_NAME \
       --format="value(config.workloadMetadataConfig.mode)"
   

   Substitua:

   • NODEPOOL_NAME pelo nome do pool de nós.
   • CLUSTER_NAME pelo nome do cluster do GKE.

3. Se a saída não tiver GKE_METADATA, atualize o pool de nós usando o guia Atualizar um pool de nós.

Ativar a interface de rede de contêiner (CNI) gerenciada

Nesta seção, mostramos como ativar a CNI gerenciada para o Cloud Service Mesh no Google Kubernetes Engine.

Visão geral da CNI gerenciada

A interface de rede de contêiner (CNI) gerenciada é uma implementação gerenciada pelo Google da CNI do Istio. O plug-in CNI simplifica a rede de pods configurando regras de iptables. Isso permite o redirecionamento de tráfego entre aplicativos e proxies do Envoy, eliminando a necessidade de permissões privilegiadas para o contêiner de inicialização necessário para gerenciar iptables.

O plug-in CNI do Istio substitui o contêiner istio-init. O contêiner istio-init era responsável por configurar o ambiente de rede do pod para permitir a interceptação de tráfego para o arquivo secundário do Istio. O plug-in CNI executa a mesma função de redirecionamento de rede, mas com o benefício adicional de reduzir a necessidade de privilégios elevados, aumentando a segurança.

Portanto, para aumentar a segurança e a confiabilidade e simplificar o gerenciamento e a solução de problemas, a CNI gerenciada é necessária em todas as implantações do Cloud Service Mesh gerenciado.

Impacto nos contêineres de inicialização

Os contêineres de inicialização são contêineres especializados que são executados antes dos contêineres de aplicativo para tarefas de configuração. As tarefas de configuração podem incluir o download de arquivos de configuração, a comunicação com serviços externos ou a execução de inicialização pré-aplicativo. Os contêineres de inicialização que dependem do acesso à rede podem encontrar problemas quando a CNI gerenciada está ativada no cluster.

O processo de configuração do pod com a CNI gerenciada é o seguinte:

1. O plug-in da CNI configura interfaces de rede de pods, atribui IPs de pods e redireciona o tráfego para o proxy sidecar do Istio, que ainda não foi iniciado.
2. Todos os contêineres de inicialização são executados e concluídos.
3. O proxy sidecar do Istio é iniciado junto com os contêineres do aplicativo.

Portanto, se um contêiner de inicialização tentar fazer conexões de rede de saída ou se conectar a serviços na malha, as solicitações de rede dos contêineres de inicialização poderão ser descartadas ou roteadas incorretamente. Isso ocorre porque o proxy sidecar do Istio, que gerencia o tráfego de rede do pod, não está em execução quando as solicitações são feitas. Para mais detalhes, consulte a documentação da CNI do Istio.

Ativar a CNI gerenciada para o cluster

Siga as etapas desta seção para ativar a CNI gerenciada no cluster.

1. Remova as dependências de rede do contêiner de inicialização. Considere as seguintes alternativas:

   • Modificar a lógica ou os contêineres do aplicativo:é possível modificar os serviços para remover a dependência de contêineres de inicialização que exigem solicitações de rede ou realizar operações de rede nos contêineres do aplicativo, depois que o proxy sidecar for iniciado.
   • Use ConfigMaps ou secrets do Kubernetes:armazene dados de configuração buscados pela solicitação de rede em ConfigMaps ou secrets do Kubernetes e monte-os nos contêineres do aplicativo. Para soluções alternativas, consulte a documentação do Istio.

2. Ative a CNI gerenciada no cluster:

   1. Faça as seguintes mudanças na configuração:

      1. Execute o comando a seguir para localizar o controlPlaneRevision.

         kubectl get controlplanerevision -n istio-system
         

      2. No recurso personalizado (CR) ControlPlaneRevision (CPR), defina o rótulo mesh.cloud.google.com/managed-cni-enabled como true.

         kubectl label controlplanerevision CPR_NAME \
             -n istio-system mesh.cloud.google.com/managed-cni-enabled=true \
             --overwrite
         

         Substitua CPR_NAME pelo valor na coluna NAME da saída da etapa anterior.

      3. No ConfigMap asm-options, defina o valor ASM_OPTS como CNI=on.

         kubectl patch configmap asm-options -n istio-system \
             -p '{"data":{"ASM_OPTS":"CNI=on"}}'
         

      4. No recurso personalizado (CR) ControlPlaneRevision (CPR), defina a anotação mesh.cloud.google.com/force-reprovision como true. Essa ação aciona a reinicialização do plano de controle.

         Observação :esse método não é o recomendado para reiniciar o plano de controle e só deve ser usado para esforços de modernização do Cloud Service Mesh.

         kubectl annotate controlplanerevision CPR_NAME \
             -n istio-system mesh.cloud.google.com/force-reprovision=true \
             --overwrite
         

   2. Verifique o estado do recurso. Recupere o estado do recurso usando o seguinte comando:

      gcloud container fleet mesh describe --project FLEET_PROJECT_ID
      

      Substitua FLEET_PROJECT_ID pelo ID do projeto host da frota. Em geral, o FLEET_PROJECT_ID tem o mesmo nome do projeto.

      • Verifique se a condição MANAGED_CNI_NOT_ENABLED foi removida de servicemesh.conditions.
      • A atualização do estado pode levar de 15 a 20 minutos. Aguarde alguns minutos e execute o comando novamente.

   3. Quando o controlPlaneManagement.state estiver Active no estado do recurso do cluster, reinicie os pods.

Abandonar o uso de binários não padrão no Sidecar

Nesta seção, sugerimos maneiras de tornar suas implantações compatíveis com a imagem de proxy do Envoy sem distroless.

Imagens de arquivo secundário do proxy Envoy distroless

O Cloud Service Mesh usa dois tipos de imagens de arquivo secundário de proxy do Envoy com base na sua configuração do plano de controle: a imagem de proxy default (que contém vários binários de depuração) e a imagem de proxy distroless.

Para clusters com o plano de controle TRAFFIC_DIRECTOR gerenciado:

• Clusters integrados diretamente: use imagens distroless por padrão.
• Clusters migrados do CSM-ISTIOD: use imagens default por padrão. É possível ativar explicitamente as imagens distroless para melhorar sua postura de segurança.

Para ativar as imagens distroless em um cluster migrado do CSM-ISTIOD, configure-as globalmente usando defaultConfig.image.imageType: distroless no MeshConfig ou por carga de trabalho usando a anotação de pod sidecar.istio.io/proxyImageType: distroless.

As imagens de base distroless são imagens do contêiner mínimas que priorizam a segurança e a otimização de recursos, incluindo apenas componentes essenciais. A superfície de ataque é reduzida para ajudar a evitar vulnerabilidades. Para mais informações, consulte a documentação sobre a imagem de proxy sem distroless.

Compatibilidade binária

Como prática recomendada, restrinja o conteúdo de um ambiente de execução do contêiner apenas aos pacotes necessários. Essa abordagem melhora a segurança e a proporção de sinal para ruído dos verificadores de vulnerabilidades e exposições comuns (CVEs, na sigla em inglês). A imagem do sidecar sem distribuição tem um conjunto mínimo de dependências, sem todos os executáveis, bibliotecas e ferramentas de depuração não essenciais. Portanto, não é possível executar um comando shell ou usar curl, ping ou outros utilitários de depuração, como kubectl exec, no contêiner.

Tornar os clusters compatíveis com imagens distroless

• Remova as referências a binários não compatíveis (como bash ou curl) da sua configuração. Principalmente dentro das sondagens de prontidão, inicialização e atividade, e dos hooks PostStart e PreStop do ciclo de vida nos contêineres istio-proxy, istio-init ou istio-validation.
• Considere alternativas como holdApplicationUntilProxyStarts para determinados casos de uso.
• Para depuração, use contêineres temporários para anexar a um pod de carga de trabalho em execução. Em seguida, é possível inspecioná-lo e executar comandos personalizados. Para ver um exemplo, consulte Como coletar registros de {service_mesh_name}.

Se você não encontrar uma solução para seu caso de uso específico, entre em contato com o suporte do Google Cloud em Como receber suporte.

Migrar para o gateway de entrada do Istio

Nesta seção, mostramos como migrar para o gateway de entrada do Istio. Há dois métodos para migrar para o gateway de entrada do Istio:

1. Migração em fases com divisão de tráfego

   Esse método prioriza a minimização de interrupções, em que você envia tráfego de forma incremental para o novo gateway do Istio, permitindo monitorar o desempenho dele em uma pequena porcentagem de solicitações e reverter rapidamente, se necessário. A configuração da divisão de tráfego da camada 7 pode ser desafiadora para alguns aplicativos. Por isso, é necessário gerenciar os dois sistemas de gateway simultaneamente durante a transição. Consulte Migração em fases com divisão de tráfego para ver as etapas.

2. Migração direta

   Esse método envolve o redirecionamento simultâneo de todo o tráfego para o novo gateway do Istio depois que você tiver realizado testes completos. A vantagem dessa abordagem é a separação completa da infraestrutura do gateway antigo, permitindo a configuração adaptável do novo gateway sem as restrições da configuração atual. No entanto, há um risco maior de inatividade caso surjam problemas inesperados com o novo gateway durante a transição. Consulte Migração direta para ver as etapas.

Os exemplos de migração a seguir pressupõem que você tenha um serviço HTTP (httpbin) em execução no namespace do aplicativo (padrão) e exposto externamente usando a API Gateway do Kubernetes. As configurações relevantes são:

• Gateway: k8-api-gateway (no namespace istio-ingress): configurado para detectar o tráfego HTTP na porta 80 para qualquer nome de host que termine com .example.com.
• HTTPRoute: httpbin-route (no namespace default): direciona qualquer solicitação HTTP com o nome do host httpbin.example.com e um caminho que começa com /get para o serviço httpbin no namespace default.
• O aplicativo httpbin pode ser acessado usando o IP externo 34.57.246.68.

Migração em fases com divisão de tráfego

Provisionar um novo gateway de entrada do Istio

1. Implante um novo gateway de entrada seguindo as etapas na seção Implantar gateway de amostra e personalize as configurações de amostra de acordo com seus requisitos. As amostras no repositório anthos-service-mesh são destinadas à implantação de um serviço loadBalancer istio-ingressgateway e dos pods ingress-gateway correspondentes.

   Exemplo de recurso de gateway (istio-ingressgateway.yaml)

    apiVersion: networking.istio.io/v1beta1
    kind: Gateway
    metadata:
      name: istio-api-gateway
      namespace: GATEWAY_NAMESPACE
    spec:
      selector:
        istio: ingressgateway  # The selector should match the ingress-gateway pod labels.
      servers:
      - port:
          number: 80
          name: http
          protocol: HTTP
        hosts:   # or specific hostnames if needed
        - "httpbin.example.com"
   

2. Aplique a configuração do Gateway para gerenciar o tráfego:

   kubectl apply -f istio-ingressgateway.yaml -n GATEWAY_NAMESPACE
   

   Verifique se o "spec.selector" no recurso de gateway corresponde aos rótulos dos pods ingress-gateway. Por exemplo, se os pods ingress-gateway tiverem o rótulo istio=ingressgateway, a configuração do gateway também precisará selecionar esse rótulo istio=ingressgateway.

Configurar o roteamento inicial para o novo gateway

1. Defina as regras de rota iniciais para seu aplicativo usando um VirtualService do Istio.

   Exemplo de VirtualService (my-app-vs-new.yaml):

   apiVersion: networking.istio.io/v1beta1
   kind: VirtualService
   metadata:
     name: httpbin-vs
     namespace: APPLICATION_NAMESPACE
   spec:
       gateways:
       - istio-ingress/istio-api-gateway  # Replace with <gateway-namespace/gateway-name>
       hosts:
       - httpbin.example.com
       http:
       - match:
         - uri:
             prefix: /get
         route:
         - destination:
             host: httpbin
             port:
               number: 8000
   

2. Aplique o VirtualService:

   kubectl apply -f my-app-vs-new.yaml -n MY_APP_NAMESPACE
   

Acesse o serviço de back-end (httpbin) pelo gateway de entrada do Istio recém-implantado.

1. Defina a variável de ambiente do host de entrada como o endereço IP externo associado ao balanceador de carga istio-ingressgateway implantado recentemente:

   export INGRESS_HOST=$(kubectl -n GATEWAY_NAMESPACE get service istio-ingressgateway -o jsonpath='{.status.loadBalancer.ingress[0].ip}')
   

2. Verifique se o aplicativo (httpbin) pode ser acessado usando o novo gateway:

   curl -s -I -HHost:httpbin.example.com "http://$INGRESS_HOST/get"
   

   A saída é semelhante a:

   HTTP/1.1 200 OK
   

Modificar a entrada atual para divisão de tráfego

Depois de confirmar que o novo gateway (por exemplo, istio-api-gateway) foi configurado, você pode começar a rotear uma parte do tráfego por ele. Para fazer isso, atualize o HTTPRoute atual para direcionar uma pequena porcentagem do tráfego para o novo gateway, enquanto a maior parte continua usando o gateway atual (k8-api-gateway).

1. Abra o httproute para edição:

   kubectl edit httproute httpbin-route -n MY_APP_NAMESPACE
   

2. Adicione uma nova referência de back-end que aponte para o serviço de balanceador de carga do novo gateway de entrada com um peso inicial de 10% e atualize o peso do back-end do gateway antigo.

   apiVersion: gateway.networking.k8s.io/v1
   kind: HTTPRoute
   metadata:
     name: httpbin-route
     namespace: MY_APP_NAMESPACE  # your application's namespace
   spec:
     parentRefs:
     - name: k8-api-gateway
       namespace: istio-ingress
     hostnames: ["httpbin.example.com"]
     rules:
     - matches:
       - path:
           type: PathPrefix
           value: /get
       backendRefs:
       - name: httpbin
         port: 8000
         weight: 90
       - name: istio-ingressgateway # Newly deployed load balancer service
         namespace: GATEWAY_NAMESPACE
         port: 80
         weight: 10
   

3. Conceder permissão para referências entre namespaces com a concessão de referência.

   Para permitir que o HTTPRoute no namespace do aplicativo (padrão) acesse o serviço loadbalancer no namespace do gateway (istio-ingress), talvez seja necessário criar uma concessão de referência. Esse recurso serve como um controle de segurança, definindo explicitamente quais referências entre namespaces são permitidas.

   O istio-ingress-grant.yaml a seguir descreve um exemplo de concessão de referência:

   apiVersion: gateway.networking.k8s.io/v1beta1
   kind: ReferenceGrant
   metadata:
     name: istio-ingressgateway-grant
     namespace: istio-ingress # Namespace of the referenced resource
   spec:
     from:
     - group: gateway.networking.k8s.io
       kind: HTTPRoute
       namespace: MY_APP_NAMESPACE # Namespace of the referencing resource
     to:
     - group: ""               # Core Kubernetes API group for Services
       kind: Service
       name: istio-ingressgateway # Loadbalancer Service of the new ingress gateway
   

4. Aplique a concessão de referência:

   kubectl apply -f istio-ingress-grant.yaml -n GATEWAY_NAMESPACE
   

5. Verifique as solicitações para o endereço IP externo atual (por exemplo, 34.57.246.68) não estão falhando. O check-traffic-flow.sh a seguir descreve um script para verificar falhas de solicitação:

   # Update the following values based on your application setup
   external_ip="34.57.246.68" # Replace with existing external IP
   url="http://$external_ip/get"
   host_name="httpbin.example.com"
   
   # Counter for successful requests
   success_count=0
   
   # Loop 50 times
   for i in {1..50}; do
     # Perform the curl request and capture the status code
     status_code=$(curl -s -HHost:"$host_name" -o /dev/null -w "%{http_code}" "$url")
     # Check if the request was successful (status code 200)
     if [ "$status_code" -eq 200 ]; then
       ((success_count++))  # Increment the success counter
     else
       echo "Request $i: Failed with status code $status_code"
     fi
   done
   
   # After the loop, check if all requests were successful
   if [ "$success_count" -eq 50 ]; then
     echo "All 50 requests were successful!"
   else
     echo "Some requests failed.  Successful requests: $success_count"
   fi
   

6. Execute o script para confirmar que nenhuma solicitação falha, independentemente da rota de tráfego:

   chmod +x check-traffic-flow.sh
   ./check-traffic-flow.sh
   

Aumentar lentamente a porcentagem de tráfego

Se nenhuma falha de solicitação for vista no endereço IP externo atual (por exemplo, 34.57.246.68), mude gradualmente mais tráfego para o novo gateway de entrada do Istio ajustando os pesos de back-end no HTTPRoute. Aumente o peso do istio-ingressgateway e diminua o peso do gateway antigo em pequenos incrementos, como 10%, 20% e assim por diante.

Importante: observe continuamente as principais métricas, como taxa de sucesso de solicitações, latência, taxas de erro e utilização de recursos dos pods do aplicativo para garantir a estabilidade em cada incremento.

Use o comando a seguir para atualizar o HTTPRoute:

kubectl edit httproute httpbin-route -n MY_APP_NAMESPACE

Migração completa de tráfego e remoção do gateway antigo

1. Quando o novo gateway de entrada do Istio demonstrar um desempenho estável e processar as solicitações com sucesso, mude todo o tráfego para ele. Atualize o HTTPRoute para definir o peso do back-end do gateway antigo como 0 e o do novo gateway como 100.

2. Depois que o tráfego for totalmente roteado para o novo gateway, atualize os registros DNS externos do nome do host do aplicativo (por exemplo, httpbin.example.com) para apontar para o endereço IP externo do serviço do balanceador de carga criado em Provisionar um novo gateway de entrada do Istio.

3. Por fim, exclua o gateway antigo e os recursos associados:

   kubectl delete gateway OLD_GATEWAY -n GATEWAY_NAMESPACE
   kubectl delete service OLD_GATEWAY_SERVICE -n GATEWAY_NAMESPACE
   

Migração direta

Provisionar um novo gateway de entrada do Istio

1. Implante um novo gateway de entrada seguindo as etapas na seção Implantar gateway de amostra e personalize as configurações de amostra de acordo com seus requisitos. As amostras no repositório anthos-service-mesh são destinadas à implantação de um serviço loadBalancer istio-ingressgateway e dos pods ingress-gateway correspondentes.

   Exemplo de recurso de gateway (istio-ingressgateway.yaml)

    apiVersion: networking.istio.io/v1beta1
    kind: Gateway
    metadata:
      name: istio-api-gateway
      namespace: GATEWAY_NAMESPACE
    spec:
      selector:
        istio: ingressgateway  # The selector should match the ingress-gateway pod labels.
      servers:
      - port:
          number: 80
          name: http
          protocol: HTTP
        hosts:   # or specific hostnames if needed
        - "httpbin.example.com"
   

2. Aplique a configuração do Gateway para gerenciar o tráfego:

   kubectl apply -f istio-ingressgateway.yaml -n GATEWAY_NAMESPACE
   

   Verifique se o "spec.selector" no recurso de gateway corresponde aos rótulos dos pods ingress-gateway. Por exemplo, se os pods ingress-gateway tiverem o rótulo istio=ingressgateway, a configuração do gateway também precisará selecionar esse rótulo istio=ingressgateway.

Configurar o roteamento inicial para o novo gateway

1. Defina as regras de rota iniciais para seu aplicativo usando um VirtualService do Istio.

   Exemplo de VirtualService (my-app-vs-new.yaml):

   apiVersion: networking.istio.io/v1beta1
   kind: VirtualService
   metadata:
     name: httpbin-vs
     namespace: APPLICATION_NAMESPACE
   spec:
       gateways:
       - istio-ingress/istio-api-gateway  # Replace with <gateway-namespace/gateway-name>
       hosts:
       - httpbin.example.com
       http:
       - match:
         - uri:
             prefix: /get
         route:
         - destination:
             host: httpbin
             port:
               number: 8000
   

2. Aplique o VirtualService:

   kubectl apply -f my-app-vs-new.yaml -n MY_APP_NAMESPACE
   

Acesse o serviço de back-end (httpbin) pelo gateway de entrada do Istio recém-implantado.

1. Defina a variável de ambiente do host de entrada como o endereço IP externo associado ao balanceador de carga istio-ingressgateway implantado recentemente:

   export INGRESS_HOST=$(kubectl -n GATEWAY_NAMESPACE get service istio-ingressgateway -o jsonpath='{.status.loadBalancer.ingress[0].ip}')
   

2. Verifique se o aplicativo (httpbin) pode ser acessado usando o novo gateway:

   curl -s -I -HHost:httpbin.example.com "http://$INGRESS_HOST/get"
   

   A saída é semelhante a:

   HTTP/1.1 200 OK
   

Testar e monitorar o novo gateway

1. Teste todas as regras de rota, valide a configuração de TLS, as políticas de segurança e outros recursos. Realize testes de carga para verificar se o novo gateway pode lidar com o tráfego esperado.

2. Depois que o novo gateway for totalmente testado, atualize os registros DNS externos do nome do host do aplicativo (por exemplo, httpbin.example.com) para apontar para o endereço IP externo do serviço do balanceador de carga criado em Provisionar um novo gateway de entrada do Istio.

3. Monitore as principais métricas, como taxa de sucesso de solicitações, latência, taxas de erro e a utilização de recursos dos pods do aplicativo para verificar a estabilidade com o novo gateway de entrada do Istio. Quando estiver estável, você poderá excluir o gateway antigo e os recursos associados a ele

   kubectl delete gateway OLD_GATEWAY -n GATEWAY_NAMESPACE
   kubectl delete service OLD_GATEWAY_SERVICE -n GATEWAY_NAMESPACE
   

Considerações importantes: verifique se os certificados e as configurações de TLS estão configurados corretamente no novo gateway de entrada do Istio se o aplicativo exigir HTTPS. Consulte Configurar o término de TLS no gateway de entrada para mais detalhes.

Corrigir vários planos de controle

Anteriormente, o Cloud Service Mesh era compatível com a integração usando asmcli (descontinuado), que não bloqueava o provisionamento de vários planos de controle. O Cloud Service Mesh agora aplica a prática recomendada de implantar apenas um canal por cluster que corresponda ao canal do cluster e não é compatível com o uso de vários canais implantados no mesmo cluster.

Se você quiser implantações canário em novas versões da malha no canal rápido antes que elas fiquem disponíveis no canal estável ou regular, use dois clusters diferentes, cada um com um canal separado. Os canais são controlados pelo canal do cluster do GKE, e o Mesh não tem um canal separado associado a ele.

Para verificar se você tem vários canais, procure a condição de status UNSUPPORTED_MULTIPLE_CONTROL_PLANES na sua assinatura. Se esse aviso não aparecer, você não será afetado e poderá pular a leitura desta seção.

1. Execute o comando a seguir para verificar se o cluster tem vários canais do plano de controle:

   gcloud container fleet mesh describe
   

   A saída é semelhante a:

   ...
   projects/.../locations/global/memberships/my-membership:
       servicemesh:
         conditions:
         - code: UNSUPPORTED_MULTIPLE_CONTROL_PLANES
           details: 'Using multiple control planes is not supported. Please remove a control plane from your cluster.'
           documentationLink: https://cloud.google.com/service-mesh/v1.30/docs/migrate/modernization-configuration-updates#multiple_control_planes
           severity: WARNING
         controlPlaneManagement:
           details:
           - code: REVISION_READY
             details: 'Ready: asm-managed-stable'
           implementation: ISTIOD
           state: ACTIVE
   ...
   

2. Se a condição UNSUPPORTED_MULTIPLE_CONTROL_PLANES aparecer, determine quais canais existem para o cluster:

   kubectl get controlplanerevisions -n istio-system
   

   A saída é semelhante a:

   NAME                 RECONCILED   STALLED   AGE
   asm-managed-stable   True         False     97d
   asm-managed          True         False     97d
   asm-managed-rapid    True         False     97d
   

   Neste exemplo, os três canais foram provisionados:

   • asm-managed-stable -> STABLE
   • asm-managed -> REGULAR
   • asm-managed-rapid -> RAPID

   Se apenas um resultado aparecer, isso significa que apenas um canal está provisionado no cluster, e você pode pular o restante destas etapas.

   Se dois ou mais resultados aparecerem, siga as etapas restantes para remover os canais excedentes.

Consolidar cargas de trabalho em um canal

Antes de remover outros canais, verifique se as cargas de trabalho estão usando apenas um canal.

1. Encontre todos os rótulos que você está usando no cluster:

   kubectl get namespaces -l istio.io/rev=RELEASE_CHANNEL
   

   Dependendo da saída do comando anterior, substitua RELEASE_CHANNEL por asm-managed-stable, asm-managed ou asm-managed-rapid. Repita essa etapa para cada canal provisionado.

   A saída é semelhante a:

   NAME      STATUS   AGE
   default   Active   110d
   

   Neste exemplo, o namespace padrão está sendo injetado com o canal normal.

   Se todas as cargas de trabalho já estiverem usando o mesmo canal, pule para a etapa Remover os canais extras. Caso contrário, continue nesta seção.

2. Mude os rótulos para que apenas um canal seja usado:

   Cuidado :considere o seguinte antes de mudar os rótulos.
   • Os pods também podem ser injetados diretamente em alguns casos com o rótulo sidecar.istio.io/inject. Não se esqueça de verificar se eles também podem ser usados para isso.
   • Você pode ignorar os rótulos istio-injection=enabled nesta etapa. Os namespaces com esse rótulo vão mudar automaticamente para corresponder ao canal que permanecer no cluster.
   • Ao selecionar um canal para manter, tente selecionar o mesmo canal do cluster do GKE. Se esse canal não existir, selecione qualquer um dos canais ativos.
   • O canal selecionado não importa. O canal do cluster do GKE determina qual versão da malha você recebe, não o canal da malha.
   • Verifique a configuração do meshconfig entre todos os canais ativos que estão em uso para garantir que não haja diferenças entre eles. Cada canal usa um configmap separado para configuração. Portanto, consolidar dois canais em um deve garantir um comportamento consistente entre os dois canais. kubectl get configmap istio-asm-managed{-rapid | -stable} -n istio-system -o yaml

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

   Substitua NAMESPACE pelo nome do namespace.

   A prática recomendada é usar istio-injection=enabled. No entanto, se você não quiser usar esse rótulo, também poderá usar istio.io/rev=RELEASE_CHANNEL.

   Depois de alterar o rótulo de um namespace / pod, reinicie todas as cargas de trabalho para que elas sejam injetadas pelo plano de controle correto.

Remover os canais extras

Depois de verificar se todas as cargas de trabalho estão em execução em um único canal, remova os canais extras não utilizados. Se os três canais de lançamento foram provisionados, execute os comandos a seguir para cada canal.

1. Exclua o recurso ControlPlaneRevision extra:

   kubectl delete controlplanerevision RELEASE_CHANNEL -n istio-system
   

   Substitua RELEASE_CHANNEL por asm-managed-stable, asm-managed ou asm-managed-rapid.

2. Exclua o MutatingWebhookConfiguration:

   kubectl delete mutatingwebhookconfiguration istiod-RELEASE_CHANNEL
   

3. Exclua o configmap meshconfig:

   kubectl delete configmap istio-RELEASE_CHANNEL
   

Ativar gerenciamento automático

Atenção: ao ativar o gerenciamento automático do plano de controle, o plano de dados gerenciado e de vários clusters é ativado automaticamente nesse cluster.

1. Execute o comando a seguir para ativar o gerenciamento automático:

   gcloud container fleet mesh update \
       --management automatic \
       --memberships MEMBERSHIP_NAME \
       --project PROJECT_ID \
       --location MEMBERSHIP_LOCATION
   

   Substitua:

   • MEMBERSHIP_NAME é o nome da assinatura listado quando você verificou que o cluster foi registrado na frota.
   • PROJECT_ID é o ID do projeto.
   • MEMBERSHIP_LOCATION é o local da assinatura (uma região ou global). Verifique o local da sua assinatura com gcloud container fleet memberships list --project PROJECT_ID.

2. Verifique se o gerenciamento automático está ativado:

   gcloud container fleet mesh describe
   

   A saída é semelhante a:

   ...
   membershipSpecs:
     projects/.../locations/us-central1/memberships/my-member:
       mesh:
         management: MANAGEMENT_AUTOMATIC
   membershipStates:
     projects/.../locations/us-central1/memberships/my-member:
       servicemesh:
         conditions:
         - code: VPCSC_GA_SUPPORTED
           details: This control plane supports VPC-SC GA.
           documentationLink: http://cloud.google.com/service-mesh/v1.30/docs/managed/vpc-sc
           severity: INFO
         controlPlaneManagement:
           details:
           - code: REVISION_READY
             details: 'Ready: asm-managed'
           implementation: TRAFFIC_DIRECTOR
           state: ACTIVE
         dataPlaneManagement:
           details:
           - code: OK
             details: Service is running.
           state: ACTIVE
       state:
         code: OK
         description: |-
           Revision ready for use: asm-managed.
           All Canonical Services have been reconciled successfully.
   ...
   

Modernizar as configurações do compressor EnvoyFilter

Se você estiver usando o filtro envoy.extensions.filters.http.compressor.v3.Compressor, vários campos de nível superior foram descontinuados no Envoy e movidos para response_direction_config.common_config e request_direction_config.common_config.

Para saber como atualizar seus recursos EnvoyFilter para o formato moderno e compatível, consulte o guia Modernizar as configurações do compressor EnvoyFilter.

Ativar uma política da organização obrigatória

O Cloud Service Mesh exige que políticas específicas sejam ativadas para funcionar corretamente.

Políticas obrigatórias

compute.disableInternetNetworkEndpointGroup

O Cloud Service Mesh precisa criar grupos de endpoints de rede (NEGs, na sigla em inglês) da Internet. Esses NEGs são componentes essenciais para rotear o tráfego para serviços fora do Google Cloud.

A restrição constraints/compute.disableInternetNetworkEndpointGroup pode impedir a criação desses NEGs de Internet necessários.

Se essa política da organização for aplicada ao seu projeto, pasta ou organização, ela vai impedir que o Cloud Service Mesh funcione corretamente com o plano de controle do Traffic Director. Isso vai impedir a migração ou a operação bem-sucedida dessa configuração do Cloud Service Mesh.

Se Enforced estiver definido como true, a criação de NEGs da Internet será desativada.

Como saber se fui afetado?

É possível verificar a política em vigor para seu projeto usando o console do Google Cloud ou a Google Cloud CLI. As instruções para visualizar as políticas da organização podem ser encontradas na seção Como visualizar as políticas da organização da documentação oficial.

Por exemplo, use este comando da Google Cloud CLI:

gcloud resource-manager org-policies describe constraints/compute.disableInternetNetworkEndpointGroup --project YOUR_PROJECT_ID --effective

Se a política mostrar o valor enforced: true, você será afetado.

constraint: constraints/compute.disableInternetNetworkEndpointGroup
booleanPolicy:
  enforced: true

Se a política mostrar um valor diferente ou estiver vazia, você não será afetado.

constraint: constraints/compute.disableInternetNetworkEndpointGroup
booleanPolicy: {}

Como resolver o problema

Se a política for aplicada, será necessário desativar essa restrição (definida como false) no nível da organização, da pasta ou do projeto.

Instruções detalhadas sobre como modificar políticas da organização, incluindo restrições booleanas como esta, podem ser encontradas no guia Como criar e gerenciar políticas da organização. Normalmente, você precisa do papel roles/orgpolicy.policyAdmin para fazer essas mudanças.

Permissões de VPC compartilhada

Ao usar o Cloud Service Mesh gerenciado com uma VPC compartilhada em que os clusters residem em um projeto de serviço e a rede VPC está em um projeto host, são necessárias permissões adicionais para o agente de serviço do Cloud Service Mesh no projeto de frota.

Como parte da migração para um plano de controle TRAFFIC_DIRECTOR, o Cloud Service Mesh requer permissões para gerenciar regras de firewall no projeto host para garantir a verificação de integridade e a funcionalidade de rede adequadas. Isso não era necessário para o plano de controle ISTIOD anterior.

Como saber se fui afetado?

Você será afetado se:

1. Os clusters do GKE estão em um projeto de serviço.
2. Esses clusters usam uma rede VPC compartilhada hospedada em um projeto diferente (o projeto host da VPC).
3. O agente de serviço do Cloud Service Mesh do projeto de frota não tem permissão para gerenciar regras de firewall no projeto host da VPC.

Talvez você veja uma mensagem de aviso com o código SHARED_VPC_MISSING_PERMISSIONS no estado do recurso da frota. Para mais detalhes sobre como entender e resolver esse problema, incluindo opções gerenciadas pelo sistema e pelo usuário, consulte Entender as verificações de integridade.

Configuração do plano de controle ausente

As práticas recomendadas do Cloud Service Mesh para gerenciar uma malha de serviço usam a API Fleet do Google Kubernetes Engine para definir o campo de gerenciamento como AUTOMATIC. Isso fornece gerenciamento totalmente automático de muitos recursos de malha, como webhooks e o plano de controle. Além disso, ele configura o cluster para receber automaticamente novas atualizações e recursos à medida que são lançados. Alguns métodos de instalação legados não configuravam o Cloud Service Mesh dessa maneira, e é necessário seguir algumas etapas manuais para corrigi-los.

Como saber se fui afetado?

Verifique se você tem um ControlPlaneRevision no cluster:

kubectl get controlplanerevisions -n istio-system

Se você já tiver um ControlPlaneRevision no cluster, este guia não se aplica a você. Se você não tiver um ControlPlaneRevision, use este guia para modernizar seus clusters.

Observação :há um problema conhecido em que o aviso MISSING_CONTROL_PLANE_CONFIG é informado mesmo que o cluster já tenha um ControlPlaneRevision. Isso acontece se o cluster tinha mais de um canal do plano de controle e você excluiu o ControlPlaneRevision de um desses canais. Se o comando anterior retornar pelo menos um ControlPlaneRevision, sua malha estará configurada corretamente, nenhuma ação será necessária e você poderá ignorar o aviso.

Se você estiver recebendo o aviso MISSING_CONTROL_PLANE_CONFIG e não quiser usar o Cloud Service Mesh, desative-o.

Etapas da modernização

Siga estas etapas para determinar o que precisa ser feito para alinhar sua configuração aos padrões atuais.

gcloud container fleet mesh describe --project PROJECT_ID

Siga estas etapas, dependendo da saída:

Saída	Etapa a ser realizada
API [gkehub.googleapis.com] not enabled on project [my-project]. Would you like to enable and retry (this will take a few minutes)? (y/N)?	Responda y e tente de novo.
ERROR: (gcloud.container.fleet.mesh.describe) Service Mesh Feature for project [my-project] is not enabled	Siga para 1. Ative o recurso de malha.
... resourceState: state: ACTIVE ...	Prossiga para 2. Registre o cluster na frota.

1. Ativar o recurso de malha

Para ativar o recurso de malha, use o comando a seguir. Isso permite que o Cloud Service Mesh seja executado no seu projeto. Para mais detalhes e possíveis efeitos colaterais, consulte Provisionar a malha de serviço.

gcloud container fleet mesh enable --project PROJECT_ID

Depois de ativar o recurso de malha, prossiga para 2. Registre o cluster na frota.

2. Registrar o cluster na frota

Verifique se o cluster já está registrado na frota:

gcloud container fleet memberships list --project PROJECT_ID

Se o cluster não estiver listado, siga estas instruções para registrá-lo: Como registrar um cluster na frota.

Ao registrar um cluster na frota, ele poderá gerenciar recursos, como o Cloud Service Mesh, por meio da frota.

3. Determinar o canal da rede

O Cloud Service Mesh depende do canal do Google Kubernetes Engine do cluster, e não de um canal de malha independente. No passado, o Cloud Service Mesh permitia escolher um ou mais canais de malha (diferentes do canal do cluster do Google Kubernetes Engine). Talvez você ainda tenha referências a esses canais na configuração da malha.

Primeiro, determine quais canais você está usando. Se você estiver usando vários canais, siga as instruções em Corrigir vários planos de controle para reduzir o uso a um único canal.

Para determinar qual canal de malha você está usando, verifique os rótulos nos namespaces. Talvez você também precise verificar as cargas de trabalho se tiver adicionado rótulos de injeção especificamente nelas. O comando a seguir verifica todas as cargas de trabalho no cluster e filtra a saída para mostrar os planos de controle e as tags de injeção usadas para essas cargas de trabalho.

kubectl get namespaces,pods,deployments,statefulsets,daemonsets --all-namespaces --show-labels | grep -E "istio.io/rev|istio-injection"

Se você criou manualmente tags personalizadas ou webhooks, também precisa verificar esses itens.

A saída é semelhante a:

namespace/default                                 Active   153d   istio-injection=enabled,istio.io/rev=asm-managed,kubernetes.io/metadata.name=default
namespace/payments                                Active   42d    istio.io/rev=asm-managed-stable,kubernetes.io/metadata.name=payments
default    pod/frontend-847f569874-v9kjz          2/2      Running  0   2m     app=frontend,istio.io/rev=asm-managed,pod-template-hash=847f569874
payments   pod/checkout-0                         2/2      Running  0   5d     app=checkout,istio.io/rev=asm-managed-stable,controller-revision-hash=5c68b9487
default    deployment.apps/frontend               1/1      1        1   153d   app=frontend,istio.io/rev=asm-managed
payments   statefulset.apps/checkout              1/1      1        1   42d    app=checkout,istio.io/rev=asm-managed-stable

Anote os valores de istio.io/rev={channel}. Os nomes correspondem aos canais desta forma. Se houver vários canais em uso, siga as instruções em Corrigir vários planos de controle para reduzir para um único canal:

Valor	Canal
asm-managed-stable	Estável
asm-managed	Normal
asm-managed-rapid	Rápido

Se o canal da malha corresponder ao canal do cluster do Google Kubernetes Engine, pule para a etapa 5.

4. Criar um recurso ControlPlaneRevision para o canal da malha

Se o canal da malha corresponder ao canal do cluster do Google Kubernetes Engine, pule esta etapa. Ativar o gerenciamento automático do plano de controle vai criar automaticamente esse recurso ControlPlaneRevision se o canal corresponder ao canal do cluster.

Crie um recurso ControlPlaneRevision para o canal de malha que você está usando:

Estável

kubectl create ns istio-system
cat <<EOF | kubectl apply -f -
apiVersion: mesh.cloud.google.com/v1beta1
kind: ControlPlaneRevision
metadata:
  name: asm-managed-stable
  namespace: istio-system
spec:
  type: managed_service
  channel: stable
EOF

Normal

kubectl create ns istio-system
cat <<EOF | kubectl apply -f -
apiVersion: mesh.cloud.google.com/v1beta1
kind: ControlPlaneRevision
metadata:
  name: asm-managed
  namespace: istio-system
spec:
  type: managed_service
  channel: regular
EOF

Rápido

kubectl create ns istio-system
cat <<EOF | kubectl apply -f -
apiVersion: mesh.cloud.google.com/v1beta1
kind: ControlPlaneRevision
metadata:
  name: asm-managed-rapid
  namespace: istio-system
spec:
  type: managed_service
  channel: rapid
EOF

5. Ativar o gerenciamento automático

Atenção: ativar o gerenciamento automático do plano de controle tem efeitos colaterais, como a ativação automática da descoberta de endpoints de vários clusters e do plano de dados gerenciado.

Para desativar a descoberta de endpoints de vários clusters, siga as instruções de desativação na API declarativa de descoberta de endpoints antes de ativar o gerenciamento automático do plano de controle.

Para desativar o plano de dados gerenciado, siga as instruções em Desativar o plano de dados gerenciado.

Para ativar o gerenciamento automático, execute o comando a seguir. Isso vai permitir que o Cloud Service Mesh gerenciado pela frota gerencie a configuração do plano de controle do cluster.

gcloud container fleet mesh update --management automatic --memberships MY_CLUSTER_MEMBERSHIP --project PROJECT_ID

Substitua MY_CLUSTER_MEMBERSHIP pelo nome da assinatura do cluster.

6. Verifique a instalação

Execute este comando:

gcloud container fleet mesh describe --project PROJECT_ID

A saída é semelhante a:

createTime: '2025-02-24T22:10:10.826263363Z'
etag: XjjRZB3-ZsueoaKihEBUupYhMDUjvoSyUHTVD2YgR6k
membershipSpecs:
  projects/1234567890/locations/us-central1/memberships/my-cluster-membership:
    mesh:
      management: MANAGEMENT_AUTOMATIC # See item 1 below
membershipStates:
  projects/1234567890/locations/us-central1/memberships/my-cluster-membership:
    servicemesh:
      conditions: [] # See item 2 below
      controlPlaneManagement: # See item 3 below
        details:
        - code: REVISION_READY
          details: 'Ready: asm-managed'
        implementation: TRAFFIC_DIRECTOR
        state: ACTIVE
      dataPlaneManagement: # See item 4 below
        details:
        - code: OK
          details: Service is running.
        state: ACTIVE
    state:
      code: OK
      description: |-
        Revision ready for use: asm-managed.
        All Canonical Services have been reconciled successfully.
      updateTime: '2025-06-17T23:39:05.267540058Z'
name: projects/my-project/locations/global/features/servicemesh
resourceState:
  state: ACTIVE
spec: {}
updateTime: '2025-02-25T04:12:16.280672401Z'

1. Em membershipSpecs, cada assinatura na frota tem uma especificação separada. Verifique se cada membro tem o gerenciamento definido como MANAGEMENT_AUTOMATIC.
2. Cada assinatura tem uma lista de condições de status associadas a ela. Verifique se não há erros ou avisos aqui e siga os links de documentação fornecidos para resolver qualquer problema.
3. controlPlaneManagement contém o status do plano de controle. Verifique se o plano de controle está no estado ACTIVE.
4. dataPlaneManagement contém o status do plano de dados. É recomendável ativar essa opção.