Intelligent Computing LINGJUN:Guia de implantação e lançamento

1.1 Entregáveis

O Runtime Kit é composto por duas camadas que se conectam por meio de uma interface gRPC unificada:

Essa interface representa o único limite entre as duas camadas e constitui a base para a compatibilidade retroativa. O Alibaba Cloud Lingjun fornece as capacidades da camada de resource, enquanto você adapta a camada de container com base nos componentes open-source. Todas as conclusões de compatibilidade de versão apresentadas neste tópico fundamentam-se nessa interface.

Responsabilidade por problemas e canais de suporte: A interface gRPC define o limite de responsabilidade. Problemas no próprio Runtime da camada de resource são considerados problemas do product Alibaba Cloud Lingjun; nesse caso, abra um ticket para o suporte técnico do Alibaba Cloud Lingjun. Se utilizar diretamente as versões oficiais pré-compiladas dos componentes open-source, envie feedback por meio de canais como issues no repositório open-source. Implementações personalizadas ou adaptadas por você são de sua responsabilidade, e o Alibaba Cloud Lingjun oferece assistência na solução de problemas quando necessário.

1.2 Pré-requisitos

1. Nó bare metal do Lingjun: O pacote de Runtime vem pré-instalado na imagem do SO bare metal do Lingjun e está disponível apenas nesse ambiente. Antes de implantar os componentes open-source, o service de Runtime no nó já deve estar em execução. Confirme isso verificando os arquivos de socket no diretório /run/amp/eKitC/xdm/sockets/.

2. Cluster Kubernetes: É necessário ter o Kubernetes 1.18 ou superior para usar o Device Plugin e o Scheduler Framework.

3. Porta somente leitura do kubelet: Os componentes open-source obtêm informações sobre os Pods no nó por meio da porta somente leitura do kubelet (10255). Para mais informações, consulte {{XREF_0}}.

4. Configuração do runtime de container: A injeção de dispositivos GPU e PPU depende do handler de runtime lj-runtime e da RuntimeClass correspondente. Para mais informações, consulte {{XREF_1}}.

5. Dependência opcional: Se você utilizar agendamento de topologia gang entre nós e seu cluster não oferecer capacidades de agendamento gang, instale o JobSet. Recomenda-se o JobSet v0.8.0 ou superior. Para mais informações, consulte {{XREF_2}}.

1.3 Limites

1. Para utilizar as capacidades do Runtime Kit no Kubernetes, integre-as da maneira padrão fornecida pelo conjunto de componentes open-source, ou seja, chamando as capacidades subjacentes por meio da interface gRPC unificada.

2. A multiplexação por divisão de tempo (TDM) e o particionamento espacial Multi-Instance GPU (MIG) não podem ser ativados simultaneamente na mesma GPU.

3. O MIG é uma tecnologia NVIDIA de nível de hardware e tem suporte em todos os modelos de placa que oferecem essa capacidade.

2.1 Repositório open-source

O código dos componentes open-source está disponível no repositório GitHub aliyun/LJ-RuntimeKit. A branch main sempre contém o código utilizável mais recente. Versões estáveis são publicadas como tags. Para obter uma versão estável, utilize uma tag; para obter o código mais recente, use a branch main.

2.2 Imagens pré-compiladas

Caso não precise personalizar os componentes, utilize diretamente as imagens pré-compiladas, sem necessidade de compilação própria. O Alibaba Cloud Lingjun lança e mantém esses componentes, oferecendo também suporte técnico. Se encontrar problemas, envie feedback por meio de canais como issues no repositório open-source.

O registro de imagens é lj-runtimekit-registry.cn-hangzhou.cr.aliyuncs.com/lj-runtimekit/. A tabela a seguir descreve o mapeamento de versões das imagens pré-compiladas para cada componente:

Observação: Na tabela, o Controller Job Agent é uma imagem de execução no lado do nó, implantada juntamente com o Controller (consulte {{XREF_3}}). Não é necessário implantá-lo separadamente.

3.1 Componentes

O Controller Job Agent é a imagem de execução no lado do nó utilizada pelo Controller para ativar ou desativar recursos em um determinado nó. Ele é referenciado pelo parâmetro --job-image e implantado junto com o Controller. Não há necessidade de implantá-lo ou gerenciá-lo separadamente. Para mais detalhes sobre seu funcionamento, consulte {{XREF_4}}.

