# Work with Amazon EC2
This section provides examples of programming [Amazon EC2](https://docs.aws.amazon.com/ec2/) that use the AWS SDK for Java 2.x.
**Topics**
+ [Manage Amazon EC2 instances](examples-ec2-instances.md)
+ [Use AWS Regions and Availability Zones](examples-ec2-regions-zones.md)
+ [Work with security groups in Amazon EC2](examples-ec2-security-groups.md)
+ [Work with Amazon EC2 instance metadata](examples-ec2-IMDS.md)
# Manage Amazon EC2 instances
## Create an instance
Create a new Amazon EC2 instance by calling the [Ec2Client](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/ec2/Ec2Client.html)’s [https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/ec2/Ec2Client.html#runInstances(software.amazon.awssdk.services.ec2.model.RunInstancesRequest)](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/ec2/Ec2Client.html#runInstances(software.amazon.awssdk.services.ec2.model.RunInstancesRequest)) method, providing it with a [RunInstancesRequest](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/ec2/model/RunInstancesRequest.html) containing the [Amazon Machine Image (AMI)](https://docs.aws.amazon.com//AWSEC2/latest/UserGuide/AMIs.html) to use and an [instance type](https://docs.aws.amazon.com//AWSEC2/latest/UserGuide/instance-types.html).
**Imports**
```
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.ec2.Ec2Client;
import software.amazon.awssdk.services.ec2.model.InstanceType;
import software.amazon.awssdk.services.ec2.model.RunInstancesRequest;
import software.amazon.awssdk.services.ec2.model.RunInstancesResponse;
import software.amazon.awssdk.services.ec2.model.Tag;
import software.amazon.awssdk.services.ec2.model.CreateTagsRequest;
import software.amazon.awssdk.services.ec2.model.Ec2Exception;
```
**Code**
```
public static String createEC2Instance(Ec2Client ec2,String name, String amiId ) {
RunInstancesRequest runRequest = RunInstancesRequest.builder()
.imageId(amiId)
.instanceType(InstanceType.T1_MICRO)
.maxCount(1)
.minCount(1)
.build();
RunInstancesResponse response = ec2.runInstances(runRequest);
String instanceId = response.instances().get(0).instanceId();
Tag tag = Tag.builder()
.key("Name")
.value(name)
.build();
CreateTagsRequest tagRequest = CreateTagsRequest.builder()
.resources(instanceId)
.tags(tag)
.build();
try {
ec2.createTags(tagRequest);
System.out.printf(
"Successfully started EC2 Instance %s based on AMI %s",
instanceId, amiId);
return instanceId;
} catch (Ec2Exception e) {
System.err.println(e.awsErrorDetails().errorMessage());
System.exit(1);
}
return "";
}
```
See the [complete example](https://github.com/awsdocs/aws-doc-sdk-examples/blob/ac748d8ef99cd17e297cb74fe13aa671e2679088/javav2/example_code/ec2/src/main/java/com/example/ec2/CreateInstance.java) on GitHub.
## Start an instance
To start an Amazon EC2 instance, call the Ec2Client’s [https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/ec2/Ec2Client.html#startInstances(software.amazon.awssdk.services.ec2.model.StartInstancesRequest)](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/ec2/Ec2Client.html#startInstances(software.amazon.awssdk.services.ec2.model.StartInstancesRequest)) method, providing it with a [StartInstancesRequest](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/ec2/model/StartInstancesRequest.html) containing the ID of the instance to start.
**Imports**
```
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.ec2.Ec2Client;
import software.amazon.awssdk.services.ec2.model.StartInstancesRequest;
import software.amazon.awssdk.services.ec2.model.StopInstancesRequest;
```
**Code**
```
public static void startInstance(Ec2Client ec2, String instanceId) {
StartInstancesRequest request = StartInstancesRequest.builder()
.instanceIds(instanceId)
.build();
ec2.startInstances(request);
System.out.printf("Successfully started instance %s", instanceId);
}
```
See the [complete example](https://github.com/awsdocs/aws-doc-sdk-examples/blob/ac748d8ef99cd17e297cb74fe13aa671e2679088/javav2/example_code/ec2/src/main/java/com/example/ec2/StartStopInstance.java) on GitHub.
## Stop an instance
To stop an Amazon EC2 instance, call the Ec2Client’s [https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/ec2/Ec2Client.html#stopInstances(software.amazon.awssdk.services.ec2.model.StopInstancesRequest)](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/ec2/Ec2Client.html#stopInstances(software.amazon.awssdk.services.ec2.model.StopInstancesRequest)) method, providing it with a [StopInstancesRequest](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/ec2/model/StopInstancesRequest.html) containing the ID of the instance to stop.
**Imports**
```
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.ec2.Ec2Client;
import software.amazon.awssdk.services.ec2.model.StartInstancesRequest;
import software.amazon.awssdk.services.ec2.model.StopInstancesRequest;
```
**Code**
```
public static void stopInstance(Ec2Client ec2, String instanceId) {
StopInstancesRequest request = StopInstancesRequest.builder()
.instanceIds(instanceId)
.build();
ec2.stopInstances(request);
System.out.printf("Successfully stopped instance %s", instanceId);
}
```
See the [complete example](https://github.com/awsdocs/aws-doc-sdk-examples/blob/ac748d8ef99cd17e297cb74fe13aa671e2679088/javav2/example_code/ec2/src/main/java/com/example/ec2/StartStopInstance.java) on GitHub.
## Reboot an instance
To reboot an Amazon EC2 instance, call the Ec2Client’s [https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/ec2/Ec2Client.html#rebootInstances(software.amazon.awssdk.services.ec2.model.RebootInstancesRequest)](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/ec2/Ec2Client.html#rebootInstances(software.amazon.awssdk.services.ec2.model.RebootInstancesRequest)) method, providing it with a [RebootInstancesRequest](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/ec2/model/RebootInstancesRequest.html) containing the ID of the instance to reboot.
**Imports**
```
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.ec2.Ec2Client;
import software.amazon.awssdk.services.ec2.model.Ec2Exception;
import software.amazon.awssdk.services.ec2.model.RebootInstancesRequest;
```
**Code**
```
public static void rebootEC2Instance(Ec2Client ec2, String instanceId) {
try {
RebootInstancesRequest request = RebootInstancesRequest.builder()
.instanceIds(instanceId)
.build();
ec2.rebootInstances(request);
System.out.printf(
"Successfully rebooted instance %s", instanceId);
} catch (Ec2Exception e) {
System.err.println(e.awsErrorDetails().errorMessage());
System.exit(1);
}
}
```
See the [complete example](https://github.com/awsdocs/aws-doc-sdk-examples/blob/ac748d8ef99cd17e297cb74fe13aa671e2679088/javav2/example_code/ec2/src/main/java/com/example/ec2/RebootInstance.java) on GitHub.
## Describe instances
To list your instances, create a [DescribeInstancesRequest](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/ec2/model/DescribeInstancesRequest.html) and call the Ec2Client’s [https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/ec2/Ec2Client.html#describeInstances(software.amazon.awssdk.services.ec2.model.DescribeInstancesRequest)](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/ec2/Ec2Client.html#describeInstances(software.amazon.awssdk.services.ec2.model.DescribeInstancesRequest)) method. It will return a [DescribeInstancesResponse](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/ec2/model/DescribeInstancesResponse.html) object that you can use to list the Amazon EC2 instances for your account and region.
Instances are grouped by *reservation*. Each reservation corresponds to the call to `startInstances` that launched the instance. To list your instances, you must first call the `DescribeInstancesResponse` class' `reservations` method, and then call `instances` on each returned [Reservation](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/ec2/model/Reservation.html) object.
**Imports**
```
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.ec2.Ec2Client;
import software.amazon.awssdk.services.ec2.model.DescribeInstancesRequest;
import software.amazon.awssdk.services.ec2.model.DescribeInstancesResponse;
import software.amazon.awssdk.services.ec2.model.Instance;
import software.amazon.awssdk.services.ec2.model.Reservation;
import software.amazon.awssdk.services.ec2.model.Ec2Exception;
```
**Code**
```
public static void describeEC2Instances( Ec2Client ec2){
String nextToken = null;
try {
do {
DescribeInstancesRequest request = DescribeInstancesRequest.builder().maxResults(6).nextToken(nextToken).build();
DescribeInstancesResponse response = ec2.describeInstances(request);
for (Reservation reservation : response.reservations()) {
for (Instance instance : reservation.instances()) {
System.out.println("Instance Id is " + instance.instanceId());
System.out.println("Image id is "+ instance.imageId());
System.out.println("Instance type is "+ instance.instanceType());
System.out.println("Instance state name is "+ instance.state().name());
System.out.println("monitoring information is "+ instance.monitoring().state());
}
}
nextToken = response.nextToken();
} while (nextToken != null);
} catch (Ec2Exception e) {
System.err.println(e.awsErrorDetails().errorMessage());
System.exit(1);
}
}
```
Results are paged; you can get further results by passing the value returned from the result object’s `nextToken` method to a new request object’s `nextToken` method, then using the new request object in your next call to `describeInstances`.
See the [complete example](https://github.com/awsdocs/aws-doc-sdk-examples/blob/ac748d8ef99cd17e297cb74fe13aa671e2679088/javav2/example_code/ec2/src/main/java/com/example/ec2/DescribeInstances.java) on GitHub.
## Monitor an instance
You can monitor various aspects of your Amazon EC2 instances, such as CPU and network utilization, available memory, and disk space remaining. To learn more about instance monitoring, see [Monitoring Amazon EC2](https://docs.aws.amazon.com//AWSEC2/latest/UserGuide/monitoring_ec2.html) in the Amazon EC2 User Guide for Linux Instances.
To start monitoring an instance, you must create a [MonitorInstancesRequest](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/ec2/model/MonitorInstancesRequest.html) with the ID of the instance to monitor, and pass it to the Ec2Client’s [https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/ec2/Ec2Client.html#monitorInstances(software.amazon.awssdk.services.ec2.model.MonitorInstancesRequest)](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/ec2/Ec2Client.html#monitorInstances(software.amazon.awssdk.services.ec2.model.MonitorInstancesRequest)) method.
**Imports**
```
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.ec2.Ec2Client;
import software.amazon.awssdk.services.ec2.model.MonitorInstancesRequest;
import software.amazon.awssdk.services.ec2.model.UnmonitorInstancesRequest;
```
**Code**
```
public static void monitorInstance( Ec2Client ec2, String instanceId) {
MonitorInstancesRequest request = MonitorInstancesRequest.builder()
.instanceIds(instanceId).build();
ec2.monitorInstances(request);
System.out.printf(
"Successfully enabled monitoring for instance %s",
instanceId);
}
```
See the [complete example](https://github.com/awsdocs/aws-doc-sdk-examples/blob/ac748d8ef99cd17e297cb74fe13aa671e2679088/javav2/example_code/ec2/src/main/java/com/example/ec2/MonitorInstance.java) on GitHub.
## Stop instance monitoring
To stop monitoring an instance, create an [UnmonitorInstancesRequest](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/ec2/model/UnmonitorInstancesRequest.html) with the ID of the instance to stop monitoring, and pass it to the Ec2Client’s [https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/ec2/Ec2Client.html#unmonitorInstances(software.amazon.awssdk.services.ec2.model.UnmonitorInstancesRequest)](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/ec2/Ec2Client.html#unmonitorInstances(software.amazon.awssdk.services.ec2.model.UnmonitorInstancesRequest)) method.
**Imports**
```
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.ec2.Ec2Client;
import software.amazon.awssdk.services.ec2.model.MonitorInstancesRequest;
import software.amazon.awssdk.services.ec2.model.UnmonitorInstancesRequest;
```
**Code**
```
public static void unmonitorInstance(Ec2Client ec2, String instanceId) {
UnmonitorInstancesRequest request = UnmonitorInstancesRequest.builder()
.instanceIds(instanceId).build();
ec2.unmonitorInstances(request);
System.out.printf(
"Successfully disabled monitoring for instance %s",
instanceId);
}
```
See the [complete example](https://github.com/awsdocs/aws-doc-sdk-examples/blob/ac748d8ef99cd17e297cb74fe13aa671e2679088/javav2/example_code/ec2/src/main/java/com/example/ec2/MonitorInstance.java) on GitHub.
## More information
+ [RunInstances](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_RunInstances.html) in the Amazon EC2 API Reference
+ [DescribeInstances](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_DescribeInstances.html) in the Amazon EC2 API Reference
+ [StartInstances](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_StartInstances.html) in the Amazon EC2 API Reference
+ [StopInstances](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_StopInstances.html) in the Amazon EC2 API Reference
+ [RebootInstances](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_RebootInstances.html) in the Amazon EC2 API Reference
+ [MonitorInstances](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_MonitorInstances.html) in the Amazon EC2 API Reference
+ [UnmonitorInstances](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_UnmonitorInstances.html) in the Amazon EC2 API Reference
# Use AWS Regions and Availability Zones
## Describe Regions
To list the Regions available to your account, call the Ec2Client’s `describeRegions` method. It returns a [DescribeRegionsResponse](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/ec2/model/DescribeRegionsResponse.html). Call the returned object’s `regions` method to get a list of [Region](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/ec2/model/Region.html) objects that represent each Region.
**Imports**
```
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.ec2.Ec2AsyncClient;
import software.amazon.awssdk.services.ec2.model.DescribeRegionsResponse;
import software.amazon.awssdk.services.ec2.model.DescribeAvailabilityZonesResponse;
import java.util.concurrent.CompletableFuture;
```
**Code**
```
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.ec2.Ec2AsyncClient;
import software.amazon.awssdk.services.ec2.model.DescribeRegionsResponse;
import software.amazon.awssdk.services.ec2.model.DescribeAvailabilityZonesResponse;
import java.util.concurrent.CompletableFuture;
/**
* Before running this Java V2 code example, set up your development
* environment, including your credentials.
*
* For more information, see the following documentation topic:
*
* https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/get-started.html
*/
public class DescribeRegionsAndZones {
public static void main(String[] args) {
Ec2AsyncClient ec2AsyncClient = Ec2AsyncClient.builder()
.region(Region.US_EAST_1)
.build();
try {
CompletableFuture future = describeEC2RegionsAndZonesAsync(ec2AsyncClient);
future.join(); // Wait for both async operations to complete.
} catch (RuntimeException rte) {
System.err.println("An exception occurred: " + (rte.getCause() != null ? rte.getCause().getMessage() : rte.getMessage()));
}
}
/**
* Asynchronously describes the EC2 regions and availability zones.
*
* @param ec2AsyncClient the EC2 async client used to make the API calls
* @return a {@link CompletableFuture} that completes when both the region and availability zone descriptions are complete
*/
public static CompletableFuture describeEC2RegionsAndZonesAsync(Ec2AsyncClient ec2AsyncClient) {
// Initiate the asynchronous request to describe regions
CompletableFuture regionsResponse = ec2AsyncClient.describeRegions();
// Handle the response or exception for regions
CompletableFuture regionsFuture = regionsResponse.whenComplete((regionsResp, ex) -> {
if (ex != null) {
// Handle the exception by throwing a RuntimeException
throw new RuntimeException("Failed to describe EC2 regions.", ex);
} else if (regionsResp == null || regionsResp.regions().isEmpty()) {
// Throw an exception if the response is null or the result is empty
throw new RuntimeException("No EC2 regions found.");
} else {
// Process the response if no exception occurred and the result is not empty
regionsResp.regions().forEach(region -> {
System.out.printf(
"Found Region %s with endpoint %s%n",
region.regionName(),
region.endpoint());
});
}
});
CompletableFuture zonesResponse = ec2AsyncClient.describeAvailabilityZones();
CompletableFuture zonesFuture = zonesResponse.whenComplete((zonesResp, ex) -> {
if (ex != null) {
throw new RuntimeException("Failed to describe EC2 availability zones.", ex);
} else if (zonesResp == null || zonesResp.availabilityZones().isEmpty()) {
throw new RuntimeException("No EC2 availability zones found.");
} else {
zonesResp.availabilityZones().forEach(zone -> {
System.out.printf(
"Found Availability Zone %s with status %s in region %s%n",
zone.zoneName(),
zone.state(),
zone.regionName()
);
});
}
});
return CompletableFuture.allOf(regionsFuture, zonesFuture);
}
}
```
See the [complete example](https://github.com/awsdocs/aws-doc-sdk-examples/blob/7486a1a092aa8e16a21698ef26f9d524fef62e55/javav2/example_code/ec2/src/main/java/com/example/ec2/DescribeRegionsAndZones.java) on GitHub.
## Describe availability zones
To list each Availability Zone available to your account, call the Ec2Client’s `describeAvailabilityZones` method. It returns a [DescribeAvailabilityZonesResponse](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/ec2/model/DescribeAvailabilityZonesResponse.html). Call its `availabilityZones` method to get a list of [AvailabilityZone](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/ec2/model/AvailabilityZone.html) objects that represent each Availability Zone.
**Imports**
```
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.ec2.Ec2AsyncClient;
import software.amazon.awssdk.services.ec2.model.DescribeRegionsResponse;
import software.amazon.awssdk.services.ec2.model.DescribeAvailabilityZonesResponse;
import java.util.concurrent.CompletableFuture;
```
**Code**
Create the Ec2Client.
```
Ec2AsyncClient ec2AsyncClient = Ec2AsyncClient.builder()
.region(Region.US_EAST_1)
.build();
```
Then call describeAvailabilityZones() and retrieve results.
```
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.ec2.Ec2AsyncClient;
import software.amazon.awssdk.services.ec2.model.DescribeRegionsResponse;
import software.amazon.awssdk.services.ec2.model.DescribeAvailabilityZonesResponse;
import java.util.concurrent.CompletableFuture;
/**
* Before running this Java V2 code example, set up your development
* environment, including your credentials.
*
* For more information, see the following documentation topic:
*
* https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/get-started.html
*/
public class DescribeRegionsAndZones {
public static void main(String[] args) {
Ec2AsyncClient ec2AsyncClient = Ec2AsyncClient.builder()
.region(Region.US_EAST_1)
.build();
try {
CompletableFuture future = describeEC2RegionsAndZonesAsync(ec2AsyncClient);
future.join(); // Wait for both async operations to complete.
} catch (RuntimeException rte) {
System.err.println("An exception occurred: " + (rte.getCause() != null ? rte.getCause().getMessage() : rte.getMessage()));
}
}
/**
* Asynchronously describes the EC2 regions and availability zones.
*
* @param ec2AsyncClient the EC2 async client used to make the API calls
* @return a {@link CompletableFuture} that completes when both the region and availability zone descriptions are complete
*/
public static CompletableFuture describeEC2RegionsAndZonesAsync(Ec2AsyncClient ec2AsyncClient) {
// Initiate the asynchronous request to describe regions
CompletableFuture regionsResponse = ec2AsyncClient.describeRegions();
// Handle the response or exception for regions
CompletableFuture regionsFuture = regionsResponse.whenComplete((regionsResp, ex) -> {
if (ex != null) {
// Handle the exception by throwing a RuntimeException
throw new RuntimeException("Failed to describe EC2 regions.", ex);
} else if (regionsResp == null || regionsResp.regions().isEmpty()) {
// Throw an exception if the response is null or the result is empty
throw new RuntimeException("No EC2 regions found.");
} else {
// Process the response if no exception occurred and the result is not empty
regionsResp.regions().forEach(region -> {
System.out.printf(
"Found Region %s with endpoint %s%n",
region.regionName(),
region.endpoint());
});
}
});
CompletableFuture zonesResponse = ec2AsyncClient.describeAvailabilityZones();
CompletableFuture zonesFuture = zonesResponse.whenComplete((zonesResp, ex) -> {
if (ex != null) {
throw new RuntimeException("Failed to describe EC2 availability zones.", ex);
} else if (zonesResp == null || zonesResp.availabilityZones().isEmpty()) {
throw new RuntimeException("No EC2 availability zones found.");
} else {
zonesResp.availabilityZones().forEach(zone -> {
System.out.printf(
"Found Availability Zone %s with status %s in region %s%n",
zone.zoneName(),
zone.state(),
zone.regionName()
);
});
}
});
return CompletableFuture.allOf(regionsFuture, zonesFuture);
}
}
```
See the [complete example](https://github.com/awsdocs/aws-doc-sdk-examples/blob/7486a1a092aa8e16a21698ef26f9d524fef62e55/javav2/example_code/ec2/src/main/java/com/example/ec2/DescribeRegionsAndZones.java) on GitHub.
## Describe accounts
To list EC2-related information about your account, call the Ec2Client’s `describeAccountAttributes` method. This method returns a [DescribeAccountAttributesResponse](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/ec2/model/DescribeAccountAttributesResponse.html) object. Invoke this objects `accountAttributes` method to get a list of [AccountAttribute](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/ec2/model/AccountAttribute.html) objects. You can iterate through the list to retrieve an `AccountAttribute` object.
You can get your account’s attribute values by invoking the `AccountAttribute` object’s `attributeValues` method. This method returns a list of [AccountAttributeValue](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/ec2/model/AccountAttributeValue.html) objects. You can iterate through this second list to display the value of attributes (see the following code example).
**Imports**
```
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.ec2.Ec2AsyncClient;
import software.amazon.awssdk.services.ec2.model.DescribeAccountAttributesResponse;
import java.util.concurrent.CompletableFuture;
```
**Code**
```
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.ec2.Ec2AsyncClient;
import software.amazon.awssdk.services.ec2.model.DescribeAccountAttributesResponse;
import java.util.concurrent.CompletableFuture;
/**
* Before running this Java V2 code example, set up your development
* environment, including your credentials.
*
* For more information, see the following documentation topic:
*
* https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/get-started.html
*/
public class DescribeAccount {
public static void main(String[] args) {
Ec2AsyncClient ec2AsyncClient = Ec2AsyncClient.builder()
.region(Region.US_EAST_1)
.build();
try {
CompletableFuture future = describeEC2AccountAsync(ec2AsyncClient);
future.join();
System.out.println("EC2 Account attributes described successfully.");
} catch (RuntimeException rte) {
System.err.println("An exception occurred: " + (rte.getCause() != null ? rte.getCause().getMessage() : rte.getMessage()));
}
}
/**
* Describes the EC2 account attributes asynchronously.
*
* @param ec2AsyncClient the EC2 asynchronous client to use for the operation
* @return a {@link CompletableFuture} containing the {@link DescribeAccountAttributesResponse} with the account attributes
*/
public static CompletableFuture describeEC2AccountAsync(Ec2AsyncClient ec2AsyncClient) {
CompletableFuture response = ec2AsyncClient.describeAccountAttributes();
return response.whenComplete((accountResults, ex) -> {
if (ex != null) {
// Handle the exception by throwing a RuntimeException.
throw new RuntimeException("Failed to describe EC2 account attributes.", ex);
} else if (accountResults == null || accountResults.accountAttributes().isEmpty()) {
// Throw an exception if the response is null or no account attributes are found.
throw new RuntimeException("No account attributes found.");
} else {
// Process the response if no exception occurred.
accountResults.accountAttributes().forEach(attribute -> {
System.out.println("\nThe name of the attribute is " + attribute.attributeName());
attribute.attributeValues().forEach(
myValue -> System.out.println("The value of the attribute is " + myValue.attributeValue()));
});
}
});
}
}
```
See the [complete example](https://github.com/awsdocs/aws-doc-sdk-examples/blob/7486a1a092aa8e16a21698ef26f9d524fef62e55/javav2/example_code/ec2/src/main/java/com/example/ec2/DescribeAccount.java) on GitHub.
## More information
+ [Regions and Availability Zones](https://docs.aws.amazon.com//AWSEC2/latest/UserGuide/using-regions-availability-zones.html) in the Amazon EC2 User Guide for Linux Instances
+ [DescribeRegions](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_DescribeRegions.html) in the Amazon EC2 API Reference
+ [DescribeAvailabilityZones](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_DescribeAvailabilityZones.html) in the Amazon EC2 API Reference
# Work with security groups in Amazon EC2
## Create a security group
To create a security group, call the Ec2Client’s `createSecurityGroup` method with a [CreateSecurityGroupRequest](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/ec2/model/CreateSecurityGroupRequest.html) that contains the key’s name.
**Imports**
```
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.ec2.Ec2Client;
import software.amazon.awssdk.services.ec2.model.CreateSecurityGroupRequest;
import software.amazon.awssdk.services.ec2.model.AuthorizeSecurityGroupIngressRequest;
import software.amazon.awssdk.services.ec2.model.AuthorizeSecurityGroupIngressResponse;
import software.amazon.awssdk.services.ec2.model.Ec2Exception;
import software.amazon.awssdk.services.ec2.model.IpPermission;
import software.amazon.awssdk.services.ec2.model.CreateSecurityGroupResponse;
import software.amazon.awssdk.services.ec2.model.IpRange;
```
**Code**
```
CreateSecurityGroupRequest createRequest = CreateSecurityGroupRequest.builder()
.groupName(groupName)
.description(groupDesc)
.vpcId(vpcId)
.build();
CreateSecurityGroupResponse resp= ec2.createSecurityGroup(createRequest);
```
See the [complete example](https://github.com/awsdocs/aws-doc-sdk-examples/blob/0b1785e42949ebf959eaa0f0da4dc2a48f92ea25/javav2/example_code/ec2/src/main/java/com/example/ec2/CreateSecurityGroup.java) on GitHub.
## Configure a security group
A security group can control both inbound (ingress) and outbound (egress) traffic to your Amazon EC2 instances.
To add ingress rules to your security group, use the Ec2Client’s `authorizeSecurityGroupIngress` method, providing the name of the security group and the access rules ([IpPermission](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/ec2/model/IpPermission.html)) you want to assign to it within an [AuthorizeSecurityGroupIngressRequest](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/ec2/model/AuthorizeSecurityGroupIngressRequest.html) object. The following example shows how to add IP permissions to a security group.
**Imports**
```
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.ec2.Ec2Client;
import software.amazon.awssdk.services.ec2.model.CreateSecurityGroupRequest;
import software.amazon.awssdk.services.ec2.model.AuthorizeSecurityGroupIngressRequest;
import software.amazon.awssdk.services.ec2.model.AuthorizeSecurityGroupIngressResponse;
import software.amazon.awssdk.services.ec2.model.Ec2Exception;
import software.amazon.awssdk.services.ec2.model.IpPermission;
import software.amazon.awssdk.services.ec2.model.CreateSecurityGroupResponse;
import software.amazon.awssdk.services.ec2.model.IpRange;
```
**Code**
First, create an Ec2Client
```
Region region = Region.US_WEST_2;
Ec2Client ec2 = Ec2Client.builder()
.region(region)
.build();
```
Then use the Ec2Client’s `authorizeSecurityGroupIngress` method,
```
IpRange ipRange = IpRange.builder()
.cidrIp("0.0.0.0/0").build();
IpPermission ipPerm = IpPermission.builder()
.ipProtocol("tcp")
.toPort(80)
.fromPort(80)
.ipRanges(ipRange)
.build();
IpPermission ipPerm2 = IpPermission.builder()
.ipProtocol("tcp")
.toPort(22)
.fromPort(22)
.ipRanges(ipRange)
.build();
AuthorizeSecurityGroupIngressRequest authRequest =
AuthorizeSecurityGroupIngressRequest.builder()
.groupName(groupName)
.ipPermissions(ipPerm, ipPerm2)
.build();
AuthorizeSecurityGroupIngressResponse authResponse =
ec2.authorizeSecurityGroupIngress(authRequest);
System.out.printf(
"Successfully added ingress policy to Security Group %s",
groupName);
return resp.groupId();
} catch (Ec2Exception e) {
System.err.println(e.awsErrorDetails().errorMessage());
System.exit(1);
}
return "";
}
```
To add an egress rule to the security group, provide similar data in an [AuthorizeSecurityGroupEgressRequest](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/ec2/model/AuthorizeSecurityGroupEgressRequest.html) to the Ec2Client’s `authorizeSecurityGroupEgress` method.
See the [complete example](https://github.com/awsdocs/aws-doc-sdk-examples/blob/0b1785e42949ebf959eaa0f0da4dc2a48f92ea25/javav2/example_code/ec2/src/main/java/com/example/ec2/CreateSecurityGroup.java) on GitHub.
## Describe security groups
To describe your security groups or get information about them, call the Ec2Client’s `describeSecurityGroups` method. It returns a [DescribeSecurityGroupsResponse](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/ec2/model/DescribeSecurityGroupsResponse.html) that you can use to access the list of security groups by calling its `securityGroups` method, which returns a list of [SecurityGroup](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/ec2/model/SecurityGroup.html) objects.
**Imports**
```
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.ec2.Ec2Client;
import software.amazon.awssdk.services.ec2.model.DescribeSecurityGroupsRequest;
import software.amazon.awssdk.services.ec2.model.DescribeSecurityGroupsResponse;
import software.amazon.awssdk.services.ec2.model.SecurityGroup;
import software.amazon.awssdk.services.ec2.model.Ec2Exception;
```
**Code**
```
public static void describeEC2SecurityGroups(Ec2Client ec2, String groupId) {
try {
DescribeSecurityGroupsRequest request =
DescribeSecurityGroupsRequest.builder()
.groupIds(groupId).build();
DescribeSecurityGroupsResponse response =
ec2.describeSecurityGroups(request);
for(SecurityGroup group : response.securityGroups()) {
System.out.printf(
"Found Security Group with id %s, " +
"vpc id %s " +
"and description %s",
group.groupId(),
group.vpcId(),
group.description());
}
} catch (Ec2Exception e) {
System.err.println(e.awsErrorDetails().errorMessage());
System.exit(1);
}
}
```
See the [complete example](https://github.com/awsdocs/aws-doc-sdk-examples/blob/0b1785e42949ebf959eaa0f0da4dc2a48f92ea25/javav2/example_code/ec2/src/main/java/com/example/ec2/DescribeSecurityGroups.java) on GitHub.
## Delete a security group
To delete a security group, call the Ec2Client’s `deleteSecurityGroup` method, passing it a [DeleteSecurityGroupRequest](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/ec2/model/DeleteSecurityGroupRequest.html) that contains the ID of the security group to delete.
**Imports**
```
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.ec2.Ec2Client;
import software.amazon.awssdk.services.ec2.model.DeleteSecurityGroupRequest;
import software.amazon.awssdk.services.ec2.model.Ec2Exception;
```
**Code**
```
public static void deleteEC2SecGroup(Ec2Client ec2,String groupId) {
try {
DeleteSecurityGroupRequest request = DeleteSecurityGroupRequest.builder()
.groupId(groupId)
.build();
ec2.deleteSecurityGroup(request);
System.out.printf(
"Successfully deleted Security Group with id %s", groupId);
} catch (Ec2Exception e) {
System.err.println(e.awsErrorDetails().errorMessage());
System.exit(1);
}
}
```
See the [complete example](https://github.com/awsdocs/aws-doc-sdk-examples/blob/0b1785e42949ebf959eaa0f0da4dc2a48f92ea25/javav2/example_code/ec2/src/main/java/com/example/ec2/DeleteSecurityGroup.java) on GitHub.
## More information
+ [Amazon EC2 Security Groups](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-security-groups.html) in the Amazon EC2 User Guide for Linux Instances
+ [Authorize inbound traffic for Your Linux Instances](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/authorizing-access-to-an-instance.html) in the Amazon EC2 User Guide for Linux Instances
+ [CreateSecurityGroup](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_CreateSecurityGroup.html) in the Amazon EC2 API Reference
+ [DescribeSecurityGroups](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_DescribeSecurityGroups.html) in the Amazon EC2 API Reference
+ [DeleteSecurityGroup](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_DeleteSecurityGroup.html) in the Amazon EC2 API Reference
+ [AuthorizeSecurityGroupIngress](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_AuthorizeSecurityGroupIngress.html) in the Amazon EC2 API Reference
# Work with Amazon EC2 instance metadata
A Java SDK client for the Amazon EC2 Instance Metadata Service (metadata client) allows your applications to access metadata on their local EC2 instance. The metadata client works with the local instance of [IMDSv2](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/configuring-instance-metadata-service.html) (Instance Metadata Service v2) and uses session-oriented requests.
Two client classes are available in the SDK. The synchronous `[Ec2MetadataClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/imds/Ec2MetadataClient.html)` is for blocking operations, and the [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) is for asynchronous, non-blocking use cases.
## Get started
To use the metadata client, add the `imds` Maven artifact to your project. You also need classes for an `[SdkHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/SdkHttpClient.html)` (or an `[SdkAsyncHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/async/SdkAsyncHttpClient.html)` for the asynchronous variant) on the classpath.
The following Maven XML shows dependency snippets for using the synchronous [UrlConnectionHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/urlconnection/UrlConnectionHttpClient.html) along with the dependency for metadata clients.
```
software.amazon.awssdk
bom
VERSION
pom
import
software.amazon.awssdk
imds
software.amazon.awssdk
url-connection-client
```
Search the [Maven central repository](https://central.sonatype.com/artifact/software.amazon.awssdk/bom) for the latest version of the `bom` artifact.
To use an asynchronous HTTP client, replace the dependency snippet for the `url-connection-client` artifact. For example, the following snippet brings in the [NettyNioAsyncHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/nio/netty/NettyNioAsyncHttpClient.html) implementation.
```
software.amazon.awssdk
netty-nio-client
```
## Use the metadata client
### Instantiate a metadata client
You can instantiate an instance of a synchronous `Ec2MetadataClient` when only one implementation of the `SdkHttpClient` interface is present on the classpath. To do so, call the static `Ec2MetadataClient#create()` method as shown in the following snippet.
```
Ec2MetadataClient client = Ec2MetadataClient.create(); // 'Ec2MetadataAsyncClient#create' is the asynchronous version.
```
If your application has multiple implementations of the `SdkHttpClient` or `SdkHttpAsyncClient` interface, you must specify an implementation for the metadata client to use as shown in the [Configurable HTTP client](#examples-ec2-IMDS-features-http) section.
**Note**
For most service clients, such as Amazon S3, the SDK for Java automatically adds implementations of the `SdkHttpClient` or `SdkHttpAsyncClient` interface. If your metadata client uses the same implementation, then `Ec2MetadataClient#create()` will work. If you require a different implementation, you must specify it when you create the metadata client.
### Send requests
To retrieve instance metadata, instantiate the `EC2MetadataClient` class and call the `get` method with a path parameter that specifies the [instance metadata category](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/instancedata-data-categories.html).
The following example prints the value associated with the `ami-id` key to the console.
```
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.
```
If the path isn't valid, the `get` method throws an exception.
Reuse the same client instance for multiple requests, but call `close` on the client when it is no longer needed to release resources. After the close method is called, the client instance can't be used anymore.
### Parse responses
EC2 instance metadata can be output in different formats. Plain text and JSON are the most commonly used formats. The metadata clients offer ways to work with those formats.
As the following example shows, use the `asString` method to get the data as a Java string. You can also use the `asList` method to separate a plain text response that returns multiple lines.
```
Ec2MetadataClient client = Ec2MetadataClient.create();
Ec2MetadataResponse response = client.get("/latest/meta-data/");
String fullResponse = response.asString();
List splits = response.asList();
```
If the response is in JSON, use the `Ec2MetadataResponse#asDocument` method to parse the JSON response into a [Document](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/core/document/Document.html) instance as shown in the following code snippet.
```
Document fullResponse = response.asDocument();
```
An exception will be thrown if the format of the metadata is not in JSON. If the response is successfully parsed, you can use the [document API](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/core/document/package-summary.html) to inspect the response in more detail. Consult the instance [metadata category chart](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/instancedata-data-categories.html) to learn which metadata categories deliver JSON-formatted responses.
## Configure a metadata client
### Retries
You can configure a metadata client with a retry mechanism. If you do, then the client can automatically retry requests that fail for unexpected reasons. By default, the client retries three times on a failed request with an exponential backoff time between attempts.
If your use case requires a different retry mechanism, you can customize the client using the `retryPolicy` method on its builder. For example, the following example shows a synchronous client configured with a fixed delay of two seconds between attempts and five retry attempts.
```
BackoffStrategy fixedBackoffStrategy = FixedDelayBackoffStrategy.create(Duration.ofSeconds(2));
Ec2MetadataClient client =
Ec2MetadataClient.builder()
.retryPolicy(retryPolicyBuilder -> retryPolicyBuilder.numRetries(5)
.backoffStrategy(fixedBackoffStrategy))
.build();
```
There are several [BackoffStrategies](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/core/retry/backoff/package-summary.html) that you can use with a metadata client.
You can also disable the retry mechanism entirely, as the following snippet shows.
```
Ec2MetadataClient client =
Ec2MetadataClient.builder()
.retryPolicy(Ec2MetadataRetryPolicy.none())
.build();
```
Using `Ec2MetadataRetryPolicy#none()` disables the default retry policy so that the metadata client attempts no retries.
### IP version
By default, a metadata client uses the IPV4 endpoint at `http://169.254.169.254`. To change the client to use the IPV6 version, use either the `endpointMode` or the `endpoint` method of the builder. An exception results if both methods are called on the builder.
The following examples show both IPV6 options.
```
Ec2MetadataClient client =
Ec2MetadataClient.builder()
.endpointMode(EndpointMode.IPV6)
.build();
```
```
Ec2MetadataClient client =
Ec2MetadataClient.builder()
.endpoint(URI.create("http://[fd00:ec2::254]"))
.build();
```
## Key features
### Asynchronous client
To use the non-blocking version of the client, instantiate an instance of the `Ec2MetadataAsyncClient` class. The code in the following example creates an asynchronous client with default settings and uses the `get` method to retrieve the value for the `ami-id` key.
```
Ec2MetadataAsyncClient asyncClient = Ec2MetadataAsyncClient.create();
CompletableFuture response = asyncClient.get("/latest/meta-data/ami-id");
```
The `java.util.concurrent.CompletableFuture` returned by the `get` method completes when the response returns. The following example prints the `ami-id` metadata to the console.
```
response.thenAccept(metadata -> System.out.println(metadata.asString()));
```
### Configurable HTTP client
The builder for each metadata client has a `httpClient` method that you can use to supply a customized HTTP client.
The following example shows code for a custom `UrlConnectionHttpClient` instance.
```
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.
```
The following example shows code for a custom `NettyNioAsyncHttpClient` instance with an asynchronous metadata client.
```
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.
```
The [Configure HTTP clients in the AWS SDK for Java 2.x](http-configuration.md) topic in this guide provides details on how to configure the HTTP clients that are available in the SDK for Java.
### Token caching
Because the metadata clients use IMDSv2, all requests are associated with a session. A session is defined by a token that has an expiration, which the metadata client manages for you. Every metadata request automatically reuses the token until it expires.
By default, a token lasts for six hours (21,600 seconds). We recommend that you keep the default time-to-live value, unless your specific use case requires advanced configuration.
If needed, configure the duration by using the `tokenTtl` builder method. For example, the code in the following snippet creates a client with a session duration of five minutes.
```
Ec2MetadataClient client =
Ec2MetadataClient.builder()
.tokenTtl(Duration.ofMinutes(5))
.build();
```
If you omit calling the `tokenTtl` method on the builder, the default duration of 21,600 is used instead.