Use multi-cluster gateways to manage north-south traffic - Container Service for Kubernetes: Central de Documentação do Alibaba Cloud

Contexto

Os Ingresses padrão do Kubernetes têm escopo de cluster e não conseguem rotear tráfego entre clusters. Os gateways multi-cluster resolvem essa limitação ao usar MSE Ingresses como Ingresses globais, oferecendo:

Redundância ativa entre zonas — o gateway é implantado em várias zonas por padrão para garantir alta disponibilidade
Balanceamento de carga entre clusters — o tráfego é distribuído proporcionalmente à quantidade de pods em cada cluster
Roteamento de tráfego baseado em cabeçalho — encaminhe solicitações específicas para clusters específicos usando cabeçalhos de requisição
Distribuição de tráfego baseada em peso — envie uma porcentagem configurável do tráfego para um cluster de destino para realizar canary releases
Failover automático entre clusters — se um Service em um cluster ficar indisponível, o tráfego é redirecionado automaticamente para clusters saudáveis, sem necessidade de configuração adicional

Referências do MSE

MseIngressConfig é uma CustomResourceDefinition (CRD) fornecida pelo MSE Ingress Controller. Ela gerencia o ciclo de vida dos gateways nativos da nuvem do MSE e controla a escuta de Ingresses e as configurações globais. Consulte Configurar um MseIngressConfig.
Os MSE Ingresses suportam as anotações principais do NGINX Ingress e adicionam anotações que estendem as capacidades além do NGINX Ingress. Consulte Anotações suportadas pelos gateways MSE Ingress.

Pré-requisitos

Antes de começar, certifique-se de ter:

Ativado o recurso de gateway multi-cluster
Ativado o GitOps na instância do ACK One Fleet
Criado um namespace na instância do ACK One Fleet que corresponda ao namespace das aplicações nos clusters associados

Etapa 1: Criar um gateway multi-cluster

Crie um gateway multi-cluster na instância Fleet. Por padrão, o gateway é implantado em várias zonas para garantir alta disponibilidade.

Usar o console

Faça login no console do ACK One. No painel de navegação à esquerda, escolha Fleet > Multi-cluster Gateways.
No canto superior direito da página Multi-cluster Gateway, clique em Create Gateway.
No painel exibido, edite o arquivo YAML conforme suas necessidades e clique em Create.

Usar a CLI

Obtenha o ID do vSwitch da instância Fleet. Execute o seguinte comando:
```
aliyun adcp DescribeHubClusterDetails --ClusterId <YOUR_FLEET_CLUSTERID>
```
Anote o ID do vSwitch no campo VSwitches da saída.

Crie um arquivo chamado mseingressconfig.yaml com o conteúdo abaixo. Substitua ${vsw-id1} pelo ID do vSwitch que você anotou. Para associar clusters durante a criação, descomente e preencha o campo annotations.

apiVersion: mse.alibabacloud.com/v1alpha1
kind: MseIngressConfig
metadata:
  name: ackone-gateway
  # Attach associated clusters to the MSE gateway.
  #annotations:
  #  mse.alibabacloud.com/remote-clusters: ${cluster1},${cluster2}
spec:
  common:
    instance:
      replicas: 3
      spec: 2c4g
    network:
      # Configure a public-facing or internal SLB instance. Defaults to public if not specified.
      #publicSLBSpec: slb.s2.small
      #privateSLBSpec: slb.s2.small
      vSwitches:
      - ${vsw-id1}
  ingress:
    local:
      ingressClass: mse
  name: mse-ingress

Aplique a configuração para criar o gateway:
```
kubectl apply -f mseingressconfig.yaml
```

Verifique se o gateway foi criado com sucesso:

Status	Descrição
Pending	O gateway está sendo criado. Isso geralmente leva cerca de 3 minutos.
Running	O gateway foi criado e está em execução, mas ainda não está escutando.
Listening	O gateway está em execução e escutando MSE Ingresses.
Failed	O gateway é inválido. Verifique o campo `message` em `Status` para solucionar o problema.

kubectl get mseingressconfig ackone-gateway

Saída esperada:

NAME             STATUS      AGE
ackone-gateway   Listening   3m15s

O status Listening indica que o gateway nativo da nuvem está em execução e escutando Ingresses com ingressClassName: mse. O gateway passa pelos seguintes estados:

Etapa 2: Associar clusters

Adicione clusters associados ao gateway multi-cluster para que ele possa rotear tráfego para os Services desses clusters.

Usar o console

