Use execuções de implementação em etapas para controlar a colocação de recursos do Azure Kubernetes Fleet Manager

• Defina as seguintes variáveis de ambiente:

  export SUBSCRIPTION_ID=<subscription>
  export GROUP=<resource-group>
  export FLEET=<fleet-name>
  export MEMBER_CLUSTER_1=aks-member-1
  export MEMBER_CLUSTER_2=aks-member-2
  

• Precisa de ter o CLI do Azure instalado para completar este artigo. Para instalar ou atualizar, consulte Instale o CLI do Azure.

• Precisas da extensão fleet CLI do Azure. Você pode instalá-lo executando o seguinte comando:

  az extension add --name fleet
  

  Execute o az extension update comando para atualizar para a versão mais recente da extensão:

  az extension update --name fleet
  

• Se você ainda não tiver a CLI do Kubernetes (kubectl), poderá instalá-la usando este comando:

  az aks install-cli
  

Aplique etiquetas aos clusters de membros utilizando o seguinte comando.

az fleet member update \
    --resource-group ${GROUP} \
    --fleet-name ${FLEET} \
    --name ${MEMBER_CLUSTER_1} \
    --labels environment=canary

az fleet member update \
    --resource-group ${GROUP} \
    --fleet-name ${FLEET} \
    --name ${MEMBER_CLUSTER_2} \
    --labels environment=staging

1. No portal Azure, aceda ao seu Gestor de Frotas.

2. No menu de serviço, em Definições, selecione clusters de membros.

3. Na lista de clusters de membros, selecione um cluster. Depois, escolha Editar etiquetas no menu de ações.

4. Adicione o rótulo apropriado ao cluster de membros e depois selecione Aplicar.

5. Repete para cada grupo de membros.

   

1. Obtenha o arquivo kubeconfig do cluster de hub do Kubernetes Fleet usando o az fleet get-credentials comando:

   az fleet get-credentials \
       --resource-group ${GROUP} \
       --name ${FLEET}
   

   O seu resultado deve parecer semelhante ao seguinte.

   Merged "hub" as current context in /home/fleet/.kube/config
   

   Note

   Se receber um erro do tipo InvalidHubOperation com a mensagem a indicar que a frota está sem hub, adicione um cluster de hubs. Para mais informações, consulte tipo de cluster do hub de atualização.

2. Crie um namespace no cluster de hub do Fleet Manager.

   kubectl create namespace test-app
   

3. Guardar o YAML seguinte como test-workload.yaml.

   apiVersion: apps/v1
   kind: Deployment
   metadata:
     name: nginx-deployment
     namespace: test-app
   spec:
     selector:
       matchLabels:
         app: nginx
     replicas: 2
     template:
       metadata:
         labels:
           app: nginx
       spec:
         containers:
         - name: nginx
           image: mcr.microsoft.com/azurelinux/base/nginx:1.28@sha256:3352a36cbcab4708883a3e77b64f64159e11e1aab358c010e1c4e465dbfb4f57
           ports:
           - containerPort: 80
   ---
   apiVersion: v1
   kind: Service
   metadata:
     name: nginx-service
     namespace: test-app
   spec:
     selector:
       app: nginx
     ports:
     - protocol: TCP
       port: 80
       targetPort: 80
     type: LoadBalancer
   

4. Espalhe a carga de trabalho de teste para o cluster hub do Gestor de Frotas usando kubectl.

   kubectl apply -f test-workload.yaml
   

1. No portal Azure, aceda ao seu Gestor de Frotas.

2. No menu de serviço, em Recursos da Frota, selecione Namespaces>+ Criar.

   Note

   Se não vires Recursos de Frota, o teu Gestor de Frotas não tem um cluster de hubs. Para mais informações sobre como adicionar um, veja o tipo de cluster do hub de atualização.

3. No menu, selecione Namespace, introduza um Nome e depois selecione Criar.

   

   Após alguns instantes, a página é atualizada e o namespace aparece na lista de namespaces no cluster hub do Fleet Manager. Agora está pronto para alojar quaisquer recursos que queira distribuir entre clusters de membros.

