기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.
# Amazon EC2 인스턴스 메타데이터 작업
Amazon EC2 인스턴스 메타데이터 서비스(메타데이터 클라이언트)용 Java SDK 클라이언트를 사용하면 애플리케이션이 로컬 EC2 인스턴스의 메타데이터에 액세스할 수 있습니다. 메타데이터 클라이언트는 [IMDSv2](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/configuring-instance-metadata-service.html)(인스턴스 메타데이터 서비스 v2)의 로컬 인스턴스와 함께 작동하며 세션 지향 요청을 사용합니다.
SDK에서는 두 개의 클라이언트 클래스를 사용할 수 있습니다. 동기식은 `[Ec2MetadataClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/imds/Ec2MetadataClient.html)`는 작업 차단용이고 [https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/imds/Ec2MetadataAsyncClient.html](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/imds/Ec2MetadataAsyncClient.html)는 비동기식 비차단 사용 사례용입니다.
## 시작하기
메타데이터 클라이언트를 사용하려면 `imds` Maven 아티팩트를 프로젝트에 추가하세요. 또한 클래스 경로에 `[SdkHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/SdkHttpClient.html)`(또는 비동기 변형용 `[SdkAsyncHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/async/SdkAsyncHttpClient.html)`)에 대한 클래스가 필요합니다.
다음 Maven XML은 메타데이터 클라이언트에 대한 종속성과 함께 동기 [UrlConnectionHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/urlconnection/UrlConnectionHttpClient.html)를 사용하기 위한 종속성 코드 조각을 보여줍니다.
```
software.amazon.awssdk
bom
VERSION
pom
import
software.amazon.awssdk
imds
software.amazon.awssdk
url-connection-client
```
[Maven 중앙 리포지토리](https://central.sonatype.com/artifact/software.amazon.awssdk/bom)에서 `bom` 아티팩트의 최신 버전을 검색하세요.
비동기 HTTP 클라이언트를 사용하려면 `url-connection-client` 아티팩트의 종속성 코드 조각을 바꾸세요. 예를 들어 다음 코드 조각은 [NettyNioAsyncHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/nio/netty/NettyNioAsyncHttpClient.html) 구현을 가져옵니다.
```
software.amazon.awssdk
netty-nio-client
```
## 메타데이터 클라이언트를 사용
### 메타데이터 클라이언트 인스턴스화
클래스 경로에 `SdkHttpClient` 인터페이스 구현이 하나만 있는 경우 비동기 `Ec2MetadataClient`를 인스턴스화할 수 있습니다. 그러려면 다음 코드 조각과 같이 정적 `Ec2MetadataClient#create()` 메서드를 호출합니다.
```
Ec2MetadataClient client = Ec2MetadataClient.create(); // 'Ec2MetadataAsyncClient#create' is the asynchronous version.
```
애플리케이션에 `SdkHttpClient` 또는 `SdkHttpAsyncClient` 인터페이스가 여러 개 구현되어 있는 경우 [구성 가능한 HTTP 클라이언트](#examples-ec2-IMDS-features-http) 단원에 표시된 대로 메타데이터 클라이언트가 사용할 구현을 지정해야 합니다.
**참고**
Amazon S3와 같은 대부분의 서비스 클라이언트의 경우 Java용 SDK는 `SdkHttpClient` 또는 `SdkHttpAsyncClient` 인터페이스의 구현을 자동으로 추가합니다. 메타데이터 클라이언트가 동일한 구현을 사용하는 경우 `Ec2MetadataClient#create()`가 작동합니다. 다른 구현이 필요한 경우 메타데이터 클라이언트를 만들 때 이를 지정해야 합니다.
### 요청 전송
인스턴스 메타데이터를 검색하려면 `EC2MetadataClient` 클래스를 인스턴스화하고 [인스턴스 메타데이터 카테고리](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/instancedata-data-categories.html)를 지정하는 경로 파라미터를 사용하여 `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 splits = response.asList();
```
응답이 JSON인 경우 다음 코드 조각과 같이 `Ec2MetadataResponse#asDocument` 메서드를 사용하여 JSON 응답을 [Document](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/core/document/Document.html) 인스턴스로 파싱합니다.
```
Document fullResponse = response.asDocument();
```
메타데이터 형식이 JSON이 아닌 경우 예외가 발생합니다. 응답이 성공적으로 파싱되면 [문서 API](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/core/document/package-summary.html)를 사용하여 응답을 더 자세히 검사할 수 있습니다. 인스턴스 [메타데이터 카테고리 차트](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/instancedata-data-categories.html)를 참조하여 JSON 형식의 응답을 제공하는 메타데이터 카테고리를 알아보세요.
## 메타데이터 클라이언트 구성
### 재시도
재시도 메커니즘을 사용하여 메타데이터 클라이언트를 구성할 수 있습니다. 이렇게 하면 클라이언트가 예상치 못한 이유로 실패한 요청을 자동으로 재시도할 수 있습니다. 기본적으로 클라이언트는 시도 사이에 기하급수적인 백오프 시간을 두고 실패한 요청에 대해 세 번 재시도합니다.
사용 사례에 다른 재시도 메커니즘이 필요한 경우 빌더의 `retryPolicy` 메서드를 사용하여 클라이언트를 사용자 지정할 수 있습니다. 예를 들어 다음 예제는 시도 간 고정 지연 시간이 2초이고 재시도 횟수가 5회로 구성된 동기 클라이언트를 보여줍니다.
```
BackoffStrategy fixedBackoffStrategy = FixedDelayBackoffStrategy.create(Duration.ofSeconds(2));
Ec2MetadataClient client =
Ec2MetadataClient.builder()
.retryPolicy(retryPolicyBuilder -> retryPolicyBuilder.numRetries(5)
.backoffStrategy(fixedBackoffStrategy))
.build();
```
메타데이터 클라이언트에서 사용할 수 있는 여러 [BackoffStrategies](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/core/retry/backoff/package-summary.html)가 있습니다.
다음 코드 조각과 같이 재시도 메커니즘을 완전히 비활성화할 수도 있습니다.
```
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 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 클라이언트 구성 AWS SDK for Java 2.x](http-configuration.md) 항목에서는 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이 대신 사용됩니다.