3.2 Tarefas pré-implantação

Execute as tarefas abaixo na ordem indicada.

Etapa 1: Verificar a disponibilidade do cluster Kubernetes (em qualquer máquina com permissões kubectl):

# 1. Change the image version in the YAML file of the component (Device Plugin is used as an example)
# Edit deploy/deviceplugin/03-daemonset.yaml and change the image field to the target version
# image: lj-runtimekit-registry.cn-hangzhou.cr.aliyuncs.com/lj-runtimekit/lj-runtimekit-device-plugin:<new-version>

# 2. Deploy a single component
./deploy/deploy-all.sh deploy --components=device-plugin

# Or deploy all components
./deploy/deploy-all.sh deploy

# 3. Verify the rolling update result
kubectl rollout status daemonset/lj-runtimekit-device-plugin -n kube-system
kubectl get pods -n kube-system -l app=lj-runtimekit-device-plugin -o wide

Resultado esperado: O cluster opera normalmente.

Etapa 2: Validar o ambiente do nó com GPU (em cada nó com GPU):

# 1. Change the image version in the YAML file of the component (Device Plugin is used as an example)
# Edit deploy/deviceplugin/03-daemonset.yaml and change the image field to the target version
# image: lj-runtimekit-registry.cn-hangzhou.cr.aliyuncs.com/lj-runtimekit/lj-runtimekit-device-plugin:<new-version>

# 2. Deploy a single component
./deploy/deploy-all.sh deploy --components=device-plugin

# Or deploy all components
./deploy/deploy-all.sh deploy

# 3. Verify the rolling update result
kubectl rollout status daemonset/lj-runtimekit-device-plugin -n kube-system
kubectl get pods -n kube-system -l app=lj-runtimekit-device-plugin -o wide

Resultado esperado: O driver está instalado corretamente e é possível consultar as informações do dispositivo.

O conjunto de containers do Lingjun inclui um runtime de container compatível com dispositivos heterogêneos GPU, PPU e AMD. Esse runtime é integrado nativamente e não exige instalação separada. Basta confirmar que o driver funciona e que o arquivo de socket existe. Para configurar o registro entre o runtime e o containerd, consulte a Etapa 5.

Etapa 3: Ativar a porta somente leitura do kubelet (10255) (como root em cada nó com GPU):

# 1. Change the image version in the YAML file of the component (Device Plugin is used as an example)
# Edit deploy/deviceplugin/03-daemonset.yaml and change the image field to the target version
# image: lj-runtimekit-registry.cn-hangzhou.cr.aliyuncs.com/lj-runtimekit/lj-runtimekit-device-plugin:<new-version>

# 2. Deploy a single component
./deploy/deploy-all.sh deploy --components=device-plugin

# Or deploy all components
./deploy/deploy-all.sh deploy

# 3. Verify the rolling update result
kubectl rollout status daemonset/lj-runtimekit-device-plugin -n kube-system
kubectl get pods -n kube-system -l app=lj-runtimekit-device-plugin -o wide

