Pré-requisitos Escolha sua abordagem de implantação Implante usando um volume Kubernetes (sem fallback)Implante usando um volume Kubernetes com fallback Implante usando o Amazon S3 com prefetch e fallback NVMe Compreendendo os pesos do modelo e a cópia dos pesos do modelo com pré-busca Configurar uma conta de serviço personalizada Pré-carregue os pesos do modelo para o NVMe Nomes de volumes reservados Coisas para lembrar Solução de problemas

Implemente modelos do armazenamento NVMe local usando kubectl

Este tópico mostra como implantar endpoints de inferência na Amazon SageMaker HyperPod que carregam pesos de modelo do armazenamento NVMe local de um nó em vez de transferi-los pela rede a partir do Amazon S3 ou do Amazon FSx. A leitura local dos pesos elimina o salto de rede durante a inicialização do pod, o que reduz o tempo de inicialização a frio do pod de inferência e é útil para eventos de escalonamento automático, cargas de trabalho com escalabilidade zero e failovers sensíveis à latência. Para cargas de trabalho em que a latência de inicialização a frio não é uma preocupação, use modelSourceType: s3 ou ignore este tópicofsx.

O NVMe local é efêmero e local do nó: os dados no NVMe são perdidos quando um nó é substituído, por exemplo, durante uma interrupção pontual, falha de hardware ou atualização da AMI. As abordagens neste tópico lidam com isso de forma diferente — algumas exigem que você pré-preencha cada nó, outras retornam ao Amazon S3 automaticamente quando o modelo não é armazenado em cache localmente. O armazenamento local de instâncias NVMe normalmente é encontrado nas famílias de instâncias P, G e Trn. Consulte as especificações do armazenamento de instâncias do Amazon EC2 para validar a disponibilidade do seu tipo de instância.

Você pode escolher entre as seguintes abordagens com base em seus requisitos de armazenamento:

Abordagens de implantação do NVMe
#	Abordagem	Description
1	Volume do Kubernetes (sem substituto)	Use quando existirem pesos de modelo no NVMe em cada nó. Configuração mais simples sem a necessidade de Amazon S3, Amazon FSx ou PV/PVC initContainers.
2	Volume do Kubernetes com fallback	Use quando o modelo pode não existir no NVMe em todos os nós. Você fornece uma versão personalizada `initContainer` que verifica primeiro o NVMe e faz o download do Amazon S3 usando credenciais IRSA se o modelo estiver ausente.
3	Amazon S3 com pré-busca e fallback	Use quando quiser colocar os pesos do modelo na RAM para a inicialização do pod. Você fornece uma versão personalizada `initContainer` que verifica primeiro o NVMe e volta a copiar da montagem do Amazon S3 provisionada pelo operador se o modelo não estiver armazenado em cache localmente.

Pré-requisitos

Antes de começar, verifique se você:

Configure recursos de inferência em seus SageMaker HyperPod clusters da Amazon. Para obter mais informações, consulte Configurando seus HyperPod clusters para implantação de modelos.
Instalou o utilitário kubectl e configurou o jq em seu terminal.
Pre-populated modele pesos no armazenamento NVMe local de seus nós de destino (consulte Pré-carregue os pesos do modelo para o NVMe para obter instruções).

Escolha sua abordagem de implantação

Use o fluxo de decisão a seguir para determinar qual abordagem é a certa para seu caso de uso.


                  ┌────────────────────────────┐
                  │ Want to use a volume of    │
                  │ your choice, e.g. NVMe?    │
                  └─────┬──────────────┬───────┘
                   YES  │              │ NO
                        ▼              ▼
        ┌──────────────────────┐   Use S3/FSx/HF
        │ Are you sure EVERY   │   as-is (no volume
        │ node has the model   │   override needed)
        │ on NVMe?             │
        └─────┬──────────┬─────┘
         YES  │          │ NO
              ▼          ▼
  ┌─────────────────┐  ┌───────────────────────────────┐
  │ Approach 1      │  │ Do you need the operator to   │
  │                 │  │ create S3/FSx PVCs as a       │
  │ Use k8sVolume   │  │ fallback when the model is    │
  │ field in CRD to │  │ missing on a node?            │
  │ read from NVMe  │  └──────┬────────────────┬───────┘
  │ directly.       │    YES  │                │ NO
  └─────────────────┘         ▼                ▼
                  ┌──────────────────┐  ┌──────────────────────┐
                  │ Approach 3       │  │ Approach 2           │
                  │                  │  │                      │
                  │ Use S3 with      │  │ Use k8sVolume with a │
                  │ prefetch enabled.│  │ custom initContainer │
                  │ Custom           │  │ you create that      │
                  │ initContainer    │  │ checks NVMe first    │
                  │ checks NVMe      │  │ and downloads from   │
                  │ first, falls     │  │ S3 via IRSA if the   │
                  │ back to S3, and  │  │ model is missing.    │
                  │ copies to RAM.   │  └──────────────────────┘
                  └──────────────────┘

