DOCA Version: confira host, runtime e BlueField antes de mudar

ANÁLISE EDITORIAL

Quando um programa DOCA compila, mas falha em tempo de execução, o problema pode não estar no código. Biblioteca de desenvolvimento, runtime, utilitários e firmware podem estar em versões diferentes. A DOCA Version transforma essa suspeita em uma verificação ordenada, com comandos explícitos, critérios de parada e uma regra importante: não afirmar uma versão que a máquina não mostrou.

Esta Skill vem do repositório oficial NVIDIA-DOCA/doca-skills. Ela entra no catálogo como exceção oficial: o repositório tinha 5 estrelas na consulta de 19 de setembro de 2026, abaixo do critério normal de 1.000. A escolha se apoia na manutenção pelo fornecedor, na documentação, no commit fixado e na licença verificável, não em popularidade.

O que esta Skill faz

A Skill orienta um agente a detectar a versão real do NVIDIA DOCA e a comparar quatro fontes que deveriam contar a mesma história: pkg-config --modversion doca-common, o arquivo /opt/mellanox/doca/applications/VERSION, doca_caps --version e, em hosts com BlueField, bfver junto de /etc/mlnx-release. O objetivo é localizar instalações parciais, mistura entre artefatos de build e runtime, divergência entre host e BFB e uso impreciso de tags de container.

Ela também organiza perguntas sobre uma API existir em determinada versão, sobre uma imagem NGC corresponder ao host e sobre a origem apt apontar para um canal diferente do pacote instalado. Não é um instalador, não escolhe pacotes e não substitui a documentação atual do DOCA SDK.

Para quem serve

É útil para equipes que desenvolvem ou operam soluções com BlueField, ConnectX e bibliotecas DOCA em Linux. Engenheiros de plataforma podem usá-la antes de atualizar um nó. Desenvolvedores podem acioná-la quando símbolos existem na documentação, mas faltam no linker ou no runtime. Suporte e SRE podem utilizá-la para separar uma falha de aplicação de uma instalação incoerente.

Ela é mais valiosa quando já há acesso legítimo ao host e a pergunta é “o que realmente está instalado?”. Para uma introdução geral ao formato, consulte o catálogo de Skills do Bastidores da IA. Para inspecionar outra Skill antes de adotá-la, a página do NVIDIA Skill Inspector cobre um problema diferente.

Origem, adoção e versão

A origem auditada é a pasta skills/doca-version no commit ccb97a286aac20d365f1631bdd720776abcc3196. O repositório se identifica como conjunto oficial de Skills para DOCA 3.3 e referencia a linha doca-3.3.0109. Isso descreve o escopo do material, não prova a versão de qualquer servidor.

A baixa contagem de estrelas precisa permanecer visível. “Oficial” indica procedência e responsabilidade do mantenedor, não adoção ampla, qualidade perfeita ou suporte comercial. O commit auditado fixa exatamente os bytes revisados.

Compatibilidade

O texto pode ser lido por agentes que suportem Skills em Markdown. Para executar as verificações, é preciso um Linux com DOCA instalado em /opt/mellanox/doca. A etapa de BFB só faz sentido quando há BlueField e acesso ao ambiente correspondente. Em um host comum, a ausência de bfver não deve ser apresentada como falha de firmware.

A compatibilidade entre host, DPU, driver e release precisa ser confirmada na política oficial de compatibilidade e nas notas da versão realmente usada. A Skill orienta a coleta, mas não transforma quatro strings iguais em certificação de toda a solução.

Pré-requisitos

• Acesso autorizado ao host Linux e, quando aplicável, ao BlueField.
• Um terminal capaz de executar comandos somente leitura.
• Registro do objetivo da inspeção e do ambiente afetado.
• Saída integral dos comandos, sem recortar sufixos de build.
• Documentação da release e janela de mudança aprovada antes de instalar ou atualizar algo.

Não forneça tokens, chaves, sessões ou credenciais ao agente. Os comandos de detecção normalmente não precisam de privilégios administrativos. Se um arquivo não puder ser lido, registre a limitação em vez de contorná-la com alteração de permissão.

Instalação segura

O download local abaixo é um espelho documental auditado. Extraia-o em uma pasta de inspeção, leia ORIGEM.md, confira o SHA-256 e só depois copie a pasta doca-version para o diretório de Skills aceito pelo seu agente. O pacote não executa instalação do DOCA.

Baixar o pacote auditado doca-version.zip

Abrir o repositório oficial no commit auditado

Use um projeto ou perfil de teste. A instalação da Skill apenas disponibiliza instruções ao agente. Ela não concede acesso ao host, não instala SDK, não baixa firmware e não autoriza uma mudança.

Configuração antes da auditoria

Defina se a análise cobre host, container, BlueField ou os três. Registre hostname não sensível, distribuição, arquitetura, janela do teste e o sintoma observado. Combine um limite claro: nesta etapa, ler versões e arquivos, sem apt install, atualização de BFB, reinicialização ou alteração de repositório.