4. No topo da lista de namespace, selecione + Criar>Aplicar um YAML e use os seguintes exemplos.

   apiVersion: apps/v1
   kind: Deployment
   metadata:
     name: nginx-deployment
     namespace: test-app
   spec:
     selector:
       matchLabels:
         app: nginx
     replicas: 2
     template:
       metadata:
         labels:
           app: nginx
       spec:
         containers:
         - name: nginx
           image: mcr.microsoft.com/azurelinux/base/nginx:1.28@sha256:3352a36cbcab4708883a3e77b64f64159e11e1aab358c010e1c4e465dbfb4f57
           ports:
           - containerPort: 80
   

   apiVersion: v1
   kind: Service
   metadata:
     name: nginx-service
     namespace: test-app
   spec:
     selector:
       app: nginx
     ports:
     - protocol: TCP
       port: 80
       targetPort: 80
     type: LoadBalancer
   

   Copie e cole as amostras e aplique-as uma de cada vez, como mostrado na imagem seguinte.

   

   O namespace e as suas cargas de trabalho estão agora prontos para serem distribuídos para clusters membros. A Implementação e o Serviço não estão programados no cluster hub do Fleet Manager.

1. Guardar o YAML seguinte como crp-two-stages-strategy.yaml.

   apiVersion: placement.kubernetes-fleet.io/v1
   kind: ClusterStagedUpdateStrategy
   metadata:
     name: two-stages-strategy
   spec:
     stages:
       - name: staging
         labelSelector:
           matchLabels:
             environment: staging
         afterStageTasks:
           - type: TimedWait
             waitTime: 4m
       - name: canary
         labelSelector:
           matchLabels:
             environment: canary
         beforeStageTasks:
           - type: Approval
   

2. Aplique o manifesto de estratégia ao cluster do hub do Fleet Manager.

   kubectl apply -f crp-two-stages-strategy.yaml
   

3. Verifica o estado do recurso de estratégia.

   kubectl get clusterstagedupdatestrategy two-stages-strategy
   

   O seu resultado deve parecer semelhante ao seguinte.

   NAME                  AGE
   two-stages-strategy   47m
   

Utilize o processo seguinte para criar uma estratégia que contenha as duas fases Staging e Canary com um tempo de espera de 4 minutos e uma aprovação prévia para a fase Canary.

1. No portal Azure, aceda ao seu Gestor de Frotas.

2. No menu de serviço, em Recursos da Frota, selecione Colocação> de RecursosEstratégias de implementação em etapas, depois Criar.

3. Insira um nome para a estratégia.

4. Selecione o âmbito de Estratégia, escolhendo entre Escopado por Cluster ou Escopo por Espaço de Nomes.

   • Para o âmbito de Namespace, selecione o Namespace existente no cluster hub Fleet Manager onde os recursos Kubernetes a distribuir são organizados.

5. Selecione Criar estágio e digite:

   • Nome da etapa - nomeie a etapa - deve ser único entre todos os nomes de etapa na estratégia.
   • Aprovações de estágio (opcional) - selecione esta opção se quiser aguardar uma aprovação antes que esta etapa comece ou depois de ser concluída.
   • (Opcional) Esperar após a fase - selecione esta opção se quiser definir uma pausa antes de passar para a próxima fase.
   • (Opcional) Duração de espera - selecione uma duração pré-definida, ou introduza um valor personalizado em segundos.
   • Seletor de etiquetas de cluster - escolha uma etiqueta de cluster membro existente para usar na seleção de clusters desta fase.
   • (Opcional) Etiqueta de ordenação de clusters - escolha uma etiqueta existente de um cluster membro para ordenar os clusters dentro da etapa.
   • (Opcional) Concorrência de estágio - defina quantos clusters devem ser atualizados simultaneamente na fase atual.

   

   Note

   O número máximo de fases em cada estratégia é 31.

6. Repete até que todas as fases sejam adicionadas à estratégia. Selecione Criar para criar a estratégia.

   

7. A página atualiza-se e a lista mostra a estratégia recém-criada.

   

1. Guardar o YAML seguinte como crp-distribute-workload-ext.yaml.

   apiVersion: placement.kubernetes-fleet.io/v1
   kind: ClusterResourcePlacement
   metadata:
     name: distribute-test-app
   spec:
     resourceSelectors:
       - group: ""
         kind: Namespace
         version: v1          
         name: test-app
     policy:
       placementType: PickAll
     strategy:
       type: External
   

   Importante

   Se não definires o tipo de strategy como External, a implementação do recurso começa assim que aplicares o manifesto com uma estratégia RollingUpdate.

2. Aplique o manifesto de colocação ao cluster do hub do Gestor de Frotas.

   kubectl apply -f crp-distribute-workload-ext.yaml
   

3. Verifique o estado da colocação dos recursos.

   kubectl get clusterresourceplacement distribute-test-app
   

   O seu resultado deve parecer semelhante ao seguinte.

   NAME                  GEN   SCHEDULED   SCHEDULED-GEN   AVAILABLE   AVAILABLE-GEN   AGE
   distribute-test-app   1     True        1                                           60s
   