Faça login no console do ACK One. No painel de navegação à esquerda, escolha Fleet > Multi-cluster Gateways.
Na lista suspensa Select a gateway, selecione o gateway desejado e clique em Modify no canto superior direito.
No painel ModifyGateway, adicione a seguinte anotação ao objeto metadata no arquivo YAML. Substitua ${cluster1-id} e ${cluster2-id} pelos IDs dos clusters a serem associados, separados por vírgulas. Em seguida, clique em Update.
```
annotations:
  mse.alibabacloud.com/remote-clusters: ${cluster1-id},${cluster2-id}
```
Se você não adicionou clusters ao criar o gateway, o campo annotations estará ausente — adicione-o manualmente ao objeto metadata.

Usar a CLI

Edite o mseingressconfig na instância Fleet para atualizar a anotação. Substitua ${cluster1-id} e ${cluster2-id} pelos IDs reais dos clusters, separados por vírgulas.
```
annotations:
  mse.alibabacloud.com/remote-clusters: ${cluster1-id},${cluster2-id}
```
Verifique se os clusters foram associados:
```
kubectl get mseingressconfig ackone-gateway -ojsonpath="{.status.remoteClusters}"
```
Saída esperada:
```
[{"clusterId":"c7fb82****"},{"clusterId":"cd3007****"}]
```
A saída lista os IDs dos clusters associados sem entradas Failed, confirmando que os clusters foram associados com sucesso.

Etapa 3: Implantar uma aplicação de exemplo com GitOps

Use o GitOps para implantar a aplicação de exemplo web-demo nos clusters associados. Para instruções de configuração, consulte Introdução ao GitOps.

Crie uma aplicação GitOps para cada cluster associado. Neste exemplo, as aplicações são nomeadas web-demo-cluster1 e web-demo-cluster2.

Defina os seguintes campos de Source:

Campo	Valor
Repository URL	`https://github.com/AliyunContainerService/gitops-demo.git`
Revision	`HEAD`
Path	`manifests/helm/web-demo`

Defina Destination como o cluster associado e defina namespace como web-demo.

Em Helm Values Files, defina a variável envName como cluster1 para a primeira aplicação e cluster2 para a segunda. O Deployment e o Service resultantes para o cluster1 ficam assim:

Visualizar o conteúdo YAML do Deployment e do Service

apiVersion: apps/v1
kind: Deployment
metadata:
  labels:
    app: web-demo
    app.kubernetes.io/instance: web-demo-cluster1
  name: web-demo
  namespace: web-demo
spec:
  replicas: 1
  selector:
    matchLabels:
      app: web-demo
  template:
    metadata:
      labels:
        app: web-demo
    spec:
      containers:
      - name: web-demo
        image: acr-multiple-clusters-registry.cn-hangzhou.cr.aliyuncs.com/ack-multiple-clusters/web-demo:0.4.0
        env:
        - name: ENV_NAME
          value: cluster1
---
apiVersion: v1
kind: Service
metadata:
  name: service1
  namespace: web-demo
spec:
  ports:
  - port: 80
    protocol: TCP
    targetPort: 8080
  selector:
    app: web-demo
  sessionAffinity: None
  type: ClusterIP

Etapa 4: Configurar roteamento de tráfego com MSE Ingresses

Defina ingressClassName: mse em um Ingress para torná-lo um MSE Ingress e habilitar o roteamento de tráfego multi-cluster. Os MSE Ingresses suportam todas as anotações principais do NGINX Ingress e adicionam anotações específicas do MSE para governança avançada de tráfego.

Importante

Os objetos Ingress e Service devem estar no mesmo namespace.

Os exemplos a seguir abordam cinco cenários comuns de roteamento.

Exemplo 1: Distribuir tráfego uniformemente entre clusters

Este exemplo roteia o tráfego proporcionalmente à quantidade de pods em ambos os clusters. Com um pod por cluster (proporção 1:1), o tráfego é dividido igualmente.

Crie um arquivo chamado ingress-demo.yaml:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: web-demo
  namespace: web-demo
spec:
  ingressClassName: mse
  rules:
  - host: example.com
    http:
      paths:
      - path: /svc1
        pathType: Exact
        backend:
          service:
            name: service1
            port:
              number: 80

Aplique o Ingress na instância Fleet:
```
kubectl apply -f ingress-demo.yaml
```

Obtenha o endereço IP público do gateway multi-cluster:

kubectl get ingress web-demo -nargocd -ojsonpath="{.status.loadBalancer}"

