EC2 메타데이터 유틸리티가 버전 1에서 버전 2로 변경 - AWS SDK for Java 2.x
높은 수준의 변경 사항동작 변경 사항구성 차이점

기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.

EC2 메타데이터 유틸리티가 버전 1에서 버전 2로 변경

이 항목에서는 버전 1(v1)에서 버전 2(v2)로 변경된 SDK for Java Amazon Elastic Compute Cloud(EC2) 메타데이터 유틸리티의 변경 사항에 대해 자세히 설명합니다.

높은 수준의 변경 사항

변경 사항 v1 v2

Maven 종속성

 
<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.amazonaws</groupId>
            <artifactId>aws-java-sdk-bom</artifactId>
            <version>1.12.5871</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>
<dependencies>
    <dependency>
        <groupId>com.amazonaws</groupId>
        <artifactId>aws-java-sdk-core</artifactId>
    </dependency>
</dependencies>
 
<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>software.amazon.awssdk</groupId>
            <artifactId>bom</artifactId>
            <version>2.27.212</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>
<dependencies>
    <dependency>
        <groupId>software.amazon.awssdk</groupId>
        <artifactId>imds</artifactId>
    </dependency>
    <dependency>
        <groupId>software.amazon.awssdk</groupId>
        <artifactId>apache-client3</artifactId>
    </dependency>
</dependencies>
패키지 이름 com.amazonaws.util software.amazon.awssdk.imds
인스턴스화 접근 방식

인스턴스화 없이 정적 유틸리티 메서드 사용:

String localHostName = 
           EC2MetadataUtils.getLocalHostName();

정적 팩토리 메서드 사용:

Ec2MetadataClient client = Ec2MetadataClient.create();

또는 빌더 접근 방식 사용:

Ec2MetadataClient client = Ec2MetadataClient.builder()
    .endpointMode(EndpointMode.IPV6)
    .build();
클라이언트 유형 동기 전용 유틸리티 메서드: EC2MetadataUtils

동기식: Ec2MetadataClient

비동기식: Ec2MetadataAsyncClient

1 최신 버전. 2 최신 버전.

3v2에 대한 apache-client 모듈 선언에 주목합니다. EC2 메타데이터 유틸리티 V2를 사용하려면 동기식 메타데이터 클라이언트의 경우 SdkHttpClient 인터페이스를 구현해야 하고, 비동기식 메타데이터 클라이언트의 경우 SdkAsyncHttpClient 인터페이스를 구현해야 합니다. HTTP 클라이언트 섹션에는 사용할 수 있는 HTTP 클라이언트 목록이 표시됩니다.

메타데이터 요청

v1에서는 파라미터를 허용하지 않는 정적 메서드를 사용하여 EC2 리소스에 대한 메타데이터를 요청합니다. 이와는 대조적으로 v2에서는 EC2 리소스의 경로를 파라미터로 지정해야 합니다. 다음 표는 서로 다른 접근 방식을 보여줍니다.

v1 v2 
String userMetaData = EC2MetadataUtils.getUserData();
 
Ec2MetadataClient client = Ec2MetadataClient.create();
Ec2MetadataResponse response = 
                client.get("/latest/user-data");
String userMetaData = 
                response.asString();

인스턴스 메타데이터 범주를 참조하여 메타데이터를 요청하기 위해 제공해야 하는 경로를 찾으세요.

참고

v2에서 인스턴스 메타데이터 클라이언트를 사용하는 경우, 메타데이터를 검색하는 모든 요청에 동일한 클라이언트를 사용해야 합니다.

동작 변경 사항

JSON 데이터

EC2에서 로컬로 실행되는 인스턴스 메타데이터 서비스(IMDS)는 일부 메타데이터를 JSON 형식의 문자열로 반환합니다. 그러한 예로 인스턴스 ID 문서의 동적 메타데이터를 들 수 있습니다.

v1 API에는 인스턴스 ID 메타데이터의 각 부분에 대한 별도의 메서드가 포함되어 있는 반면, v2 API는 JSON 문자열을 직접 반환합니다. JSON 문자열로 작업하려면 문서 API를 사용하여 응답을 구문 분석하고 JSON 구조를 탐색할 수 있습니다.

다음 표는 v1과 v2에서 인스턴스 ID 문서의 메타데이터를 검색하는 방법을 비교한 것입니다.

사용 사례 v1 v2
리전 검색 
InstanceInfo instanceInfo = 
        EC2MetadataUtils.getInstanceInfo();
String region = instanceInfo.getRegion();
 
Ec2MetadataResponse response = 
    client.get("/latest/dynamic/instance-identity/document");
Document instanceInfo = response.asDocument();
String region = instanceInfo.asMap().get("region").asString();
인스턴스 ID 검색 
InstanceInfo instanceInfo = 
        EC2MetadataUtils.getInstanceInfo();
String instanceId = instanceInfo.instanceId;
 
Ec2MetadataResponse response = 
    client.get("/latest/dynamic/instance-identity/document");
Document instanceInfo = response.asDocument();
String instanceId = instanceInfo.asMap().get("instanceId").asString();
인스턴스 유형 검색 
InstanceInfo instanceInfo = 
        EC2MetadataUtils.getInstanceInfo();
String instanceType = instanceInfo.instanceType();
 
Ec2MetadataResponse response = 
    client.get("/latest/dynamic/instance-identity/document");
Document instanceInfo = response.asDocument();
String instanceType = instanceInfo.asMap().get("instanceType").asString();

엔드포인트 해상도 차이

