Windows no Kubernetes

O Kubernetes oferece suporte a nós que executam Microsoft Windows.

O Kubernetes oferece suporte a nós de trabalho que executam Linux ou Microsoft Windows.

🛇 Este item aponta para um projeto ou produto de terceiros que não é parte do Kubernetes. Mais informações

A CNCF e sua mantenedora, a Linux Foundation, adotam uma abordagem neutra a fornecedores em relação à compatibilidade. É possível adicionar seu servidor Windows como um nó de trabalho em um cluster Kubernetes.

Você pode instalar e configurar o kubectl no Windows, independentemente do sistema operacional que você usa em seu cluster.

Se você estiver usando nós Windows, pode ler:

Ou, para uma visão geral, leia:

1 - Contêineres Windows no Kubernetes

Aplicativos Windows constituem uma grande parte dos serviços e aplicações que rodam em muitas organizações. Contêineres Windows fornecem uma maneira de encapsular processos e empacotar dependências, facilitando o uso de práticas DevOps e seguindo padrões nativos da nuvem para aplicativos Windows.

Organizações com investimentos em aplicativos baseados em Windows e Linux não precisam procurar orquestradores separados para gerenciar suas cargas de trabalho, levando a eficiências operacionais aumentadas em suas implantações, independentemente do sistema operacional.

Nós Windows no Kubernetes

Para habilitar a orquestração de contêineres Windows no Kubernetes, inclua nós Windows em seu cluster Linux existente. A alocação de contêineres Windows em Pods no Kubernetes é similar à alocação de contêineres baseados em Linux.

Para executar contêineres Windows, seu cluster Kubernetes deve incluir múltiplos sistemas operacionais. Embora você possa executar a camada de gerenciamento apenas no Linux, você pode implantar nós de trabalho executando Windows ou Linux.

Nós Windows são suportados desde que o sistema operacional seja Windows Server 2022 ou Windows Server 2025.

Este documento usa o termo contêineres Windows para se referir a contêineres Windows com isolamento de processo. O Kubernetes não suporta a execução de contêineres Windows com isolamento Hyper-V.

Compatibilidade e limitações

Alguns recursos do nó estão disponíveis apenas se você usar um agente de execução de contêiner específico; outros não estão disponíveis em nós Windows, incluindo:

Nem todos os recursos de namespaces compartilhados são suportados. Veja Compatibilidade da API para mais detalhes.

Veja Compatibilidade de versão do sistema operacional Windows para detalhes sobre as versões do Windows nas quais o Kubernetes é testado.

Do ponto de vista da API e do kubectl, contêineres Windows se comportam de maneira muito semelhante aos contêineres baseados em Linux. No entanto, há algumas diferenças notáveis em funcionalidades-chave que são destacadas nesta seção.

Comparação com Linux

Elementos-chave do Kubernetes funcionam da mesma forma no Windows como no Linux. Esta seção refere-se a várias abstrações de carga de trabalho e como elas se mapeiam para o Windows.

Pods, recursos de carga de trabalho e Services são elementos críticos para gerenciar cargas de trabalho Windows no Kubernetes. No entanto, por si só, eles não são suficientes para habilitar o gerenciamento adequado do ciclo de vida de cargas de trabalho Windows em um ambiente nativo da nuvem dinâmico.

Opções de linha de comando para o kubelet

Algumas opções de linha de comando do kubelet se comportam de maneira diferente no Windows, conforme descrito abaixo:

Compatibilidade da API

Existem diferenças sutis na forma como as APIs do Kubernetes funcionam para o Windows devido ao SO e ao agente de execução de contêiner. Algumas propriedades de carga de trabalho foram projetadas para Linux e falham ao rodar no Windows.

Em um nível alto, esses conceitos de SO são diferentes:

Códigos de saída de Contêiner seguem a mesma convenção onde 0 é sucesso e diferente de zero é falha. Os códigos de erro específicos podem diferir entre Windows e Linux. No entanto, códigos de saída passados dos componentes do Kubernetes (kubelet, kube-proxy) são inalterados.

Compatibilidade de campos para especificações de Contêiner