Teste o roteamento de tráfego. Substitua XX.XX.XX.XX pelo endereço IP obtido na etapa anterior.

for i in {1..50}; do curl -H "host: example.com" XX.XX.XX.XX/svc1; sleep 1; done

Saída esperada:

This is env cluster1 !
Config file is
This is env cluster1 !
Config file is
This is env cluster1 !
Config file is
This is env cluster1 !
Config file is
This is env cluster2 !
Config file is
This is env cluster1 !
Config file is
...

O tráfego é distribuído para ambos os clusters proporcionalmente à quantidade de pods (1:1 neste exemplo). Para alterar a proporção, escale o Deployment em qualquer um dos clusters.

Exemplo 2: Roteiar todo o tráfego para um único cluster

Este exemplo direciona todo o tráfego para o Cluster 1 usando as anotações mse.ingress.kubernetes.io/service-subset e mse.ingress.kubernetes.io/subset-labels.

Crie um arquivo chamado ingress-demo-cluster-one.yaml. Substitua ${cluster1-id} pelo ID do primeiro cluster associado.

Anotação	Descrição
`mse.ingress.kubernetes.io/service-subset`	Nome do subconjunto do Service. Use um nome que identifique o cluster.
`mse.ingress.kubernetes.io/subset-labels`	ID do cluster associado para onde o tráfego deve ser roteado.

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    mse.ingress.kubernetes.io/service-subset: cluster-demo-1
    mse.ingress.kubernetes.io/subset-labels: |
      topology.istio.io/cluster ${cluster1-id}
  name: web-demo-cluster-one
  namespace: web-demo
spec:
  ingressClassName: mse
  rules:
  - host: example.com
    http:
      paths:
      - path: /service1
        pathType: Exact
        backend:
          service:
            name: service1
            port:
              number: 80

Referência de anotações: Para a lista completa de anotações suportadas, consulte Anotações suportadas pelos gateways MSE Ingress.

Aplique o Ingress:

kubectl apply -f ingress-demo-cluster-one.yaml

Obtenha o endereço IP público:

kubectl get ingress web-demo -nargocd -ojsonpath="{.status.loadBalancer}"

Teste o roteamento de tráfego. Substitua XX.XX.XX.XX pelo IP do gateway.

for i in {1..50}; do curl -H "host: example.com" XX.XX.XX.XX/service1; sleep 1; done

Saída esperada:

This is env cluster1 !
Config file is
This is env cluster1 !
Config file is
This is env cluster1 !
Config file is
...

Todas as requisições são atendidas pelo Cluster 1.

Exemplo 3: Roteiar tráfego canary por cabeçalho de requisição

Este exemplo roteia requisições com o cabeçalho stage: gray para o Cluster 2 e todo o outro tráfego para o outro cluster (via Ingress do Exemplo 1 ou Exemplo 2).

Importante

O roteamento baseado em cabeçalho requer dois Ingresses com o mesmo host e caminho — um com a anotação canary e política de correspondência de cabeçalho, e outro sem. O Ingress não-canary lida com todo o tráfego não correspondido. Crie o Ingress do Exemplo 1 ou Exemplo 2 antes de aplicar este exemplo.

Crie um arquivo chamado ingress-demo-header.yaml:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    mse.ingress.kubernetes.io/service-subset: cluster-demo-2
    mse.ingress.kubernetes.io/subset-labels: |
      topology.istio.io/cluster c15d48ca9d1fd43f9bbb89c56a474843c
    nginx.ingress.kubernetes.io/canary: "true"
    nginx.ingress.kubernetes.io/canary-by-header: "stage"
    nginx.ingress.kubernetes.io/canary-by-header-value: "gray"
  name: web-demo-cluster-second
  namespace: web-demo
spec:
  ingressClassName: mse
  rules:
  - host: example.com
    http:
      paths:
      - path: /service1
        pathType: Exact
        backend:
          service:
            name: service1
            port:
              number: 80

Aplique o Ingress:

kubectl apply -f ingress-demo-header.yaml

Obtenha o endereço IP público:

kubectl get ingress web-demo -nargocd -ojsonpath="{.status.loadBalancer}"

Teste o roteamento baseado em cabeçalho. Substitua XX.XX.XX.XX pelo IP do gateway.

for i in {1..50}; do curl -H "host: example.com" -H "stage: gray" xx.xx.xx.xx/service1; sleep 1; done

Saída esperada:

This is env cluster2 !
Config file is
This is env cluster2 !
Config file is
This is env cluster2 !
Config file is
...