Implante usando um volume Kubernetes (sem fallback)

Use essa abordagem quando você tiver pesos de modelo no NVMe em cada nó e quiser a configuração mais simples — sem configuração do Amazon S3 ou Amazon FSx, sem e sem PV/PVC initContainers.

Quando você definemodelSourceType: kubernetesVolume, o operador ignora totalmente PV/PVC a criação. Nenhum driver CSI, montagem de fusível Amazon S3 ou montagem Amazon FSx é usada. O model-weights volume fornecido pelo cliente é usado diretamente na especificação do pod, e o trabalhador lê os dados do modelo do NVMe em. /opt/ml/model

Importante

Ao usarmodelSourceType: kubernetesVolume, o operador deriva o nome do volume esperado modelVolumeMount.name na configuração do seu trabalhador. kubernetes.volumesdeve conter um volume com o mesmo nome. O operador valida isso e rejeita a implantação com uma KubernetesVolumeValidationFailed condição se nenhum volume correspondente for encontrado. Nos exemplos a seguir, ambos usammodel-weights.

Crie o arquivo InferenceEndpointConfig YAML. Substitua os valores do espaço reservado pelos seus identificadores de recursos reais.


cat <<EOF> deploy_nvme_k8s_volume.yaml
apiVersion: inference.sagemaker.aws.amazon.com/v1
kind: InferenceEndpointConfig
metadata:
  name: nvme-k8s-volume
  namespace: default
spec:
  endpointName: nvme-k8s-volume
  modelName: Qwen2.5-VL-7B-Instruct
  invocationEndpoint: v1/chat/completions
  replicas: 1
  modelSourceConfig:
    modelSourceType: kubernetesVolume
  kubernetes:
    volumes:
      - name: model-weights
        hostPath:
          path: /opt/dlami/nvme/<YOUR_MODEL>
          type: Directory
  loadBalancer:
    healthCheckPath: /health
  worker:
    image: lmcache/vllm-openai:latest
    args:
      - /opt/ml/model
      - --max-model-len
      - "15000"
      - --tensor-parallel-size
      - "1"
    modelInvocationPort:
      containerPort: 8000
      name: http
    modelVolumeMount:
      name: model-weights
      mountPath: /opt/ml/model
    resources:
      limits:
        nvidia.com/gpu: "1"
      requests:
        cpu: "6"
        memory: 30Gi
        nvidia.com/gpu: "1"
    environmentVariables:
      - name: PYTHONHASHSEED
        value: "123"
      - name: VLLM_REQUEST_TIMEOUT
        value: "600"
EOF

nota

Para configurar o cache KV e o roteamento inteligente para melhorar o desempenho, consulte. Configurar o cache KV e o roteamento inteligente

Implante InferenceEndpointConfig o.


kubectl apply -f deploy_nvme_k8s_volume.yaml

Verifique o status da implantação.


kubectl describe InferenceEndpointConfig nvme-k8s-volume -n default

Implante usando um volume Kubernetes com fallback

Use essa abordagem quando o modelo estiver ou não no NVMe em um determinado nó. Um hostPath volume só funciona em nós onde os dados existem — os pods programados em outros nós montariam um caminho vazio ou inexistente, fazendo com que o servidor modelo falhasse.

Nessa abordagem, você define modelSourceType: kubernetesVolume e fornece um modelo personalizado initContainer que verifica primeiro o NVMe e faz o download do Amazon S3 usando credenciais IRSA se o modelo estiver ausente.

Configurar o IRSA

Antes da implantação, configure o IAM Roles for Service Accounts (IRSA) para fornecer aos seus pods credenciais para download do Amazon S3.

Obtenha o ID do provedor OIDC para seu cluster.


aws eks describe-cluster --name <CLUSTER_NAME> --region <REGION> \
  --query "cluster.identity.oidc.issuer" --output text

