Amazon EC2 인스턴스 메타데이터 작업

Amazon EC2 인스턴스 메타데이터 서비스(메타데이터 클라이언트)용 Java SDK 클라이언트를 사용하면 애플리케이션이 로컬 EC2 인스턴스의 메타데이터에 액세스할 수 있습니다. 메타데이터 클라이언트는 IMDSv2(인스턴스 메타데이터 서비스 v2)의 로컬 인스턴스와 함께 작동하며 세션 지향 요청을 사용합니다.

SDK에서는 두 개의 클라이언트 클래스를 사용할 수 있습니다. 동기식은 Ec2MetadataClient는 작업 차단용이고 Ec2MetadataAsyncClient는 비동기식 비차단 사용 사례용입니다.

시작하기

메타데이터 클라이언트를 사용하려면 imds Maven 아티팩트를 프로젝트에 추가하세요. 또한 클래스 경로에 SdkHttpClient(또는 비동기 변형용 SdkAsyncHttpClient)에 대한 클래스가 필요합니다.

다음 Maven XML은 메타데이터 클라이언트에 대한 종속성과 함께 동기 UrlConnectionHttpClient를 사용하기 위한 종속성 코드 조각을 보여줍니다.

<dependencyManagement>
   <dependencies>
        <dependency>
            <groupId>software.amazon.awssdk</groupId>
            <artifactId>bom</artifactId>
            <version>VERSION</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>url-connection-client</artifactId>
    </dependency>
    <!-- other dependencies --> 
</dependencies>

Maven 중앙 리포지토리에서 bom 아티팩트의 최신 버전을 검색하세요.

비동기 HTTP 클라이언트를 사용하려면 url-connection-client 아티팩트의 종속성 코드 조각을 바꾸세요. 예를 들어 다음 코드 조각은 NettyNioAsyncHttpClient 구현을 가져옵니다.

    <dependency>
        <groupId>software.amazon.awssdk</groupId>
        <artifactId>netty-nio-client</artifactId>
    </dependency>

메타데이터 클라이언트를 사용

메타데이터 클라이언트 인스턴스화

클래스 경로에 SdkHttpClient 인터페이스 구현이 하나만 있는 경우 비동기 Ec2MetadataClient를 인스턴스화할 수 있습니다. 그러려면 다음 코드 조각과 같이 정적 Ec2MetadataClient#create() 메서드를 호출합니다.

Ec2MetadataClient client = Ec2MetadataClient.create(); // 'Ec2MetadataAsyncClient#create' is the asynchronous version.

애플리케이션에 SdkHttpClient 또는 SdkHttpAsyncClient 인터페이스가 여러 개 구현되어 있는 경우 구성 가능한 HTTP 클라이언트 단원에 표시된 대로 메타데이터 클라이언트가 사용할 구현을 지정해야 합니다.

참고

Amazon S3와 같은 대부분의 서비스 클라이언트의 경우 Java용 SDK는 SdkHttpClient 또는 SdkHttpAsyncClient 인터페이스의 구현을 자동으로 추가합니다. 메타데이터 클라이언트가 동일한 구현을 사용하는 경우 Ec2MetadataClient#create()가 작동합니다. 다른 구현이 필요한 경우 메타데이터 클라이언트를 만들 때 이를 지정해야 합니다.

요청 전송

인스턴스 메타데이터를 검색하려면 EC2MetadataClient 클래스를 인스턴스화하고 인스턴스 메타데이터 카테고리를 지정하는 경로 파라미터를 사용하여 get 메서드를 호출합니다.

다음 예제는 ami-id 키와 관련된 값을 콘솔에 출력합니다.

Ec2MetadataClient client = Ec2MetadataClient.create();
Ec2MetadataResponse response = client.get("/latest/meta-data/ami-id");
System.out.println(response.asString());
client.close(); // Closes the internal resources used by the Ec2MetadataClient class.