A lista a seguir documenta as diferenças entre como as especificações de Contêiner do Pod funcionam entre Windows e Linux:

Compatibilidade de campos para especificações de Pod

A lista a seguir documenta as diferenças entre como as especificações de Pod funcionam entre Windows e Linux:

Compatibilidade de campos para hostNetwork

ESTADO DA FUNCIONALIDADE: Kubernetes v1.26 [alpha]

O kubelet agora pode solicitar que pods em execução em nós Windows usem o namespace de rede do host em vez de criar um novo namespace de rede de pod. Para habilitar essa funcionalidade, passe --feature-gates=WindowsHostNetwork=true para o kubelet.

Nota:

Esta funcionalidade requer um agente de execução de contêiner que suporte essa funcionalidade.

Compatibilidade de campos para o contexto de segurança do Pod

Apenas securityContext.runAsNonRoot e securityContext.windowsOptions dos campos securityContext do Pod funcionam no Windows.

Detector de problemas do nó

O detector de problemas do nó (veja Monitorando a integridade do nó) tem suporte preliminar para Windows. Para mais informações, visite a página do GitHub do projeto.

Contêiner de pausa

Em um Pod Kubernetes, um Contêiner de infraestrutura ou "pausa" é criado primeiro para hospedar o Contêiner. No Linux, os cgroups e namespaces que compõem um pod precisam de um processo para manter sua existência contínua; o processo de pausa fornece isso. Contêineres que pertencem ao mesmo pod, incluindo infraestrutura e contêineres de trabalho, compartilham um endpoint de rede comum (mesmo endereço IPv4 e/ou IPv6, mesmos espaços de porta de rede). O Kubernetes usa contêineres de pausa para permitir que contêineres de trabalho falhem ou reiniciem sem perder qualquer configuração de rede. O detector de problemas do nó (veja Monitorando a integridade do nó) tem suporte preliminar para Windows. Para mais informações, visite a página do GitHub do projeto. O Kubernetes mantém uma imagem multi-arquitetura que inclui suporte para Windows. Para o Kubernetes v1.35.0 a imagem de pausa recomendada é registry.k8s.io/pause:3.6. O código fonte está disponível no GitHub.

A Microsoft mantém uma imagem multi-arquitetura diferente, com suporte para Windows amd64 e Linux, que você pode encontrar como mcr.microsoft.com/oss/kubernetes/pause:3.6. Esta imagem é construída a partir do mesmo código fonte que a imagem mantida pelo Kubernetes, mas todos os binários do Windows são assinados pelo Authenticode pela Microsoft. O projeto Kubernetes recomenda usar a imagem mantida pela Microsoft se você estiver implantando em um ambiente de produção ou similar que exija binários assinados.

Agente de Execução de Contêiner

Você precisa instalar um agente de execução de contêiner em cada nó do cluster para que os Pods possam ser executados lá.

Os seguintes runtimes de Contêiner funcionam com Windows:

Nota: Esta seção contém links para projetos de terceiros que fornecem a funcionalidade exigida pelo Kubernetes. Os autores do projeto Kubernetes não são responsáveis por esses projetos. Esta página obedece as diretrizes de conteúdo do site CNCF, listando os itens em ordem alfabética. Para adicionar um projeto a esta lista, leia o guia de conteúdo antes de enviar sua alteração.

ContainerD

ESTADO DA FUNCIONALIDADE: Kubernetes v1.20 [stable]

Você pode usar ContainerD 1.4.0+ como o agente de execução de contêiner para nós Kubernetes que executam Windows.

Aprenda como instalar o ContainerD em um nó Windows.

Nota:

Há uma limitação conhecida ao usar GMSA com containerd para acessar compartilhamentos de rede do Windows, o que requer um patch no kernel.

Mirantis Contêiner Runtime

Mirantis Container Runtime (MCR) está disponível como um agente de execução de contêiner para todas as versões do Windows Server 2019 e posteriores.

Veja Instalar MCR em servidores Windows para mais informações.

Compatibilidade de versão do sistema operacional Windows

