API Gateway에서 사용자 지정 도메인 이름을 다른 API 엔드포인트 유형으로 마이그레이션 - Amazon API Gateway
고려 사항사용자 지정 도메인 이름 마이그레이션

API Gateway에서 사용자 지정 도메인 이름을 다른 API 엔드포인트 유형으로 마이그레이션

엣지 최적화 및 리전 엔드포인트 간에 사용자 지정 도메인 이름을 마이그레이션할 수 있습니다. 퍼블릭 사용자 지정 도메인 이름은 프라이빗 사용자 지정 도메인 이름으로 마이그레이션할 수 없습니다. 먼저 사용자 지정 도메인 이름에 대한 기존 endpointConfiguration.types 목록에 새로운 엔드포인트 구성 유형을 추가합니다. 그 다음에 DNS 레코드를 설정하여 사용자 지정 도메인 이름이 새로 프로비저닝된 엔드포인트를 가리키도록 합니다. 마지막으로, 더 이상 사용되지 않는 사용자 지정 도메인 이름 엔드포인트를 제거합니다.

고려 사항

리전 API 엔드포인트와 엣지 최적화 API 엔드포인트 간에 사용자 지정 도메인을 마이그레이션할 때 고려할 사항은 다음과 같습니다.

  • 엣지 최적화 사용자 지정 도메인 이름에는 미국 동부(버지니아 북부) – us-east-1 리전의 ACM에서 제공하는 인증서가 필요합니다. 이 인증서는 모든 지리적 위치에 배포됩니다.

  • 리전 사용자 지정 도메인 이름에는 API를 호스팅하는 동일한 리전의 ACM에서 제공하는 인증서가 필요합니다. API에 대해 로컬인 리전에 새로운 ACM 인증서를 요청하여 us-east-1 리전에 있지 않은 엣지 최적화 사용자 지정 도메인 이름을 리전 사용자 지정 도메인 이름으로 마이그레이션할 수 있습니다.

  • 엣지 최적화 사용자 지정 도메인 이름과 리전 사용자 지정 도메인 이름 간에 마이그레이션을 완료하는 데 최대 60초가 걸릴 수 있습니다. DNS 레코드를 업데이트하는 시점에 따라서도 마이그레이션 시간이 달라집니다.

  • 엔드포인트 액세스 모드가 BASIC으로 설정된 경우에만 엔드포인트 구성을 추가할 수 있습니다. 두 개의 엔드포인트 구성이 있으면 엔드포인트 액세스 모드를 변경할 수 없습니다. 자세한 내용은 엔드포인트 액세스 모드 섹션을 참조하세요.

  • 사용자 지정 도메인 이름이 SecurityPolicy_로 시작하는 보안 정책을 사용하는 경우 새 엔드포인트 구성 유형을 추가할 때 엔드포인트 액세스 모드는 두 엔드포인트 유형에서 동일하므로 새 엔드포인트 구성 유형에 대해 SecurityPolicy_로 시작하는 보안 정책을 선택해야 합니다.

사용자 지정 도메인 이름 마이그레이션

참고

마이그레이션을 완료하려면 사용자 지정 도메인 이름에서 더 이상 사용되지 않는 엔드포인트를 제거해야 합니다.

엣지 최적화 사용자 지정 도메인 이름을 리전 사용자 지정 도메인 이름으로 마이그레이션하려면 다음 절차를 따르세요.

