API Gateway에서 리전 사용자 지정 도메인 이름 설정

AWS 리전의 경우 리전 API 엔드포인트에 대한 사용자 지정 도메인 이름을 생성할 수 있습니다. 사용자 지정 도메인 이름을 생성하려면 리전별 ACM 인증서를 제공해야 합니다. 사용자 지정 도메인 이름 인증서 생성 또는 업로드에 대한 자세한 내용은 AWS Certificate Manager에서 인증서 준비하기를 참조하세요.

중요

API Gateway 리전 사용자 지정 도메인 이름의 경우, API와 동일한 리전에서 인증서를 요청하거나 가져와야 합니다.

ACM 인증서로 리전 사용자 지정 도메인 이름을 생성(또는 마이그레이션)하면 API Gateway는 해당 계정에 서비스 연결 역할을 생성합니다(이 역할이 아직 없는 경우). 서비스 연결 역할은 ACM 인증서를 해당 리전 엔드포인트에 연결하는 데 필요합니다. 그 역할의 이름은 AWSServiceRoleForAPIGateway이고 이 역할에는 APIGatewayServiceRolePolicy 관리형 정책이 연결됩니다. 서비스 연결 역할을 사용하는 방법에 대한 자세한 내용은 서비스 연결 역할 사용을 참조하세요.

중요

DNS 레코드를 생성하여 사용자 지정 도메인 이름이 리전 도메인 이름을 가리키도록 해야 합니다. 이렇게 하면 목적지가 사용자 지정 도메인 이름인 트래픽이 API의 리전 호스트 이름으로 라우팅됩니다. DNS 레코드는 CNAME 또는 “A” 유형일 수 있습니다.

API Gateway 콘솔을 사용하여 ACM 인증서로 리전 사용자 지정 도메인 이름 설정

API Gateway 콘솔을 사용하여 리전 사용자 지정 도메인 이름을 설정하려면 다음 절차를 따르세요.

API Gateway 콘솔을 사용하여 리전 사용자 지정 도메인 이름을 설정하려면

1. https://console.aws.amazon.com/apigateway에서 API Gateway 콘솔에 로그인합니다.

2. 기본 탐색 창에서 사용자 지정 도메인 이름을 선택합니다.

3. Create를 선택합니다.

4. 도메인 이름에 도메인 이름을 입력합니다.

5. 구성에서 Regional(지역별)을 선택합니다.

6. 최소 TLS 버전을 선택합니다.

7. ACM 인증서를 선택합니다. 인증서는 API와 동일한 리전에 있어야 합니다.

8. Create를 선택합니다.

9. Route 53 설명서에 따라 트래픽을 API Gateway로 라우팅하도록 Route 53을 구성합니다.

다음 절차에서는 사용자 지정 도메인 이름에서 API 스테이지로 경로를 매핑하도록 API 매핑을 설정합니다.

API Gateway 콘솔을 사용하여 API 매핑 이름을 생성하려면

1. https://console.aws.amazon.com/apigateway에서 API Gateway 콘솔에 로그인합니다.

2. 사용자 지정 도메인 이름을 선택합니다.

3. API 매핑 구성을 선택합니다.

4. Add new mapping(새 매핑 추가)을 선택합니다.

5. 매핑에 대한 API, 스테이지 및 경로를 지정합니다.

6. 저장(Save)을 선택합니다.

사용자 지정 도메인에 대한 기본 경로 매핑 설정에 대해 자세히 알아보려면 사용자 지정 도메인 이름을 호스트 이름으로 사용하여 API의 기본 경로 매핑 구성 단원을 참조하세요.

AWS CLI를 사용하여 ACM 인증서로 리전 사용자 지정 도메인 이름 설정

AWS CLI를 사용하여 리전 API에 대한 사용자 지정 도메인 이름을 설정하려면 다음 절차를 따르세요.

