기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다. # HyperPod 추론을 위한 사용자 지정 인증서 및 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)을 포함해야 합니다. 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 호스트 이름을 찾으려면 지능형 라우팅 활성화 여부에 따라 수신 이름이 달라집니다. **지능형 라우팅 사용 안 함:** 네임스페이스`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 공급자에서 도메인이이 ALB 호스트 이름을 가리키도록 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` 또는 사양`endpointName`에서 `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` (`customCertificateConfig`) 또는 `hostedZoneId` (`dnsConfig`)를 업데이트할 수 있습니다. 도메인 이름을 변경하면 인증서 재검증과 DNS 전환이 모두 트리거됩니다. 새 도메인은 ACM 인증서(SAN 또는 와일드카드 일치)에서 유효해야 합니다. 운영자는 안전한 전환을 수행합니다. 1. 새 영역 또는 새 도메인에 대한 새 DNS 레코드를 생성합니다. 1. 새 레코드가 확인되는지 확인합니다. 1. 새 레코드가 활성 상태로 확인된 후에만 이전 DNS 레코드를 삭제합니다. 전환 중에 이전 도메인과 새 도메인이 모두 ALB로 확인됩니다. TXT 소유권 레코드의 TTL은 300초(5분)이므로 DNS 클라이언트는 정리 후 최대 5분 동안 이전 레코드를 캐싱할 수 있습니다. **정리** `dnsConfig` 섹션을 삭제`InferenceEndpointConfig`하거나 제거하면 연산자가 생성한 Route 53 A 및 TXT 레코드를 자동으로 삭제합니다. 연산자는 자신이 소유한 레코드만 삭제합니다(소유권 TXT 레코드로 확인됨). ## 문제 해결 사용자 지정 인증서 또는 DNS 구성이 예상대로 작동하지 않는 경우이 디버깅 단계를 사용합니다. + **Amazon S3 액세스 오류와 함께 배포에 실패합니다.** 에 지정된 Amazon S3 버킷이 `tlsCertificateOutputS3Uri` 존재하고 동일한 리전에 있는지 확인합니다. 운영자의 실행 역할에 버킷에 대한 `s3:PutObject` 및 `s3:PutObjectTagging` 권한이 있는지 확인합니다. 연산자는 초기 배포 중에 0바이트 테스트 객체를 업로드하여 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에 다시 업로드합니다.