AWS Management 콘솔

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

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

  3. 엣지 최적화 사용자 지정 도메인 이름을 선택합니다.

  4. 엔드포인트 구성에서 편집을 선택합니다.

  5. 리전 엔드포인트 추가를 선택합니다.

  6. ACM 인증서에서 인증서를 선택합니다.

    리전 인증서는 리전 API와 동일한 리전의 것이어야 합니다.

  7. 변경 사항 저장을 선택합니다.

  8. 리전 사용자 지정 도메인 이름이 이 리전 호스트 이름으로 연결되도록 DNS 레코드를 설정해야 합니다. 자세한 내용은 트래픽을 API Gateway로 라우팅하도록 Route 53 구성을 참조하세요.

  9. DNS 구성이 올바른 엔드포인트로 연결되는지 확인한 후 엣지 최적화 엔드포인트 구성을 삭제합니다. 사용자 지정 도메인 이름을 선택하고 엣지 최적화 엔드포인트 구성에서 삭제를 선택합니다.

  10. 선택 사항을 확인하고 엔드포인트를 삭제합니다.

AWS CLI

다음 update-domain-name 명령은 엣지 최적화 사용자 지정 도메인 이름을 리전 사용자 지정 도메인 이름으로 마이그레이션합니다.

aws apigateway update-domain-name \
    --domain-name 'api.example.com' \
    --patch-operations  '[ 
        { "op":"add", "path": "/endpointConfiguration/types","value": "REGIONAL" },
        { "op":"add", "path": "/regionalCertificateArn", "value": "arn:aws:acm:us-west-2:123456789012:certificate/cd833b28-58d2-407e-83e9-dce3fd852149" }
      ]'

리전 인증서는 리전 API와 동일한 리전의 것이어야 합니다.

출력은 다음과 같습니다.

{
    "certificateArn": "arn:aws:acm:us-east-1:123456789012:certificate/34a95aa1-77fa-427c-aa07-3a88bd9f3c0a",
    "certificateName": "edge-cert",
    "certificateUploadDate": "2017-10-16T23:22:57Z",
    "distributionDomainName": "d1frvgze7vy1bf.cloudfront.net",
    "domainName": "api.example.com",
    "endpointConfiguration": {
        "types": [
            "EDGE",
            "REGIONAL"
        ]
    },
    "regionalCertificateArn": "arn:aws:acm:us-west-2:123456789012:certificate/cd833b28-58d2-407e-83e9-dce3fd852149",
    "regionalDomainName": "d-fdisjghyn6.execute-api.us-west-2.amazonaws.com"
}

그 결과 얻는 regionalDomainName 속성은 마이그레이션된 리전 사용자 지정 도메인 이름에 대해 리전 API 호스트 이름을 반환합니다. 리전 사용자 지정 도메인 이름이 이 리전 호스트 이름을 가리키도록 DNS 레코드를 설정해야 합니다. 이렇게 하면 목적지가 사용자 지정 도메인 이름인 트래픽이 리전 호스트로 라우팅됩니다.

DNS 레코드가 설정된 후에는 엣지 최적화 사용자 지정 도메인 이름을 제거할 수 있습니다. 다음 update-domain-name 명령은 엣지 최적화 사용자 지정 도메인 이름을 제거합니다.

aws apigateway update-domain-name \
    --domain-name api.example.com \
    --patch-operations '[
            {"op":"remove", "path":"/endpointConfiguration/types", "value":"EDGE"},
            {"op":"remove", "path":"certificateName"},
            {"op":"remove", "path":"certificateArn"}
        ]'

다음 절차에서는 향상된 보안 정책을 사용하는 엣지 최적화 사용자 지정 도메인 이름을 향상된 보안 정책도 사용하는 리전 사용자 지정 도메인 이름으로 마이그레이션하는 방법을 보여 줍니다.