경로가 유효하지 않은 경우 get 메서드에서 예외가 발생합니다.

여러 요청에 동일한 클라이언트 인스턴스를 재사용하되 리소스를 릴리스하는 데 더 이상 필요하지 않을 때는 클라이언트에서 close를 호출하세요. close 메서드가 호출된 후에는 클라이언트 인스턴스를 더 이상 사용할 수 없습니다.

응답 파싱

EC2 인스턴스 메타데이터는 다양한 형식으로 출력될 수 있습니다. 일반 텍스트와 JSON이 가장 일반적으로 사용되는 형식입니다. 메타데이터 클라이언트는 이러한 형식을 사용할 수 있는 방법을 제공합니다.

다음 예제에서 볼 수 있듯이 asString 메서드를 사용하여 데이터를 Java 문자열로 가져옵니다. asList 메서드를 사용하여 여러 줄을 반환하는 일반 텍스트 응답을 분리할 수도 있습니다.

Ec2MetadataClient client = Ec2MetadataClient.create();
Ec2MetadataResponse response = client.get("/latest/meta-data/");
String fullResponse = response.asString();
List<String> splits = response.asList();

응답이 JSON인 경우 다음 코드 조각과 같이 Ec2MetadataResponse#asDocument 메서드를 사용하여 JSON 응답을 Document 인스턴스로 파싱합니다.

Document fullResponse = response.asDocument();

메타데이터 형식이 JSON이 아닌 경우 예외가 발생합니다. 응답이 성공적으로 파싱되면 문서 API를 사용하여 응답을 더 자세히 검사할 수 있습니다. 인스턴스 메타데이터 카테고리 차트를 참조하여 JSON 형식의 응답을 제공하는 메타데이터 카테고리를 알아보세요.

메타데이터 클라이언트 구성

재시도

재시도 메커니즘을 사용하여 메타데이터 클라이언트를 구성할 수 있습니다. 이렇게 하면 클라이언트가 예상치 못한 이유로 실패한 요청을 자동으로 재시도할 수 있습니다. 기본적으로 클라이언트는 시도 사이에 기하급수적인 백오프 시간을 두고 실패한 요청에 대해 세 번 재시도합니다.

사용 사례에 다른 재시도 메커니즘이 필요한 경우 빌더의 retryPolicy 메서드를 사용하여 클라이언트를 사용자 지정할 수 있습니다. 예를 들어 다음 예제는 시도 간 고정 지연 시간이 2초이고 재시도 횟수가 5회로 구성된 동기 클라이언트를 보여줍니다.

BackoffStrategy fixedBackoffStrategy = FixedDelayBackoffStrategy.create(Duration.ofSeconds(2));
Ec2MetadataClient client =
    Ec2MetadataClient.builder()
                     .retryPolicy(retryPolicyBuilder -> retryPolicyBuilder.numRetries(5)
                                                                           .backoffStrategy(fixedBackoffStrategy))
                     .build();

메타데이터 클라이언트에서 사용할 수 있는 여러 BackoffStrategies가 있습니다.

다음 코드 조각과 같이 재시도 메커니즘을 완전히 비활성화할 수도 있습니다.

Ec2MetadataClient client =
    Ec2MetadataClient.builder()
                    .retryPolicy(Ec2MetadataRetryPolicy.none())
                    .build();

Ec2MetadataRetryPolicy#none()를 사용하면 기본 재시도 정책이 비활성화되어 메타데이터 클라이언트가 재시도를 시도하지 않습니다.

IP 버전

기본적으로 메타데이터 클라이언트는 http://169.254.169.254에서 IPV4 엔드포인트를 사용합니다. IPV6 버전을 사용하도록 클라이언트를 변경하려면 빌더의 endpointMode 또는 endpoint 메서드를 사용하세요. 빌더에서 두 메서드를 모두 호출하면 예외가 발생합니다.

다음 예제는 두 IPV6 옵션을 모두 보여줍니다.