A saída indica que o tráfego com o cabeçalho stage: gray é distribuído para o Cluster 2.

Exemplo 4: Failover automático entre clusters

Os gateways multi-cluster realizam failover automático do tráfego quando um Service em um cluster fica indisponível. Nenhuma configuração adicional é necessária.

Este exemplo demonstra o failover usando a configuração do Exemplo 3. Requisições com stage: gray normalmente vão para o Cluster 2. Quando o Service no Cluster 2 cai ou é excluído, o tráfego é automaticamente redirecionado para o Cluster 1.

Obtenha o endereço IP público do gateway:

kubectl get ingress web-demo -nargocd -ojsonpath="{.status.loadBalancer}"

Envie requisições com o cabeçalho stage: gray. Substitua XX.XX.XX.XX pelo IP do gateway.

for i in {1..50}; do curl -H "host: example.com" -H "stage: gray" XX.XX.XX.XX/service1; sleep 1; done

Saída esperada:

This is env cluster1 !
Config file is
This is env cluster1 !
Config file is
This is env cluster1 !
Config file is
...

A saída indica que o tráfego foi automaticamente redirecionado para o Cluster 1.

Exemplo 5: Canary release baseada em peso

Este exemplo roteia 10% do tráfego para o Cluster 2 e 90% para o Cluster 1 usando a anotação nginx.ingress.kubernetes.io/canary-weight. Utilize este padrão para canary releases.

Importante

O roteamento baseado em peso requer dois Ingresses com o mesmo host e caminho — um com canary: "true" e um valor de peso, e outro sem a anotação canary. O Ingress não-canary absorve o tráfego restante.

Crie um arquivo chamado ingress-weight.yaml. Substitua ${cluster1-id} e ${cluster2-id} pelos IDs reais dos clusters.

Anotação	Descrição
`mse.ingress.kubernetes.io/service-subset`	Nome do subconjunto do Service. Use um nome que identifique o cluster.
`mse.ingress.kubernetes.io/subset-labels`	ID do cluster associado.
`nginx.ingress.kubernetes.io/canary`	Defina como `"true"` para ativar o roteamento canary.
`nginx.ingress.kubernetes.io/canary-weight`	Especifique a porcentagem de tráfego distribuído para o cluster, em um intervalo de 0 a 100.

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    mse.ingress.kubernetes.io/service-subset: cluster-demo-1
    mse.ingress.kubernetes.io/subset-labels: |
      topology.istio.io/cluster ${cluster1-id}
  name: web-demo-weight
  namespace: web-demo
spec:
  ingressClassName: mse
  rules:
  - host: example.com
    http:
      paths:
      - path: /svc1-w
        pathType: Exact
        backend:
          service:
            name: service1
            port:
              number: 80
---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    mse.ingress.kubernetes.io/service-subset: cluster-demo-2
    mse.ingress.kubernetes.io/subset-labels: |
      topology.istio.io/cluster ${cluster2-id}
    nginx.ingress.kubernetes.io/canary: "true"
    nginx.ingress.kubernetes.io/canary-weight: "10"
  name: web-demo-weight-canary
  namespace: web-demo
spec:
  ingressClassName: mse
  rules:
  - host: example.com
    http:
      paths:
      - path: /svc1-w
        pathType: Exact
        backend:
          service:
            name: service1
            port:
              number: 80

Referência de anotações:

Aplique ambos os Ingresses:

kubectl apply -f ingress-weight.yaml -nargocd

Obtenha o endereço IP público:

kubectl get ingress web-demo -nargocd -ojsonpath="{.status.loadBalancer}"

Teste a distribuição ponderada de tráfego. Substitua XX.XX.XX.XX pelo IP do gateway.

for i in {1..50}; do curl -H "host: example.com" XX.XX.XX.XX/svc1-w; sleep 1; done

Saída esperada:

This is env cluster1 !
Config file is
This is env cluster1 !
Config file is
This is env cluster1 !
Config file is
This is env cluster1 !
Config file is
This is env cluster1 !
Config file is
This is env cluster1 !
Config file is
This is env cluster1 !
Config file is
This is env cluster1 !
Config file is
This is env cluster1 !
Config file is
This is env cluster1 !
Config file is
This is env cluster1 !
Config file is
This is env cluster2 !
Config file is
This is env cluster1 !
Config file is
...

A saída indica que 90% do tráfego é distribuído para o Cluster 1 e 10% do tráfego é distribuído para o Cluster 2.