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

Implante modelos do armazenamento NVMe local usando kubectl

Este tópico mostra como implantar endpoints de inferência na Amazon SageMaker HyperPod que carregam pesos do modelo do armazenamento NVMe local de um nó em vez de extraí-los da rede 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 escaláveis a partir de 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 fsx pule este tópico.

O NVMe local é local e efêmero: 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ê preencha previamente cada nó, outras recorrem automaticamente ao Amazon S3 quando o modelo não é armazenado em cache localmente. O armazenamento de instâncias NVMe locais geralmente é 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 retorno)	Use quando existirem pesos do 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 ferramenta personalizada `initContainer` que verifica primeiro o NVMe e baixa do Amazon S3 usando as credenciais do IRSA se o modelo estiver ausente.
3	Amazon S3 com pré-busca e fallback	Use quando quiser transferir os pesos do modelo para a RAM para inicialização do pod. Você fornece um recurso personalizado `initContainer` que verifica primeiro o NVMe e volta a copiar a partir 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 no NVMe para obter instruções).

Escolha sua abordagem de implantação

Use o fluxo de decisão a seguir para determinar qual abordagem é adequada 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.   │  └──────────────────────┘
                  └──────────────────┘

Implemente usando um volume Kubernetes (sem retorno)

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 do Amazon FSx, sem e sem initContainers. PV/PVC

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 de sua configuração modelVolumeMount.name de trabalho. 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 por 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

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

Implemente usando um volume Kubernetes com fallback

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

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

Configurar o IRSA

Antes da implantação, configure funções do IAM para contas de serviço (IRSA) para fornecer credenciais aos seus pods 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 definido para seu bucket de modelos.


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 do 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 por 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

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

Implemente usando o Amazon S3 com pré-busca e alternativa de NVMe

Use essa abordagem quando quiser desempenho de inferência 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 do seu modelVolumeMount.name (normalmentemodel-weights) — um suporte de fusível Amazon S3 CSI 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 do suporte do Amazon S3 (model-weights) para a RAM (model-weights-copy). Opcionalmente, copia para o NVMe para que as startups subsequentes do pod no mesmo nó usem o caminho local rápido.

Importante

Não substitua model-weights 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 por 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

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 a pré-busca

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

Um volume com o nome do seu modelVolumeMount.name (normalmentemodel-weights) — um suporte de fusível Amazon S3 CSI 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ênciamodel-weights, 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 chamadomodel-weights-copy, que é onde o trabalhador espera encontrá-los.

QuandoprefetchEnabled: false, há apenas um volume (com o nome do seumodelVolumeMount.name) e ele é montado diretamente em/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 iniciais — por exemplo, para baixar pesos de modelos 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 pelo administrador do cluster antes do uso. Para obter instruções, consulte Ativar contas de serviço personalizadas.

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

Ativar contas de serviço personalizadas

O suporte à conta de serviço personalizada 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 seusInferenceEndpointConfig.

Atualize os valores do Helm do operador 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-operator-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).

Identifique a conta de serviço

Antes de fazer referência a uma personalização ServiceAccount, um administrador de cluster deve rotulá-la como atribuível pelo usuário:


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

Somente ServiceAccounts com esse rótulo pode ser referenciado 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 necessária — serviceAccountName "X" is not labeled as user-assignable (requires label sagemaker.amazonaws.com/user-assignable=true)
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 (worker, contêineres init e sidecars) herdam as permissões especificadas. ServiceAccount Se ServiceAccount for 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 pelo usuário depois de analisar as funções RBAC associadas e as permissões do IAM.

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 escalonamento ou o reagendamento) falhará porque o não existe mais. ServiceAccount O operador valida ServiceAccount quando a implantação é criada pela primeira vez e quando a especificação IEC é atualizada — ele não monitora continuamente o. ServiceAccount A atualização da 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 um personalizado 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 worker, os contêineres de inicialização e os sidecars, herdam as permissões especificadas. ServiceAccount Siga essas melhores práticas para proteger seu cluster.

Bloqueie as permissões do RBAC

Crie uma carga de trabalho dedicada ServiceAccount para cada 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 ser lido do Amazon S3, ele não deve ter permissões para listar ou modificar recursos ServiceAccount 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: 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 privilégio mínimo.

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 de forma ampla, como AmazonS3FullAccess na produção. Use AmazonS3ReadOnlyAccess ou uma política personalizada com escopo definido para seu repositório de modelos.

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 os rótulos no seu namespace.
Analise as funções do RBAC e as permissões do IAM associadas a ServiceAccount antes de rotulá-la como atribuível pelo usuário.

Audite periodicamente quais ServiceAccounts possuem 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 incluam patch nem create verbos nos ServiceAccount recursos. update 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 uma. ServiceAccount Restringir quem pode modificar ServiceAccounts via 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. Ao contrário 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 no NVMe

Se você precisar pré-preencher 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 do escalonamento automático nodeName e não funciona com ele. 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 do InitContainer.

Crie o arquivo YAML do pod de pré-carregamento. Substitua os valores do espaço reservado por 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 via. 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 de. modelVolumeMount.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, você pode usar modelSourceType: s3 oufsx. O operador provisiona S3/FSx os volumes automaticamente. Você ainda pode adicionar volumes personalizados initContainers e de substituição sobre o 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 isso 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ê
Embora você faça 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 chamadomodel-weights-copy, que é onde o trabalhador espera encontrá-los. QuandoprefetchEnabled: false, há apenas um volume (com o nome do seumodelVolumeMount.name) e ele é montado diretamente em/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 pelo 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 da operadora”, crie uma conta 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 Route 53 DNS