Em nós Windows, aplicam-se regras estritas de compatibilidade onde a versão do SO do host deve corresponder à versão da imagem base do Contêiner. Apenas contêineres Windows com um sistema operacional de Contêiner do Windows Server 2019 são totalmente suportados.

Para o Kubernetes v1.35, a compatibilidade do sistema operacional para nós Windows (e Pods) é a seguinte:

Windows Server LTSC release

Windows Server 2022

Windows Server 2025

A política de desvio de versão do Kubernetes também se aplica.

Recomendações e considerações de hardware

Nota: Esta seção contém links para projetos de terceiros que fornecem a funcionalidade exigida pelo Kubernetes. Os autores do projeto Kubernetes não são responsáveis por esses projetos. Esta página obedece as diretrizes de conteúdo do site CNCF, listando os itens em ordem alfabética. Para adicionar um projeto a esta lista, leia o guia de conteúdo antes de enviar sua alteração.

Nota:

As especificações de hardware a seguir devem ser consideradas como valores padrão sensatos. Elas não se destinam a representar requisitos mínimos ou recomendações específicas para ambientes de produção. Dependendo dos requisitos para sua carga de trabalho, esses valores podem precisar ser ajustados.

Consulte Requisitos de hardware para o Windows Server na documentação da Microsoft para obter as informações mais atualizadas sobre requisitos mínimos de hardware. Para orientação sobre como decidir sobre recursos para nós de trabalho em produção, consulte Nós de trabalho em produção na documentação do Kubernetes.

Para otimizar os recursos do sistema, se uma interface gráfica de usuário não for necessária, pode ser preferível usar uma instalação do Windows Server que exclua a opção de instalação Windows Desktop Experience, já que esta configuração normalmente libera mais recursos do sistema.

Ao avaliar o espaço em disco para nós de trabalho Windows, observe que as imagens de Contêiner do Windows são tipicamente maiores que as imagens de Contêiner do Linux, com tamanhos de imagem de Contêiner variando de 300MB a mais de 10GB para uma única imagem. Além disso, observe que a unidade C: em contêineres Windows representa um tamanho virtual livre de 20GB por padrão, que não é o espaço consumido real, mas sim o tamanho do disco para o qual um único Contêiner pode crescer ao ocupar quando usa armazenamento local no host. Veja Contêineres no Windows - Documentação de Armazenamento de Contêiner para mais detalhes.

Obtendo ajuda e solucionando problemas

Sua principal fonte de ajuda para solucionar problemas em seu cluster Kubernetes deve começar com a página de Solução de Problemas.

Alguma ajuda adicional, específica para Windows, está incluída nesta seção. Logs são um elemento importante na solução de problemas no Kubernetes. Certifique-se de incluí-los sempre que buscar assistência de outros colaboradores. Siga as instruções no guia de contribuição do SIG Windows sobre coleta de logs.

Relatando problemas e solicitações de funcionalidades

Se você tiver algo que pareça um bug ou gostaria de fazer uma solicitação de recurso, siga o guia de contribuição do SIG Windows para criar uma nova issue. Você deve primeiro pesquisar na lista de issues existentes caso tenha sido relatado anteriormente e comentar com sua experiência na issue e adicionar logs adicionais. O canal SIG Windows no Slack do Kubernetes também é uma ótima maneira de obter suporte inicial e ideias de solução de problemas antes de criar um ticket.

Validando a operabilidade do cluster Windows

O projeto Kubernetes fornece uma especificação de Windows Operational Readiness, acompanhada por um conjunto de testes estruturados. Este conjunto é dividido em dois conjuntos de testes, principal (core) e estendido (extended), cada um contendo categorias destinadas a testar áreas específicas. Pode ser usado para validar todas as funcionalidades de um sistema Windows e híbrido (misturado com nós Linux) com cobertura total.

Para configurar o projeto em um cluster recém-criado, consulte as instruções no guia do projeto.

Ferramentas de implantação

A ferramenta kubeadm ajuda você a implantar um cluster Kubernetes, fornecendo a camada de gerenciamento para gerenciá-lo, e nós para executar suas cargas de trabalho.

O projeto cluster API do Kubernetes também fornece meios para automatizar a implantação de nós Windows.