1. No portal Azure, aceda ao seu Gestor de Frotas.

2. No menu de serviço, em Recursos da Frota, selecione Colocação>de Recursos + Criar.

3. Na guia Noções básicas, configure as seguintes opções:

   • Nos detalhes da colocação, insira um nome para a colocação.

   • Em Detalhes do recurso, deixe Âmbito como Âmbito do cluster e introduza o Grupo, versão e tipo (GVK) e o nome do recurso a distribuir. Neste exemplo, use os seguintes valores.

     group: ""
     kind: Namespace
     version: v1          
     name: test-app
     

   • Na seleção de clusters de membros, para o tipo de colocaçãoescolhe Todos os clusters.

   • Para Rollout, selecione Externo. Use a estratégia de atualização em estágios para selecionar a estratégia de lançamento que criou anteriormente.

   • Deixe a caixa Iniciar Implementação Automática desmarcada.

   

4. Selecione Seguinte para rever o manifesto resultante ClusterResourcePlacement . Pode modificar o manifesto se necessário, validar usando a opção Validar (ensaio geral), ou selecionar Rever + criar para avançar para a confirmação final.

   

5. Selecione Criar para criar a execução de implementação faseada, mas não a iniciar.

   

6. A página atualiza-se e a lista de Posicionamentos de Recursos mostra a nova colocação criada. Mostra o número de clusters selecionados e se o programador da frota consegue cumprir a política de colocação. Repare que o tipo de Lançamento está definido como Externo.

   

Quando utiliza o portal do Azure para criar um posicionamento com uma estratégia de implementação, é criada automaticamente para si uma execução de implementação faseada.

Use o lançamento por etapas para controlar a distribuição

Neste artigo, crias o lançamento por etapas com um state de Initialize para que possas iniciar o lançamento quando quiseres, em vez de a execução começar imediatamente quando o manifesto é aplicado. Defina o estado como Run para começar imediatamente em vez disso.

1. Guardar o YAML seguinte como staged-rollout-test-app.yaml.

   apiVersion: placement.kubernetes-fleet.io/v1
   kind: ClusterStagedUpdateRun
   metadata:
     name: staged-rollout-test-app
   spec:
     placementName: distribute-test-app
     stagedRolloutStrategyName: two-stages-strategy
     state: Initialize
   

   Note

   Se não definires o tipo de strategy como External, a implementação do recurso começa assim que aplicares o manifesto com uma estratégia RollingUpdate.

2. Aplique o manifesto de implementação faseada ao cluster hub do Fleet Manager.

   kubectl apply -f staged-rollout-test-app.yaml
   

3. Verifica o estado do recurso de execução de rollout. Está inicializado, mas não avança.

   kubectl get clusterstagedupdaterun staged-rollout-test-app
   

   O seu resultado deve parecer semelhante ao seguinte.

   NAME                      PLACEMENT             RESOURCE-SNAPSHOT-INDEX   POLICY-SNAPSHOT-INDEX   INITIALIZED   PROGRESSING   SUCCEEDED   AGE
   staged-rollout-test-app   distribute-test-app                             0                       True                                    101s
   

Para iniciar um lançamento por etapas, atualize o state campo na especificação para Run.

kubectl patch clusterstagedupdaterun staged-rollout-test-app --type merge -p '{"spec":{"state":"Run"}}'

Verifica o estado do recurso de execução de rollout. Está inicializado, mas não avança.

kubectl get clusterstagedupdaterun staged-rollout-test-app

O seu resultado deverá ser semelhante ao seguinte, notando que o progresso é agora True.

NAME                      PLACEMENT             RESOURCE-SNAPSHOT-INDEX   POLICY-SNAPSHOT-INDEX   INITIALIZED   PROGRESSING   SUCCEEDED   AGE
staged-rollout-test-app   distribute-test-app                             0                       True          True                      36m

Consulte o estado detalhado da implementação ao especificar o ClusterStagedUpdateRun.

kubectl describe clusterstagedupdaterun staged-rollout-test-app

Na resposta, analise o Status, observando o Conditions e o Stages Status para determinar que fase e que cluster estão atualmente a ser processados, ou se está atualmente ativa uma tarefa de TimedWait ou de Approval.

