에지 최적화 사용자 지정 도메인 이름 생성 - Amazon API Gateway

에지 최적화 사용자 지정 도메인 이름 생성

API Gateway API에 대한 엣지 최적화 사용자 지정 도메인 이름 설정

다음 절차에서는 API Gateway 콘솔을 사용하여 API에 대한 사용자 지정 도메인 이름 생성을 설정하는 방법을 설명합니다.

API Gateway 콘솔을 사용하여 사용자 지정 도메인 이름을 생성하려면

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

  2. 기본 탐색 창에서 Custom domain names(사용자 지정 도메인 이름)를 선택합니다.

  3. 생성을 선택합니다.

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

  5. 구성에서 Edge-optimized(엣지 최적화)를 선택합니다.

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

  7. ACM 인증서를 선택합니다.

    참고

    API Gateway 엣지 최적화 사용자 지정 도메인 이름이 포함된 ACM 인증서를 사용하려면 us-east-1 리전(미국 동부(버지니아 북부)에서 인증서를 요청하거나 가져와야 합니다.

  8. Create를 선택합니다.

  9. 사용자 지정 도메인 이름을 생성한 후에는 distribution-id.cloudfront.net 형태의 연결된 CloudFront 배포 도메인 이름이 인증서 ARN과 함께 콘솔에 표시됩니다. 출력에 표시된 CloudFront 배포 도메인 이름을 적어 둡니다. 다음 단계인 DNS에서 사용자 지정 도메인의 CNAME 값 또는 A 레코드 별칭 대상을 설정할 때 필요합니다.

    참고

    새로 생성된 사용자 지정 도메인 이름은 사용할 수 있을 때까지 약 40분이 소요됩니다. 그 동안 DNS 레코드 별칭을 구성하여 사용자 지정 도메인 이름을 연결된 CloudFront 배포 도메인 이름에 매핑하고, 사용자 지정 도메인 이름이 초기화되는 동안 사용자 지정 도메인 이름의 기본 경로 매핑을 설정할 수 있습니다.

  10. 이 단계에서는 Amazon Route 53을 DNS 공급자의 예로 사용하여 사용자 지정 도메인 이름을 연결된 CloudFront 배포 이름에 매핑하도록 인터넷 도메인의 A 레코드 별칭을 설정하는 방법을 보여줍니다. 다른 DNS 공급자에 대해서도 이 지침을 적절히 적용할 수 있습니다.

    1. Route 53 콘솔에 로그인합니다.

    2. 사용자 지정 도메인(예: A-IPv4 address)에 대한 api.example.com 레코드 세트를 생성합니다. A 레코드는 사용자 지정 도메인 이름을 IP4 주소에 매핑합니다.

    3. Alias(별칭)에서 Yes(예)를 선택하고, Alias Target(별칭 대상)에 CloudFront 도메인 이름(예: d3boq9ikothtgw.cloudfront.net)을 입력한 다음, Create(생성)를 선택합니다. 여기서 A 레코드 별칭은 사용자 지정 도메인 이름을 IP4 주소에 매핑되는 지정된 CloudFront 도메인 이름에 매핑합니다.

      
                                    API Gateway에서 API에 대한 사용자 지정 도메인 이름의 DNS 레코드 별칭 설정
    작은 정보

    별칭 호스팅 영역 ID(Alias Hosted Zone ID)는 지정된 별칭 대상(Alias Target)의 호스팅 영역을 식별합니다. Alias Target(별칭 대상)에 유효한 도메인 이름을 입력하면 Route 53 콘솔에서 값이 자동으로 채워집니다. AWS CLI를 사용할 때와 같이 Route 53 콘솔을 사용하지 않고 A 레코드 별칭을 생성하려면 필수 호스팅 영역 ID를 지정해야 합니다. CloudFront의 AWS 리전 및 엔드포인트의 설명과 같이, CloudFront 배포 도메인 이름에 대한 호스팅 영역 id 값은 항상 Z2FDTNDATAQYW2입니다.

    DNS 공급자 대부분의 경우, 사용자 지정 도메인 이름은 CNAME 리소스 레코드 세트로 호스팅 영역에 추가됩니다. CNAME 레코드 이름은 앞서 도메인 이름에 입력한 사용자 지정 도메인 이름(예: api.example.com)을 지정합니다. CNAME 레코드 값은 CloudFront 배포의 도메인 이름을 지정합니다. 그러나 사용자 지정 도메인이 zone apex인 경우(즉, example.com이 아닌 api.example.com인 경우) CNAME 레코드는 작동하지 않습니다. zone apex는 일반적으로 조직의 루트 도메인이라고도 합니다. zone apex의 경우 A 레코드 별칭을 사용해야 하는데, 다만 DNS 공급자가 그것을 지원해야 합니다.

    위와 같이 Route 53을 사용하면 사용자 지정 도메인 이름의 A 레코드 별칭을 생성하고 CloudFront 배포 도메인 이름을 별칭 대상으로 지정할 수 있습니다. 다시 말해서 사용자 지정 도메인이 zone apex라고 하더라도 Route 53은 사용자 지정 도메인 이름을 라우팅할 수 있습니다. 자세한 내용은 Amazon Route 53 개발자 안내서별칭 및 비별칭 리소스 레코드 세트 간의 선택에서 확인할 수 있습니다.

    도메인 이름 매핑이 전적으로 Route 53 내에서 수행되기 때문에 A 레코드 별칭을 사용하면 기본 CloudFront 배포 도메인 이름의 노출도 방지할 수 있습니다. 이러한 이유로 가능하면 항상 Route 53 A 레코드 별칭을 사용하는 것이 좋습니다.

API Gateway 콘솔 사용 외에도 API Gateway REST API, AWS CLI 또는 AWS SDK 중 하나를 사용하여 API에 대한 사용자 지정 도메인 이름을 설정할 수 있습니다. 다음 절차에서는 REST API 호출을 사용하여 이를 수행하는 단계를 간략하게 설명합니다.

API Gateway REST API를 사용하여 사용자 지정 도메인 이름을 설정하려면

  1. 사용자 지정 도메인 이름과 AWS Certificate Manager에 저장된 인증서의 ARN를 지정하여 domainname:create를 호출하여 합니다.

    성공적인 API 호출은 페이로드에 인증서 ARN뿐 아니라 연결된 CloudFront 배포 이름을 포함하는 201 Created 응답을 반환합니다.

  2. 출력에 표시된 CloudFront 배포 도메인 이름을 적어 둡니다. 다음 단계인 DNS에서 사용자 지정 도메인의 CNAME 값 또는 A 레코드 별칭 대상을 설정할 때 필요합니다.

  3. 이전 절차에 따라 사용자 지정 도메인 이름을 CloudFront 배포 이름에 매핑하도록 A 레코드 별칭을 설정합니다.

이 REST API 호출의 코드 예는 domainname:create를 참조하십시오.

CloudTrail에서 사용자 지정 도메인 이름 생성 로그

계정에서 수행한 API Gateway 호출을 로깅하기 위해 CloudTrail을 활성화한 경우, API에 대한 사용자 지정 도메인 이름을 생성하거나 업데이트할 때 API Gateway는 연결된 CloudFront 배포 업데이트를 기록합니다. 이러한 CloudFront 배포는 API Gateway가 소유하므로, 이러한 각 보고된 CloudFront 배포는 API 소유자의 계정 ID 대신 다음과 같은 리전별 API Gateway 계정 ID 중 하나로 식별됩니다.

리전 계정 ID
us-east-1 392220576650
us-east-2 718770453195
us-west-1 968246515281
us-west-2 109351309407
ca-central-1 796887884028
eu-west-1 631144002099
eu-west-2 544388816663
eu-west-3 061510835048
eu-central-1 474240146802
eu-north-1 394634713161
ap-northeast-1 969236854626
ap-northeast-2 020402002396
ap-southeast-1 195145609632
ap-southeast-2 798376113853
ap-south-1 507069717855
ap-east-1 174803364771
sa-east-1 287228555773
me-south-1 855739686837

사용자 지정 도메인 이름을 호스트 이름으로 사용하여 API의 기본 경로 매핑 구성

단일 사용자 지정 도메인 이름을 여러 API의 호스트 이름으로 사용할 수 있습니다. 사용자 지정 도메인 이름에 대한 기본 경로 매핑을 구성하여 이를 달성합니다. 기본 경로 매핑을 사용하면 사용자 지정 도메인의 API를 사용자 지정 도메인 이름 및 연관된 기본 경로의 결합을 통해 액세스할 수 있습니다.

예를 들어, PetStore라는 API 와 PetShop이라는 다른 API를 생성하고 API Gateway에서 api.example.com의 사용자 지정 도메인 이름을 설정한 경우 PetStore API의 URL을 https://api.example.com 또는 https://api.example.com/myPetStore로 설정할 수 있습니다. PetStore API는 빈 문자열의 기본 경로 또는 myPetStore의 사용자 지정 도메인 이름 아래의 api.example.com와 연관됩니다. 마찬가지로 yourPetShop API에 대해 PetShop의 기본 경로를 지정할 수 있습니다. https://api.example.com/yourPetShop의 URL은 PetShop API의 루트 URL입니다.

API에 대한 기본 경로를 설정하기 전에 API Gateway API에 대한 엣지 최적화 사용자 지정 도메인 이름 설정의 단계를 완료합니다.

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

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

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

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

  3. Configure API mappings(API 매핑 구성)를 선택합니다.

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

  5. 매핑에 대한 API, 스테이지, 및 경로(선택 사항)를 지정합니다.

  6. 저장을 선택합니다.

또한 API Gateway REST API, AWS CLI 또는 AWS SDK 중 하나를 호출하여 사용자 지정 도메인 이름을 호스트 이름으로 사용하는 API의 기본 경로 매핑을 설정할 수 있습니다. 다음 절차에서는 REST API 호출을 사용하여 이를 수행하는 단계를 간략하게 설명합니다.

API Gateway REST API를 사용하여 API의 기본 경로 매핑을 설정하려면

  • 요청 페이로드에서 basePath, restApiId 및 배포 stage 속성을 지정하여 특정 사용자 지정 도메인 이름에 대해 basepathmapping:create를 호출합니다.

    성공적인 API 응답은 201 Created 응답을 반환합니다.

REST API 호출의 코드 예는 basepathmapping:create를 참조하십시오.

ACM에 가져온 인증서 교체

ACM은 발급한 인증서의 갱신을 자동으로 처리합니다. 사용자 지정 도메인 이름에 대해 ACM이 발급한 인증서는 교체할 필요가 없습니다. CloudFront가 사용자를 대신하여 처리합니다.

하지만 인증서를 ACM에 가져와서 사용자 지정 도메인 이름에 사용할 경우 만료되기 전에 인증서를 교체해야 합니다. 여기에는 도메인 이름에 대한 새 타사 인증서를 가져오고 기존 인증서를 새 인증서로 교체하는 작업이 포함됩니다. 새로 가져온 인증서가 만료되면 이 프로세스를 반복해야 합니다. 또는 도메인 이름에 대한 새 인증서를 발급하도록 ACM에 요청하고 기존 인증서를 ACM에서 발급한 새 인증서로 교체할 수 있습니다. 이후에는 ACM과 CloudFront에서 인증서 교체를 자동으로 처리하도록 둘 수 있습니다. 새 ACM 인증서를 생성하거나 가져오려면 지정된 도메인 이름에 대해 새 ACM 인증서를 요청하거나 가져오는 단계를 수행합니다.

도메인 이름에 대한 인증서를 교체하려면 API Gateway 콘솔, API Gateway REST API, AWS CLI 또는 AWS SDK 중 하나를 사용할 수 있습니다.

API Gateway 콘솔을 사용하여 ACM에 가져온 만료될 인증서를 교체하려면

  1. ACM에서 인증서를 요청하거나 가져옵니다.

  2. API Gateway 콘솔로 돌아갑니다.

  3. API Gateway 콘솔 기본 탐색 창에서 Custom Domain Names(사용자 지정 도메인 이름)를 선택합니다.

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

  5. [Edit]를 선택합니다.

  6. ACM certificate(ACM 인증서) 드롭다운 목록에서 원하는 인증서를 선택합니다.

  7. 저장을 선택하여 사용자 지정 도메인 이름에 대한 인증서 교체를 시작합니다.

    참고

    프로세스를 완료하는 데는 약 40분이 소요됩니다. 교체가 완료된 후에 ACM 인증서(ACM Certificate) 옆에 있는 양방향 화살표를 선택하여 원래 인증서로 롤백할 수 있습니다.

사용자 지정 도메인 이름에 대해 가져온 인증서를 프로그래밍 방식으로 교체하는 방법을 설명하기 위해 여기서는 API Gateway REST API를 사용하여 단계를 설명합니다.

API Gateway REST API를 사용하여 가져온 인증서 교체

  • 지정된 도메인 이름에 대한 새 ACM 인증서의 ARN을 지정하여 domainname:update 작업을 호출합니다.

사용자 지정 도메인 이름을 사용하여 API 호출

사용자 지정 도메인 이름을 사용하여 API를 호출하는 것은 올바른 URL을 사용한 경우 기본 도메인 이름을 사용하여 API를 호출하는 것과 동일합니다.

다음 예제에서는 기본 URL 세트와 지정된 리전(us-east-1) 및 해당 사용자 지정 도메인 이름(api.example.com)의 두 API(udxjefqf3duz)에 해당되는 사용자 지정 URL을 비교 및 대비합니다.

기본 및 사용자 지정 도메인 이름이 포함된 API의 루트 URL
API ID Stage 기본 URL 기본 경로 사용자 지정 URL
udxjef pro https://udxjef.execute-api.us-east-1.amazonaws.com/pro /petstore https://api.example.com/petstore
udxjef tst https://udxjef.execute-api.us-east-1.amazonaws.com/tst /petdepot https://api.example.com/petdepot
qf3duz dev https://qf3duz.execute-api.us-east-1.amazonaws.com/dev /bookstore https://api.example.com/bookstore
qf3duz tst https://qf3duz.execute-api.us-east-1.amazonaws.com/tst /bookstand https://api.example.com/bookstand

API Gateway는 SNI(Server Name Indication)를 사용하여 API에 대한 사용자 지정 도메인 이름을 지원합니다. 브라우저 또는 SNI를 지원하는 클라이언트 라이브러리를 사용하여 사용자 지정 도메인 이름이 포함된 API를 호출할 수 있습니다.

API Gateway는 CloudFront 배포에 SNI를 적용합니다. CloudFront에서 사용자 지정 도메인 이름을 사용하는 방법에 대한 자세한 내용은 Amazon CloudFront 사용자 지정 SSL을 참조하십시오.