다음 표는 SDK가 엔드포인트를 IMDS로 확인하기 위해 확인하는 위치를 보여줍니다. 위치는 내림차순으로 나열됩니다.

v1 v2
시스템 속성: com.amazonaws.sdk.ec2MetadataServiceEndpointOverride 클라이언트 빌더 구성 메서드: endpoint(...)
환경 변수: AWS_EC2_METADATA_SERVICE_ENDPOINT 시스템 속성: aws.ec2MetadataServiceEndpoint
Default Value: http://169.254.169.254 구성 파일: ec2_metadata_service_endpoint 설정이 포함된 ~.aws/config
확인된 endpoint-mode 관련된 값
기본 값: http://169.254.169.254

v2의 엔드포인트 해상도

빌더를 사용하여 엔드포인트를 명시적으로 설정하면 해당 엔드포인트 값이 다른 모든 설정보다 우선합니다. 다음 코드가 실행될 때 aws.ec2MetadataServiceEndpoint 시스템 속성 및 구성 파일 ec2_metadata_service_endpoint 설정이 있는 경우 무시됩니다.

Ec2MetadataClient client = Ec2MetadataClient
  .builder()
  .endpoint(URI.create("endpoint.to.use"))
  .build();

엔드포인트 모드

v2에서는 엔드포인트 모드를 지정하여 IPv4 또는 IPv6의 기본 엔드포인트 값을 사용하도록 메타데이터 클라이언트를 구성할 수 있습니다. v1에는 엔드포인트 모드를 사용할 수 없습니다. IPv4에 사용되는 기본값은 http://169.254.169.254, IPv6의 경우 http://[fd00:ec2::254]입니다.

다음 표는 우선 순위가 내려가는 순서대로 엔드포인트 모드를 설정할 수 있는 다양한 방법을 보여줍니다.

가능한 값
클라이언트 빌더 구성 메서드: endpointMode(...) 
Ec2MetadataClient client = Ec2MetadataClient
  .builder()
  .endpointMode(EndpointMode.IPV4)
  .build();
 EndpointMode.IPV4, EndpointMode.IPV6
시스템 속성 aws.ec2MetadataServiceEndpointMode IPv4, IPv6(대/소문자를 구분하지 않음)
Config 파일: ~.aws/config ec2_metadata_service_endpoint 설정 IPv4, IPv6(대/소문자를 구분하지 않음)
이전 방법으로는 지정되지 않음 IPv4가 사용됨

SDK가 v2에서 endpoint 또는 endpoint-mode를 확인하는 방법

  1. SDK는 클라이언트 빌더의 코드에서 설정한 값을 사용하며 외부 설정은 무시합니다. 클라이언트 빌더에서 endpoint와 endpointMode가 모두 호출되면 SDK는 예외를 던지므로, 어떤 메서드를 사용하든 엔드포인트 값을 사용합니다.

  2. 코드에서 값을 설정하지 않으면 SDK는 외부 구성에서 먼저 시스템 속성을 찾은 다음 구성 파일의 설정을 찾습니다.

    1. SDK는 먼저 엔드포인트 값을 확인합니다. 값이 발견되면 해당 값이 사용됩니다.

    2. 여전히 값을 찾지 못한 경우 SDK는 엔드포인트 모드 설정을 찾습니다.

  3. 마지막으로, SDK가 외부 설정을 찾지 못하고 코드에서 메타데이터 클라이언트를 구성하지 않은 경우 SDK는 http://169.254.169.254의 IPv4 값을 사용합니다.

IMDSv2

Amazon EC2는 인스턴스 메타데이터에 액세스하는 두 가지 접근 방식을 정의합니다.

  • 인스턴스 메타데이터 서비스 버전 1(IMDSv1) - 요청/응답 방식

  • 인스턴스 메타데이터 서비스 버전 2(IMDSv2) - 세션 지향 방식

다음 표는 Java SDK와 IMDS의 작동 방식을 비교한 것입니다.

v1 v2
IMDSv2가 기본적으로 사용됨 항상 IMDSv2를 사용함
각 요청에 대해 세션 토큰을 가져오려고 시도하고 세션 토큰을 가져오지 못하면 IMDSv1으로 돌아갑니다. 여러 요청에 재사용되는 세션 토큰을 내부 캐시에 보관합니다.

SDK for Java 2.x는 IMDSv2만 지원하며 IMDSv1로 돌아가지 않습니다.

구성 차이점

다음 표에는 다양한 구성 옵션이 나와 있습니다.

구성 v1 v2
재시도 구성을 사용할 수 없음 빌더 메서드 retryPolicy(...)를 통해 구성할 수 있습니다.
HTTP 연결 시간 제한은 AWS_METADATA_SERVICE_TIMEOUT 환경 변수를 통해 구성할 수 있습니다. 기본값은 1초입니다. 빌더 메서드인 httpClient(...)에 HTTP 클라이언트를 전달하여 구성할 수 있습니다. HTTP 클라이언트의 기본 연결 시간 제한은 2초입니다.

예제 v2 HTTP 구성

다음 예제는 메타데이터 클라이언트를 구성하는 방법을 보여줍니다. 이 예제에서는 연결 시간 제한을 구성하고 Apache HTTP 클라이언트를 사용합니다.

SdkHttpClient httpClient = ApacheHttpClient.builder()
    .connectionTimeout(Duration.ofSeconds(1))
    .build();

Ec2MetadataClient imdsClient = Ec2MetadataClient.builder()
    .httpClient(httpClient)
    .build();