Canais de distribuição do Windows

Para uma explicação detalhada dos canais de distribuição do Windows, consulte a documentação da Microsoft.

Informações sobre os diferentes canais de serviço do Windows Server, incluindo seus modelos de suporte, podem ser encontradas em Canais de serviço do Windows Server.

2 - Guia para Executar Contêineres Windows no Kubernetes

Esta página fornece um passo a passo para executar contêineres Windows usando o Kubernetes. Esta página também destaca funcionalidades específicas do Windows dentro do Kubernetes.

É importante notar que criar e implantar serviços e cargas de trabalho no Kubernetes comporta-se de forma muito semelhante para contêineres Linux e Windows. Os comandos kubectl para interagir com o cluster são idênticos. Os exemplos nesta página são fornecidos para iniciar sua experiência com contêineres Windows.

Objetivos

Configurar um exemplo de implantação para executar contêineres Windows em um nó Windows.

Antes de você começar

Você deve ter acesso a um cluster Kubernetes que inclua um nó de trabalho executando Windows Server.

Começando: Implantando uma Carga de Trabalho Windows

O exemplo de arquivo YAML abaixo implanta um aplicativo simples de servidor web executando dentro de um contêiner Windows.

Crie um manifesto chamado win-webserver.yaml com o conteúdo abaixo:

---
apiVersion: v1
kind: Service
metadata:
  name: win-webserver
  labels:
    app: win-webserver
spec:
  ports:
    # a porta em que este serviço deve rodar
    - port: 80
      targetPort: 80
  selector:
    app: win-webserver
  type: NodePort
---
apiVersion: apps/v1
kind: Deployment
metadata:
  labels:
    app: win-webserver
  name: win-webserver
spec:
  replicas: 2
  selector:
    matchLabels:
      app: win-webserver
  template:
    metadata:
      labels:
        app: win-webserver
      name: win-webserver
    spec:
     containers:
      - name: windowswebserver
        image: mcr.microsoft.com/windows/servercore:ltsc2019
        command:
        - powershell.exe
        - -command
        - "<# código retirado de https://gist.github.com/19WAS85/5424431# > ; $$listener = New-Object System.Net.HttpListener ; $$listener.Prefixes.Add('http://*:80/') ; $$listener.Start() ; $$callerCounts = @{} ; Write-Host('Listening at http://*:80/') ; while ($$listener.IsListening) { ;$$context = $$listener.GetContext() ;$$requestUrl = $$context.Request.Url ;$$clientIP = $$context.Request.RemoteEndPoint.Address ;$$response = $$context.Response ;Write-Host '' ;Write-Host('> {0}' -f $$requestUrl) ;  ;$$count = 1 ;$$k=$$callerCounts.Get_Item($$clientIP) ;if ($$k -ne $$null) { $$count += $$k } ;$$callerCounts.Set_Item($$clientIP, $$count) ;$$ip=(Get-NetAdapter | Get-NetIpAddress); $$header='<html><body><H1>Windows Container Web Server</H1>' ;$$callerCountsString='' ;$$callerCounts.Keys | % { $$callerCountsString+='<p>IP {0} callerCount {1} ' -f $$ip[1].IPAddress,$$callerCounts.Item($$_) } ;$$footer='</body></html>' ;$$content='{0}{1}{2}' -f $$header,$$callerCountsString,$$footer ;Write-Output $$content ;$$buffer = [System.Text.Encoding]::UTF8.GetBytes($$content) ;$$response.ContentLength64 = $$buffer.Length ;$$response.OutputStream.Write($$buffer, 0, $$buffer.Length) ;$$response.Close() ;$$responseStatus = $$response.StatusCode ;Write-Host('< {0}' -f $$responseStatus)  } ; "
     nodeSelector:
      kubernetes.io/os: windows

Nota:

Mapeamento de portas também é suportado, mas para simplicidade este exemplo expõe a porta 80 do contêiner diretamente para o Service.

  1. Verifique se todos os nós estão íntegros:

    kubectl get nodes

  2. Implante o serviço e monitore as atualizações do pod:

    kubectl apply -f win-webserver.yaml
