Usar a manutenção planejada para agendar e controlar atualizações para o cluster Serviço de Kubernetes do Azure

• Este artigo considera que já existe um cluster do AKS. Se você não tiver um cluster do AKS, confira Criar um cluster do AKS.

• Uma assinatura de Azure ativa. Se você não tiver uma assinatura do Azure, crie uma conta gratuita antes de começar.

• Defina o contexto de assinatura usando o az account set comando. Por exemplo:

  az account set --subscription "00000000-0000-0000-0000-000000000000"
  

• Terraform instalado localmente. Para obter instruções de instalação, consulte Instalar o Terraform.

Criar o arquivo de configuração do Terraform

Os arquivos de configuração do Terraform definem a infraestrutura que o Terraform cria e gerencia.

Crie um arquivo chamado main.tf e adicione o seguinte código para definir a versão do Terraform e especificar o provedor de Azure:

terraform {
 required_providers {
   azurerm = {
     source  = "hashicorp/azurerm"
     version = "~>4.0"
   }
   azapi = {
     source  = "azure/azapi"
     version = "~>2.0"
   }
 }
}
provider "azurerm" {
 features {}
}
provider "azapi" {}

Criar um grupo de recursos

Adicione o código a seguir para main.tf para criar um grupo de recursos Azure. Atualize os valores location e name para que correspondam ao seu ambiente.

resource "azurerm_resource_group" "rg" {
 name     = "aks-maintenance-rg"
 location = "East US"
}

Criar um cluster do AKS

Adicione o seguinte código em main.tf para criar um cluster do AKS. Atualize os valores conforme necessário para corresponder ao seu ambiente.

resource "azurerm_kubernetes_cluster" "aks" {
 name                = "aks-maintenance-cluster"
 location            = azurerm_resource_group.rg.location
 resource_group_name = azurerm_resource_group.rg.name
 dns_prefix          = "aksmaintenance"
 default_node_pool {
   name       = "nodepool1"
   node_count = 1
   vm_size    = "Standard_DS2_v2"
 }
 identity {
   type = "SystemAssigned"
 }
}

Adicione uma configuração de janela de manutenção a um cluster do AKS usando o az aks maintenanceconfiguration add comando.

O primeiro exemplo adiciona uma nova default configuração que agenda a manutenção a ser executada das 1h às 5h todas as segundas-feiras no UTC fuso horário. O segundo exemplo adiciona uma nova configuração aksManagedAutoUpgradeSchedule que agenda a manutenção a ser executada a cada três sextas-feiras entre 0h e 8h no fuso horário UTC+5:30.

# Add a new default configuration
az aks maintenanceconfiguration add --resource-group $RESOURCE_GROUP --cluster-name $CLUSTER_NAME --name default --schedule-type Weekly --day-of-week Monday --interval-weeks 1 --duration 4 --utc-offset +00:00 --start-time 01:00

# Add a new aksManagedAutoUpgradeSchedule configuration
az aks maintenanceconfiguration add --resource-group $RESOURCE_GROUP --cluster-name $CLUSTER_NAME --name aksManagedAutoUpgradeSchedule --schedule-type Weekly --day-of-week Friday --interval-weeks 3 --duration 8 --utc-offset +05:30 --start-time 00:00

1. No portal do Azure, acesse o recurso de cluster do AKS.

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

3. Em Atualizar>Agendador de atualização automático, selecione Adicionar agendamento.

   

4. No painel Adicionar agendamento de manutenção, defina as seguintes configurações de janela de manutenção:

   • Repete: selecione a frequência para a janela de manutenção. Recomendamos selecionar Semanal.
   • Frequência: selecione o dia da semana para a janela de manutenção. Recomendamos selecionar Domingo.
   • Data de início da manutenção: selecione a data de início para a janela de manutenção.
   • Hora de início da manutenção: selecione a hora de início para a janela de manutenção.
   • Diferença UTC: selecione a diferença UTC para a janela de manutenção. O padrão é +00:00.

   

5. Clique em Salvar.

Você pode usar um arquivo JSON para criar uma configuração de manutenção, em vez de usar parâmetros. Ao usar esse método, você pode impedir a manutenção durante um intervalo de datas especificando notAllowedDates para default, aksManagedAutoUpgradeSchedulee aksManagedNodeOSUpgradeSchedule configurações.