Se a porta não estiver ativada, edite o arquivo de configuração do kubelet (por exemplo, /var/lib/kubelet/config.yaml. Em seguida, execute systemctl restart kubelet e verifique novamente a porta. A porta 10255 é somente leitura e aceita apenas consultas. Caso a política de segurança do seu cluster não permita essa porta, contate o administrador do cluster para avaliar a possibilidade de ativação.

Etapa 4: Rotular os nós que utilizarão as capacidades do Runtime Kit:

# 1. Change the image version in the YAML file of the component (Device Plugin is used as an example)
# Edit deploy/deviceplugin/03-daemonset.yaml and change the image field to the target version
# image: lj-runtimekit-registry.cn-hangzhou.cr.aliyuncs.com/lj-runtimekit/lj-runtimekit-device-plugin:<new-version>

# 2. Deploy a single component
./deploy/deploy-all.sh deploy --components=device-plugin

# Or deploy all components
./deploy/deploy-all.sh deploy

# 3. Verify the rolling update result
kubectl rollout status daemonset/lj-runtimekit-device-plugin -n kube-system
kubectl get pods -n kube-system -l app=lj-runtimekit-device-plugin -o wide

Somente os nós rotulados com lj_runtimekit_enable=true executam o Device Plugin e o Exporter. Os componentes do Runtime Kit não são implantados em nós sem esse rótulo, e as capacidades relacionadas permanecem desativadas. Essa label também funciona como chave de ativação do recurso. Para mais informações, consulte {{XREF_5}}.

Etapa 5: Configurar o runtime de container (obrigatório para injeção de dispositivos GPU e PPU):

O Runtime Kit configura automaticamente o handler de runtime lj-runtime no arquivo config.toml do containerd. Não é necessário modificar manualmente o config.toml. A configuração abaixo é adicionada após a seção existente runtimes.nvidia:

# 1. Change the image version in the YAML file of the component (Device Plugin is used as an example)
# Edit deploy/deviceplugin/03-daemonset.yaml and change the image field to the target version
# image: lj-runtimekit-registry.cn-hangzhou.cr.aliyuncs.com/lj-runtimekit/lj-runtimekit-device-plugin:<new-version>

# 2. Deploy a single component
./deploy/deploy-all.sh deploy --components=device-plugin

# Or deploy all components
./deploy/deploy-all.sh deploy

# 3. Verify the rolling update result
kubectl rollout status daemonset/lj-runtimekit-device-plugin -n kube-system
kubectl get pods -n kube-system -l app=lj-runtimekit-device-plugin -o wide

Crie o resource RuntimeClass correspondente no cluster:

# 1. Change the image version in the YAML file of the component (Device Plugin is used as an example)
# Edit deploy/deviceplugin/03-daemonset.yaml and change the image field to the target version
# image: lj-runtimekit-registry.cn-hangzhou.cr.aliyuncs.com/lj-runtimekit/lj-runtimekit-device-plugin:<new-version>

# 2. Deploy a single component
./deploy/deploy-all.sh deploy --components=device-plugin

# Or deploy all components
./deploy/deploy-all.sh deploy

# 3. Verify the rolling update result
kubectl rollout status daemonset/lj-runtimekit-device-plugin -n kube-system
kubectl get pods -n kube-system -l app=lj-runtimekit-device-plugin -o wide

# 1. Change the image version in the YAML file of the component (Device Plugin is used as an example)
# Edit deploy/deviceplugin/03-daemonset.yaml and change the image field to the target version
# image: lj-runtimekit-registry.cn-hangzhou.cr.aliyuncs.com/lj-runtimekit/lj-runtimekit-device-plugin:<new-version>

# 2. Deploy a single component
./deploy/deploy-all.sh deploy --components=device-plugin

# Or deploy all components
./deploy/deploy-all.sh deploy

# 3. Verify the rolling update result
kubectl rollout status daemonset/lj-runtimekit-device-plugin -n kube-system
kubectl get pods -n kube-system -l app=lj-runtimekit-device-plugin -o wide

Verificação:

# 1. Change the image version in the YAML file of the component (Device Plugin is used as an example)
# Edit deploy/deviceplugin/03-daemonset.yaml and change the image field to the target version
# image: lj-runtimekit-registry.cn-hangzhou.cr.aliyuncs.com/lj-runtimekit/lj-runtimekit-device-plugin:<new-version>

# 2. Deploy a single component
./deploy/deploy-all.sh deploy --components=device-plugin

# Or deploy all components
./deploy/deploy-all.sh deploy

# 3. Verify the rolling update result
kubectl rollout status daemonset/lj-runtimekit-device-plugin -n kube-system
kubectl get pods -n kube-system -l app=lj-runtimekit-device-plugin -o wide

Os Pods de carga de trabalho subsequentes devem especificar runtimeClassName: lj-runtime. Caso contrário, os dispositivos GPU e PPU não serão injetados corretamente no container.

Etapa 6 (opcional): Implantar o JobSet. Se o seu cluster não oferecer capacidades de agendamento gang e você precisar de agendamento ciente de topologia para muitos Pods que iniciam e param simultaneamente, implante o JobSet. Para mais informações, consulte Instalação do JobSet. Recomenda-se o JobSet v0.8.0 ou superior.

3.3 Implantação com um clique (recomendado)

Se não houver requisitos de personalização, recomendamos o uso direto das imagens pré-compiladas e a implantação com o script abaixo.

Substitua <version> pela tag de imagem desejada na tabela de mapeamento de versões:

# 1. Change the image version in the YAML file of the component (Device Plugin is used as an example)
# Edit deploy/deviceplugin/03-daemonset.yaml and change the image field to the target version
# image: lj-runtimekit-registry.cn-hangzhou.cr.aliyuncs.com/lj-runtimekit/lj-runtimekit-device-plugin:<new-version>

# 2. Deploy a single component
./deploy/deploy-all.sh deploy --components=device-plugin

# Or deploy all components
./deploy/deploy-all.sh deploy

# 3. Verify the rolling update result
kubectl rollout status daemonset/lj-runtimekit-device-plugin -n kube-system
kubectl get pods -n kube-system -l app=lj-runtimekit-device-plugin -o wide

Para personalizações simples, ajuste o script acima e os scripts chamados por ele, como o deploy-all.sh. Consulte os comentários nos próprios scripts para mais detalhes.

É possível executar o script de implantação repetidamente. Se uma implantação falhar, corrija o ambiente conforme as mensagens exibidas e execute o script novamente. Durante toda a execução, o script gera um log completo de operações para auxiliar na verificação da implantação e na solução de problemas.

3.4 Verificar a implantação

Após concluir a implantação, siga as etapas abaixo para validar cada item.

Etapa 1: Checar o status de execução dos componentes

Execute o comando a seguir:

# 1. Change the image version in the YAML file of the component (Device Plugin is used as an example)
# Edit deploy/deviceplugin/03-daemonset.yaml and change the image field to the target version
# image: lj-runtimekit-registry.cn-hangzhou.cr.aliyuncs.com/lj-runtimekit/lj-runtimekit-device-plugin:<new-version>

# 2. Deploy a single component
./deploy/deploy-all.sh deploy --components=device-plugin

# Or deploy all components
./deploy/deploy-all.sh deploy

# 3. Verify the rolling update result
kubectl rollout status daemonset/lj-runtimekit-device-plugin -n kube-system
kubectl get pods -n kube-system -l app=lj-runtimekit-device-plugin -o wide

Resultado esperado:

Critérios de validação:

• Todos os Pods apresentam estado Running e a coluna READY exibe 1/1, indicando sucesso na implantação.

• Caso algum Pod esteja em CrashLoopBackOff, consulte os logs para identificar a causa: kubectl logs -n kube-system <pod-name>.

• Se um Pod permanecer em Pending ou Init, verifique se as labels e os resources do nó atendem às condições de agendamento: kubectl describe pod -n kube-system <pod-name>.

Etapa 2: Conferir os resources relatados pelo nó

# 1. Change the image version in the YAML file of the component (Device Plugin is used as an example)
# Edit deploy/deviceplugin/03-daemonset.yaml and change the image field to the target version
# image: lj-runtimekit-registry.cn-hangzhou.cr.aliyuncs.com/lj-runtimekit/lj-runtimekit-device-plugin:<new-version>

# 2. Deploy a single component
./deploy/deploy-all.sh deploy --components=device-plugin

# Or deploy all components
./deploy/deploy-all.sh deploy

# 3. Verify the rolling update result
kubectl rollout status daemonset/lj-runtimekit-device-plugin -n kube-system
kubectl get pods -n kube-system -l app=lj-runtimekit-device-plugin -o wide

Resultado esperado (cenário de GPU inteira): Resources estendidos relacionados ao acelerador aparecem nas seções Capacity e Allocatable do nó. Exemplo:

# 1. Change the image version in the YAML file of the component (Device Plugin is used as an example)
# Edit deploy/deviceplugin/03-daemonset.yaml and change the image field to the target version
# image: lj-runtimekit-registry.cn-hangzhou.cr.aliyuncs.com/lj-runtimekit/lj-runtimekit-device-plugin:<new-version>

# 2. Deploy a single component
./deploy/deploy-all.sh deploy --components=device-plugin

# Or deploy all components
./deploy/deploy-all.sh deploy

# 3. Verify the rolling update result
kubectl rollout status daemonset/lj-runtimekit-device-plugin -n kube-system
kubectl get pods -n kube-system -l app=lj-runtimekit-device-plugin -o wide

Critérios de validação:

• As quantidades de resources em Capacity devem corresponder ao número real de dispositivos no nó (por exemplo, um nó com 8 GPUs deve relatar 8).

• Para os resources estendidos relatados pelo Device Plugin, Allocatable normalmente equivale a Capacity. Para verificar o uso de resources pelos Pods, execute kubectl describe node e examine a seção Allocated resources. Se Allocatable for 0, mas Capacity não for 0, geralmente trata-se de resíduo decorrente de alteração no nome do resource.

• Se nenhum resource estendido aparecer, o Device Plugin falhou ao relatá-los. Verifique os logs do Pod do Device Plugin e o status do service de Runtime no nó, inclusive a existência do arquivo de socket.

Etapa 3: Confirmar que o Exporter expõe métricas (execute em um nó onde o Exporter esteja implantado)

# 1. Change the image version in the YAML file of the component (Device Plugin is used as an example)
# Edit deploy/deviceplugin/03-daemonset.yaml and change the image field to the target version
# image: lj-runtimekit-registry.cn-hangzhou.cr.aliyuncs.com/lj-runtimekit/lj-runtimekit-device-plugin:<new-version>

# 2. Deploy a single component
./deploy/deploy-all.sh deploy --components=device-plugin

# Or deploy all components
./deploy/deploy-all.sh deploy

# 3. Verify the rolling update result
kubectl rollout status daemonset/lj-runtimekit-device-plugin -n kube-system
kubectl get pods -n kube-system -l app=lj-runtimekit-device-plugin -o wide

Resultado esperado: Métricas no formato Prometheus são retornadas (linhas iniciadas com # HELP e # TYPE).

Critérios de validação:

• Retorno do texto de métricas indica que o Exporter funciona adequadamente.

• Falha na requisição com "Connection refused" exige verificar se o Pod do Exporter está operando corretamente e confirmar a correspondência das portas.

3.5 Ativar e desativar recursos

O Controller ativa ou desativa automaticamente os recursos do Runtime Kit em um nó com base na label desse nó. Ao adicionar a label lj_runtimekit_enable=true a um nó, o Controller habilita automaticamente os recursos nele. Ao remover a label, os recursos são desabilitados automaticamente. O mecanismo funciona da seguinte forma: o Controller cria automaticamente um Job do Kubernetes que executa a imagem do Controller Job Agent no nó alvo para concluir essas operações. Após a conclusão, o Job é limpo automaticamente. Rotule novos nós ao adicioná-los. A tabela a seguir descreve o impacto da ativação e desativação de recursos:

Recomendamos realizar upgrades de componentes e operações de ativação/desativação de recursos fora dos horários de pico.

3.6 Implantação avançada e personalização

Utilize esta seção caso precise implantar componentes individualmente, compilar suas próprias imagens ou personalizar componentes com base no código open-source.

Antes de implantar os componentes, compile as imagens correspondentes e envie-as para um registro de imagens acessível ao cluster. Para compilar a imagem de cada componente, navegue até seu diretório-fonte e execute make docker. Após a compilação, envie as imagens para um registro acessível aos nós do cluster e garanta que os nomes e tags das imagens nos manifestos de implantação correspondam exatamente aos artefatos compilados. Os arquivos de implantação dos componentes são os seguintes:

Por exemplo, o arquivo de implantação do Device Plugin é deploy/deviceplugin/03-daemonset.yaml, e a configuração de imagem nele contida é a seguinte:

# 1. Change the image version in the YAML file of the component (Device Plugin is used as an example)
# Edit deploy/deviceplugin/03-daemonset.yaml and change the image field to the target version
# image: lj-runtimekit-registry.cn-hangzhou.cr.aliyuncs.com/lj-runtimekit/lj-runtimekit-device-plugin:<new-version>

# 2. Deploy a single component
./deploy/deploy-all.sh deploy --components=device-plugin

# Or deploy all components
./deploy/deploy-all.sh deploy

# 3. Verify the rolling update result
kubectl rollout status daemonset/lj-runtimekit-device-plugin -n kube-system
kubectl get pods -n kube-system -l app=lj-runtimekit-device-plugin -o wide

Se precisar alterar apenas itens de configuração — como nomes de resources estendidos, chaves de labels de nó ou chaves de anotações — sem modificar a lógica do código, edite a configuração (ConfigMap) no manifesto de implantação de cada componente e reimplante-o. Não será necessário recompilar a imagem. Para mais informações, consulte {{XREF_6}}.

4.1 Formato do número de versão

O Runtime Kit adota um esquema unificado de numeração de versões no formato v{major}.{feature}.{iteration} (por exemplo, v1.13.0).

Critério de upgrade: se o comportamento existente muda após o upgrade sem que você modifique nenhuma configuração ou arquivo YAML. Um upgrade de versão de iteração não altera o comportamento visível ao usuário. Já um upgrade de versão de feature pode introduzir novas funcionalidades ou mudanças de comportamento. Um upgrade de versão major pode conter alterações incompatíveis, exigindo avaliação prévia antes da atualização.

4.2 Versões do Runtime e dos componentes open-source

Versão do Runtime: A partir da versão 1.13.0, o Runtime suporta integração com os componentes open-source.

Versão dos componentes open-source: As versões dos componentes open-source acompanham as versões do Runtime.

5.1 Política de compatibilidade

A interface gRPC entre o Runtime e os componentes open-source é apenas aditiva e retrocompatível: a interface evolui incrementalmente (novas interfaces e campos são adicionados), e a semântica das interfaces e campos existentes não se altera.

Se circunstâncias especiais exigirem futuramente uma alteração incompatível, ela será sempre lançada como upgrade de versão major e destacada nas notas de lançamento. Por outro lado, um upgrade de versão major não necessariamente contém alterações incompatíveis. Consulte as notas de lançamento da versão específica.

5.2 Conclusões sobre compatibilidade

Com base nessa política:

1. Dentro da mesma versão major, a partir da versão 1.13.0, qualquer versão dos componentes open-source funciona com qualquer versão do Runtime.

2. Um upgrade do Runtime não quebra os componentes já implantados. Não é necessária nenhuma atualização por motivos de compatibilidade.

3. Implementações personalizadas com base no proto de uma versão anterior continuam funcionando após um upgrade do Runtime.

4. Quando ocorrer um upgrade de versão major, revise as notas de lançamento para verificar possíveis alterações incompatíveis e avalie-as antes de prosseguir.

5.3 Dependências de versão entre componentes

Não há vinculação rígida de versão entre os componentes open-source. Eles se conectam ao Runtime por meio da interface gRPC unificada e ao cluster através dos mecanismos padrão de extensão do Kubernetes (framework de device plugin, Scheduler Framework e protocolo de métricas Prometheus). Em princípio, componentes de versões diferentes podem operar em conjunto.

Como um novo recurso geralmente requer a colaboração do Runtime e de múltiplos componentes, cada nova funcionalidade estabelece um requisito mínimo de versão unificado tanto para o Runtime quanto para todo o conjunto de componentes. Para mais informações, consulte a Seção 6.

6. Requisitos mínimos de versão para recursos

As capacidades básicas (alocação de GPU inteira, fatiamento de poder computacional e memória da GPU por divisão de tempo, e monitoramento básico) estão disponíveis a partir da versão 1.13.0, sem requisitos adicionais de versão. Recursos incrementais possuem requisitos mínimos específicos, conforme as regras a seguir:

Antes de utilizar um recurso, certifique-se de que a versão do Runtime e as versões de todos os componentes open-source associados sejam iguais ou superiores à versão mínima exigida para esse recurso. Como os componentes open-source são lançados com um número de versão unificado, isso significa que tanto a versão do Runtime quanto a dos componentes devem atender aos requisitos da tabela abaixo.

Observação: Se o requisito de versão não for atendido, apenas o recurso específico ficará indisponível. Os recursos existentes não serão afetados.

7. Upgrades

# 1. Change the image version in the YAML file of the component (Device Plugin is used as an example)
# Edit deploy/deviceplugin/03-daemonset.yaml and change the image field to the target version
# image: lj-runtimekit-registry.cn-hangzhou.cr.aliyuncs.com/lj-runtimekit/lj-runtimekit-device-plugin:<new-version>

# 2. Deploy a single component
./deploy/deploy-all.sh deploy --components=device-plugin

# Or deploy all components
./deploy/deploy-all.sh deploy

# 3. Verify the rolling update result
kubectl rollout status daemonset/lj-runtimekit-device-plugin -n kube-system
kubectl get pods -n kube-system -l app=lj-runtimekit-device-plugin -o wide

Perguntas frequentes