Use execuções de implantação em etapas para controlar os posicionamentos 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
  

• Você precisa CLI do Azure instalado para concluir este artigo. Para instalar ou atualizar, consulte Instale o CLI do Azure.

• Você precisa da extensão fleet CLI do Azure. Instale-o executando o seguinte comando:

  az extension add --name fleet
  

  Execute o comando az extension update 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 rótulos aos clusters de membros usando o comando a seguir.

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 do Azure, acesse o Fleet Manager.

2. No menu de serviço, em Configurações, selecione Clusters de membros.

3. Na lista de clusters de membro, selecione um cluster. Em seguida, escolha Editar rótulos no menu de ação.

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

5. Repita para cada cluster de membros.

   

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

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

   Sua saída deve ser semelhante à seguinte.

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

   Note

   Se você receber um erro do tipo InvalidHubOperation com a mensagem informando que a frota não tem hub, adicione um cluster de hubs. Para obter mais informações, consulte o tipo de cluster do hub de atualização.

2. Cria um namespace do Kubernetes no cluster de hub do Gerenciador de Frota.

   kubectl create namespace test-app
   

3. Salve o YAML a seguir 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. Implante a carga de trabalho de teste no cluster de hub do Fleet Manager usando kubectl.

   kubectl apply -f test-workload.yaml
   

1. No portal do Azure, acesse o Fleet Manager.

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

   Note

   Se você não vir Os Recursos da Frota, o Fleet Manager não terá um cluster de hub. Para obter mais informações sobre como adicionar um, consulte o tipo de cluster do hub de atualização.

3. No menu, selecione Namespace, insira um Nome e selecione Criar.

   

   Após alguns instantes, a página é atualizada e o namespace aparece na lista de namespaces no cluster do Hub do Fleet Manager. Agora ele está pronto para hospedar todos os recursos que você deseja distribuir entre clusters membros.

4. Na parte superior da lista de namespaces, selecione + Criar>Aplicar um YAML e use os exemplos a seguir.

   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 os exemplos e aplique-os um de cada vez, conforme mostrado na imagem a seguir.

   

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

1. Salve o YAML a seguir 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. Verifique o status do recurso de estratégia.

   kubectl get clusterstagedupdatestrategy two-stages-strategy
   

   Sua saída deve ser semelhante à seguinte.

   NAME                  AGE
   two-stages-strategy   47m
   

Use o processo a seguir para criar uma estratégia que contenha os dois estágios Staging e Canary com um tempo de espera de 4 minutos e uma aprovação pré-estágio para o Canary estágio.

1. No portal do Azure, acesse o Fleet Manager.

2. No menu de serviço, em Recursos de frota, selecione Posicionamentos de recursos>Estratégias de implementação em etapas, depois Criar.

3. Insira um nome para a estratégia.

4. Selecione o escopo da estratégia, escolhendo entre com escopo de cluster ou com escopo de namespace.

   • Para o namespace com escopo, selecione o Namespace existente no cluster do hub do Fleet Manager em que os recursos do Kubernetes a serem distribuídos são preparados.

5. Selecione Criar Estágio e insira:

   • Nome do estágio - nome do estágio - deve ser único entre todos os nomes de estágio na estratégia.
   • (Opcional) Aprovações de estágio – selecione essa opção se você quiser aguardar uma aprovação antes que essa fase seja iniciada ou depois que ela for concluída.
   • (Opcional) Aguarde após o estágio – selecione essa opção se quiser definir uma pausa antes de passar para o próximo estágio.
   • (Opcional) Duração da espera – selecione uma duração predefinida ou insira um valor personalizado em segundos.
   • Seletor de rótulo de cluster – escolha um rótulo de cluster de membro existente a ser usado para selecionar clusters para este estágio.
   • (Opcional) Rótulo de ordenação de cluster – escolha um rótulo de cluster membro existente para usar para ordenar os clusters dentro do estágio.
   • (Opcional) Simultaneidade de estágio – defina quantos clusters devem ser atualizados simultaneamente no estágio atual.

   

   Note

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