1. create-domain-name을 호출하여 사용자 지정 도메인 이름과 리전 인증서의 ARN을 지정합니다.

   aws apigatewayv2 create-domain-name \ 
       --domain-name 'regional.example.com' \
       --domain-name-configurations CertificateArn=arn:aws:acm:us-west-2:123456789012:certificate/123456789012-1234-1234-1234-12345678

   지정된 인증서의 출처는 us-west-2 리전이고, 이 예제에서는 기본 API의 출처도 같은 리전이라고 가정합니다.

   호출이 성공하면 다음과 비슷한 결과가 반환됩니다.

   {
       "ApiMappingSelectionExpression": "$request.basepath",
       "DomainName": "regional.example.com",
       "DomainNameConfigurations": [
           {
               "ApiGatewayDomainName": "d-id.execute-api.us-west-2.amazonaws.com",
               "CertificateArn": "arn:aws:acm:us-west-2:123456789012:certificate/id",
               "DomainNameStatus": "AVAILABLE",
               "EndpointType": "REGIONAL",
               "HostedZoneId": "id",
               "SecurityPolicy": "TLS_1_2"
           }
       ]
   }

   DomainNameConfigurations 속성 값은 리전 API의 호스트 이름을 반환합니다. DNS 레코드를 생성하여 사용자 지정 도메인 이름이 이 리전 도메인 이름을 가리키도록 해야 합니다. 이렇게 하면 목적지가 사용자 지정 도메인 이름인 트래픽이 이 리전 API의 호스트 이름으로 라우팅됩니다.

2. DNS 레코드를 생성하여 사용자 지정 도메인 이름 및 리전 도메인 이름을 연결합니다. 이렇게 하면 목적지가 사용자 지정 도메인 이름인 요청이 API의 리전 호스트 이름으로 라우팅됩니다.

3. 기본 경로 매핑을 추가하여 지정된 사용자 지정 도메인 이름(예: 0qzs2sy7bh)으로 배포 단계(예: test)에서 지정 API(예: regional.example.com)를 노출합니다.

   aws apigatewayv2 create-api-mapping \
       --domain-name 'regional.example.com' \
       --api-mapping-key 'myApi' \
       --api-id 0qzs2sy7bh \
       --stage 'test'

   결과적으로 그 단계에서 배포되는 API에 대해 사용자 지정 도메인 이름을 사용하는 기본 URL은 https://regional.example.com/myAPI이 됩니다.

4. 리전 사용자 지정 도메인 이름을 지정된 호스팅 영역 ID의 호스트 이름으로 매핑하도록 DNS 레코드를 구성합니다. 먼저, 리전 도메인 이름에 대해 DNS 레코드를 설정하기 위한 구성을 포함하는 JSON 파일을 생성합니다. 다음 예제에서는 DNS A 레코드를 생성하여 사용자 지정 도메인 이름을 생성하는 과정에서 프로비저닝된 리전 호스트 이름(regional.example.com)에 리전 사용자 지정 도메인 이름(d-numh1z56v6.execute-api.us-west-2.amazonaws.com)을 매핑하는 방법을 보여줍니다. DNSName의 HostedZoneId 및 AliasTarget 속성은 사용자 지정 도메인 이름의 regionalDomainName 및 regionalHostedZoneId 값을 가져올 수 있습니다. 또한 Amazon API Gateway 엔드포인트 및 할당량에서 리전 Route 53 호스팅 영역 ID를 가져올 수 있습니다.

   {
     "Changes": [
       {
         "Action": "CREATE",
         "ResourceRecordSet": {
           "Name": "regional.example.com",
           "Type": "A",
           "AliasTarget": {
             "DNSName": "d-numh1z56v6.execute-api.us-west-2.amazonaws.com",
             "HostedZoneId": "Z2OJLYMUO9EFXC",
             "EvaluateTargetHealth": false
           }
         }
       }
     ]
   }
   

5. 다음 CLI 명령을 실행합니다.

   aws route53 change-resource-record-sets \
       --hosted-zone-id {your-hosted-zone-id} \
       --change-batch file://path/to/your/setup-dns-record.json

   {your-hosted-zone-id}는 계정에 설정된 DNS 레코드의 Route 53 호스팅 영역 ID입니다. change-batch 파라미터 값은 폴더(path/to/your)의 JSON 파일(setup-dns-record.json)을 가리킵니다.