kubectl get pods -o wide -w

    Quando o serviço for implantado corretamente, ambos os Pods serão marcados como prontos. Para sair do comando de monitoramento, pressione Ctrl+C.

  3. Verifique se a implantação foi bem-sucedida. Para verificar:

Nota:

Os hosts de contêiner Windows não conseguem acessar o IP de serviços alocados neles devido a limitações da pilha de rede do Windows. Apenas pods Windows conseguem acessar IPs de serviço.

Observabilidade

Capturando logs de cargas de trabalho

Os logs são um elemento importante da observabilidade; eles permitem que os usuários obtenham insights sobre o aspecto operacional das cargas de trabalho e são um componente essencial na solução de problemas. Como os contêineres Windows e as cargas de trabalho dentro de contêineres Windows se comportam de maneira diferente dos contêineres Linux, os usuários enfrentaram dificuldades na coleta de logs, limitando a visibilidade operacional. As cargas de trabalho Windows, por exemplo, geralmente são configuradas para registrar logs no ETW (Event Tracing for Windows) ou enviar entradas para o log de eventos de aplicativos. O LogMonitor, uma ferramenta de código aberto da Microsoft, é a maneira recomendada para monitorar as fontes de logs configuradas dentro de um contêiner Windows. O LogMonitor oferece suporte para monitorar logs de eventos, provedores ETW e logs personalizados de aplicativos, canalizando-os para o STDOUT para consumo pelo comando kubectl logs <pod>.

Siga as instruções na página do GitHub do LogMonitor para copiar seus binários e arquivos de configuração para todos os seus contêineres e adicionar os entrypoints necessários para que o LogMonitor envie seus logs para o STDOUT.

Configurando usuários de contêiner

Usando nomes de usuário configuráveis para Contêineres

Contêineres Windows podem ser configurados para executar seus entrypoints e processos com nomes de usuário diferentes dos padrões da imagem. Saiba mais sobre isso aqui.

Gerenciando Identidade de Carga de Trabalho com Contas de Serviço Gerenciadas por Grupo

As cargas de trabalho em contêineres Windows podem ser configuradas para usar Contas de Serviço Gerenciadas por Grupo (GMSA). As GMSAs são um tipo específico de conta do Active Directory que fornece gerenciamento automático de senhas, gerenciamento simplificado de nomes principais de serviço (SPN) e a capacidade de delegar o gerenciamento a outros administradores em vários servidores. Contêineres configurados com uma GMSA podem acessar recursos de domínio do Active Directory externo enquanto mantêm a identidade configurada com a GMSA. Saiba mais sobre como configurar e usar GMSA para contêineres Windows aqui.

Taints e tolerations

Os usuários precisam usar uma combinação de taint e selectors de nós para agendar cargas de trabalho Linux e Windows em seus respectivos nós específicos de sistema operacional. A abordagem recomendada está descrita abaixo, com o objetivo principal de não quebrar a compatibilidade com cargas de trabalho Linux existentes.

Você pode (e deve) definir .spec.os.name para cada Pod, para indicar o sistema operacional para o qual os contêineres nesse Pod foram projetados. Para Pods que executam contêineres Linux, defina .spec.os.name como linux. Para Pods que executam contêineres Windows, defina .spec.os.name como windows.

Nota:

Se você estiver executando uma versão do Kubernetes anterior à 1.24, pode ser necessário habilitar o feature gate IdentifyPodOS para definir um valor para .spec.pod.os.

O escalonador não utiliza o valor de .spec.os.name ao atribuir Pods a nós. Você deve usar os mecanismos normais do Kubernetes para atribuir Pods a nós para garantir que a camada de gerenciamento do seu cluster coloque os Pods em nós que estão executando o sistema operacional apropriado.

O valor de .spec.os.name não tem efeito na alocação dos Pods Windows, então taints e tolerations (ou selectors de nós) ainda são necessários para garantir que os Pods Windows sejam atribuídos aos nós Windows apropriados.

Garantindo que cargas de trabalho específicas de SO sejam atribuídas ao host de contêiner apropriado

