翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。 # HyperPod Inference のカスタム証明書と Route 53 DNS 管理 次の手順では、HyperPod 推論エンドポイントに独自の ACM 証明書を使用し、オプションでカスタムドメインの Route 53 DNS レコードを管理するように演算子を設定する方法を示します。 カスタム証明書では、ACM 証明書 ARN を指定すると、オペレーターはそれを Application Load Balancer (ALB) にアタッチし、その状態をモニタリングし、自動更新検出をサポートします。演算子は、パブリックに信頼された ACM 証明書、 AWS プライベート CA 証明書、および外部 CAs からインポートされた証明書をサポートします。 カスタム証明書は、単独で使用することも、Route 53 DNS 管理と組み合わせることもできます。Route 53 DNS 管理にはカスタム証明書が必要であり、証明書設定のドメイン名を使用して DNS レコードを作成および管理します。 ## 前提条件 開始する前に、以下が整っていることを検証します。 + Amazon SageMaker HyperPod クラスターでの推論機能の設定。詳細については、「[モデルデプロイ用の HyperPod クラスターの設定](sagemaker-hyperpod-model-deployment-setup.md)」を参照してください。 + ターミナルに [kubectl](https://kubernetes.io/docs/reference/kubectl/) をインストールしました。 + HyperPod クラスターと同じ AWS リージョンの ACM で TLS 証明書をプロビジョニングまたはインポートしました。証明書は**発行済み**状態であり、証明書チェーン (中間 CA とルート CA) が含まれている必要があります。ACM にインポートされた自己署名証明書は、証明書チェーンがないため、カスタム証明書としてサポートされていません。 + (Route 53 DNS 管理用) ドメインの Route 53 ホストゾーンを作成しました。パブリックホストゾーンが推奨されます。プライベートホストゾーンはレコード作成に使用できますが、オペレーターは VPC DNS リゾルバーに依存するポッドの DNS リゾルバーを使用して 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 ステートメントを追加するだけで済みます。 ### DNS 管理のための Route 53 アクセス許可 ``` { "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`セクションを追加します。フィールド`tlsConfig`と `dnsConfig`フィールドは両方の CRDs。 `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 署名証明書が置き換えられます。 ## 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 レコードを作成します。 を使用してデプロイすると`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 固有のエラーを確認します。 ## Route 53 DNS 管理なしでカスタム証明書を使用する Route 53 DNS 管理はオプションです。独自の DNS レコードを管理する場合は、 `dnsConfig`セクションを省略し、ドメインを手動で設定します。 デプロイの ALB ホスト名を見つけるには、入力名はインテリジェントルーティングが有効になっているかどうかによって異なります。 **インテリジェントルーティングなし:** Ingress は名前空間`alb-`に名前が付けられます。 ``` kubectl get ingress alb- -n \ -o jsonpath='{.status.loadBalancer.ingress[0].hostname}' ``` **インテリジェントルーティングの場合:** Ingress は `hyperpod-inference-system`名前空間`alb--`に名前が付けられます。 ``` kubectl get ingress alb-- -n hyperpod-inference-system \ -o jsonpath='{.status.loadBalancer.ingress[0].hostname}' ``` ドメインがこの ALB ホスト名を指す DNS プロバイダーに DNS レコードを作成します。 + **Route 53** — ALB を指す**エイリアス**を有効にして **A レコード**を作成します。 + **その他の DNS プロバイダー** — ドメインを ALB DNS 名を指す **CNAME レコード**を作成します。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 レコードは正常に解決されます。カスタムドメインを使用する準備ができました。 + **保留中** — DNS レコードは Route 53 で作成されていますが、まだ伝播されていません。オペレーターは 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 エンドポイントを介して を呼び出すには、 `InferenceEndpointConfig`または `sageMakerEndpoint.name` `JumpStartModel` 仕様`endpointName`で を設定します。が設定され`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` ( の場合`customCertificateConfig`) または `hostedZoneId` ( の場合`dnsConfig`) を更新できます。ドメイン名を変更すると、証明書の再検証と 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 レコードが親ドメインレジストラから適切に委任されていることを確認します。演算子はポッドの DNS リゾルバー (通常は CoreDNS) を使用します。これにより、結果がキャッシュされる可能性があります。解決せずに 10 分経過すると、ステータスは に移行します`Error`。 + **証明書の有効期限に関する警告。**ACM で証明書を更新または置き換えます。ACM が発行した証明書の場合、ACM は自動的に更新を処理します。インポートされた証明書の場合は、新しい証明書をインポートします。オペレーターは更新を自動的に検出し、パブリック証明書を Amazon S3 に再アップロードします。