Ec2MetadataClient client =
    Ec2MetadataClient.builder()
                     .endpointMode(EndpointMode.IPV6)
                     .build();

Ec2MetadataClient client =
    Ec2MetadataClient.builder()
                     .endpoint(URI.create("http://[fd00:ec2::254]"))
                     .build();

주요 기능

비동기 클라이언트

비차단 버전의 클라이언트를 사용하려면 Ec2MetadataAsyncClient 클래스의 인스턴스를 인스턴스화하세요. 다음 예제의 코드는 기본 설정으로 비동기 클라이언트를 만들고 get 메서드를 사용하여 ami-id 키 값을 검색합니다.

Ec2MetadataAsyncClient asyncClient = Ec2MetadataAsyncClient.create();
CompletableFuture<Ec2MetadataResponse> response = asyncClient.get("/latest/meta-data/ami-id");

get 메서드에서 반환된 java.util.concurrent.CompletableFuture은 응답이 반환될 때 완료됩니다. 다음 예제는 ami-id 메타데이터를 콘솔에 출력합니다.

response.thenAccept(metadata -> System.out.println(metadata.asString()));

구성 가능한 HTTP 클라이언트

각 메타데이터 클라이언트의 빌더에는 사용자 지정 HTTP 클라이언트를 제공하는 데 사용할 수 있는 httpClient 방법이 있습니다.

다음 예제는 사용자 지정 UrlConnectionHttpClient 인스턴스의 코드를 보여줍니다.

SdkHttpClient httpClient =
    UrlConnectionHttpClient.builder()
                           .socketTimeout(Duration.ofMinutes(5))
                           .proxyConfiguration(proxy -> proxy.endpoint(URI.create("http://proxy.example.net:8888"))))
                           .build();
Ec2MetadataClient metaDataClient =
    Ec2MetadataClient.builder()
                     .httpClient(httpClient)
                     .build();
// Use the metaDataClient instance.
metaDataClient.close();   // Close the instance when no longer needed.

다음 예제는 비동기 메타데이터 클라이언트가 있는 사용자 지정 NettyNioAsyncHttpClient 인스턴스의 코드를 보여줍니다.

SdkAsyncHttpClient httpAsyncClient = 
    NettyNioAsyncHttpClient.builder()
                           .connectionTimeout(Duration.ofMinutes(5))
                           .maxConcurrency(100)
                           .build();
Ec2MetadataAsyncClient asyncMetaDataClient =
    Ec2MetadataAsyncClient.builder()
                          .httpClient(httpAsyncClient)
                          .build();
// Use the asyncMetaDataClient instance.
asyncMetaDataClient.close();   // Close the instance when no longer needed.

이 가이드의 HTTP고객 항목에서는 Java용 SDK에서 사용할 수 있는 HTTP 클라이언트를 구성하는 방법에 대한 세부 정보를 제공합니다.

토큰 캐싱

메타데이터 클라이언트는 IMDSv2를 사용하므로 모든 요청은 세션과 연결됩니다. 세션은 메타데이터 클라이언트가 관리하는 만료일이 있는 토큰으로 정의됩니다. 모든 메타데이터 요청은 만료될 때까지 토큰을 자동으로 재사용합니다.

기본적으로 토큰은 6시간(21,600초) 동안 지속됩니다. 특정 사용 사례에 고급 구성이 필요한 경우가 아니면 기본 TTL(time to live) 값을 유지하는 것이 좋습니다.

필요한 경우 tokenTtl 빌더 메서드를 사용하여 기간을 구성하세요. 예를 들어 다음 코드 조각의 코드는 세션 기간이 5분인 클라이언트를 만듭니다.

Ec2MetadataClient client =
    Ec2MetadataClient.builder()
                     .tokenTtl(Duration.ofMinutes(5))
                     .build();

빌더에서 tokenTtl 메서드 호출을 생략하면 기본 기간인 21,600이 대신 사용됩니다.