Em containers, registre a referência completa da imagem. A Skill alerta para não inventar tags e não tratar latest como versão. Confirme tags no catálogo NVIDIA NGC no momento do uso.

Primeiro uso

Peça ao agente para coletar, sem corrigir nada, as quatro fontes aplicáveis. A sequência base é:

pkg-config --modversion doca-common
cat /opt/mellanox/doca/applications/VERSION
doca_caps --version
bfver
cat /etc/mlnx-release

O quarto bloco se aplica ao BlueField. Preserve a saída e a mensagem de erro de cada comando. Se pkg-config não localizar doca-common, isso pode significar caminho de metadados ausente, pacote de desenvolvimento não instalado ou sessão fora do ambiente esperado. Não conclua automaticamente que DOCA não existe.

A cadeia de quatro fontes

pkg-config representa o que o build encontra. applications/VERSION descreve a árvore de aplicações instalada. doca_caps expõe a versão do utilitário no runtime. bfver e mlnx-release acrescentam a visão do BlueField. Cada fonte responde a uma pergunta diferente, por isso uma única saída não basta.

A regra da Skill é procurar coerência entre as fontes aplicáveis. Ela não manda esconder sufixos nem arredondar versões. Uma diferença pequena pode ser justamente a pista de um pacote parcialmente atualizado.

Leitura do build

Comece pela saída do pkg-config porque ela mostra os metadados que um processo de compilação tende a encontrar naquela sessão. Registre também se a variável PKG_CONFIG_PATH foi alterada, pois uma pasta adicionada manualmente pode fazer o compilador enxergar uma instalação diferente da padrão. Não mude o caminho durante a coleta. Se a equipe usa um script de ambiente, documente se ele foi carregado antes do comando.

Leitura das aplicações instaladas

O arquivo applications/VERSION fornece uma segunda visão, ligada à árvore de aplicações. Leia o arquivo no caminho real, preserve toda a linha e informe claramente quando ele não existir. Uma ausência pode indicar outro layout ou uma instalação incompleta, mas não autoriza escolher uma versão pela documentação aberta no navegador. A evidência local continua sendo necessária.

Leitura do runtime

doca_caps --version ajuda a verificar o utilitário disponível no runtime. Além da string, registre se o binário veio do caminho esperado. Em ambientes com múltiplas instalações, o primeiro executável encontrado pelo PATH pode não corresponder à biblioteca usada pela aplicação. A Skill direciona o raciocínio, mas a confirmação do caminho e das bibliotecas carregadas ainda depende de comandos e políticas do ambiente.

Leitura do BlueField

No ramo BlueField, bfver e /etc/mlnx-release devem ser tratados como evidências complementares. Não substitua esses comandos por nomes lembrados de outra versão e não execute regravação de firmware para “testar”. Se não houver DPU no escopo, marque essa perna como não aplicável. Se houver, identifique de forma controlada qual unidade foi consultada para não misturar saídas de equipamentos diferentes.

Como interpretar divergências

Se o build mostra uma versão e doca_caps outra, interrompa o diagnóstico da aplicação e investigue caminhos, pacotes e bibliotecas carregadas. Se o host e o BFB divergem, consulte a matriz suportada antes de recomendar upgrade ou downgrade. Se apenas um comando falta, primeiro confirme se ele pertence à forma de implantação em uso.

Uma correspondência completa reduz uma classe de erro, mas não prova que hardware, firmware, kernel, driver, permissões e configuração de rede estejam corretos. A documentação de release continua sendo a referência para limitações conhecidas.

Uma divergência também precisa ser colocada no tempo. Compare o horário dos comandos com a última manutenção e com a criação do container. Um shell antigo pode conservar variáveis de ambiente de uma instalação anterior. Um container em execução pode usar uma imagem diferente da especificação atualmente salva. Um nó pode ter recebido parte dos pacotes antes de uma falha. Essas são hipóteses para investigar, não conclusões automáticas.

Ao escrever o diagnóstico, use uma tabela com as colunas “fonte”, “comando ou arquivo”, “valor observado”, “aplicável” e “interpretação”. Marque a interpretação como hipótese até conferir a documentação e o inventário de pacotes. Evite a palavra “compatível” quando o que foi comprovado é apenas que duas strings são iguais.

Apt source e containers

A Skill inclui uma checagem da origem de pacotes. Um sistema pode executar uma versão estável enquanto o arquivo de repositório aponta para outro canal. Nessa situação, a próxima instalação pode introduzir deriva. O procedimento correto é comparar a origem configurada com a versão pretendida e parar antes de instalar.

Dentro de container, registre tanto a tag quanto o digest quando disponíveis. Não misture bibliotecas do host com as da imagem sem documentação explícita. O guia oficial de containers DOCA deve orientar o desenho real.