Name:         staged-rollout-test-app
Namespace:
Labels:       <none>
Annotations:  <none>
API Version:  placement.kubernetes-fleet.io/v1
Kind:         ClusterStagedUpdateRun
Metadata:
  Creation Timestamp:  2026-07-27T04:25:14Z
  Finalizers:
    kubernetes-fleet.io/stagedupdaterun-finalizer
  Generation:        3
  Resource Version:  2684410
  UID:               5e20d0a1-515a-4f1c-b566-89676100a968
Spec:
  Placement Name:                distribute-test-app
  Resource Snapshot Index:
  Staged Rollout Strategy Name:  two-stages-strategy
  State:                         Run
Status:
  Applied Strategy:
    Comparison Option:  PartialComparison
    Type:               ClientSideApply
    When To Apply:      Always
    When To Take Over:  Always
  Conditions:
    Last Transition Time:  2026-07-27T04:25:14Z
    Message:               The UpdateRun initialized successfully
    Observed Generation:   3
    Reason:                UpdateRunInitializedSuccessfully
    Status:                True
    Type:                  Initialized
    Last Transition Time:  2026-07-27T05:01:56Z
    Message:               The update run is making progress
    Observed Generation:   3
    Reason:                UpdateRunProgressing
    Status:                True
    Type:                  Progressing
  Deletion Stage Status:
    Clusters:
    Stage Name:                   kubernetes-fleet.io/deleteStage
  Policy Observed Cluster Count:  2
  Policy Snapshot Index Used:     0
  Resource Snapshot Index Used:   0
  Staged Update Strategy Snapshot:
    Stages:
      After Stage Tasks:
        Type:       TimedWait
        Wait Time:  1h0m0s
      Label Selector:
        Match Labels:
          Environment:  staging
      Max Concurrency:  1
      Name:             staging
      Before Stage Tasks:
        Type:  Approval
      Label Selector:
        Match Labels:
          Environment:  canary
      Max Concurrency:  1
      Name:             canary
  Stages Status:
    After Stage Task Status:
      Type:  TimedWait
    Clusters:
      Cluster Name:  aks-place-member-02-fm
      Conditions:
        Last Transition Time:  2026-07-27T05:01:56Z
        Message:               Cluster update started
        Observed Generation:   3
        Reason:                ClusterUpdatingStarted
        Status:                True
        Type:                  Started
    Conditions:
      Last Transition Time:  2026-07-27T05:01:56Z
      Message:               Clusters in the stage started updating
      Observed Generation:   3
      Reason:                StageUpdatingStarted
      Status:                True
      Type:                  Progressing
    Stage Name:              staging
    Start Time:              2026-07-27T05:01:56Z
    Before Stage Task Status:
      Approval Request Name:  staged-rollout-test-app-before-canary
      Type:                   Approval
    Clusters:
      Cluster Name:  aks-place-member-01-fm
    Stage Name:      canary
Events:              <none>

1. No portal Azure, aceda ao seu Gestor de Frotas.

2. No menu de serviço, em Recursos da Frota, selecione Execuções de implementação em etapas.

3. Na lista, selecione a corrida de implementação em fases que foi criada automaticamente na etapa anterior e depois selecione Iniciar no menu de ações.

   

4. A página é atualizada e a lista Execuções de implementação faseada apresenta a execução de implementação faseada com o estado Em curso, com a fase atualmente em execução apresentada.

   

5. Quando o lançamento atinge um TimedWait, o estado muda para Espera. Pode passar o cursor sobre o ícone de informação para confirmar que este estado é devido a um TimedWait.

   

Para parar uma implementação faseada em execução, atualize o campo state na especificação para Stop. Esta ação interrompe graciosamente a execução de implementação em etapas, de modo que os clusters em curso terminam as suas atualizações antes de o processo parar.

kubectl patch clusterstagedupdaterun staged-rollout-test-app --type merge -p '{"spec":{"state":"Stop"}}'

A execução de atualização em fases é inicializada, mas já não está em execução.

kubectl get clusterstagedupdaterun staged-rollout-test-app

O resultado deve ser semelhante ao exemplo seguinte, tendo em conta que progressing é agora False.

NAME                      PLACEMENT             RESOURCE-SNAPSHOT-INDEX   POLICY-SNAPSHOT-INDEX   INITIALIZED   PROGRESSING   SUCCEEDED   AGE
staged-rollout-test-app   distribute-test-app                             0                       True          False                     46m

Para interromper uma implementação faseada em execução, proceda do seguinte modo. Esta ação interrompe graciosamente o lançamento em etapas, para que os clusters em progresso terminem as suas atualizações antes que o processo termine.

1. No portal Azure, aceda ao seu Gestor de Frotas.

