As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá. # Certificados personalizados e gerenciamento de DNS do Route 53 para HyperPod inferência As etapas a seguir mostram como usar seus próprios certificados ACM para endpoints de HyperPod inferência e, opcionalmente, configurar o operador para gerenciar os registros DNS do Route 53 para seu domínio personalizado. Com certificados personalizados, você fornece um certificado ACM ARN e o operador o anexa ao Application Load Balancer (ALB), monitora sua integridade e oferece suporte à detecção automática de renovação. O operador oferece suporte a certificados ACM de confiança pública, certificados de CA AWS privada e certificados importados de CAs externas. Os certificados personalizados podem ser usados sozinhos ou combinados com o gerenciamento de DNS do Route 53. O gerenciamento de DNS do Route 53 requer um certificado personalizado e usa o nome de domínio da configuração do seu certificado para criar e gerenciar registros DNS. ## 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](sagemaker-hyperpod-model-deployment-setup.md). + O [kubectl](https://kubernetes.io/docs/reference/kubectl/) foi instalado em seu terminal. + Provisionou ou importou um certificado TLS no ACM na mesma AWS região do seu cluster. HyperPod O certificado deve estar no estado **Emitido** e incluir uma cadeia de certificados (CA intermediária e raiz). Self-signed os certificados importados para o ACM não são aceitos como certificados personalizados porque não possuem uma cadeia de certificados. + (Para gerenciamento de DNS do Route 53) Criou uma zona hospedada do Route 53 para seu domínio. Zonas hospedadas públicas são recomendadas. As zonas hospedadas privadas funcionam para a criação de registros, mas o operador verifica a resolução do DNS usando o resolvedor de DNS do pod, que depende do resolvedor de DNS da VPC. Para zonas hospedadas privadas, a VPC deve ter a resolução DNS e os nomes de host DNS habilitados, e a zona hospedada privada deve estar associada à VPC do cluster. ## Configurar permissões do IAM A função de execução do operador de inferência exige permissões adicionais para certificados personalizados e gerenciamento de DNS do Route 53. Adicione as políticas a seguir à sua função de execução de HyperPod inferência. ### Permissões do ACM e do Amazon S3 para certificados personalizados ``` { "Version": "2012-10-17", "Statement": [ { "Sid": "ACMCustomCertificateAccess", "Effect": "Allow", "Action": [ "acm:DescribeCertificate", "acm:GetCertificate" ], "Resource": "arn:aws:acm:::certificate/*" }, { "Sid": "S3CertificateUpload", "Effect": "Allow", "Action": [ "s3:PutObject", "s3:PutObjectTagging" ], "Resource": "arn:aws:s3:::/*", "Condition": { "StringEquals": { "s3:RequestObjectTag/CreatedBy": "HyperPodInference" } } } ] } ``` **nota** Se o nome do seu bucket do Amazon S3 começar com`hyperpod-tls`, as permissões do Amazon S3 já estão incluídas na política gerenciada e você só precisa adicionar a declaração `AmazonSageMakerHyperPodInferenceAccess` do ACM. ### Permissões do Route 53 para gerenciamento de DNS ``` { "Version": "2012-10-17", "Statement": [ { "Sid": "Route53DNSManagement", "Effect": "Allow", "Action": [ "route53:GetHostedZone", "route53:ListResourceRecordSets", "route53:ChangeResourceRecordSets" ], "Resource": "arn:aws:route53:::hostedzone/" } ] } ``` Substitua ````,``,, e `` por seus valores reais. Você pode definir o escopo do ARN do recurso ACM para certificados específicos para maior segurança. ## Configurar um certificado personalizado Para usar um certificado personalizado, adicione a `customCertificateConfig` seção à sua `tlsConfig` na `JumpStartModel` especificação `InferenceEndpointConfig` ou. Os `dnsConfig` campos `tlsConfig` e são idênticos nos dois CRDs. Os campos a seguir estão disponíveis em `customCertificateConfig` e`tlsConfig`: `tlsConfig.customCertificateConfig.acmArn`(Obrigatório, Cadeia de caracteres) O ARN do seu certificado ACM. Deve estar no estado **emitido**. `tlsConfig.customCertificateConfig.domainName`(Obrigatório, Cadeia de caracteres) O nome de domínio a ser usado no certificado. + Deve ser um domínio específico, não um curinga. Para certificados curinga (por exemplo,`*.example.com`), especifique o subdomínio específico (por exemplo,`api.example.com`). + Deve estar em minúsculas. + Deve corresponder a um dos nomes de domínio listados no certificado. `tlsConfig.tlsCertificateOutputS3Uri`(Condicional, Cadeia de caracteres) URI do Amazon S3 em que o operador carrega o certificado público. Obrigatório, a menos que o operador tenha sido instalado com a variável de `TLS_CERTIFICATE_OUTPUT_S3URI` ambiente configurada. Se você não tiver certeza se isso foi definido, especifique-o explicitamente. Veja a seguir um exemplo de arquivo YAML para criar um endpoint com um certificado personalizado. ``` apiVersion: inference.sagemaker.aws.amazon.com/v1 kind: InferenceEndpointConfig metadata: name: my-model namespace: my-namespace spec: modelName: my-llm instanceType: ml.g5.24xlarge invocationEndpoint: v1/chat/completions replicas: 2 modelSourceConfig: modelSourceType: s3 s3Storage: bucketName: my-model-bucket region: us-west-2 modelLocation: models/my-llm tlsConfig: customCertificateConfig: acmArn: arn:aws:acm:us-west-2:123456789012:certificate/abc12345-1234-1234-1234-abc123456789 domainName: api.example.com tlsCertificateOutputS3Uri: s3://my-tls-bucket worker: image: my-inference-image:latest modelInvocationPort: containerPort: 8000 name: http modelVolumeMount: name: model-weights mountPath: /opt/ml/model resources: limits: nvidia.com/gpu: "4" requests: cpu: "6" memory: 30Gi nvidia.com/gpu: "4" ``` Você pode adicionar `customCertificateConfig` a uma implantação que já está em execução. O operador detecta a alteração na próxima reconciliação, valida o certificado, o anexa ao ALB e carrega o certificado público no Amazon S3. Não é necessário tempo de inatividade ou reimplantação. **Importante** Se você remover a `customCertificateConfig` seção de uma implantação em execução, o operador voltará a gerar um novo certificado autoassinado. Isso substitui seu CA-signed certificado no ALB. ## Configurar o gerenciamento de DNS do Route 53 O gerenciamento de DNS do Route 53 exige que um certificado personalizado seja configurado e use o nome de domínio de`tlsConfig.customCertificateConfig.domainName`. Se você não configurou um certificado personalizado, consulte [Configurar um certificado personalizado](#sagemaker-hyperpod-model-deployment-custom-certs-configure) primeiro. Para habilitar o gerenciamento de DNS do Route 53, adicione a `dnsConfig` seção à sua especificação: ``` spec: tlsConfig: customCertificateConfig: acmArn: arn:aws:acm:us-west-2:123456789012:certificate/abc12345-1234-1234-1234-abc123456789 domainName: api.example.com tlsCertificateOutputS3Uri: s3://my-tls-bucket dnsConfig: hostedZoneId: Z1234567890ABC ``` A `dnsConfig` seção pode ser adicionada ao mesmo `customCertificateConfig` tempo ou adicionada posteriormente a uma implantação existente. O operador cria os registros DNS na próxima reconciliação sem reiniciar seus pods. Quando você implanta com`dnsConfig`, o operador: 1. Valida que a zona hospedada existe e que seu domínio pertence à zona hospedada (por exemplo, `api.example.com` requer uma zona hospedada para`example.com`). 1. Verifica os registros A existentes no domínio de destino para evitar substituições acidentais. 1. Cria **um registro** A (alias) apontando seu domínio para o ALB e um **registro TXT** com um marcador de propriedade (`hyperpod-inference/owner=/`) para evitar conflitos entre endpoints. Não modifique nem exclua o registro TXT manualmente. 1. Pesquisa a resolução do DNS a cada 30 segundos até que o domínio seja resolvido e, em seguida, marca o status como. `Active` Se o registro não for resolvido em 10 minutos, o status mudará para`Error`. **nota** O gerenciamento de DNS do Route 53 não bloqueia. Erros na criação ou propagação do registro DNS não impedem que seu endpoint de inferência alcance o estado. `Ready` O endpoint permanece acessível por meio do nome de host padrão do ALB. Verifique se há DNS-specific erros na `dnsStatus` seção de status do recurso. ## Use um certificado personalizado sem o gerenciamento de DNS do Route 53 O gerenciamento de DNS do Route 53 é opcional. Se você quiser gerenciar seus próprios registros DNS, omita a `dnsConfig` seção e configure seu domínio manualmente. Para encontrar o nome do host ALB para sua implantação, o nome de entrada depende se o roteamento inteligente está habilitado. **Sem roteamento inteligente:** a entrada é nomeada `alb-` em seu namespace. ``` kubectl get ingress alb- -n \ -o jsonpath='{.status.loadBalancer.ingress[0].hostname}' ``` **Com roteamento inteligente:** a entrada é nomeada `alb--` no namespace. `hyperpod-inference-system` ``` kubectl get ingress alb-- -n hyperpod-inference-system \ -o jsonpath='{.status.loadBalancer.ingress[0].hostname}' ``` Crie um registro DNS em seu provedor de DNS apontando seu domínio para este nome de host ALB: + **Route 53** — Crie **um registro A** com o **Alias** ativado, apontando para o ALB. + **Outros provedores de DNS** — Crie um **registro CNAME apontando seu domínio para o nome** DNS do ALB. Os registros CNAME não podem ser usados no domínio raiz (por exemplo,`example.com`); use um subdomínio como. `api.example.com` **nota** Se o ALB for recriado (por exemplo, depois de excluir e reimplantar o endpoint), o nome do host do ALB será alterado. Você deve atualizar seu registro DNS manualmente. O gerenciamento de DNS do Route 53 lida com isso automaticamente. ## Verificar o status da implantação ### Verifique o status do certificado personalizado ``` kubectl describe InferenceEndpointConfig my-model -n my-namespace ``` Procure a `tlsCertificate` seção no status: ``` Status: Tls Certificate: Certificate ARN: arn:aws:acm:us-west-2:123456789012:certificate/abc12345-... Certificate Health: Valid Certificate Domain Names: api.example.com Last Cert Expiry Time: 2027-04-23T00:00:00Z ``` Valores de saúde do certificado: + **Válido** — O certificado é válido há mais de 60 dias a partir da expiração. + **Expirando** — O certificado expira em 60 dias. Um evento de aviso do Kubernetes (`CertificateExpiring`) é emitido. + **Expirado** — O certificado expirou. Um evento de aviso do Kubernetes (`CertificateExpired`) é emitido. O operador verifica a expiração do certificado a cada 24 horas. Quando detecta que um certificado foi renovado no ACM (a `NotAfter` data muda), ele recarrega automaticamente o certificado público para o Amazon S3 e emite um evento. `CertificateRenewed` ### Verifique o status do DNS Procure a `dnsStatus` seção: ``` Status: Dns Status: Managed By Operator: true Record Name: api.example.com Hosted Zone Id: Z1234567890ABC Dns Health: Active Message: DNS record resolves successfully ``` Valores de integridade do DNS: + **Ativo** — O registro DNS é resolvido com êxito. Seu domínio personalizado está pronto para uso. + **Pendente** — os registros DNS foram criados no Route 53, mas ainda não foram propagados. O operador verifica novamente a cada 30 segundos. + **Erro** — Falha na criação ou propagação do registro DNS. Verifique o `Message` campo para obter detalhes. ### Teste o endpoint implantado Se você configurou o gerenciamento de DNS do Route 53, invoque seu endpoint usando seu domínio personalizado depois que o status do DNS for exibido. `Active` Se você configurou somente um certificado personalizado sem gerenciamento de DNS, use o nome do host ALB da entrada (consulte). [Use um certificado personalizado sem o gerenciamento de DNS do Route 53](#sagemaker-hyperpod-model-deployment-custom-certs-no-dns) ``` curl -X POST https://api.example.com/v1/chat/completions \ -H "Content-Type: application/json" \ -d '{"model": "my-llm", "messages": [{"role": "user", "content": "Hello"}]}' ``` **nota** Para invocar por meio do endpoint de SageMaker IA, defina `endpointName` em sua `InferenceEndpointConfig` ou `sageMakerEndpoint.name` em sua `JumpStartModel` especificação. Se não `endpointName` estiver definido, nenhum endpoint de SageMaker IA será criado e somente a invocação direta do ALB estará disponível. ``` aws sagemaker-runtime invoke-endpoint \ --endpoint-name my-model \ --content-type "application/json" \ --body '{"model": "my-llm", "messages": [{"role": "user", "content": "Hello"}]}' \ --region us-west-2 \ --cli-binary-format raw-in-base64-out \ /dev/stdout ``` ## Gerencie seus certificados personalizados e registros DNS **Alterando o domínio ou a zona hospedada** Você pode atualizar o `domainName` (in`customCertificateConfig`) ou `hostedZoneId` (in`dnsConfig`) em uma implantação em execução. A alteração do nome de domínio aciona a revalidação do certificado e a substituição do DNS — o novo domínio deve ser válido em seu certificado ACM (como uma combinação de SAN ou curinga). O operador realiza uma transição segura: 1. Cria novos registros DNS na nova zona ou para o novo domínio. 1. Verifica a resolução dos novos registros. 1. Exclui os registros DNS antigos somente depois que os novos registros forem confirmados como ativos. Durante a transição, os domínios antigos e novos são transferidos para o ALB. O registro de propriedade TXT tem um TTL de 300 segundos (5 minutos), então os clientes DNS podem armazenar em cache o registro antigo por até 5 minutos após a limpeza. **Limpeza** Quando você exclui `InferenceEndpointConfig` ou remove a `dnsConfig` seção, o operador exclui automaticamente os registros do Route 53 A e TXT que ele criou. O operador exclui somente os registros de sua propriedade (verificados pelo registro TXT de propriedade). ## Solução de problemas Use essas etapas de depuração se seu certificado personalizado ou configuração de DNS não estiver funcionando conforme o esperado. + **A implantação falha com erro de acesso ao Amazon S3.** Verifique se o bucket do Amazon S3 especificado em `tlsCertificateOutputS3Uri` existe e está na mesma região. Verifique se a função de execução do operador tem `s3:PutObject` `s3:PutObjectTagging` permissões no bucket. O operador valida o acesso de gravação ao Amazon S3 fazendo o upload de um objeto de teste de zero bytes durante a implantação inicial. + **Falha na validação do certificado.** Verifique se o certificado ACM está no `ISSUED` estado:`aws acm describe-certificate --certificate-arn --region `. Verifique se `domainName` corresponde a um domínio ou SAN no certificado. Para certificados curinga (`*.example.com`), use um subdomínio específico, como. `api.example.com` + **Falha na criação do registro DNS.** Verifique se o ID da zona hospedada está correto e se a função de execução do operador tem permissões do Route 53. Verifique se o domínio pertence à zona hospedada (por exemplo, `api.example.com` requer uma zona hospedada para`example.com`). Se você observar um conflito de delegação de NS, use o ID da zona hospedada da zona delegada. Se você observar um conflito de registros, outro endpoint ou processo externo possui o registro A nesse domínio. + **O registro DNS mostra Pendente por tempo prolongado.** Verifique se os registros NS da zona hospedada estão devidamente delegados pelo registrador do domínio principal. O operador usa o resolvedor de DNS do pod (normalmente CoreDNS), que pode armazenar os resultados em cache. Após 10 minutos sem resolução, o status muda para`Error`. + **Avisos de expiração do certificado.** Renove ou substitua o certificado no ACM. Para ACM-issued certificados, o ACM processa a renovação automaticamente. Para certificados importados, importe um novo certificado. O operador detecta a renovação automaticamente e recarrega o certificado público para o Amazon S3.