6. Repita até que todos os estágios sejam adicionados à estratégia. Selecione Criar para criar a estratégia.

   

7. A página é atualizada e a lista exibe a estratégia recém-criada.

   

1. Salve o YAML a seguir 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 você não definir o tipo strategy como External, a implantação do recurso será iniciada assim que você aplicar o manifesto usando uma estratégia RollingUpdate.

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

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

3. Verifique o status do posicionamento do recurso.

   kubectl get clusterresourceplacement distribute-test-app
   

   Sua saída deve ser semelhante à seguinte.

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

1. No portal do Azure, acesse o Fleet Manager.

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

3. Na guia Básico, configure os seguintes valores:

   • Em Detalhes do posicionamento, insira um nome para o posicionamento.

   • Em detalhes do recurso, deixe o Escopo como escopo de cluster e insira o Tipo de Versão de Grupo (GVK) e o nome do recurso a ser distribuído. Neste exemplo, use os valores a seguir.

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

   • Em Seleção de clusters membros, em Tipo de posicionamento, escolha Todos os clusters.

   • Para Distribuição, selecione Externo. Use a estratégia de atualização em etapas para selecionar a estratégia de distribuição criada anteriormente.

   • Deixe a caixa Iniciar implantação automaticamente desmarcada.

   

4. Selecione Avançar para examinar o manifesto resultante ClusterResourcePlacement . Você pode modificar o manifesto se necessário, validar usando a opção Validar (execução seca) ou selecionar Examinar + criar para prosseguir para a confirmação final.

   

5. Selecione Criar para criar a execução de distribuição, mas não iniciá-la.

   

6. A página é recarregada e a lista Alocações de recursos exibe a alocação recém-criada. Ele mostra o número de clusters selecionados e se o agendador de frota pode atender à política de posicionamento. Observe que o tipo de distribuição está definido como Externo.

   

Quando você usa o Portal do Azure para criar uma alocação com uma estratégia de implantação, ele cria automaticamente uma execução de implantação em etapas para você.

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

Neste artigo, você cria a implantação em etapas com uma state de Initialize, para que possa iniciar a implantação quando quiser, em vez de a execução começar imediatamente quando o manifesto for aplicado. Defina o estado como Run para iniciar imediatamente em vez disso.

1. Salve o YAML a seguir 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 você não definir o tipo strategy como External, a implantação do recurso será iniciada assim que você aplicar o manifesto usando uma estratégia RollingUpdate.

2. Aplique o manifesto de implantação em etapas ao cluster de hub do Fleet Manager.

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

3. Verifique o status do recurso de execução da implantação. Foi inicializado, mas não avança.

   kubectl get clusterstagedupdaterun staged-rollout-test-app
   

   Sua saída deve ser semelhante à 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 uma distribuição em etapas, corrija o state campo na especificação para Run.

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

Verifique o status do recurso de execução da implantação. Foi inicializado, mas não avança.

kubectl get clusterstagedupdaterun staged-rollout-test-app

Sua saída deve ser semelhante à seguinte, tendo em mente que 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

Exiba o status detalhado da implantação ao descrever ClusterStagedUpdateRun.

kubectl describe clusterstagedupdaterun staged-rollout-test-app

Na resposta, revise o Status, observando o Conditions e o Stages Status para entender qual estágio e qual cluster estão sendo processados no momento, ou se uma tarefa TimedWait ou Approval está ativa no momento.

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 do Azure, acesse o Fleet Manager.

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

3. Na lista, selecione a execução de distribuição em etapas criada automaticamente na etapa anterior e selecione Iniciar no menu de ação.

   

4. A página é atualizada, e a lista de execuções de implantação em etapas exibe a execução de implantação em etapas com o estado Em andamento, com o estágio atualmente em execução sendo exibido.

   