2. No menu de serviço, em Recursos da Frota, selecione Execuções de implementação em etapas.

3. Na lista, selecione a execução da implementação faseada que pretende parar. Depois, escolhe Parar no menu de ação.

   

4. A página atualiza-se e a lista de lançamentos em etapas exibe o lançamento em etapas com o estado de Interrompido.

   

Quando uma execução de implementação faseada atinge uma aprovação, é criado um pedido de aprovação (ClusterApprovalRequest ou ApprovalRequest). Tens de corrigir este pedido. Depois de aplicar a correção, a execução da implementação prossegue.

Verifique se há aprovações pendentes usando os seguintes comandos.

kubectl get clusterapprovalrequest

Ao verificar recursos pendentes ApprovalRequest , certifique-se de fornecer o namespace onde os recursos residem.

kubectl get clusterapprovalrequest -n test-app

Se receber uma resposta de No resources found, significa que, de momento, não há aprovações de âmbito do cluster pendentes.

Se houver aprovações pendentes, a resposta deverá ser semelhante ao exemplo seguinte.

NAME                                    UPDATE-RUN                STAGE    APPROVED   AGE
staged-rollout-test-app-before-canary   staged-rollout-test-app   canary              4m13s

Pode aprovar o ClusterApprovalRequest criando um ficheiro de patch JSON e aplicando-o.

cat << EOF > approval.json
"status": {
    "conditions": [
        {
            "lastTransitionTime": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
            "message": "lgtm",
            "observedGeneration": 1,
            "reason": "testPassed",
            "status": "True",
            "type": "Approved"
        }
    ]
}
EOF

Submeta um pedido de atualização para aprovar o pedido usando o ficheiro JSON que criou.

kubectl patch clusterapprovalrequests staged-rollout-test-app-before-canary --type='merge' --subresource=status --patch-file approval.json

Verifica se a aprovação foi aplicada ao pedido.

kubectl get clusterapprovalrequest staged-rollout-test-app-before-canary

O seu resultado deve parecer semelhante ao seguinte. Note que APPROVED está definido como True.

NAME                                    UPDATE-RUN                STAGE    APPROVED   AGE
staged-rollout-test-app-before-canary   staged-rollout-test-app   canary   True       6m

A fase de implementação continua.

kubectl get clusterstagedupdaterun staged-rollout-test-app

A sua saída deve parecer semelhante à seguinte, que mostra uma execução concluída com SUCCEEDED definido para True.

NAME                      PLACEMENT             RESOURCE-SNAPSHOT-INDEX   POLICY-SNAPSHOT-INDEX   INITIALIZED   PROGRESSING   SUCCEEDED   AGE
staged-rollout-test-app   distribute-test-app                             0                       True          False         True        9m

Quando uma execução de implementação faseada atingir uma aprovação, utilize o processo seguinte para desbloquear a aprovação, para que a execução continue.

1. No portal Azure, aceda ao seu Gestor de Frotas.

2. No menu de serviço, em Recursos da Frota, selecione Execuções de implementação em etapas.

3. Na lista, localize a execução da implementação faseada com o estado Aprovação pendente.

   

4. Pode abrir o diálogo de aprovação a partir de qualquer um de três locais:

   • Em linha na vista de lista de execuções da implementação faseada (mostrada anteriormente).
   • Na vista de detalhes da execução da implementação faseada:
     • No campo Estado da secção Essenciais.
     • Em linha na vista de palco.

   

5. Selecione uma opção para abrir o diálogo de Aprovação . Introduza uma Mensagem opcional e escolha Aprovar.

   

6. A página é atualizada e a lista de execuções de implementação faseada mostra a execução da implementação faseada com o estado Em curso.

   

7. A execução da implementação faseada continua até estar concluída, com a lista Execuções da implementação faseada a apresentar a execução da implementação faseada com o estado Succeeded.

   

Remova uma execução de implementação em fases eliminando o recurso Kubernetes no cluster do hub do Gestor de Frotas.

kubectl delete clusterstagedupdaterun staged-rollout-test-app

1. No portal Azure, aceda ao seu Gestor de Frotas.

2. No menu de serviço, em Recursos da Frota, selecione Execuções de implementação em etapas.

3. Na lista, selecione a execução de implementação faseada a eliminar e, em seguida, escolha Eliminar no menu de ações.

4. No diálogo Apagar , confirma que o recurso está correto e depois seleciona Confirmar eliminar. Por fim, escolhe Apagar.

   

5. A página atualiza-se e a execução de implementação em fases eliminada já não está presente.