Kueue Who Preempted: identifique a carga que preemptou um Workload

ANÁLISE EDITORIAL

Um Job desaparece da execução e a primeira suspeita é falta de recurso. Em um cluster que usa Kueue, pode ter ocorrido preempção: uma carga admitida perdeu a vaga para outra, segundo as políticas da fila. A Skill kueue-who-preempted, mantida no repositório do projeto, orienta a localizar a carga preemptora com eventos e condições do Workload, sem confundir hipótese com prova. O download desta página é apenas um roteiro documental. Ele não se conecta a cluster nem instala Kueue.

O que a Skill faz

O SKILL.md original traz um procedimento de investigação, não um detector autônomo. Primeiro procura o evento Preempted ligado ao Workload afetado. Se esse evento não estiver disponível, consulta a mensagem da condição Evicted no estado do Workload. Em seguida extrai o identificador do Workload preemptor e, quando houver, o identificador do Job que o originou. A etapa final procura essa carga e relata o motivo e os caminhos das filas. A documentação de preempção do Kueue confirma que a condição de estado registra a expulsão e o motivo.

Isso responde a uma pergunta muito mais precisa do que “por que o Pod reiniciou?”. A Skill investiga preempção registrada pelo Kueue para um objeto Workload gerenciado por ele. Ela não demonstra que uma queda de nó, um limite de memória, uma alteração manual ou a preempção do scheduler nativo do Kubernetes foram causados por outra carga do Kueue. Antes de aplicá-la, confirme que o objeto afetado existe no Kueue e que a condição realmente indica Preempted. O quickstart oficial mostra como Jobs gerenciados originam Workloads.

Para quem serve e quando não usar

É útil para operadores de plataforma, SREs e responsáveis por filas de jobs que precisam explicar uma interrupção concreta a outra equipe. Um caso típico é uma carga de processamento que foi admitida, saiu da execução e aparece como preemptada. O roteiro ajuda a identificar o Workload beneficiado, sua fila e a relação com o Job original. Esse encadeamento dá base para revisar prioridade, cota e política de preempção com os responsáveis, em vez de alterar a fila às cegas.

Não serve como mecanismo de prevenção, medição de desempenho ou autorização para modificar ClusterQueue. Também não oferece uma resposta completa quando os eventos expiraram, o objeto foi removido e os logs já não estão retidos. Se não há evidência de Preempted, trate como outro incidente. A definição de LocalQueue ajuda a entender por que times em namespaces diferentes podem compartilhar a mesma ClusterQueue, ponto decisivo para não encerrar a busca no namespace da carga afetada.

Compatibilidade e pré-requisitos

O arquivo segue o formato SKILL.md e pode ser lido como instrução por um agente que aceite Skills em Markdown. O índice mantido pelo projeto o descreve como roteiro para perguntas sobre quem preemptou uma carga. Ele fica em uma árvore chamada experimental; isso pede comparação com a versão efetivamente instalada antes de usar comandos ou supor estabilidade de formato. O repositório ressalta que esses arquivos são guias Markdown, não plugins próprios do Claude Code. Instalar o texto no seu cliente não instala uma extensão de Kubernetes nem garante execução automática. Consulte a convenção de Skills do agente escolhido antes de copiar.

Para investigar um caso real, tenha kubectl conectado ao cluster certo, Kueue presente, o nome e namespace do Workload vítima e permissão de leitura adequada. Recomenda-se verificar contexto e identidade ativos antes de consultar dados. A Skill usa kubectl get events, kubectl get kueueworkload e kubectl auth can-i; uma rota de busca por UID também usa jq. O pacote local não traz esses programas, acesso ao cluster, credenciais nem exemplos de dados reais. A documentação de kubectl auth can-i explica como confirmar o alcance da identidade atual.

Instalação e configuração

Baixe o ZIP documental do Bastidores e compare o SHA-256 indicado abaixo. Abra o arquivo, leia ORIGEM.md e a licença, depois extraia SKILL.md para uma pasta chamada kueue-who-preempted no diretório de Skills suportado pelo seu agente. A localização exata depende do produto. Em clientes que não descobrem Skills dinamicamente, inicie uma nova sessão e peça que o agente confirme o nome e o conteúdo da Skill antes de qualquer consulta. Como alternativa, aponte o agente diretamente para o arquivo do commit auditado no repositório oficial.

Não copie kubeconfig, tokens ou respostas de eventos para a pasta da Skill. Configure o acesso a Kubernetes pelos procedimentos de sua organização e prefira uma identidade de leitura. Antes de iniciar, confira o contexto de kubectl, o namespace informado e a política de retenção de eventos. O roteiro não pede alteração de filas. Uma consulta em produção ainda pode expor nomes de Jobs, namespaces e prioridades no terminal ou no histórico do agente; escolha onde a saída pode ser armazenada.

Primeiro uso e resultado esperado