5. Quando a distribuição atinge um TimedWait, o estado é alterado para Aguardando. Você pode passar o mouse sobre o ícone de informações para confirmar se esse estado é devido a um TimedWait.

   

Para interromper uma implantação gradual em execução, altere o campo state na especificação para Stop. Essa ação interrompe de forma controlada a execução da implantação em etapas, para que os clusters com atualização em andamento concluam suas atualizações antes que o processo pare.

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

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

kubectl get clusterstagedupdaterun staged-rollout-test-app

Sua saída deve ser semelhante ao exemplo a seguir, observando 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 distribuição em etapas em execução, use as etapas a seguir. Essa ação interrompe de forma controlada a implantação em fases, de modo que os clusters com atualização em andamento concluam suas atualizações antes da interrupção do processo.

1. No portal do Azure, acesse o Fleet Manager.

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

3. Na lista, selecione a execução do lançamento em etapas que você deseja interromper. Em seguida, escolha Parar no menu de ação.

   

4. A página é atualizada e a lista de execuções de distribuição em etapas exibe a execução de distribuição em etapas com o estado de Parada.

   

Quando uma execução de implantação gradual chega a uma etapa de aprovação, ela cria uma solicitação de aprovação (ClusterApprovalRequest ou ApprovalRequest). Você deve corrigir essa solicitação. Depois de corrigi-lo, a execução da implantação continua.

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

kubectl get clusterapprovalrequest

Ao verificar se há recursos pendentes ApprovalRequest , forneça o namespace no qual os recursos residem.

kubectl get clusterapprovalrequest -n test-app

Se você receber uma resposta de No resources found, então, no momento, não há aprovações pendentes no escopo do cluster.

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

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

Você pode aprovar o ClusterApprovalRequest criando um arquivo 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

Envie uma solicitação de patch para aprovar a solicitação usando o arquivo JSON que você criou.

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

Verifique se a aprovação foi aplicada à solicitação.

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

Sua saída deve ser semelhante à seguinte. Observe 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 rodada de implantação continua.

kubectl get clusterstagedupdaterun staged-rollout-test-app

Sua saída deve ser semelhante à mostrada a seguir, que exibe uma execução concluída com SUCCEEDED definido como 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 implantação gradual chegar a uma etapa de aprovação, use o processo a seguir para liberar a aprovação para que a execução prossiga.

1. No portal do Azure, acesse o Fleet Manager.

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

3. Na lista, localize a execução da distribuição em fases com o status de aprovação pendente.

   

4. Você pode abrir a caixa de diálogo de aprovação de qualquer um dos três locais:

   • Embutido no modo de exibição de lista de execução de distribuição em etapas (mostrado anteriormente).
   • Na visualização de detalhes da execução da distribuição em etapas:
     • No campo Estado na seção Noções básicas.
     • Integrado à visualização do palco.

   

5. Selecione uma opção para abrir a caixa de diálogo Aprovação . Insira uma mensagem opcional e escolha Aprovar.

   

6. A página é atualizada, e a lista de execuções de implantação em etapas exibe a execução da implantação em etapas com o status Em andamento.

   

7. A execução de distribuição em etapas continua até que seja concluída, com a lista de execuções de distribuição em etapas exibindo a execução de distribuição em etapas com o estado de Succeeded.

   

Remova uma execução de distribuição em etapas excluindo o recurso kubernetes no cluster do hub do Fleet Manager.

kubectl delete clusterstagedupdaterun staged-rollout-test-app

1. No portal do Azure, acesse o Fleet Manager.

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

3. Na lista, selecione a execução da implementação em fases que deseja excluir e, em seguida, escolha Excluir no menu de ações.

4. Na caixa de diálogo Excluir, confirme se o recurso está correto e selecione Confirmar exclusão. Por fim, escolha Excluir.

   

5. A página é atualizada e a execução de distribuição em etapas excluída não está mais presente.