Os usuários podem garantir que contêineres Windows sejam agendados no host apropriado usando taints e tolerations. Todos os nós Kubernetes que executam o Kubernetes 1.35 têm os seguintes rótulos padrão:

Se uma especificação de Pod não especificar um nodeSelector, como "kubernetes.io/os": windows, é possível que o Pod seja agendado em qualquer host, Windows ou Linux. Isso pode ser problemático, já que um contêiner Windows só pode ser executado em Windows e um contêiner Linux só pode ser executado em Linux. A prática recomendada para o Kubernetes 1.35 é usar um nodeSelector.

No entanto, em muitos casos, os usuários têm um grande número de implantações existentes para contêineres Linux, bem como um ecossistema de configurações prontas para uso, como chart do Helm da comunidade e casos de geração programática de Pods, como com operadores. Nessas situações, você pode hesitar em fazer a alteração de configuração para adicionar campos nodeSelector a todos os Pods e modelos de Pod. A alternativa é usar taints. Como o kubelet pode definir taints durante o registro, ele pode ser facilmente modificado para adicionar automaticamente um taint ao executar apenas em Windows.

Por exemplo: --register-with-taints='os=windows:NoSchedule'

Ao adicionar um taint a todos os nós Windows, nada será agendado neles (isso inclui Pods Linux existentes). Para que um Pod Windows seja alocação em um nó Windows, ele precisará tanto do nodeSelector quanto da toleration correspondente para escolher Windows.

nodeSelector:
    kubernetes.io/os: windows
    node.kubernetes.io/windows-build: '10.0.20348'
tolerations:
    - key: "os"
      operator: "Equal"
      value: "windows"
      effect: "NoSchedule"

Lidando com várias versões do Windows no mesmo cluster

A versão do Windows Server usada por cada Pod deve corresponder à do nó. Se você quiser usar várias versões do Windows Server no mesmo cluster, deverá definir rótulos adicionais de nó e campos nodeSelector.

O Kubernetes adiciona automaticamente um rótulo, node.kubernetes.io/windows-build, para simplificar isso.

Este rótulo reflete o número principal, secundário e de build do Windows que precisam corresponder para compatibilidade. Aqui estão os valores usados para cada versão do Windows Server:

Nome do Produto Versão
Windows Server 2022 10.0.20348
Windows Server 2025 10.0.26100

Simplificando com RuntimeClass

RuntimeClass pode ser usado para simplificar o processo de usar taints e tolerations. Um administrador de cluster pode criar um objeto RuntimeClass, que é usado para encapsular esses taints e tolerations.

  1. Salve este arquivo como runtimeClasses.yml. Ele inclui o nodeSelector apropriado para o SO, arquitetura e versão do Windows.

    ---
apiVersion: node.k8s.io/v1
kind: RuntimeClass
metadata:
  name: windows-2019
handler: example-container-runtime-handler
scheduling:
  nodeSelector:
    kubernetes.io/os: 'windows'
    kubernetes.io/arch: 'amd64'
    node.kubernetes.io/windows-build: '10.0.20348'
  tolerations:
  - effect: NoSchedule
    key: os
    operator: Equal
    value: "windows"

  2. Execute kubectl create -f runtimeClasses.yml como administrador do cluster.

  3. Adicione runtimeClassName: windows-2019 conforme apropriado às especificações de Pods.

    Por exemplo:

    ---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: iis-2019
  labels:
    app: iis-2019
spec:
  replicas: 1
  template:
    metadata:
      name: iis-2019
      labels:
        app: iis-2019
    spec:
      runtimeClassName: windows-2019
      containers:
      - name: iis
        image: mcr.microsoft.com/windows/servercore/iis:windowsservercore-ltsc2019
        resources:
          limits:
            cpu: 1
            memory: 800Mi
          requests:
            cpu: .1
            memory: 300Mi
        ports:
          - containerPort: 80
 selector:
    matchLabels:
      app: iis-2019
---
apiVersion: v1
kind: Service
metadata:
  name: iis
spec:
  type: LoadBalancer
  ports:
  - protocol: TCP
    port: 80
  selector:
    app: iis-2019