AWS Management 콘솔

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

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

  3. 엣지 최적화 사용자 지정 도메인 이름을 선택합니다.

  4. 엔드포인트 구성에서 편집을 선택합니다.

  5. 리전 엔드포인트 추가를 선택합니다.

  6. ACM 인증서에서 인증서를 선택합니다.

    리전 인증서는 리전 API와 동일한 리전의 것이어야 합니다.

  7. 보안 정책의 경우 SecurityPolicy_로 시작하는 보안 정책을 선택합니다.

  8. 엔드포인트 액세스 모드에서 기본을 선택합니다.

  9. 변경 사항 저장을 선택합니다.

  10. 리전 사용자 지정 도메인 이름이 이 리전 호스트 이름으로 연결되도록 DNS 레코드를 설정해야 합니다. 자세한 내용은 트래픽을 API Gateway로 라우팅하도록 Route 53 구성을 참조하세요.

  11. DNS 구성이 올바른 엔드포인트로 연결되는지 확인한 후 엣지 최적화 엔드포인트 구성을 삭제합니다. 사용자 지정 도메인 이름을 선택하고 엣지 최적화 엔드포인트 구성에서 삭제를 선택합니다.

  12. 선택 사항을 확인하고 엔드포인트를 삭제합니다.

AWS CLI

다음 update-domain-name 명령은 엣지 최적화 사용자 지정 도메인 이름을 리전 사용자 지정 도메인 이름으로 마이그레이션합니다.

aws apigateway update-domain-name \
    --domain-name 'api.example.com' \
    --patch-operations  '[ 
        { "op":"add", "path": "/endpointConfiguration/types","value": "REGIONAL" },
        { "op":"replace", "path": "/securityPolicy", "value":"SecurityPolicy_TLS13_1_3_2025_09"},
        { "op":"add", "path": "/regionalCertificateArn", "value": "arn:aws:acm:us-west-2:123456789012:certificate/cd833b28-58d2-407e-83e9-dce3fd852149" }
      ]'

리전 인증서는 리전 API와 동일한 리전의 것이어야 합니다.

출력은 다음과 같습니다.

{
    "certificateArn": "arn:aws:acm:us-east-1:123456789012:certificate/34a95aa1-77fa-427c-aa07-3a88bd9f3c0a",
    "certificateName": "edge-cert",
    "certificateUploadDate": "2017-10-16T23:22:57Z",
    "distributionDomainName": "d1frvgze7vy1bf.cloudfront.net",
    "domainName": "api.example.com",
    "endpointConfiguration": {
        "types": [
            "EDGE",
            "REGIONAL"
        ]
    },
    "securityPolicy": "SecurityPolicy_TLS13_1_3_2025_09",
    "endpointAccessMode": "BASIC",
    "regionalCertificateArn": "arn:aws:acm:us-west-2:123456789012:certificate/cd833b28-58d2-407e-83e9-dce3fd852149",
    "regionalDomainName": "d-fdisjghyn6.execute-api.us-west-2.amazonaws.com"
}

그 결과 얻는 regionalDomainName 속성은 마이그레이션된 리전 사용자 지정 도메인 이름에 대해 리전 API 호스트 이름을 반환합니다. 리전 사용자 지정 도메인 이름이 이 리전 호스트 이름을 가리키도록 DNS 레코드를 설정해야 합니다. 이렇게 하면 목적지가 사용자 지정 도메인 이름인 트래픽이 리전 호스트로 라우팅됩니다.

DNS 레코드가 설정된 후에는 엣지 최적화 사용자 지정 도메인 이름을 제거할 수 있습니다. 다음 update-domain-name 명령은 엣지 최적화 사용자 지정 도메인 이름을 제거합니다.

aws apigateway update-domain-name \
    --domain-name api.example.com \
    --patch-operations '[
            {"op":"remove", "path":"/endpointConfiguration/types", "value":"EDGE"},
            {"op":"remove", "path":"certificateName"},
            {"op":"remove", "path":"certificateArn"}
        ]'

리전 사용자 지정 도메인 이름을 엣지 최적화 사용자 지정 도메인 이름으로 마이그레이션하려면 다음 절차를 따르세요.