Antes de qualquer operação no gerenciador de pacotes, capture os arquivos de origem e a política de pinning conforme o procedimento aprovado pela equipe. Uma URL com a palavra latest não descreve de forma estável o conteúdo que será resolvido amanhã. Para mudanças repetíveis, prefira referências documentadas pela NVIDIA e registre o repositório exato aprovado. Se a origem e a intenção não coincidirem, pare. Ajustar a origem já é uma mudança de configuração e não pertence à coleta inicial.

Em orquestradores, a mesma disciplina vale para a imagem declarada no workload e a imagem efetivamente executada. Um manifesto pode ter sido alterado sem recriar o pod, ou uma política pode reescrever a referência. Reúna os dois estados com ferramentas autorizadas e não assuma que o arquivo no repositório representa sozinho o runtime.

Resultado esperado

O resultado não é uma frase genérica como “DOCA está atualizado”. É um relatório curto com cada fonte, saída observada, ambiente, horário, correspondência ou divergência, evidência ausente e próximo passo seguro. Quando houver incompatibilidade, o relatório deve separar fato observado de hipótese.

O melhor resultado pode ser interromper uma mudança até obter documentação e aprovação. A Skill favorece essa decisão quando os dados não sustentam uma correção.

Um relatório útil inclui ainda o comando exato que produziu cada valor e a indicação de qual saída foi sanitizada. Se um dado sensível for removido, sinalize a remoção para que o revisor não confunda o recorte com a resposta completa. Inclua um resumo de uma linha, seguido das evidências, das hipóteses e da decisão recomendada. Essa estrutura permite que outra pessoa repita a coleta sem depender da memória de quem investigou.

Quando todas as fontes coincidem, a próxima etapa é voltar ao sintoma original. Um erro de recurso não suportado ainda pode depender de capacidade específica do hardware ou de configuração. Uma referência indefinida ainda pode envolver flags, ordem de link ou biblioteca errada. A Skill reduz o espaço de busca, não substitui o diagnóstico da biblioteca correspondente.

Permissões e riscos

Os comandos propostos são de leitura, mas ainda podem revelar versões e topologia úteis a um atacante. Armazene o relatório no local adequado e remova nomes internos antes de compartilhar. Não publique inventário de infraestrutura, endereços, serial, configuração de rede ou saída que contenha segredo.

Atualização de pacote, alteração de apt source, troca de imagem, regravação de BFB e reinicialização ficam fora deste pacote. Essas ações exigem plano, backup, janela, rollback e responsável. Consulte também a política de segurança do repositório.

Também existe risco de disponibilidade. Uma recomendação apressada de upgrade pode afetar workloads que compartilham driver, DPU ou host. Mapeie dependências e proprietários antes de propor alteração. Se o ambiente for de produção, faça a reprodução em laboratório quando isso for possível. O agente pode ajudar a organizar evidências, mas a autorização e a decisão continuam humanas.

Erros comuns e como corrigir

Confiar apenas em pkg-config. Ele descreve o build, não todo o runtime. Colete as demais fontes.

Tratar comando ausente como versão zero. Registre “não disponível” e investigue pacote, caminho e forma de implantação.

Inventar uma tag NGC. Abra o catálogo oficial, fixe a referência real e preserve o digest quando possível.

Confundir igualdade com suporte. Compare a combinação na política e nas notas da release. O arquivo oficial de documentação ajuda quando a instalação não é a mais recente.

Corrigir durante a coleta. Primeiro produza o diagnóstico. Mudanças simultâneas apagam a evidência do estado inicial e aumentam o risco.

Versão, licença e pacote auditado

A auditoria fixou o commit ccb97a286aac20d365f1631bdd720776abcc3196. O arquivo de licença do repositório declara Apache-2.0 para código e CC-BY-4.0 para documentação, salvo indicação diferente em arquivo específico. Consulte o texto integral da licença.

SHA-256 do ZIP local: 09e3e410dd5724d86c0d667386808d4a07c04b57dc0eb2f017f38813e7e1e3cf. O pacote contém cinco arquivos: SKILL.md, CAPABILITIES.md, TASKS.md, LICENSE e ORIGEM.md.

Limites do pacote local

O espelho é estritamente documental. Não inclui binários, dependências, SDK, pacotes apt ou rpm, container NGC, imagem BFB, scripts, credenciais nem resultados coletados. Referências internas a outras Skills do repositório podem não existir no pacote reduzido. Nesse caso, consulte a fonte completa do SKILL.md.

Checklist antes de usar

• Confirmar que o acesso ao host e ao BlueField foi autorizado.
• Fixar commit, tag e digest usados na análise.
• Executar apenas a cadeia de leitura na primeira passagem.
• Preservar saídas completas e marcar dados indisponíveis.
• Comparar host, runtime, ferramentas e BFB aplicáveis.
• Consultar política e notas da versão antes de recomendar mudança.
• Revisar qualquer plano de atualização com rollback e janela aprovada.

Fontes oficiais consultadas

Foram consultados o repositório oficial, o README fixado, o CAPABILITIES.md, o TASKS.md, a documentação do SDK, a política de compatibilidade e as notas de release. As URLs e hashes foram verificados em 19 de setembro de 2026.