Comece com uma pergunta delimitada: “Investigue por que o Workload nome no namespace equipe foi marcado como preemptado; faça apenas leituras, informe os comandos antes de executá-los e não altere recursos”. O agente deve verificar a existência do Workload, consultar os eventos filtrados por nome e motivo e, se nada aparecer, ler a condição Evicted. A Skill ensina a extrair UID, JobUID, motivo e caminhos de ClusterQueue da mensagem, quando esses campos estiverem presentes. Esses valores são evidência a conferir, não dados que possam ser preenchidos por suposição.

Antes da busca em todos os namespaces, execute a checagem de autorização documentada: kubectl auth can-i list kueueworkloads --all-namespaces. Se o resultado permitir a leitura global e houver JobUID, o roteiro usa o seletor kueue.x-k8s.io/job-uid. Se o identificador do Job vier como UNKNOWN, ele orienta comparar o UID do Workload. Com acesso apenas a alguns namespaces, a investigação fica limitada a eles. Se o preemptor não aparecer, a resposta correta é “não localizei com estas permissões” e a solicitação de uma verificação por administrador, não a invenção de um nome. A referência de kubectl get permite conferir os filtros e formatos de saída.

O relatório esperado inclui namespace e nome do Workload preemptor, o Job pai quando a referência de propriedade existir, o motivo de preempção e os caminhos das filas envolvidas. Separe o que veio do evento ou condição do que foi encontrado em busca posterior. Se o Job pai já tiver sido excluído, apresente o UID recuperado e declare a limitação. Não concluímos um teste funcional em cluster nesta curadoria; o resultado descrito é o fluxo esperado das instruções oficiais, não uma execução verificada pelo Bastidores.

Permissões, privacidade e riscos

A consulta global pode exigir permissão de list em todos os namespaces. Ela não filtra automaticamente apenas os namespaces que a pessoa pode ver; se a identidade não tiver o direito necessário, pode receber Forbidden. A Skill oferece um caminho por namespace para acesso limitado e pede escalonamento quando o Workload preemptor está fora do alcance. Não amplie RBAC apenas para satisfazer uma pergunta pontual sem aprovação do responsável. A referência oficial de RBAC descreve o efeito dos verbos e escopos.

Eventos e condições podem conter nomes, UIDs, prioridades e estrutura de filas que revelam atividades internas. Evite colar saída integral em serviços externos ou tickets públicos. Remova dados sensíveis antes de compartilhar um relatório e mantenha a relação entre vítima e preemptor verificável por IDs. A documentação de políticas de preempção deixa claro que configuração de ClusterQueue e mecanismos de cota afetam quem pode expulsar quem. Alterar esses parâmetros com base em um único evento seria uma decisão operacional separada, sujeita a revisão e rollback.

Erros comuns e limites

O erro mais comum é procurar só no namespace da vítima. LocalQueues de namespaces diferentes podem apontar à mesma ClusterQueue, portanto o preemptor pode estar em outra área. Outro erro é tomar a ausência de evento como prova de que não houve preempção. Eventos têm retenção limitada; a Skill sugere a condição Evicted como segunda fonte e logs do controlador como último recurso, se a equipe tiver acesso e retenção apropriados. O comando oficial de eventos ajuda a distinguir o objeto e o recorte consultado.

Uma condição ausente ou com motivo diferente pede reavaliar a hipótese. Um Forbidden pede revisar RBAC e o escopo aprovado, não trocar silenciosamente de identidade. Um seletor por JobUID sem retorno pode indicar que o Job não está mais presente, que a carga foi criada sem pai ou que o preemptor está em namespace inacessível. Também há diferenças entre versões do Kueue e retenções configuradas pela operação. Antes de usar o roteiro em versão posterior ao commit fixado, compare a mensagem atual do controlador com as instruções e a página de release do projeto; esta página não promete compatibilidade testada em todas as versões.

Versão, licença e download local

A cópia foi fixada no commit a5d02a6c2da3dc7eb8a533486c8ff70c09d6408d, consultado em 15 de outubro de 2026. O repositório kubernetes-sigs/kueue tinha 3.064 estrelas nessa consulta, número de interesse editorial, não prova de segurança ou eficácia. O release do Kueue v0.20.2 foi verificado, mas o pacote desta página é identificado pelo commit, não como arquivo de release da Skill. O cabeçalho do SKILL.md declara Apache-2.0, compatível com o arquivo de licença do repositório. A licença permite redistribuição sob suas condições; por isso a cópia inclui o texto integral.

O download hospedado pelo Bastidores contém somente SKILL.md, LICENSE e ORIGEM.md. Não contém kubectl, jq, scripts executáveis, manifestos de instalação, dependências, credenciais ou dados de cluster. SHA-256 do ZIP: a066258cbec6f70c00d95cbc9654dd48f2d1b573b4f193a9b49c512934b33297. Compare esse valor após baixar e consulte a origem se precisar de uma versão mais nova. A cópia auditada ajuda a reproduzir as instruções; não substitui revisão de permissões nem teste no seu ambiente.

Fontes primárias

Leituras principais: Skill no commit auditado, índice oficial de Skills, conceitos de preempção, LocalQueue, permissões do kubectl e licença original. O botão de repositório oficial é separado do download local e abre a fonte viva, que pode mudar após este commit.