1. Crie um arquivo JSON com as configurações da janela de manutenção.

   O exemplo a seguir cria um default.json arquivo que agenda a manutenção a ser executada das 1h às 5h todas as terças-feiras no UTC fuso horário. Também há uma exceção de 2021-05-26 a 2021-05-30, em que a manutenção não é permitida mesmo que se sobreponha a uma janela de manutenção.

   {
     "properties": {
       "maintenanceWindow": {
           "schedule": {
               "weekly": {
                   "intervalWeeks": 1,
                   "dayOfWeek": "Tuesday"
               }
           },
           "durationHours": 4,
           "utcOffset": "+00:00",
           "startTime": "01:00",
           "notAllowedDates": [
               {
                   "start": "2021-05-26",
                   "end": "2021-05-30"
               }
           ]
       }
     }
   }
   

   O exemplo a seguir cria um arquivo autoUpgradeWindow.json que agenda a manutenção a ser executada a cada três meses no primeiro mês entre 9h e 13h no fuso horário UTC-08. Também há uma exceção de 2023-12-23 a 2024-01-05, em que a manutenção não é permitida mesmo que se sobreponha a uma janela de manutenção.

   {
     "properties": {
       "maintenanceWindow": {
           "schedule": {
               "absoluteMonthly": {
                   "intervalMonths": 3,
                   "dayOfMonth": 1
               }
           },
           "durationHours": 4,
           "utcOffset": "-08:00",
           "startTime": "09:00",
           "notAllowedDates": [
               {
                   "start": "2023-12-23",
                   "end": "2024-01-05"
               }
           ]
       }
     }
   }
   

2. Adicione a configuração da janela de manutenção usando o az aks maintenanceconfiguration add comando com o --config-file parâmetro.

   O primeiro exemplo adiciona uma nova configuração default usando o arquivo default.json. O segundo exemplo adiciona uma nova configuração aksManagedAutoUpgradeSchedule usando o arquivo autoUpgradeWindow.json.

   # Add a new default configuration
   az aks maintenanceconfiguration add --resource-group $RESOURCE_GROUP --cluster-name $CLUSTER_NAME --name default --config-file ./default.json
   
   # Add a new aksManagedAutoUpgradeSchedule configuration
   az aks maintenanceconfiguration add --resource-group $RESOURCE_GROUP --cluster-name $CLUSTER_NAME --name aksManagedAutoUpgradeSchedule --config-file ./autoUpgradeWindow.json
   

Adicione a configuração da janela de manutenção ao main.tf usando o recurso azapi_resource.

Configuração de manutenção padrão

O exemplo a seguir cria uma default configuração de manutenção que agenda a manutenção a ser executada das 2h às 6h todos os sábados no UTC-04:00 fuso horário:

resource "azapi_resource" "default_maintenance" {
 type      = "Microsoft.ContainerService/managedClusters/maintenanceConfigurations@2025-10-01"
 name      = "default"
 parent_id = azurerm_kubernetes_cluster.aks.id
 schema_validation_enabled = false
 body = {
   properties = {
     maintenanceWindow = {
       schedule = {
         weekly = {
           dayOfWeek     = "Saturday"
           intervalWeeks = 1
         }
       }
       durationHours = 4
       startTime     = "02:00"
       utcOffset     = "-04:00"
     }
   }
 }
}

Configuração de manutenção de atualização automática

O exemplo a seguir cria uma aksManagedAutoUpgradeSchedule configuração de manutenção que agenda a manutenção a ser executada todos os domingos das 1h às 5h no fuso horário UTC-04:00, começando em 20 de abril de 2026:

resource "azapi_resource" "auto_upgrade" {
 type      = "Microsoft.ContainerService/managedClusters/maintenanceConfigurations@2025-10-01"
 name      = "aksManagedAutoUpgradeSchedule"
 parent_id = azurerm_kubernetes_cluster.aks.id
 schema_validation_enabled = false
 body = {
   properties = {
     maintenanceWindow = {
       startDate     = "2026-04-20"
       startTime     = "01:00"
       durationHours = 4
       utcOffset     = "-04:00"
       schedule = {
         weekly = {
           dayOfWeek     = "Sunday"
           intervalWeeks = 1
         }
       }
     }
   }
 }
}

Configuração de manutenção para atualização do SO do nó

O exemplo a seguir cria uma aksManagedNodeOSUpgradeSchedule configuração de manutenção que agenda a manutenção a ser executada todas as segundas-feiras das 3h às 7h no fuso horário, começando em UTC-04:00 21 de abril de 2026:

resource "azapi_resource" "node_os_upgrade" {
 type      = "Microsoft.ContainerService/managedClusters/maintenanceConfigurations@2025-10-01"
 name      = "aksManagedNodeOSUpgradeSchedule"
 parent_id = azurerm_kubernetes_cluster.aks.id
 schema_validation_enabled = false
 body = {
   properties = {
     maintenanceWindow = {
       startDate     = "2026-04-21"
       startTime     = "03:00"
       durationHours = 4
       utcOffset     = "-04:00"
       schedule = {
         weekly = {
           dayOfWeek     = "Monday"
           intervalWeeks = 1
         }
       }
     }
   }
 }
}

Atualize uma configuração de manutenção existente usando o az aks maintenanceconfiguration update comando.

O exemplo a seguir atualiza a default configuração para agendar a manutenção a ser executada das 2h às 6h todas as sextas-feiras:

az aks maintenanceconfiguration update --resource-group $RESOURCE_GROUP --cluster-name $CLUSTER_NAME --name default --schedule-type Weekly --day-of-week Friday --interval-weeks 1 --duration 4 --utc-offset +00:00 --start-time 02:00

1. No portal Azure, navegue até o recurso de cluster do AKS.

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

3. Em Atualizar>Agendador de atualização automático, selecione Editar agendamento.

   

4. No painel Editar agendamento de manutenção, atualize as configurações da janela de manutenção conforme necessário.

5. Clique em Salvar.

1. Atualize o arquivo JSON de configuração com as novas configurações da janela de manutenção.

   O exemplo a seguir atualiza o default.json arquivo da seção anterior para agendar a manutenção a ser executada das 2h às 6h todas as segundas-feiras:

   {
     "properties": {
       "maintenanceWindow": {
           "schedule": {
               "weekly": {
                   "intervalWeeks": 1,
                   "dayOfWeek": "Monday"
               }
           },
           "durationHours": 4,
           "utcOffset": "+00:00",
           "startTime": "02:00",
           "notAllowedDates": [
               {
                   "start": "2021-05-26",
                   "end": "2021-05-30"
               }
           ]
       }
     }
   }
   

2. Atualize a configuração da janela de manutenção usando o az aks maintenanceconfiguration update comando com o --config-file parâmetro:

   az aks maintenanceconfiguration update --resource-group $RESOURCE_GROUP --cluster-name $CLUSTER_NAME --name default --config-file ./default.json
   

Se você já tiver um cluster AKS existente gerenciado pelo Terraform, poderá atualizar a configuração da janela de manutenção modificando o arquivo de configuração do Terraform e aplicando as alterações usando o terraform apply comando.

Inicializar Terraform

Inicialize o Terraform no diretório que contém o main.tf arquivo usando o terraform init comando. Esse comando baixa o provedor de Azure necessário para gerenciar Azure recursos com o Terraform.

terraform init

Criar um plano de execução do Terraform

Crie um plano de execução do Terraform usando o comando terraform plan. Este comando mostra os recursos que o Terraform criará ou modificará em sua assinatura Azure.

terraform plan

Aplicar a configuração do Terraform

Depois de examinar e confirmar o plano de execução, aplique a configuração do Terraform usando o terraform apply comando. Esse comando cria ou modifica os recursos definidos em seu arquivo main.tf em sua assinatura Azure.

terraform apply

Exclua uma janela de configuração de manutenção no cluster do AKS usando o az aks maintenanceconfiguration delete comando.

O exemplo a seguir exclui a configuração de manutenção autoUpgradeSchedule:

az aks maintenanceconfiguration delete --resource-group $RESOURCE_GROUP --cluster-name $CLUSTER_NAME --name autoUpgradeSchedule

1. No portal Azure, navegue até o recurso de cluster do AKS.

2. No menu de serviço, em Configurações, selecione Configuração de cluster.

3. Em Atualizar>Agendador de atualização automático, selecione Editar agendamento.

   

4. No painel Editar agendamento de manutenção, selecione Remover agendamento.

   

Exclua uma janela de configuração de manutenção no cluster do AKS usando o az aks maintenanceconfiguration delete comando.

O exemplo a seguir exclui a configuração de manutenção autoUpgradeSchedule:

az aks maintenanceconfiguration delete --resource-group $RESOURCE_GROUP --cluster-name $CLUSTER_NAME --name autoUpgradeSchedule

Para excluir uma configuração de manutenção, remova o bloco correspondente da configuração do Terraform e aplique as alterações usando o terraform apply comando.