Crie uma política de confiança do IAM. Salve o seguinte comotrust-policy.json, substituindo os valores do espaço reservado.


{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Principal": {
      "Federated": "arn:aws:iam::<ACCOUNT_ID>:oidc-provider/oidc.eks.<REGION>.amazonaws.com/id/<OIDC_ID>"
    },
    "Action": "sts:AssumeRoleWithWebIdentity",
    "Condition": {
      "StringEquals": {
        "oidc.eks.<REGION>.amazonaws.com/id/<OIDC_ID>:sub": "system:serviceaccount:<NAMESPACE>:<SA_NAME>",
        "oidc.eks.<REGION>.amazonaws.com/id/<OIDC_ID>:aud": "sts.amazonaws.com"
      }
    }
  }]
}

Atenção

Sempre defina o escopo da política de confiança para um namespace e ServiceAccount um nome específicos. Nunca use curingas na condição de assunto (por exemplo,system:serviceaccount:*:*), pois isso permitiria que qualquer pessoa ServiceAccount em qualquer namespace assumisse a função.

Crie a função do IAM e anexe uma política de leitura do Amazon S3 com escopo para seu bucket modelo.


aws iam create-role --role-name <ROLE_NAME> \
  --assume-role-policy-document file://trust-policy.json

aws iam put-role-policy --role-name <ROLE_NAME> \
  --policy-name S3ModelReadAccess \
  --policy-document '{
    "Version": "2012-10-17",
    "Statement": [{
      "Effect": "Allow",
      "Action": ["s3:GetObject", "s3:ListBucket"],
      "Resource": [
        "arn:aws:s3:::<YOUR_BUCKET>",
        "arn:aws:s3:::<YOUR_BUCKET>/<YOUR_MODEL_PREFIX>/*"
      ]
    }]
  }'

Crie a conta de serviço Kubernetes com a anotação IRSA.


kubectl create sa <SA_NAME> -n <NAMESPACE>
kubectl annotate sa <SA_NAME> -n <NAMESPACE> \
  eks.amazonaws.com/role-arn=arn:aws:iam::<ACCOUNT_ID>:role/<ROLE_NAME>

Implantar o modelo

Crie o arquivo InferenceEndpointConfig YAML. Substitua os valores do espaço reservado pelos seus identificadores de recursos reais.


cat <<EOF> deploy_nvme_k8s_volume_fallback.yaml
apiVersion: inference.sagemaker.aws.amazon.com/v1
kind: InferenceEndpointConfig
metadata:
  name: nvme-k8s-volume-fallback
  namespace: default
spec:
  endpointName: nvme-k8s-volume-fallback
  modelName: Qwen2.5-VL-7B-Instruct
  invocationEndpoint: v1/chat/completions
  replicas: 1
  modelSourceConfig:
    modelSourceType: kubernetesVolume
  kubernetes:
    serviceAccountName: <YOUR_SERVICE_ACCOUNT>
    initContainers:
      - name: smart-loader
        image: public.ecr.aws/aws-cli/aws-cli:latest
        command: ["/bin/bash", "-c"]
        args:
          - |
            if [ "$(ls -A /model)" ]; then
              echo "NVMe hit — model already present ($(du -sh /model | cut -f1))"
            else
              echo "NVMe miss — downloading from S3"
              aws s3 sync s3://<YOUR_BUCKET>/<YOUR_MODEL>/ /model/
            fi
        volumeMounts:
          - name: model-weights
            mountPath: /model
    volumes:
      - name: model-weights
        hostPath:
          path: /opt/dlami/nvme/<YOUR_MODEL>
          type: DirectoryOrCreate
  loadBalancer:
    healthCheckPath: /health
  worker:
    image: lmcache/vllm-openai:latest
    args:
      - /opt/ml/model
      - --max-model-len
      - "15000"
      - --tensor-parallel-size
      - "1"
    modelInvocationPort:
      containerPort: 8000
      name: http
    modelVolumeMount:
      name: model-weights
      mountPath: /opt/ml/model
    resources:
      limits:
        nvidia.com/gpu: "1"
      requests:
        cpu: "6"
        memory: 30Gi
        nvidia.com/gpu: "1"
    environmentVariables:
      - name: PYTHONHASHSEED
        value: "123"
EOF

nota

Para configurar o cache KV e o roteamento inteligente para melhorar o desempenho, consulte. Configurar o cache KV e o roteamento inteligente

