本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。 # 用于 HyperPod 推理的自定义证书和 Route 53 DNS 管理 以下步骤向您展示如何使用自己的 ACM 证书作为 HyperPod推理终端节点，以及如何选择配置操作员以管理自定义域的 Route 53 DNS 记录。 使用自定义证书，您可以提供 ACM 证书 ARN，操作员将其附加到 Application Load Balancer (ALB)，监控其运行状况，并支持自动续订检测。操作员支持公开信任的 ACM 证书、 AWS 私有 CA 证书和从外部 CA 导入的证书。 自定义证书可以单独使用，也可以与 Route 53 DNS 管理结合使用。Route 53 DNS 管理需要自定义证书，并使用您的证书配置中的域名来创建和管理 DNS 记录。 ## 先决条件 在开始之前，请确认您已经： + 在您的 Amazon SageMaker HyperPod 集群上设置推理功能。有关更多信息，请参阅 [设置 HyperPod 集群以进行模型部署](sagemaker-hyperpod-model-deployment-setup.md)。 + 在你的终端中安装了 [kubectl](https://kubernetes.io/docs/reference/kubectl/)。 + 在 ACM 中配置或导入了 TLS 证书，该证书与您的 HyperPod 集群位于同一 AWS 区域。证书必须处于 “**已颁发**” 状态，并且必须包含证书链（中间证书和根 CA）。 Self-signed 不支持导入到 ACM 的证书作为自定义证书，因为它们缺少证书链。 + （用于 Route 53 的 DNS 管理）为您的域创建了 Route 53 托管区域。建议使用公共托管区域。私有托管区域用于创建记录，但运营商使用容器的 DNS 解析器验证 DNS 解析器，该解析器依赖于 VPC DNS 解析器。对于私有托管区域，VPC 必须启用 DNS 解析和 DNS 主机名，并且私有托管区域必须与集群的 VPC 关联。 ## 配置 IAM 权限 推理运算符的执行角色需要自定义证书和 Route 53 DNS 管理的额外权限。将以下策略添加到您的 HyperPod 推理执行角色中。 ### ACM 和 Amazon S3 对自定义证书的权限 ``` { "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" } } } ] } ``` **注意** 如果您的 Amazon S3 存储桶名称以开头`hyperpod-tls`，则表示 Amazon S3 权限已包含在`AmazonSageMakerHyperPodInferenceAccess`托管策略中，您只需添加 ACM 语句即可。 ### Route 53 的 DNS 管理权限 ``` { "Version": "2012-10-17", "Statement": [ { "Sid": "Route53DNSManagement", "Effect": "Allow", "Action": [ "route53:GetHostedZone", "route53:ListResourceRecordSets", "route53:ChangeResourceRecordSets" ], "Resource": "arn:aws:route53:::hostedzone/" } ] } ``` 将``、````、和，``替换为实际值。您可以将 ACM 资源 ARN 的范围限定为特定的证书，以提高安全性。 ## 配置自定义证书 要使用自定义证书，请在`InferenceEndpointConfig`或`JumpStartModel`规范`tlsConfig`中将该`customCertificateConfig`部分添加到您的中。两个 CRD 中的`tlsConfig`和`dnsConfig`字段相同。 `customCertificateConfig`和中提供了以下字段`tlsConfig`： `tlsConfig.customCertificateConfig.acmArn`（必填，字符串） 您的 ACM 证书的 ARN。必须处于 “**已发放**” 状态。 `tlsConfig.customCertificateConfig.domainName`（必填，字符串） 证书中要使用的域名。 + 必须是特定的域名，而不是通配符。对于通配符证书（例如，`*.example.com`），请指定特定的子域（例如）。`api.example.com` + 必须是小写字母。 + 必须与证书中列出的其中一个域名相匹配。 `tlsConfig.tlsCertificateOutputS3Uri`（有条件，字符串） 操作员上传公共证书的 Amazon S3 URI。除非操作员安装时配置了`TLS_CERTIFICATE_OUTPUT_S3URI`环境变量，否则为必填项。如果您不确定是否已设置，请明确指定。 以下是使用自定义证书创建端点的 YAML 文件示例。 ``` 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" ``` 您可以`customCertificateConfig`向已在运行的部署中进行添加。操作员在下次对账时检测到更改，验证证书，将其附加到 ALB，然后将公共证书上传到 Amazon S3。无需停机或重新部署。 **重要** 如果您从正在运行的部署中删除该`customCertificateConfig`部分，则操作员会回退到生成新的自签名证书。这将替换您在 ALB 上的 CA-signed 证书。 ## 配置 Route 53 的 DNS 管理 Route 53 DNS 管理需要配置自定义证书，并使用来自的域名`tlsConfig.customCertificateConfig.domainName`。如果您尚未配置自定义证书，请[配置自定义证书](#sagemaker-hyperpod-model-deployment-custom-certs-configure)先参见。 要启用 Route 53 DNS 管理，请在您的规范中添加以下`dnsConfig`部分： ``` 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 ``` 该`dnsConfig`部分可以与现有部署同时添加`customCertificateConfig`，也可以稍后添加到现有部署中。操作员在下次协调时创建 DNS 记录，无需重启你的 pod。 使用部署时`dnsConfig`，操作员： 1. 验证托管区域是否存在以及您的域是否属于托管区域（例如，`api.example.com`需要托管区域`example.com`）。 1. 检查目标域中是否存在现有 A 记录，以防止意外覆盖。 1. 创建**一条将您的域名指向 ALB 的 A 记录**（别名），以及一条带有所有权标记 (`hyperpod-inference/owner=/`) 的 **TXT 记录**以防止端点之间发生冲突。请勿手动修改或删除 TXT 记录。 1. 每 30 秒轮询一次 DNS 解析度，直到域名解析，然后将状态标记为`Active`。如果记录未在 10 分钟内解析，则状态将转换为`Error`。 **注意** Route 53 的 DNS 管理是非阻塞的。DNS 记录创建或传播中的错误不会阻止您的推理终端节点进入`Ready`状态。仍可通过 ALB 的默认主机名访问该端点。检查资源状态中的`dnsStatus`部分是否有 DNS-specific 错误。 ## 使用不管理 Route 53 DNS 的自定义证书 Route 53 的 DNS 管理是可选的。如果您想管理自己的 DNS 记录，请省略该`dnsConfig`部分并手动配置您的域。 要查找部署的 ALB 主机名，入口名称取决于是否启用了智能路由。 **没有智能路由：**入口`alb-`在你的命名空间中命名。 ``` kubectl get ingress alb- -n \ -o jsonpath='{.status.loadBalancer.ingress[0].hostname}' ``` **使用智能路由：**入口在命名`hyperpod-inference-system`空间`alb--`中命名。 ``` kubectl get ingress alb-- -n hyperpod-inference-system \ -o jsonpath='{.status.loadBalancer.ingress[0].hostname}' ``` 在您的 DNS 提供商中创建 DNS 记录，将您的域名指向此 ALB 主机名： + **Route 53** — 在启用**别名的**情况下创建 **A 记录**，指向 ALB。 + **其他 DNS 提供商** — 创建一条将您的域**名指向 ALB DNS 名称的别名记录记录**。CNAME 记录不能用于根域（例如`example.com`）；请使用类似的子域名。`api.example.com` **注意** 如果重新创建 ALB（例如，在删除并重新部署终端节点之后），ALB 的主机名会发生变化。您必须手动更新 DNS 记录。Route 53 的 DNS 管理会自动处理这个问题。 ## 确认部署状态 ### 检查自定义证书状态 ``` kubectl describe InferenceEndpointConfig my-model -n my-namespace ``` 在状态下查找相应`tlsCertificate`部分： ``` 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 ``` 证书运行状况值： + **有效**-证书到期后超过 60 天。 + **即将到期**-证书将在 60 天内过期。会发出一个 Kubernetes 警告事件 (`CertificateExpiring`)。 + **已过期**-证书已过期。会发出一个 Kubernetes 警告事件 (`CertificateExpired`)。 操作员每 24 小时检查一次证书到期时间。当它在 ACM 中检测到证书已续订（`NotAfter`日期变更）时，它会自动将公共证书重新上传到 Amazon S3 并发出事件。`CertificateRenewed` ### 检查 DNS 状态 查找以下`dnsStatus`部分： ``` Status: Dns Status: Managed By Operator: true Record Name: api.example.com Hosted Zone Id: Z1234567890ABC Dns Health: Active Message: DNS record resolves successfully ``` DNS 运行状况值： + **活动** — DNS 记录已成功解析。您的自定义域名已准备就绪，可供使用。 + **待处理** — 已在 Route 53 中创建了 DNS 记录，但尚未传播。操作员每 30 秒重新检查一次。 + **错误**-DNS 记录创建或传播失败。有关详细信息，请查看该`Message`字段。 ### 测试已部署的终端节点 如果您配置了 Route 53 DNS 管理，请在显示 DNS 状态后使用您的自定义域调用您的终端节点`Active`。如果您只配置了不带 DNS 管理的自定义证书，请使用入口的 ALB 主机名（请参阅[使用不管理 Route 53 DNS 的自定义证书](#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"}]}' ``` **注意** 要通过 SageMaker AI 端点进行调用，请在您的规范`endpointName`中`InferenceEndpointConfig`或您的`JumpStartModel`规范`sageMakerEndpoint.name`中进行设置。如果未设置，`endpointName`则不创建 SageMaker AI 终端节点，只能直接调用 ALB。 ``` 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 ``` ## 管理您的自定义证书和 DNS 记录 **更改域名或托管区域** 您可以在正在运行的部署上更新 `domainName``hostedZoneId`（中 `customCertificateConfig``dnsConfig`）或（in）。更改域名会同时触发证书重新验证和 DNS 切换 — 新域名在您的 ACM 证书中必须有效（作为 SAN 或通配符匹配）。 操作员执行安全切换： 1. 在新区域或新域中创建新的 DNS 记录。 1. 验证新记录是否已解析。 1. 只有在新记录被确认处于活动状态后，才会删除旧的 DNS 记录。 在过渡期间，新旧域名都将解析为 ALB。TXT 所有权记录的 TTL 为 300 秒（5 分钟），因此 DNS 客户端可以在清理后将旧记录缓存最多 5 分钟。 **清除** 当您删除`InferenceEndpointConfig`或移除该路`dnsConfig`段时，操作员会自动删除其创建的 Route 53 A 和 TXT 记录。操作员仅删除其拥有的记录（由所有权 TXT 记录验证）。 ## 问题排查 如果您的自定义证书或 DNS 配置未按预期运行，请使用以下调试步骤。 + **部署失败，出现 Amazon S3 访问错误。**验证中指定的 Amazon S3 存储桶`tlsCertificateOutputS3Uri`存在且位于同一区域。验证操作员的执行角色对存储桶拥有`s3:PutObject`和`s3:PutObjectTagging`权限。操作员通过在初始部署期间上传零字节测试对象来验证 Amazon S3 的写入权限。 + **证书验证失败。**验证 ACM 证书的`ISSUED`状态为：`aws acm describe-certificate --certificate-arn --region `。验证证书中的域或 SAN 是否`domainName`匹配。对于通配符证书 (`*.example.com`)，请使用特定的子域名，例如。`api.example.com` + **创建 DNS 记录失败。**验证托管区域 ID 是否正确且操作员的执行角色具有 Route 53 权限。验证域属于托管区域（例如，`api.example.com`需要托管区域`example.com`）。如果您看到 NS 委托冲突，请改用委托区域的托管区域 ID。如果您看到记录冲突，则说明另一个端点或外部进程拥有该域的 A 记录。 + **DNS 记录显示长时间待定。**验证托管区域的 NS 记录是否已由父域注册商正确委托。操作员使用 pod 的 DNS 解析器（通常是 CoreDNS），该解析器可能会缓存结果。10 分钟未解决问题后，状态将转换为`Error`。 + **证书到期警告。**在 ACM 中续订或替换证书。对于 ACM-issued 证书，ACM 会自动处理续订。对于导入的证书，请导入新证书。操作员会自动检测到续订情况，并将公共证书重新上传到 Amazon S3。