AWS Management 콘솔

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

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

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

  4. 엔드포인트 구성에서 편집을 선택합니다.

  5. 엣지 최적화 엔드포인트 추가를 선택합니다.

  6. ACM 인증서에서 인증서를 선택합니다.

    엣지 최적화 도메인 인증서는 us-east-1 리전에 생성되어야 합니다.

  7. 저장을 선택합니다.

  8. 엣지 최적화 사용자 지정 도메인 이름이 엣지 최적화 호스트 이름으로 연결되도록 DNS 레코드를 설정합니다. 자세한 내용은 트래픽을 API Gateway로 라우팅하도록 Route 53 구성을 참조하세요.

  9. DNS 구성이 올바른 엔드포인트로 연결되는지 확인한 후 리전 엔드포인트 구성을 삭제합니다. 사용자 지정 도메인 이름을 선택하고 리전 엔드포인트 구성에서 삭제를 선택합니다.

  10. 선택 사항을 확인하고 엔드포인트를 삭제합니다.

AWS CLI

다음 update-domain-name 명령은 리전 사용자 지정 도메인 이름을 엣지 최적화 사용자 지정 도메인 이름으로 마이그레이션합니다.

aws apigateway update-domain-name \
    --domain-name 'api.example.com' \
    --patch-operations  '[ 
        { "op":"add", "path": "/endpointConfiguration/types","value": "EDGE" },
        { "op":"add", "path": "/certificateName", "value": "edge-cert" },
	{"op":"add", "path": "/certificateArn", "value": "arn:aws:acm:us-east-1:738575810317:certificate/34a95aa1-77fa-427c-aa07-3a88bd9f3c0a"}
      ]'

엣지 최적화 도메인 인증서는 us-east-1 리전에 생성되어야 합니다.

출력은 다음과 같습니다.

{
    "certificateArn": "arn:aws:acm:us-east-1:738575810317:certificate/34a95aa1-77fa-427c-aa07-3a88bd9f3c0a",
    "certificateName": "edge-cert",
    "certificateUploadDate": "2017-10-16T23:22:57Z",
    "distributionDomainName": "d1frvgze7vy1bf.cloudfront.net",
    "domainName": "api.example.com",
    "endpointConfiguration": {
        "types": [
            "EDGE",
            "REGIONAL"
        ]
    },
    "regionalCertificateArn": "arn:aws:acm:us-east-1:123456789012:certificate/3d881b54-851a-478a-a887-f6502760461d",
    "regionalDomainName": "d-cgkq2qwgzf.execute-api.us-east-1.amazonaws.com"
}

API Gateway는 지정된 사용자 지정 도메인 이름에 대해 distributionDomainName 속성 값으로 엣지 최적화 API 호스트 이름을 반환합니다. DNS 레코드를 설정하여 엣지 최적화 사용자 지정 도메인 이름이 이 배포 도메인 이름을 가리키도록 해야 합니다. 이렇게 하면 목적지가 엣지 최적화 사용자 지정 도메인 이름인 트래픽이 엣지 최적화 API 호스트 이름으로 라우팅됩니다.

DNS 레코드가 설정된 후에는 다음과 같이 사용자 지정 도메인 이름의 REGION 엔드포인트 유형을 제거할 수 있습니다. 다음 update-domain-name 명령은 리전 엔드포인트 유형을 제거합니다.

aws apigateway update-domain-name \
    --domain-name api.example.com \
    --patch-operations '[
        {"op":"remove", "path":"/endpointConfiguration/types", value:"REGIONAL"},
        {"op":"remove", "path":"regionalCertificateArn"}
      ]'

출력은 다음과 같습니다.

{
    "certificateArn": "arn:aws:acm:us-east-1:738575810317:certificate/34a95aa1-77fa-427c-aa07-3a88bd9f3c0a",
    "certificateName": "edge-cert",
    "certificateUploadDate": "2017-10-16T23:22:57Z",
    "distributionDomainName": "d1frvgze7vy1bf.cloudfront.net",
    "domainName": "api.example.com",
    "endpointConfiguration": {
        "types": "EDGE"
    }
}