Implante InferenceEndpointConfig o.


kubectl apply -f deploy_nvme_k8s_volume_fallback.yaml

Verifique o status da implantação.


kubectl describe InferenceEndpointConfig nvme-k8s-volume-fallback -n default

Implante usando o Amazon S3 com prefetch e fallback NVMe

Use essa abordagem quando quiser inferir o desempenho transferindo os pesos do modelo para a RAM, com retorno automático para o Amazon S3 se o modelo não estiver armazenado em cache localmente no NVMe.

Quando você define modelSourceType: s3 comprefetchEnabled: true, o operador cria dois volumes automaticamente:

Um volume com o nome de seu modelVolumeMount.name (normalmentemodel-weights) — um suporte de fusível CSI do Amazon S3 contendo seu modelo
model-weights-copy— a de RAM-backed emptyDir onde o trabalhador lê

Você adiciona um nvme-cache volume personalizado apontando para o armazenamento NVMe local do nó e um personalizado initContainer que:

Se o modelo existir no NVMe — copia do NVMe para a RAM (model-weights-copy), ignorando totalmente a rede.
Se o modelo estiver ausente, volte a copiar da montagem do Amazon S3 (model-weights) para a RAM (model-weights-copy). Opcionalmente, copia para o NVMe para que as inicializações subsequentes do pod no mesmo nó usem o caminho local rápido.

Importante

Não se model-weights sobreponha kubernetes.volumes ao usar essa abordagem. O operador cria um model-weights apontamento para o volume CSI do Amazon S3. A substituição remove o volume provisionado pelo operador que seu initContainer precisa para o fallback. Use um nome de volume separado (por exemplo,nvme-cache) para seu NVMe HostPath.

Importante

Não inclua model-weights-copy emkubernetes.volumes. É um nome reservado criado automaticamente pelo operador. Seu initContainer pode referenciá-lovolumeMounts, mas não deve declará-lo como um volume.

Crie o arquivo InferenceEndpointConfig YAML. Substitua os valores do espaço reservado pelos seus identificadores de recursos reais.


cat <<EOF> deploy_nvme_s3_prefetch_fallback.yaml
apiVersion: inference.sagemaker.aws.amazon.com/v1
kind: InferenceEndpointConfig
metadata:
  name: nvme-s3-prefetch-fallback
  namespace: default
