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

리전 사용자 지정 도메인 이름을 사용하여 사용자 친화적인 API 기본 URL을 생성합니다. 리전 사용자 지정 도메인 이름을 사용하면 HTTP 및 REST API 스테이지를 동일한 사용자 지정 도메인 이름에 매핑하고 상호 TLS 인증을 사용할 수 있습니다.

고려 사항

다음은 리전 사용자 지정 도메인 이름에 대한 고려 사항입니다.

• 리전별 ACM 인증서를 제공해야 합니다. 인증서는 API와 동일한 리전에 있어야 합니다. 사용자 지정 도메인 이름 인증서 생성 또는 업로드에 대한 자세한 내용은 AWS Certificate Manager에서 인증서 준비를 참조하세요.

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

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

리전 사용자 지정 도메인 이름 생성

다음 절차는 리전 사용자 지정 도메인 이름을 생성하는 방법을 보여 줍니다. 이 절차를 완료한 후 DNS 레코드를 생성하여 사용자 지정 도메인 이름을 리전 도메인 이름에 연결해야 합니다.

AWS Management Console

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

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

3. 생성을 선택합니다.

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

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

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

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

8. 생성(Create)을 선택합니다.

AWS CLI

다음 create-domain-name 명령을 사용하여 사용자 지정 도메인 이름을 생성할 수 있습니다.

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

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

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

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

리전 사용자 지정 도메인 이름에 대한 DNS 레코드 생성

다음 절차는 DNS 레코드를 생성하여 사용자 지정 도메인 이름을 새로 생성한 리전 도메인 이름에 연결하는 방법을 보여 줍니다.

AWS Management Console

AWS Management Console을 사용하려면 Route 53 설명서에 따라 트래픽을 API Gateway로 라우팅하도록 Route 53를 구성합니다.

AWS CLI

리전 사용자 지정 도메인 이름을 지정된 호스팅 영역 ID의 호스트 이름으로 매핑하도록 DNS 레코드를 구성하려면 먼저 리전 도메인 이름에 대해 DNS 레코드를 설정하기 위한 구성을 포함하는 JSON 파일을 생성합니다.

다음 setup-dns-record.json에서는 DNS A 레코드를 생성하여 사용자 지정 도메인 이름을 생성하는 과정에서 프로비저닝된 리전 호스트 이름(d-numh1z56v6.execute-api.us-west-2.amazonaws.com)에 리전 사용자 지정 도메인 이름(regional.example.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
        }
      }
    }
  ]
}

다음 change-resource-record-sets는 리전 사용자 지정 도메인 이름에 대한 DNS 레코드를 생성하는 방법을 보여 줍니다.

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

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

지역 사용자 지정 도메인 이름에 대한 기본 경로 매핑을 생성합니다.

DNS 레코드를 생성한 후 기본 경로 매핑을 생성하여 API를 사용자 지정 도메인 이름에 매핑합니다. 예를 들어 myApi의 API 매핑 키를 사용하여 abc123의 API ID에 대한 스테이지 test를 사용자 지정 도메인 이름 regional.example.com에 매핑할 수 있습니다. 이렇게 하면 API https://abcd1234.execute-api.us-west-2.amazonaws.com/test가 https://regional.example.com/myApi에 매핑됩니다.

AWS Management Console

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

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

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

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

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

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

AWS CLI

다음 create-api-mapping 명령을 사용하여 기본 경로 매핑을 생성할 수 있습니다.

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

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

리전 사용자 지정 도메인 이름을 사용하면 https://regional.example.com/orders/v1/items/123과 같이 여러 수준의 API 매핑을 생성할 수 있습니다. HTTP 및 REST API 스테이지를 동일한 사용자 지정 도메인 이름에 매핑할 수 있습니다. 자세한 내용은 API 스테이지를 REST API에 대한 사용자 지정 도메인 이름에 매핑 단원을 참조하십시오.