spec:
  endpointName: nvme-s3-prefetch-fallback
  modelName: Qwen2.5-VL-7B-Instruct
  invocationEndpoint: v1/chat/completions
  replicas: 1
  modelSourceConfig:
    modelSourceType: s3
    s3Storage:
      bucketName: <YOUR_BUCKET>
      region: <YOUR_REGION>
    prefetchEnabled: true
  kubernetes:
    serviceAccountName: <YOUR_SERVICE_ACCOUNT>
    initContainers:
      - name: smart-loader
        image: public.ecr.aws/aws-cli/aws-cli:latest
        command: ["/bin/bash", "-c"]
        args:
          - |
            # Check NVMe first, fall back to S3 mount, then copy to RAM
            if [ "$(ls -A /nvme)" ]; then
              echo "NVMe hit ($(du -sh /nvme | cut -f1))"
              echo "Copying model from NVMe to RAM..."
              cp -r /nvme/* /model/
            else
              echo "NVMe miss — copying from S3 mount to NVMe, then NVMe to RAM"
              cp -r /s3-model/* /nvme/
              cp -r /nvme/* /model/
            fi
            echo "Done. $(du -sh /model | cut -f1) in RAM."
        volumeMounts:
          - name: model-weights
            mountPath: /s3-model
          - name: nvme-cache
            mountPath: /nvme
          - name: model-weights-copy
            mountPath: /model
    volumes:
      - name: nvme-cache
        hostPath:
          path: /opt/dlami/nvme/<YOUR_MODEL>
          type: DirectoryOrCreate
  loadBalancer:
    healthCheckPath: /health
  worker:
    image: lmcache/vllm-openai:latest
    args:
      - /opt/ml/model
      - --max-model-len
      - "15000"
      - --tensor-parallel-size
      - "1"
    modelInvocationPort:
      containerPort: 8000
      name: http
    modelVolumeMount:
      name: model-weights
      mountPath: /opt/ml/model
    resources:
      limits:
        nvidia.com/gpu: "1"
      requests:
        cpu: "6"
        memory: 30Gi
        nvidia.com/gpu: "1"
    environmentVariables:
      - name: PYTHONHASHSEED
        value: "123"
      - name: VLLM_REQUEST_TIMEOUT
        value: "600"
EOF

nota

Para configurar o cache KV e o roteamento inteligente para melhorar o desempenho, consulte. Configurar o cache KV e o roteamento inteligente

Implante InferenceEndpointConfig o.


kubectl apply -f deploy_nvme_s3_prefetch_fallback.yaml

Verifique o status da implantação.


kubectl describe InferenceEndpointConfig nvme-s3-prefetch-fallback -n default

Compreendendo os pesos do modelo e a cópia dos pesos do modelo com pré-busca

Ao usar a pré-busca, o operador cria dois volumes relacionados ao modelo:

Um volume com o nome de seu modelVolumeMount.name (normalmentemodel-weights) — um suporte de fusível CSI do Amazon S3 contendo seu modelo
model-weights-copy— um RAM-backed EmptyDir de onde o trabalhador realmente lê

No seuInferenceEndpointConfig, você define:


modelVolumeMount:
    name: model-weights
    mountPath: /opt/ml/model

Enquanto você faz referência a quando model-weightsprefetchEnabled: true, na verdade é isso model-weights-copy que é montado /opt/ml/model no contêiner do trabalhador. Ao usar um initContainer personalizado, certifique-se de copiar os dados no volume chamado model-weights-copy — é onde o trabalhador espera encontrá-los.

QuandoprefetchEnabled: false, há apenas um volume (com o nome do seumodelVolumeMount.name) e ele é montado diretamente nele/opt/ml/model.

Configurar uma conta de serviço personalizada

Você pode atribuir um Kubernetes personalizado ServiceAccount aos seus pods de endpoint de inferência usando o campo no. spec.kubernetes.serviceAccountName InferenceEndpointConfig Isso é útil para fornecer AWS credenciais via IRSA (IAM Roles for Service Accounts) para seus contêineres de trabalho ou contêineres de inicialização — por exemplo, para baixar pesos de modelo do Amazon S3 em um cenário alternativo.

Importante

O suporte à conta de serviço personalizada está desativado por padrão e deve ser explicitamente ativado por um administrador do cluster antes do uso. Para obter instruções, consulte Habilitar contas de serviço personalizadas.

Se você não especificar um ServiceAccount, o padrão do namespace será ServiceAccount usado.

Habilitar contas de serviço personalizadas

O suporte à conta de serviço personalizado está desativado por padrão. Um administrador de cluster deve habilitá-lo na configuração do Helm do operador antes que os usuários possam referenciar o personalizado ServiceAccounts em seuInferenceEndpointConfig.

Atualize os valores do operador Helm para ativar o recurso. Se você implantou o operador via Helm, atualize com a bandeira:
```
helm upgrade hyperpod-inference-operator <CHART_PATH> \
  --set enableCustomServiceAccounts=true \
  --reuse-values
```
Se você implantou o operador como um complemento do Amazon EKS, atualize a configuração do complemento para incluí-la enableCustomServiceAccounts: true nas configurações avançadas.

Verifique se o pod do operador tem a variável de ambiente definida:


kubectl get deployment hyperpod-inference-controller-manager \
  -n hyperpod-inference-system \
  -o jsonpath='{.spec.template.spec.containers[0].env}' | jq '.[] | select(.name=="ENABLE_CUSTOM_SERVICE_ACCOUNTS")'

Você deve ver:


{
  "name": "ENABLE_CUSTOM_SERVICE_ACCOUNTS",
  "value": "true"
}

Importante

Se esse recurso não estiver habilitado, qualquer um InferenceEndpointConfig que kubernetes.serviceAccountName especifique será rejeitado com um DeploymentFailed status e a mensagem:kubernetes.serviceAccountName is not enabled. Requires addon configuration (enableCustomServiceAccounts: true).

Etiquete a conta de serviço

Antes que você possa referenciar uma personalização ServiceAccount, um administrador de cluster deve rotulá-la como atribuível ao usuário:


kubectl label serviceaccount <your-service-account> \
  sagemaker.amazonaws.com/user-assignable=true \
  -n <namespace>

Somente ServiceAccounts com esse rótulo podem ser referenciados por endpoints de inferência. Esse é um controle de segurança para evitar o aumento não autorizado de privilégios.

Especifique a conta de serviço em sua configuração

Adicione o serviceAccountName campo abaixo spec.kubernetes em seuInferenceEndpointConfig:


apiVersion: inference.sagemaker.aws.amazon.com/v1
kind: InferenceEndpointConfig
metadata:
  name: my-inference-endpoint
  namespace: my-namespace
spec:
  kubernetes:
    serviceAccountName: my-inference-sa
  # ... rest of your config

Regras de validação

O operador valida o serviceAccountName campo nas operações de criação e atualização. Sua implantação será rejeitada com um DeploymentFailed status se alguma das seguintes condições for atendida:

O ServiceAccount não existe no namespace — serviceAccountName "X" not found in namespace "Y"
ServiceAccount Está faltando a etiqueta exigida — serviceAccountName "X" is not labeled as user-assignable (requires label sagemaker.amazonaws.com/user-assignable=true)
O ServiceAccount é o sistema do operador ServiceAccount — serviceAccountName must not reference the operator's service account

nota

Todos os contêineres no pod de inferência (trabalhador, contêineres de inicialização e sidecars) herdam as permissões do especificado. ServiceAccount Se ServiceAccount estiver anotado comeks.amazonaws.com/role-arn, o pod receberá AWS credenciais temporárias para essa função do IAM. Os administradores de cluster só devem rotular ServiceAccounts como atribuíveis ao usuário depois de analisar as funções do RBAC e as permissões do IAM associadas.

nota

Se a ServiceAccount for excluído enquanto um já InferenceEndpointConfig estiver em execução, os pods existentes continuarão sendo executados com suas credenciais atuais até serem reiniciados. No entanto, a criação de um novo pod (por exemplo, durante o dimensionamento ou o reagendamento) falhará porque ele não existe mais. ServiceAccount O operador valida o ServiceAccount quando a implantação é criada pela primeira vez e quando a especificação IEC é atualizada — ele não monitora continuamente o. ServiceAccount Atualizar a especificação IEC após a exclusão do SA resultará em um DeploymentFailed status.

Práticas recomendadas de segurança para contas de serviço personalizadas

Quando você usa uma personalização ServiceAccount com endpoints de inferência, o operador de HyperPod inferência cria implantações em seu nome. Todos os contêineres no pod de inferência, incluindo o trabalhador, os contêineres de inicialização e os sidecars, herdam as permissões do especificado. ServiceAccount Siga essas práticas recomendadas para proteger seu cluster.

Bloquear as permissões do RBAC

Crie um dedicado ServiceAccount para cada carga de trabalho de inferência. Não reutilize ServiceAccounts em cargas de trabalho não relacionadas.

Vincule somente as permissões mínimas de RBAC necessárias. Por exemplo, se seu contêiner de inicialização só precisa ler do Amazon S3, ele não ServiceAccount deve ter permissões para listar ou modificar recursos do Kubernetes.


# Example: minimal Role for an inference workload that only needs S3 access via IRSA
# No Kubernetes API permissions needed — IRSA provides AWS credentials directly
apiVersion: v1
kind: ServiceAccount
metadata:
  name: my-inference-sa
  namespace: my-namespace
  labels:
    sagemaker.amazonaws.com/user-assignable: "true"
  annotations:
    eks.amazonaws.com/role-arn: arn:aws:iam::<ACCOUNT_ID>:role/<SCOPED_ROLE_NAME>

Evite conceder permissões em todo o cluster (ClusterRoleBindings) para serem ServiceAccounts usadas por pods de inferência.

Escopo das funções do IRSA IAM

Ao anotar um ServiceAccount comeks.amazonaws.com/role-arn, certifique-se de que a função do IAM siga os princípios de menor privilégio.

Defina o escopo das permissões do Amazon S3 para o bucket e o prefixo específicos que contêm os pesos do seu modelo.


{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Action": ["s3:GetObject", "s3:ListBucket"],
    "Resource": [
      "arn:aws:s3:::<YOUR_BUCKET>",
      "arn:aws:s3:::<YOUR_BUCKET>/<YOUR_MODEL_PREFIX>/*"
    ]
  }]
}

Não use políticas gerenciadas amplas, como AmazonS3FullAccess na produção. Use AmazonS3ReadOnlyAccess ou use uma política personalizada com o escopo do seu bucket de modelo.

Proteja a etiqueta atribuível pelo usuário

Somente administradores de cluster devem adicionar ou remover o sagemaker.amazonaws.com/user-assignable=true rótulo. Use o Kubernetes RBAC para restringir quem pode modificar ServiceAccount rótulos em seu namespace.
Analise as funções do RBAC e as permissões do IAM associadas a um ServiceAccount antes de rotulá-lo como atribuível ao usuário.

Audite periodicamente ServiceAccounts quem carrega a user-assignable etiqueta.


kubectl get serviceaccounts -n <NAMESPACE> -l sagemaker.amazonaws.com/user-assignable=true

Certifique-se de que as funções não administrativas não patch incluam update nem create verbos nos ServiceAccount recursos. O operador valida a user-assignable etiqueta no momento da implantação, mas não impede que usuários não autorizados adicionem a etiqueta a um. ServiceAccount Restringir quem pode modificar ServiceAccounts por meio do RBAC é o principal controle para proteger esse rótulo. Non-admin os usuários só devem ter get e list acessar:
```
# Example: RBAC Role for non-admin users — read-only access to ServiceAccounts
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: sa-read-only
  namespace: <NAMESPACE>
rules:
  - apiGroups: [""]
    resources: ["serviceaccounts"]
    verbs: ["get", "list"]
```

Importante

O operador de HyperPod inferência atua como um intermediário que cria implantações em nome dos usuários. Diferentemente das cargas de trabalho padrão do Kubernetes, nas quais o chamador cria pods diretamente, o operador atribui o especificado aos pods que ele cria. ServiceAccount Isso significa que todas as permissões concedidas a um usuário atribuível ServiceAccount estão efetivamente disponíveis para qualquer pessoa que possa criar uma InferenceEndpointConfig nesse namespace. Certifique-se de que o RBAC em nível de namespace controle quem pode criar e atualizar recursos. InferenceEndpointConfig

Pré-carregue os pesos do modelo para o NVMe

Se você precisar preencher previamente o NVMe em nós específicos antes da implantação, você pode usar um pod único para sincronizar a partir do Amazon S3.

nota

Essa abordagem visa um nó específico por meio de nodeName e não funciona com escalonamento automático. Para cenários de escalonamento automático, use o volume Kubernetes com fallback ou o Amazon S3 com abordagens de pré-busca, que tratam modelos ausentes automaticamente por meio da lógica de fallback initContainer.

Crie o arquivo YAML do pod de pré-carregamento. Substitua os valores do espaço reservado pelos seus identificadores de recursos reais.


cat <<EOF> nvme-s3-copy.yaml
apiVersion: v1
kind: Pod
metadata:
  name: nvme-s3-copy
  namespace: default
spec:
  nodeName: <TARGET_NODE>
  restartPolicy: Never
  containers:
    - name: s3-copy
      image: public.ecr.aws/aws-cli/aws-cli:latest
      command: ["/bin/bash", "-c"]
      args:
        - |
          echo "=== Starting S3 sync to NVMe ==="
          aws s3 sync s3://<YOUR_BUCKET>/<YOUR_MODEL>/ /nvme/<YOUR_MODEL>/ --region <YOUR_REGION>
          echo "=== Sync complete ==="
          ls -la /nvme/<YOUR_MODEL>/
          du -sh /nvme/<YOUR_MODEL>/
          echo "=== Done ==="
      volumeMounts:
        - name: nvme-storage
          mountPath: /nvme
  serviceAccountName: default
  volumes:
    - name: nvme-storage
      hostPath:
        path: /opt/dlami/nvme
        type: Directory
EOF

Aplique o pod e monitore o progresso da sincronização.


kubectl apply -f nvme-s3-copy.yaml
kubectl get pod nvme-s3-copy -w
kubectl logs nvme-s3-copy -f

Limpe o pod após a conclusão da sincronização.
```
kubectl delete pod nvme-s3-copy
```

Nomes de volumes reservados

O operador gerencia vários volumes internos que não podem ser substituídos por meio de. kubernetes.volumes Usar qualquer um desses nomes resulta em uma KubernetesVolumeValidationFailed condição.

Nomes de volumes reservados
#	Nome	Finalidade
1	`shm`	Memória compartilhada (`/dev/shm`) para comunicação entre processos
2	`model-weights-copy`	RAM-backed EmptyDir usado quando `prefetchEnabled: true`
3	`parallel-copy-configmap`	ConfigMap para script de cópia paralela (pré-busca)
4	`lmcache-config`	Volume de configuração do LMCache
5	`gated-model-downloader-configmap`	ConfigMap para script de download de modelo fechado

Coisas para lembrar

Não use nomes de volumes reservados. O operador gerencia vários volumes internos (consulteNomes de volumes reservados). Usar qualquer um desses nomes kubernetes.volumes resulta em uma KubernetesVolumeValidationFailed condição.
Os nomes dos volumes devem corresponder. O operador deriva o nome do volume demodelVolumeMount.name. Ao usarmodelSourceType: kubernetesVolume, kubernetes.volumes deve conter um volume com o mesmo nome.
Monte os volumes no local correto em seu initContainer. Certifique-se de que qualquer volume criado esteja montado no caminho correto em seu initContainer.
Nenhuma conta de serviço personalizada é necessária para S3/FSx. Se você não conseguir criar contas de serviço personalizadas ou preferir não criar, você pode usar modelSourceType: s3 oufsx. O operador provisiona S3/FSx volumes automaticamente. Você ainda pode adicionar volumes personalizados initContainers e de substituição ao armazenamento gerenciado pelo operador.
As credenciais do IRSA são injetadas em todos os contêineres. Quando você configura kubernetes.serviceAccountName uma conta de serviço com uma anotação IRSA, o Amazon EKS injeta AWS credenciais (aws-iam-tokenvolume,,AWS_WEB_IDENTITY_TOKEN_FILE) em todos os contêineresAWS_ROLE_ARN, incluindo seus initContainers personalizados.
Não defina modelLocation ao usarkubernetesVolume. O caminho do volume é controlado porkubernetes.volumes. Definir modelLocation quando modelSourceType é kubernetesVolume resulta em um erro de validação.
Entenda como o model-weights vs model-weights-copy funciona com a pré-busca. QuandoprefetchEnabled: true, o operador cria dois volumes relacionados ao modelo:
- model-weights— o volume de origem (do Amazon S3/Amazon FSx PVC ou seu substituto)
- model-weights-copy— um RAM-backed EmptyDir de onde o trabalhador realmente lê
Enquanto você faz referência model-weights em sua configuração, quandoprefetchEnabled: true, na verdade, é isso model-weights-copy que é montado /opt/ml/model no contêiner de trabalho. Ao usar um initContainer personalizado, certifique-se de copiar os dados no volume chamado model-weights-copy — é onde o trabalhador espera encontrá-los. QuandoprefetchEnabled: false, há apenas um volume (com o nome do seumodelVolumeMount.name) e ele é montado diretamente nele/opt/ml/model.

Solução de problemas

Use esses comandos de depuração se a implantação não estiver funcionando conforme o esperado.

Verifique o InferenceEndpointConfig status para ver o estado de implantação de alto nível e quaisquer problemas de configuração.
```
kubectl describe InferenceEndpointConfig <ENDPOINT_NAME> -n <NAMESPACE>
```

Verifique o status da implantação do Kubernetes.


kubectl describe deployment <ENDPOINT_NAME> -n <NAMESPACE>

Verifique o status de todos os objetos do Kubernetes em seu namespace.


kubectl get pods,svc,deployment,InferenceEndpointConfig,sagemakerendpointregistration -n <NAMESPACE>

Verifique os registros do initContainer se a etapa de carregamento do modelo falhar.
```
kubectl logs <POD_NAME> -c smart-loader -n <NAMESPACE>
```
Se a implantação falhar com “não encontrado no namespace”, verifique se existe: ServiceAccount
```
kubectl get serviceaccount <name> -n <namespace>
```
Se a implantação falhar com “não rotulado como atribuível ao usuário”, peça ao administrador do cluster que adicione o rótulo necessário:
```
kubectl label serviceaccount <name> sagemaker.amazonaws.com/user-assignable=true -n <namespace>
```
Se a implantação falhar com “não deve referenciar a conta de serviço do operador”, crie uma separada ServiceAccount para sua carga de trabalho. Você não pode usar o próprio ServiceAccount operador de HyperPod inferência.

Atenção O Javascript está desativado ou não está disponível no seu navegador.

Para usar a documentação da AWS, o Javascript deve estar ativado. Consulte as páginas de Ajuda do navegador para obter instruções.

Convenções do documento

Implante modelos do Amazon S3, Amazon FSx ou Hugging Face Hub usando kubectl

Certificados personalizados e DNS do Route 53