# Capacity Blocks for ML
Capacity Blocks for ML allow you to reserve GPU-based accelerated computing instances on a future date to support your short duration machine learning (ML) workloads. Instances that run inside a Capacity Block are automatically placed close together inside [ Amazon EC2 UltraClusters](https://aws.amazon.com/ec2/ultraclusters/), for low-latency, petabit-scale, non-blocking networking.
You can also use Capacity Blocks to reserve capacity for Amazon EC2 UltraServers. UltraServers connect multiple Amazon EC2 instances within a low-latency, high-bandwidth accelerator interconnect. You can use UltraServers to handle the most compute and memory intensive AI/ML workloads in training, fine-tuning, and inference. For more information, see [Amazon EC2 UltraServers](https://aws.amazon.com/ec2/ultraservers/).
With Capacity Blocks, you can see when GPU instance capacity is available on future dates, and you can schedule a Capacity Block to start at a time that works best for you. When you reserve a Capacity Block, you get predictable capacity assurance for GPU instances while paying only for the amount of time that you need. We recommend Capacity Blocks when you need GPUs to support your ML workloads for days or weeks at a time and don't want to pay for a reservation while your GPU instances aren't in use.
The following are some common use cases for Capacity Blocks.
+ **ML model training and fine-tuning** – Get uninterrupted access to the GPU instances that you reserved to complete ML model training and fine-tuning.
+ **ML experiments and prototypes** – Run experiments and build prototypes that require GPU instances for short durations.
Capacity Blocks are available for select instance types in some AWS Regions. For more information, see [Supported instance types and Regions](#capacity-blocks-prerequisites).
You can reserve a Capacity Block with a reservation start time up to eight weeks in the future. Each Capacity Block can have up to 64 instances, and you can have up to 256 instances across Capacity Blocks.
**Topics**
+ [
## Supported instance types and Regions
](#capacity-blocks-prerequisites)
+ [
## Supported platforms
](#capacity-blocks-platforms)
+ [
## Considerations
](#capacity-blocks-considerations)
+ [
## Related resources
](#capacity-blocks-related-resources)
+ [
# How Amazon EC2 Capacity Blocks work
](capacity-blocks-how.md)
+ [
# Capacity Blocks pricing and billing
](capacity-blocks-pricing-billing.md)
+ [
# Find and purchase Capacity Blocks
](capacity-blocks-purchase.md)
+ [
# Launch instances using Capacity Blocks
](capacity-blocks-launch.md)
+ [
# View Capacity Blocks
](capacity-blocks-view.md)
+ [
# Extend Capacity Blocks
](capacity-blocks-extend.md)
+ [
# Share Capacity Blocks
](capacity-blocks-share.md)
+ [
# Create a resource group for UltraServer Capacity Blocks
](cb-group.md)
+ [
# Monitor Capacity Blocks using EventBridge
](capacity-blocks-monitor.md)
+ [
# Logging Capacity Blocks API calls with AWS CloudTrail
](capacity-blocks-logging-using-cloudtrail.md)
## Supported instance types and Regions
Instance and UltraServer Capacity Blocks can use be used with the following instance types and AWS regions.
**Note**
Capacity Block sizes of 64 instances are not supported for all instance types in all AWS Regions.
### Instance Capacity Blocks
+ **`p6-b300.48xlarge`**
+ US West (Oregon) — `us-west-2`
+ **`p6-b200.48xlarge`**
+ US East (N. Virginia) — `us-east-1`
+ US East (Ohio) — `us-east-2`
+ US West (Oregon) — `us-west-2`
+ **`p5.4xlarge`**
+ US East (N. Virginia) — `us-east-1`
+ US East (Ohio) — `us-east-2`
+ US West (Oregon) — `us-west-2`
+ Europe (London) — `eu-west-2`
+ Asia Pacific (Mumbai) — `ap-south-1`
+ Asia Pacific (Tokyo) — `ap-northeast-1`
+ Asia Pacific (Sydney) — `ap-southeast-2`
+ South America (São Paulo) — `sa-east-1`
+ **`p5.48xlarge`**
+ US East (N. Virginia) — `us-east-1`
+ US East (Ohio) — `us-east-2`
+ US West (N. California) — `us-west-1`
+ US West (Oregon) — `us-west-2`
+ Europe (Stockholm) — `eu-north-1`
+ Europe (London) — `eu-west-2`
+ South America (São Paulo) — `sa-east-1`
+ Asia Pacific (Tokyo) — `ap-northeast-1`
+ Asia Pacific (Mumbai) — `ap-south-1`
+ Asia Pacific (Sydney) — `ap-southeast-2`
+ Asia Pacific (Jakarta) — `ap-southeast-3`
+ US East (Atlanta) Local Zone — `us-east-1-atl-2a`
+ **`p5e.48xlarge`**
+ US East (N. Virginia) — `us-east-1`
+ US East (Ohio) — `us-east-2`
+ US West (N. California) — `us-west-1`
+ US West (Oregon) — `us-west-2`
+ Europe (Stockholm) — `eu-north-1`
+ Europe (London) — `eu-west-2`
+ Europe (Spain) — `eu-south-2`
+ South America (São Paulo) — `sa-east-1`
+ Asia Pacific (Tokyo) — `ap-northeast-1`
+ Asia Pacific (Seoul) — `ap-northeast-2`
+ Asia Pacific (Mumbai) — `ap-south-1`
+ Asia Pacific (Jakarta) — `ap-southeast-3`
+ US West (Phoenix) Local Zone — `us-west-2-phx-2a`
+ **`p4d.24xlarge`**
+ US East (N. Virginia) — `us-east-1`
+ US East (Ohio) — `us-east-2`
+ US West (Oregon) — `us-west-2`
+ **`p4de.24xlarge`**
+ US East (N. Virginia) — `us-east-1`
+ US West (Oregon) — `us-west-2`
+ **`trn1.32xlarge`**
+ US East (N. Virginia) — `us-east-1`
+ US East (Ohio) — `us-east-2`
+ US West (N. California) — `us-west-1`
+ US West (Oregon) — `us-west-2`
+ Europe (Stockholm) — `eu-north-1`
+ Asia Pacific (Mumbai) — `ap-south-1`
+ Asia Pacific (Sydney) — `ap-southeast-2`
+ Asia Pacific (Melbourne) — `ap-southeast-4`
+ **`trn2.3xlarge `**
+ Asia Pacific (Melbourne) — `ap-southeast-4`
+ South America (São Paulo) — `sa-east-1`
+ **`trn2.48xlarge`**
+ US East (Ohio) — `us-east-2`
### UltraServer Capacity Blocks
+ **`Trn2`**
+ US East (Ohio) — `us-east-2`
+ **`P6e-GB200`**
+ US East (Dallas) Local Zone — `us-east-1-dfw-2a`
## Supported platforms
Capacity Blocks for ML currently support instances and UltraServers with default tenancy only. When you use the AWS Management Console to purchase a Capacity Block, the default platform option is Linux/UNIX. When you use the AWS Command Line Interface (AWS CLI) or AWS SDK to purchase a Capacity Block, the following platform options are available:
+ Linux/Unix
+ Red Hat Enterprise Linux
+ RHEL with HA
+ SUSE Linux
+ Ubuntu Pro
## Considerations
Before you use Capacity Blocks, consider the following details and limitations.
+ If we detect impairment impacting an UltraServer Capacity Block, we will notify you but generally will not take action to terminate your instances on the Capacity Block. This is to minimize unintended disruption to your workloads. You can continue using the UltraServer Capacity Block as is after receiving this notification or request remediation by terminating all instances on the capacity block and submitting an AWS support case. After we receive your support case, we will notify you when we have completed remediation and you can relaunch instances onto your UltraServer Capacity Block.
+ For `P6e-GB200` UltraServer Capacity Blocks, you must terminate your instances at least 60 minutes before the Capacity Block end time.
+ To purchase and use Capacity Blocks in Local Zones, you must be opted in to the Local Zone.
+ Each Capacity Block can have up to 64 instances, and you can have up to 256 instances across Capacity Blocks.
+ You can describe Capacity Block offerings that can start in as soon as 30 minutes.
+ Capacity Blocks end at 11:30AM Coordinated Universal Time (UTC).
+ The termination process for instances running in a Capacity Block begins at 11:00AM Coordinated Universal Time (UTC) on the final day of the reservation.
+ Capacity Blocks can be reserved with a start time up to 8 weeks in the future.
+ Capacity Block cancellations aren't allowed.
+ UltraServer Capacity Blocks can't be shared across AWS accounts or within your AWS Organization.
+ Capacity Block can't be [moved](capacity-reservations-move.md) or [split](capacity-reservations-split.md).
+ Only UltraServer Capacity Blocks can be used with resource groups. Instance Capacity Blocks can't be used with resource groups. For more information, see [Create a resource group for UltraServer Capacity Blocks](cb-group.md).
+ The total number of instances that can be reserved in Capacity Blocks across all accounts in your AWS Organization can't exceed 256 instances on a particular date.
+ To use a Capacity Block, instances must specifically target the reservation ID.
+ Instances in a Capacity Block don't count against your On-Demand Instances limits.
+ For P5 instances using a custom AMI, ensure that you have the [required software and configuration for EFA](gpu-instances-started.md).
+ For Amazon EKS managed node groups, see [Create a managed node group with Amazon EC2 Capacity Blocks for ML](https://docs.aws.amazon.com/eks/latest/userguide/capacity-blocks-mng.html). For Amazon EKS self-managed node groups, see [Use Capacity Blocks for ML with self-managed nodes](https://docs.aws.amazon.com/eks/latest/userguide/capacity-blocks.html).
## Related resources
After you create a Capacity Block, you can do the following with the Capacity Block:
+ Launch instances into the Capacity Block. For more information, see [Launch instances using Capacity Blocks](capacity-blocks-launch.md).
+ Create an Amazon EC2 Auto Scaling group. For more information, see [Use Capacity Blocks for machine learning workloads](https://docs.aws.amazon.com/autoscaling/ec2/userguide/launch-template-capacity-blocks.html) in the *Amazon EC2 Auto Scaling User Guide*.
**Note**
If you use Amazon EC2 Auto Scaling or Amazon EKS, you can schedule scaling to run at the start of the Capacity Block reservation. With scheduled scaling, AWS automatically handles retries for you, so you don't need to worry about implementing retry logic to handle transient failures.
+ Enhance ML workflows with AWS Parallel Computing Service. For more information, see [ Capacity Blocks support for AWS Parallel Computing Service](https://aws.amazon.com/blogs/hpc/announcing-capacity-blocks-support-for-aws-parallel-computing-service/).
+ Enhance ML workflows with AWS ParallelCluster. For more information, see [ Enhancing ML workflows with AWS ParallelCluster and Amazon EC2 Capacity Blocks for ML](https://aws.amazon.com/blogs/hpc/enhancing-ml-workflows-with-aws-parallelcluster-and-amazon-ec2-capacity-blocks-for-ml/).
For more information about AWS Parallel Computing Service, see [What is AWS Parallel Computing Service](https://docs.aws.amazon.com/pcs/latest/userguide/what-is-service.html).
For more information about AWS ParallelCluster, see [What is AWS ParallelCluster](https://docs.aws.amazon.com/parallelcluster/latest/ug/what-is-aws-parallelcluster.html).
# How Amazon EC2 Capacity Blocks work
You can reserve a Capacity Block with the following specifications:
+ Reserve a start time up to 8 weeks in advance
+ Set a reservation duration of one to 14 days or a multiple of 7 days, up to 182 days (Examples: 21 days, 28 days)
+ Configure up to 64 instances per Capacity Block
+ Configure up to 256 instances across multiple Capacity Blocks
For Amazon EC2 UltraServers, each UltraServer corresponds to one Capacity Block. You can request multiple UltraServers through a single request.
You can use Capacity Blocks to reserve `p6-b200`, `p5`, `p5e`, `p5en`, `p4d`, `p4de`, `trn1`, and `trn2` instances. You can purchase the following UltraServer types through Capacity Blocks: `P6e-GB200` and `Trn2` (in preview).
To reserve a Capacity Block, you start by specifying your capacity needs, including the instance type or UltraServer type, the number of instances or UltraServers, amount of time, earliest start date, and latest end date that you need. Then, you can see an available Capacity Block offering that meets your specifications. The Capacity Block offering includes details such as start time, Availability Zone, and reservation price. The price of a Capacity Block offering depends on available supply and demand at the time the offering was delivered. After you reserve a Capacity Block, the price doesn't change. For more information, see [Capacity Blocks pricing and billing](capacity-blocks-pricing-billing.md).
When you purchase a Capacity Block offering, your reservation is created for the date and number of instances that you selected. When your Capacity Block reservation begins, you can target instance launches by specifying the reservation ID in your launch requests.
You can use all the instances you reserved until 30 minutes (for instance types) or 60 minutes (for UltraServer type) before the end time of the Capacity Block. With 30 minutes (for instance types) or 60 minutes (for UltraServer types) left in your Capacity Block reservation, we begin terminating any instances that are running in the Capacity Block. We use this time to clean up your instances before delivering the Capacity Block to the next customer. We emit an event through EventBridge 10 minutes before the termination process begins. For more information, see [Monitor Capacity Blocks using EventBridge](capacity-blocks-monitor.md).
# Capacity Blocks pricing and billing
With Amazon EC2 Capacity Blocks for ML, you pay only for what you reserve. The price of a Capacity Block depends on available supply and demand for Capacity Blocks at the time of purchase. You can view the price of a Capacity Block offering before you reserve it. The price of the Capacity Block is charged up front at the time the reservation is made. When you search for a Capacity Block across a range of dates, we return the lowest-priced Capacity Block offering available. After you've reserved a Capacity Block, the price doesn't change.
When you use a Capacity Block, you pay for the operating system you use when your instances are running. For more information about operating system prices, see [Amazon EC2 Capacity Blocks for ML Pricing](https://aws.amazon.com/ec2/capacityblocks/pricing/).
## Billing
The price of a Capacity Block offering is charged up front. Payment is billed to your AWS account within 5 minutes to 12 hours after you purchase a Capacity Block. While your payment is processing, your Capacity Block reservation resource remains in a state of `payment-pending`. If your payment can't be processed at least 5 minutes before your block start time, or within 12 hours (whichever comes first), your Capacity Block is released and the reservation state changes to `payment-failed`.
After your payment is processed successfully, the Capacity Block resource state changes from `payment-pending` to `scheduled`. You receive an invoice that reflects the one-time upfront payment. In the invoice, you can associate the paid amount with the Capacity Block reservation ID.
When your Capacity Block reservation begins, you are billed based only on the operating system you use while your instances are running in the reservation. You can view your usage and associated charges in your anniversary bill for the month of usage in your AWS Cost and Usage Report.
**Note**
Savings Plans and Reserved Instance discounts don't apply to Capacity Blocks.
**Viewing your bill**
You can view your bill in the AWS Billing and Cost Management console. The upfront payment for your Capacity Block appears in the month that you purchased the reservation.
After your reservation begins, your bill shows separate lines for the block reservation used and unused time. You can use these line items to see how much time was used in your reservation. You will see only a usage charge in the line for used time if you use a premium operating system. For more information, see [Capacity Blocks pricing and billing](#capacity-blocks-pricing-billing). There is no additional charge for unused time.
For more information, see [Viewing your bill](https://docs.aws.amazon.com/awsaccountbilling/latest/aboutv2/getting-viewing-bill.html) in the *AWS Billing and Cost Management User Guide*.
If your Capacity Block starts in a different month then the month you purchased your reservation, the upfront price and reservation usage show up under separate billing months. In your AWS Cost and Usage Report, the Capacity Block reservation ID is listed in the **reservation/ReservationARN** line item of your upfront fee and the **lineitem/ResourceID** in your anniversary bill so that you can associate the usage to the corresponding upfront price.
# Find and purchase Capacity Blocks
To reserve a Capacity Block, you first need to find a block of time when capacity is available that matches your needs. To find a Capacity Block that is available to reserve, you specify the following.
+ The number of instances that you need
+ The duration of time you that you need the instances
+ The date range that you need your reservation
To search for an available Capacity Block offering, you specify a reservation duration and instance count. You must specify reservation durations in ** 1-day increments up to 14 days, and in 7-day increments up to 182 days**. Each Capacity Block can have up to 64 instances, and you can have up to 256 instances across Capacity Blocks.
When you request a Capacity Block that matches your specifications, we provide the details of up to 6 available blocks. All Capacity Blocks end at 11:30AM UTC, so the blocks starting on the same day will have durations that are the closest match to your desired duration. One block will have a duration that is slightly less than your desired duration, while the other will have a duration slightly greater than your desired duration.
The offering details include the start time of the reservation, the Availability Zone for the reservation, and the price of the reservation. For more information, see [Capacity Blocks pricing and billing](capacity-blocks-pricing-billing.md).
You can purchase the Capacity Block offering you are shown, or you can modify your search criteria to see the other options that are available. There is no predefined expiration time for the offering, but offerings are only available on a first-come, first-served basis.
When you purchase a Capacity Block offering, you get an immediate response confirming that your Capacity Block was reserved. After confirmation, you will see a new Capacity Reservation in your account with a reservation type of `capacity-block` and a `start-date` set to the start time of the offering that you purchased. Your Capacity Block reservation is created with a state of `payment-pending`. After the upfront payment is successfully processed, the reservation state changes to `scheduled`. For more information, see [Billing](capacity-blocks-pricing-billing.md#capacity-blocks-billing).
**Note**
To purchase and use Capacity Blocks in Local Zones, you must be opted in to the Local Zone.
------
#### [ Console ]
**To find and purchase a Capacity Block**
1. Open the Amazon EC2 console at [https://console.aws.amazon.com/ec2/](https://console.aws.amazon.com/ec2/).
1. In the navigation bar at the top of the screen, select an AWS Region. This choice is important because Capacity Block sizes of 64 instances are not supported for all instance types in all Regions.
1. In the navigation pane, choose **Capacity Reservations**, **Create Capacity Block**.
1. Under **Capacity Block types**, choose either **Instances** or ** UltraServers**.
1. Under **Capacity attributes**, you can define your Capacity Block search parameters. By default, the platform is Linux. If you want to select a different operating system, use the AWS CLI. For more information, see [Supported platforms](ec2-capacity-blocks.md#capacity-blocks-platforms).
1. Under **Total capacity** (for Instances) or **UltraServer count** (for UltraServers), specify the number of instances or UltraServers you want to reserve.
1. Under **Duration**, enter the number of days or weeks you need the reservation for.
1. Under **Date range to search for Capacity Blocks**, enter the earliest date that you want your reservation to start.
1. Choose **Find Capacity Blocks**.
1. If a Capacity Block is available that meets your specifications, you see an offering under **Recommended Capacity Blocks**. If there are multiple offerings that meet your specifications, the earliest available Capacity Block offering is shown. To view other Capacity Block offerings, adjust your search inputs and choose **Find Capacity Blocks** again.
1. When you find a Capacity Block offering that you want to purchase, choose **Next**.
1. (Optional) On the **Add tags** page, choose **Add new tag**.
1. The **Review and purchase** page lists the start and end date, duration, total number of instances, and price.
**Note**
Capacity Blocks can't be canceled after you reserve them.
1. In the popup window **Purchase a Capacity Block**, type confirm, then choose **Purchase**.
------
#### [ AWS CLI ]
**To find an instance Capacity Block**
Use the [ describe-capacity-block-offerings](https://docs.aws.amazon.com/cli/latest/reference/ec2/describe-capacity-block-offerings.html) command.
The following example finds instance Capacity Blocks.
```
aws ec2 describe-capacity-block-offerings \
--instance-type p5.48xlarge \
--instance-count 16 \
--start-date-range 2023-08-14T00:00:00Z \
--end-date-range 2023-10-22-T00:00:00Z \
--capacity-duration-hours 48 \
--all-availability-zones
```
The following example finds UltraServer Capacity Blocks.
```
aws ec2 describe-capacity-block-offerings \
--ultraserver-type u-p6e-gb200x72 \
--ultraserver-count 1 \
--start-date-range 2023-08-14T00:00:00Z \
--end-date-range 2023-10-22-T00:00:00Z \
--capacity-duration-hours 48
```
**To purchase a Capacity Block**
Use the [ purchase-capacity-block](https://docs.aws.amazon.com/cli/latest/reference/ec2/purchase-capacity-block.html) command with the offering ID of the Capacity Block from the output of the previous example.
```
aws ec2 purchase-capacity-block \
--capacity-block-offering-id cb-0123456789abcdefg \
--instance-platform Linux/UNIX
```
------
#### [ PowerShell ]
**To find Capacity Blocks**
Use the [Get-EC2CapacityBlockOffering](https://docs.aws.amazon.com/powershell/latest/reference/items/Get-EC2CapacityBlockOffering.html) cmdlet.
The following example finds instance Capacity Blocks.
```
Get-EC2CapacityBlockOffering `
-InstanceType p5.48xlarge `
-InstanceCount 16 `
-CapacityDurationHour 48 `
-StartDateRange 2023-08-14T00:00:00Z `
-EndDateRange 2023-10-22-T00:00:00Z `
-AllAvailabilityZones $true
```
The following example finds UltraServer Capacity Blocks.
```
Get-EC2CapacityBlockOffering `
-UltraserverType u-p6e-gb200x72 `
-UltraserverCount 1 `
-CapacityDurationHour 48 `
-StartDateRange 2023-08-14T00:00:00Z `
-EndDateRange 2023-10-22-T00:00:00Z
```
**To purchase a Capacity Block**
Use the [New-EC2EC2CapacityBlock](https://docs.aws.amazon.com/powershell/latest/reference/items/New-EC2EC2CapacityBlock.html) cmdlet with the offering ID of the Capacity Block from the output of the previous example.
```
New-EC2EC2CapacityBlock `
-CapacityBlockOfferingId cb-0123456789abcdefg `
-InstancePlatform Linux/UNIX
```
------
# Launch instances using Capacity Blocks
To use your Capacity Block, you must specify the Capacity Block reservation ID when launching instances. Launching an instance into a Capacity Block reduces the available capacity by the number of instances launched. For example, if your purchased instance capacity is eight instances and you launch four instances, the available capacity is reduced by four.
If you terminate an instance running in the Capacity Block before the reservation ends, you can launch a new instance in its place. When you stop or terminate an instance in a Capacity Block, it takes several minutes to clean up your instance before you can launch another instance to replace it. During this time, your instance will be in a stopping or `shutting-down` state. After this process is complete, your instance state will change to `stopped` or `terminated`. Then, the available capacity in your Capacity Block will update to show another instance available to use.
**Requirements**
+ Your instance can't launch in a subnet in a different Availability Zone from the Availability Zone where your Capacity Block is located.
+ Your instance can't launch using an AMI with a different platform than the platform for your Capacity Block.
+ To use Capacity Blocks in Local Zones, you must be opted in to the Local Zone.
------
#### [ Console ]
**To launch instances into a Capacity Block**
1. Open the Amazon EC2 console at [https://console.aws.amazon.com/ec2/](https://console.aws.amazon.com/ec2/).
1. In the navigation bar at the top of the screen, select the Region for your Capacity Block reservation.
1. From the Amazon EC2 console dashboard, choose **Launch instance**.
1. Follow the procedure to [launch an instance](ec2-launch-instance-wizard.md).
1. Expand **Advanced details**, and for **Purchasing option**, choose **Capacity Blocks**. Then do one of the following:
+ To launch the instances into a specific Capacity Block, for **Capacity Reservation** choose **Specify Capacity Reservation**, and then select the Capacity Block.
+ (*UltraServers only*) To launch the instances into an UltraServer Capacity Block resource group, for **Capacity Reservation** choose **Specify Capacity Reservation resource group**, and then select the resource group.
1. Choose **Launch instance**.
------
#### [ AWS CLI ]
**To launch instances using into a Capacity Block**
Use the [run-instances](https://docs.aws.amazon.com/cli/latest/reference/ec2/run-instances.html) command with the `instance-market-options MarketType` option.
The following example launches an instance into a specific Capacity Block.
```
aws ec2 run-instances \
--image-id ami-0abcdef1234567890 \
--count 1 \
--instance-type p5.48xlarge \
--key-name my-key-pair \
--subnet-id subnet-0abcdef1234567890 \
--instance-market-options MarketType='capacity-block' \
--capacity-reservation-specification CapacityReservationTarget={CapacityReservationId=capacity_block_id}
```
The following example launches an instance into an UltraServer Capacity Block resource group.
```
aws ec2 run-instances \
--image-id ami-0abcdef1234567890 \
--count 1 \
--instance-type p6e-gb200.36xlarge \
--key-name my-key-pair \
--subnet-id subnet-0abcdef1234567890 \
--instance-market-options MarketType='capacity-block' \
--capacity-reservation-specification CapacityReservationTarget={CapacityReservationResourceGroupArn=resource_group_arn}
```
------
#### [ PowerShell ]
**To launch instances into a Capacity Block**
Use the [New-EC2Instance](https://docs.aws.amazon.com/powershell/latest/reference/items/New-EC2Instance.html) cmdlet with the `-InstanceMarketOption` option defined as follows.
```
$marketoption = New-Object Amazon.EC2.Model.InstanceMarketOptionsRequest
$marketoption.MarketType = "capacity-block"
```
The following example launches an instance into a specific Capacity Block.
```
New-EC2Instance `
-ImageId ami-0abcdef1234567890 `
-InstanceType p5.48xlarge `
-KeyName "my-key-pair" `
-SubnetId subnet-0abcdef1234567890 `
-InstanceMarketOptions $marketoption `
-CapacityReservationTarget_CapacityReservationId capacity_block_id
```
The following example launches an instance into an UltraServer Capacity Block resource group.
```
New-EC2Instance `
-ImageId ami-0abcdef1234567890 `
-InstanceType p6e-gb200.36xlarge `
-KeyName "my-key-pair" `
-SubnetId subnet-0abcdef1234567890 `
-InstanceMarketOptions $marketoption `
-CapacityReservationTarget_CapacityReservationResourceGroupArn "resource_group_arn"
```
------
**Related resources**
+ To create a launch template targeting a Capacity Block, see [Store instance launch parameters in Amazon EC2 launch templates](ec2-launch-templates.md).
+ To launch instances into a Capacity Block using EC2 Fleet, see [Tutorial: Configure your EC2 Fleet to launch instances into Capacity Blocks](ec2-fleet-launch-instances-capacity-blocks-walkthrough.md).
+ To set up an EKS managed node group with a Capacity Block, see [Create a managed node group with Capacity Blocks for ML](https://docs.aws.amazon.com/eks/latest/userguide/capacity-blocks-mng.html) in the **Amazon EKS User Guide**.
+ To set up AWS ParallelCluster using a Capacity Block, see [ML on AWS ParallelCluster](https://catalog.workshops.aws/ml-on-aws-parallelcluster/en-US).
# View Capacity Blocks
After you reserve a Capacity Block, you can view the Capacity Block reservation in your AWS account. You can view the `start-date` and `end-date` to see when your reservation will begin and end. Before a Capacity Block reservation begins, the available capacity appears as zero. You can see how many instances will be available in your Capacity Block by the tag value for the tag key `aws:ec2capacityreservation:incrementalRequestedQuantity`.
When a Capacity Block reservation begins, the reservation state changes from `scheduled` to `active`. We emit an event through Amazon EventBridge to notify you that the Capacity Block is available to use. For more information, see [Monitor Capacity Blocks using EventBridge](capacity-blocks-monitor.md).
Capacity Blocks have the following states:
+ `payment-pending` – The upfront payment hasn't been processed yet.
+ `payment-failed`—The payment couldn't be processed in the 12 hour time frame. Your Capacity Block was released.
+ `scheduled` – The payment was processed and the Capacity Block reservation hasn't started yet.
+ `active` – The reserved capacity is available for your use.
+ `expired` – The Capacity Block reservation expired automatically at the date and time specified in your reservation request. The reserved capacity is no longer available for your use.
------
#### [ Console ]
**To view Capacity Blocks**
1. Open the Amazon EC2 console at [https://console.aws.amazon.com/ec2/](https://console.aws.amazon.com/ec2/).
1. In the navigation pane, choose **Capacity Reservations**.
1. On the **Capacity Reservations overview** page, you see a resource table with details about all of your Capacity Reservation resources. To find your Capacity Blocks reservations, select **Capacity Blocks** from the dropdown list above **Capacity Reservation ID**. In the table, you can see information about your Capacity Blocks such as start and end dates, duration, and status.
1. For more details about a Capacity Block, select the reservation ID for the Capacity Block that you want to view. The **Capacity Reservation details** page displays all the properties of the reservation and the number of instances in use and available in the Capacity Block.
**Note**
Before a Capacity Block reservation begins, the available capacity appears as zero. You can see how many instances will be available when the Capacity Block reservation starts by using the following tag value for the tag key: `aws:ec2capacityreservation:incrementalRequestedQuantity`.
------
#### [ AWS CLI ]
**To view Capacity Blocks**
By default, when you use the [describe-capacity-reservations](https://docs.aws.amazon.com/cli/latest/reference/ec2/describe-capacity-reservations.html) command both On-Demand Capacity Reservations and Capacity Block reservations are listed. To view only your Capacity Block reservations, filter for reservations of type `capacity-block`.
```
aws ec2 describe-capacity-reservations \
--filters Name=reservation-type,Values=capacity-block
```
------
#### [ PowerShell ]
**To view Capacity Blocks**
Use the [Get-EC2CapacityReservation](https://docs.aws.amazon.com/powershell/latest/reference/items/Get-EC2CapacityReservation.html) cmdlet. By default, both On-Demand Capacity Reservations and Capacity Block reservations are listed. To view only your Capacity Block reservations, filter for reservations of type `capacity-block`.
```
Get-EC2CapacityReservation `
-Filter @{Name="reservation-type"; Values="capacity-block"}
```
------
# Extend Capacity Blocks
With Capacity Blocks, you reserve compute capacity for your workloads, ensuring availability and consistency. To accommodate your changing needs, you can extend the duration of your existing Capacity Blocks as required.
To extend a Capacity Block, it must have a status of `active` or `scheduled`, and have no extensions that are `payment-pending`. You can request to extend the duration of your Capacity Block up to a minimum of 1 hour or a maximum of 56 days before it expires. You can extend your Capacity Block by 1-day increments up to 14 days, and 7-day increments up to 182 days (26 weeks) total. When you extend your Capacity Block, its end date will be updated so that your instances can continue to run without disruption.
+ There is no limit to the number of extensions you can apply to a Capacity Block
+ Your Capacity Reservation ID will remain the same after extending the block
+ Capacity Blocks can only be extended if there is sufficient capacity available to support them, which is not guaranteed.
## Billing
The price of a Capacity Block offering is charged up front. The extension will remain in `payment-pending` until the bill is paid. If your payment can't be processed within 12 hours, or up to 35 minutes before the Capacity Block is scheduled to end (whichever comes first), your extension is not successful and the status changes to `payment-failed`. Your Capacity Block reservation will remain `active` and will be terminated on the original end date.
After your payment is processed successfully, the Capacity Block extension status changes to `payment-succeeded` and the end date of the Capacity Block reservation will be updated to the new end date. The details of your extension can be viewed in the **Capacity Block Extension details** section of the console, or by using the [describe-capacity-block-extension-history](https://docs.aws.amazon.com/cli/latest/reference/ec2/describe-capacity-block-extension-history.html) command.
## Extend your Capacity Block
------
#### [ Console ]
**To extend a Capacity Block**
1. Open the Amazon EC2 console at [https://console.aws.amazon.com/ec2/](https://console.aws.amazon.com/ec2/).
1. In the navigation pane, choose **Capacity Reservations**.
1. On the **Capacity Reservations overview** page, you see a resource table with details about all of your Capacity Reservations resources. Select the reservation ID for the Capacity Block that you want to extend.
1. From the **Actions** drop down menu, choose **Extend Capacity Block**.
1. Under **Duration**, enter the number of days or weeks you need to extend the reservation for.
1. Choose **Find Capacity Block**.
1. If a Capacity Block is available that meets your specifications, an offering appears under **Recommended Capacity Blocks**. To view other Capacity Block offerings, adjust your search inputs and choose **Find Capacity Blocks** again.
1. When you find a Capacity Block offering that you want to purchase, choose **Extend**.
1. In the pop-up window **Extend Capacity Block**, enter *confirm*, then choose **Extend**.
------
#### [ AWS CLI ]
**To find a Capacity Block extension**
Use the [describe-capacity-block-extension-offerings](https://docs.aws.amazon.com/cli/latest/reference/ec2/describe-capacity-block-extension-offerings.html) command. The following example searches for a 48 hour Capacity Block extension for the specified Reservation.
```
aws ec2 describe-capacity-block-extension-offerings \
--capacity-reservation-id cr-1234567890abcdefg \
--capacity-block-extension-duration-hours 48
```
**To extend a Capacity Block**
Use the [purchase-capacity-block-extension](https://docs.aws.amazon.com/cli/latest/reference/ec2/purchase-capacity-block-extension.html) command. Specify the extension offering ID from the output of the previous example.
```
aws ec2 purchase-capacity-block-extension \
--capacity-block-extension-offering-id cbe-0123456789abcdefg \
--capacity-reservation-id cr-1234567890abcdefg
```
------
#### [ PowerShell ]
**To find a Capacity Block extension**
Use the [Get-EC2CapacityBlockExtensionOffering](https://docs.aws.amazon.com/powershell/latest/reference/items/Get-EC2CapacityBlockExtensionOffering.html) cmdlet. The following example searches for a 48 hour Capacity Block extension for the specified Reservation.
```
Get-EC2CapacityBlockExtensionOffering `
-CapacityReservationId cr-1234567890abcdefg `
-CapacityBlockExtensionDurationHour 48
```
**To extend a Capacity Block**
Use the [Invoke-EC2CapacityBlockExtension](https://docs.aws.amazon.com/powershell/latest/reference/items/Invoke-EC2CapacityBlockExtension.html) cmdlet. Specify the extension offering ID from the output of the previous example.
```
Invoke-EC2CapacityBlockExtension `
-CapacityBlockExtensionOfferingId cbe-0123456789abcdefg `
-CapacityReservationId cr-1234567890abcdefg
```
------
# Share Capacity Blocks
Capacity Block sharing enables Capacity Block owners to share Amazon EC2 Capacity Blocks with other AWS accounts within an AWS Organization. This allows you to maximize utilization of reserved GPU capacity across different teams and projects to efficiently use the Capacity Blocks.
The AWS account that owns the Capacity Block (owner) can share it with other AWS accounts (consumers). An owner can share a Capacity Block with specific AWS accounts inside their AWS Organization, an organizational unit inside their AWS Organization, or the entire AWS Organization. Consumers can launch instances into Capacity Blocks that are shared with them in the same way that they launch instances into Capacity Blocks they own.
## Prerequisites for sharing Capacity Blocks
Before you can share a Capacity Block, the following conditions must be met:
+ **You must own the Capacity Block** - You cannot share a Capacity Block that has been shared with you.
+ **The Capacity Block state must be active or scheduled** - Capacity Blocks that are in other [states](https://docs.aws.amazon.com/cli/latest/reference/ec2/purchase-capacity-block.html), such as `expired` or `payment-pending` cannot be shared.
+ **Sharing within your AWS Organization only** - An owner can share a Capacity Block with specific AWS accounts inside their AWS Organization, an organizational unit inside their AWS Organization, or the entire AWS Organization.
+ **UltraServer Capacity Blocks not supported** - You cannot share Capacity Blocks for Amazon EC2 UltraServers.
+ **Account eligibility** - Capacity Block sharing is not available to new AWS accounts or AWS accounts that have a limited billing history.
## Related services
Capacity Block sharing integrates with AWS Resource Access Manager (AWS RAM). AWS RAM is a service that enables you to share your AWS resources with any AWS account or through AWS Organizations. With AWS RAM, you share resources that you own by creating a *resource share*. A resource share specifies the resources to share, and the consumers with whom to share them. Consumers can be individual AWS accounts, or organizational units or an entire organization from AWS Organizations.
For more information about AWS RAM, see the *[AWS RAM User Guide](https://docs.aws.amazon.com/ram/latest/userguide/)*.
## Shared Capacity Block permissions
### Permissions for owners
The Capacity Block owner remains responsible for managing the Capacity Block (e.g. extending, sharing), and the instances they launch into it. Owners cannot modify instances that consumers launch into Capacity Blocks they have shared.
### Permissions for consumers
Consumers can launch instances into the shared capacity and are responsible for managing those instances. Consumers cannot view or modify instances owned by other consumers or by the Capacity Block owner. Consumers can also only view the total capacity and available capacity in the shared Capacity Block.
## Share a Capacity Block
To share a Capacity Block, you must add it to a resource share. A resource share is an AWS RAM resource that lets you share your resources across AWS accounts.
If you added your Capacity Block to a resource share that is shared with the entire AWS Organization, consumers in your organization are granted access to the shared Capacity Block.
------
#### [ Console ]
**To share a Capacity Block that you own using the Amazon EC2 console**
1. Open the Amazon EC2 console at [https://console.aws.amazon.com/ec2/](https://console.aws.amazon.com/ec2/).
1. In the navigation pane, choose **Capacity Reservations**.
1. Select the Capacity Block to share and choose **Actions, Share reservation**.
1. Select the resource share to which to add the Capacity Block and choose **Share Capacity Reservation**.
It could take a few minutes for consumers to get access to the shared Capacity Block.
**To add a Capacity Block to a new resource share**
You must first create the resource share using the AWS RAM console. For more information, see [Creating a resource share](https://docs.aws.amazon.com/ram/latest/userguide/working-with-sharing.html#working-with-sharing-create) in the *AWS RAM User Guide*.
------
#### [ AWS CLI ]
**To share a Capacity Block that you own**
Use the [create-resource-share](https://docs.aws.amazon.com/cli/latest/reference/ram/create-resource-share.html) and [associate-resource-share](https://docs.aws.amazon.com/cli/latest/reference/ram/associate-resource-share.html) commands.
```
aws ram create-resource-share \
--name my-resource-share \
--resource-arns arn:aws:ec2:us-east-2:123456789012:capacity-reservation/cr-1234abcd56EXAMPLE
```
```
aws ram associate-resource-share \
--resource-share-arn arn:aws:ram:us-east-2:123456789012:resource-share/7ab63972-b505-7e2a-420d-6f5d3EXAMPLE \
--resource-arns arn:aws:ec2:us-east-2:123456789012:capacity-reservation/cr-1234abcd56EXAMPLE
```
------
#### [ PowerShell ]
**To share a Capacity Block that you own**
Use the [New-RAMResourceShare](https://docs.aws.amazon.com/powershell/latest/reference/items/New-RAMResourceShare.html) and [Connect-RAMResourceShare](https://docs.aws.amazon.com/powershell/latest/reference/items/Connect-RAMResourceShare.html) cmdlets.
```
New-RAMResourceShare `
-Name my-resource-share `
-ResourceArn "arn:aws:ec2:us-east-2:123456789012:capacity-reservation/cr-1234abcd56EXAMPLE"
```
```
Connect-RAMResourceShare `
-ResourceShareArn "arn:aws:ram:us-east-2:123456789012:resource-share/7ab63972-b505-7e2a-420d-6f5d3EXAMPLE" `
-ResourceArn "arn:aws:ec2:us-east-2:123456789012:capacity-reservation/cr-1234abcd56EXAMPLE"
```
------
Capacity Blocks operate on a **first-come, first-served basis** for all accounts, regardless of ownership status. When you share a Capacity Block, if a consumer launches instances before the owner, those instances occupy the capacity until the consumer terminates the instances or until 30 minutes before the Capacity Block expires.
## Stop sharing a Capacity Block
You can stop sharing a Capacity Block at any time until 30 minutes before the block expiry date.
**What happens when you stop sharing:**
+ Consumers can no longer launch new instances into the Capacity Block that was unshared.
+ Any running instances continue running until 30 minutes before the Capacity Block expiry date, unless terminated by the consumer.
------
#### [ Console ]
**To stop sharing a Capacity Block that you own using the Amazon EC2 console**
1. Open the Amazon EC2 console at [https://console.aws.amazon.com/ec2/](https://console.aws.amazon.com/ec2/).
1. In the navigation pane, choose **Capacity Reservations**.
1. Select the Capacity Block and choose the **Sharing** tab.
1. The **Sharing** tab lists the resource shares to which the Capacity Block has been added. Select the resource share from which to remove the Capacity Block.
1. Choose **Remove from resource share**.
------
#### [ AWS CLI ]
**To stop sharing a Capacity Block that you own**
Use the [disassociate-resource-share](https://docs.aws.amazon.com/cli/latest/reference/ram/disassociate-resource-share.html) command.
```
aws ram disassociate-resource-share \
--resource-share-arn arn:aws:ram:us-east-2:123456789012:resource-share/7ab63972-b505-7e2a-420d-6f5d3EXAMPLE \
--resource-arns arn:aws:ec2:us-east-2:123456789012:capacity-reservation/cr-1234abcd56EXAMPLE
```
------
#### [ PowerShell ]
**To stop sharing a Capacity Block that you own**
Use the [Disconnect-RAMResourceShare](https://docs.aws.amazon.com/powershell/latest/reference/items/Disconnect-RAMResourceShare.html) cmdlet.
```
Disconnect-RAMResourceShare `
-ResourceShareArn "arn:aws:ram:us-east-2:123456789012:resource-share/7ab63972-b505-7e2a-420d-6f5d3EXAMPLE" `
-ResourceArn "arn:aws:ec2:us-east-2:123456789012:capacity-reservation/cr-1234abcd56EXAMPLE"
```
------
## Monitor shared Capacity Block usage
Capacity Block owners can monitor which accounts are using their shared Capacity Blocks and track instance usage per account.
------
#### [ AWS CLI ]
**To monitor usage of a Capacity Block**
Use the [get-capacity-reservation-usage](https://docs.aws.amazon.com/cli/latest/reference/ec2/get-capacity-reservation-usage.html) command.
```
aws ec2 get-capacity-reservation-usage \
--capacity-reservation-id cr-1234abcd56EXAMPLE
```
**This API enables owners to:**
+ View which accounts are currently using the Capacity Block.
+ See the number of instances each account is running.
------
## Instance termination notices
Owner and consumer accounts that have instances running in the Capacity Block will receive an EventBridge event 40 minutes before the Capacity Block reservation ends, indicating that any instances running in the reservation will begin to terminate in 10 minutes. For more information, see [Monitor Capacity Blocks using EventBridge](capacity-blocks-monitor.md).
## Capacity Block extensions
Capacity Blocks can be extended while they are shared. Only the owner account can extend a shared Capacity Block.
When a Capacity Block is extended, running instances launched by the owner or consumers automatically inherit the new expiry date, and consumers can continue using the shared capacity until the new expiry date without any instance interruption.
## Pricing and billing
Owners are billed for the Capacity Blocks they share and pay upfront for the Capacity Block when they purchase it. Owners also pay for operating system charges for instances they run on the Capacity Block.
Consumers are billed only for the operating system charges for instances they run in the shared Capacity Block. Consumers are not charged for the Capacity Block reservation itself.
# Create a resource group for UltraServer Capacity Blocks
You can use AWS Resource Groups to create logical collections of UltraServer Capacity Blocks. After you create the resource group, you can add UltraServer Capacity Blocks that you own in your account. After you add the UltraServer Capacity Blocks, you can target instances launches to the resource group instead of the individual Capacity Blocks. Instances that target a resource group match with any UltraServer Capacity Blocks in the group that has matching attributes and available capacity. If the resource group does not have an UltraServer Capacity Block with matching attributes and available capacity, the instance launch fails.
If an UltraServer Capacity Block is removed from a resource group while it has running instances, those instances continue to run in the Capacity Block. If an UltraServer Capacity Block in a group ends while it has running instances, the instances are terminated.
You can't add instance Capacity Blocks to a resource group.
To create a resource group for UltraServer Capacity Blocks, use one of the following methods.
------
#### [ AWS CLI ]
**To create a resource group for UltraServer Capacity Blocks**
Use the [create-group](https://docs.aws.amazon.com/cli/latest/reference/resource-groups/create-group.html) AWS CLI command, and for `--configuration`, specify the following:
```
{
"Configuration": [
{
"Type": "AWS::EC2::CapacityReservationPool",
"Parameters": [
{
"Name": "instance-type",
"Values": [
"instance_type"
]
},
{
"Name": "reservation-type",
"Values": [
"capacity-block"
]
}
]
},
{
"Type": "AWS::ResourceGroups::Generic",
"Parameters": [
{
"Name": "allowed-resource-types",
"Values": [
"AWS::EC2::CapacityReservation"
]
}
]
}
]
}
```
------
#### [ PowerShell ]
**To create a resource group for UltraServer Capacity Blocks**
Use the [New-RGGroup](https://docs.aws.amazon.com/powershell/latest/reference/items/New-RGGroup.html) cmdlet. For `-Configuration`, specify the following:
```
{
"Configuration": [
{
"Type": "AWS::EC2::CapacityReservationPool",
"Parameters": [
{
"Name": "instance-type",
"Values": [
"instance_type"
]
},
{
"Name": "reservation-type",
"Values": [
"capacity-block"
]
}
]
},
{
"Type": "AWS::ResourceGroups::Generic",
"Parameters": [
{
"Name": "allowed-resource-types",
"Values": [
"AWS::EC2::CapacityReservation"
]
}
]
}
]
}
```
------
After you create a resource group for UltraServer Capacity Block, use one of the following methods to add existing UltraServer Capacity Blocks to it.
------
#### [ AWS CLI ]
**To add an UltraServer Capacity Block to a resource group**
Use the [ group-resources](https://docs.aws.amazon.com/cli/latest/reference/resource-groups/group-resources.html) command. For `--group` specify the name of the resource group you created. For `--resource-arns`, specify the ARNs of the UltraServer Capacity Blocks to add.
```
aws resource-groups group-resources \
--group MyCRGroup \
--resource-arns CapacityReservationArn
```
------
#### [ PowerShell ]
**To add an UltraServer Capacity Block to a resource group**
Use the [Add-RGResource](https://docs.aws.amazon.com/powershell/latest/reference/items/Add-RGResource.html) cmdlet. For `-Group` specify the name of the resource group you created. For `-ResourceArn `, specify the ARNs of the UltraServer Capacity Blocks to add.
The following example adds two Capacity Reservations to the specified group.
```
Add-RGResource `
-Group MyCRGroup `
-ResourceArn CapacityReservationArn
```
------
# Monitor Capacity Blocks using EventBridge
When your Capacity Block reservation starts, Amazon EC2 will emit an event through EventBridge that indicates your capacity is ready to use. Forty minutes before your Capacity Block reservation ends, you receive another EventBridge event that tells you that any instances running in the reservation will begin to terminate in 10 minutes. For more information about EventBridge events, see [Amazon EventBridge Events](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-events.html).
The following event structures for events emitted for Capacity Blocks:
**Capacity Block Delivered**
The following example shows an event for Capacity Block Delivered.
```
{
"customer_event_id": "[Capacity Reservation Id]-delivered",
"detail_type": "Capacity Block Reservation Delivered",
"source": "aws.ec2",
"account": "[Customer Account ID]",
"time": "[Current time]",
"resources": [
"[ODCR ARN]"
],
"detail": {
"capacity-reservation-id": "[ODCR ID]",
"end-date": "[ODCR End Date]"
}
}
```
**Capacity Block Expiration Warning**
The following example shows an event for Capacity Block Expiration Warning.
```
{
"customer_event_id": "[Capacity Reservation Id]-approaching-expiry",
"detail_type": "Capacity Block Reservation Expiration Warning",
"source": "aws.ec2",
"account": "[Customer Account ID]",
"time": "[Current time]",
"resources": [
"[ODCR ARN]"
],
"detail": {
"capacity-reservation-id": "[ODCR ID]",
"end-date": "[ODCR End Date]"
}
}
```
**Capacity Reservation Instance Interruption Warning**
The following example shows an event for EC2 Capacity Reservation Instance Interruption Warning.
```
{
"version": "0",
"id": "12345678-1234-1234-1234-123456789012",
"detail_type": "EC2 Capacity Reservation Instance Interruption Warning",
"source": "aws.ec2",
"account": "[Customer Account ID]",
"time": "[Current time]",
"region": "[Region]",
"resources": [
"[Instance ARN]"
],
"detail": {
"instance-id": "[Instance ID]",
"instance-action": "terminate",
"instance-termination-time": "[Current time]",
"availability-zone-id": "[Availability Zone ID]",
"instance-lifecycle": "capacity-block"
}
}
```
# Logging Capacity Blocks API calls with AWS CloudTrail
Capacity Blocks is integrated with AWS CloudTrail, a service that provides a record of actions taken by a user, role, or an AWS service in Capacity Blocks. CloudTrail captures API calls for Capacity Blocks as events. The calls captured include calls from the Capacity Blocks console and code calls to the Capacity Blocks API operations. If you create a trail, you can enable continuous delivery of CloudTrail events to an Amazon S3 bucket, including events for Capacity Blocks. If you don't configure a trail, you can still view the most recent events in the CloudTrail console in **Event history**. Using the information collected by CloudTrail, you can determine the request that was made to Capacity Blocks, the IP address from which the request was made, who made the request, when it was made, and additional details.
To learn more about CloudTrail, see the [AWS CloudTrail User Guide](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-user-guide.html).
## Capacity Blocks information in CloudTrail
CloudTrail is enabled on your AWS account when you create the account. When activity occurs in Capacity Blocks, that activity is recorded in a CloudTrail event along with other AWS service events in **Event history**. You can view, search, and download recent events in your AWS account. For more information, see [Viewing events with CloudTrail Event history](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/view-cloudtrail-events.html).
For an ongoing record of events in your AWS account, including events for Capacity Blocks, create a trail. A *trail* enables CloudTrail to deliver log files to an Amazon S3 bucket. By default, when you create a trail in the console, the trail applies to all AWS Regions. The trail logs events from all Regions in the AWS partition and delivers the log files to the Amazon S3 bucket that you specify. Additionally, you can configure other AWS services to further analyze and act upon the event data collected in CloudTrail logs. For more information, see the following:
+ [Overview for creating a trail](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-create-and-update-a-trail.html)
+ [CloudTrail supported services and integrations](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-aws-service-specific-topics.html)
+ [Configuring Amazon SNS notifications for CloudTrail](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/configure-sns-notifications-for-cloudtrail.html)
+ [Receiving CloudTrail log files from multiple regions](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/receive-cloudtrail-log-files-from-multiple-regions.html) and [Receiving CloudTrail log files from multiple accounts](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-receive-logs-from-multiple-accounts.html)
All Capacity Blocks actions are logged by CloudTrail and are documented in the Amazon EC2 API Reference. For example, calls to the `CapacityBlockScheduled`, and `CapacityBlockActive` actions generate entries in the CloudTrail log files.
Every event or log entry contains information about who generated the request. The identity information helps you determine the following:
+ Whether the request was made with root or AWS Identity and Access Management (IAM) user credentials.
+ Whether the request was made with temporary security credentials for a role or federated user.
+ Whether the request was made by another AWS service.
For more information, see the [CloudTrail userIdentity element](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-event-reference-user-identity.html).
## Understanding Capacity Blocks log file entries
A trail is a configuration that enables delivery of events as log files to an Amazon S3 bucket that you specify. CloudTrail log files contain one or more log entries. An event represents a single request from any source and includes information about the requested action, the date and time of the action, request parameters, and so on. CloudTrail log files aren't an ordered stack trace of the public API calls, so they don't appear in any specific order.
The following examples show CloudTrail log entries for:
+ [TerminateCapacityBlocksInstances](#understanding-capacity-blocks-entries-terminatecapacityblockinstances)
+ [CapacityBlockPaymentFailed](#understanding-capacity-blocks-entries-capacityblockpaymentfailed)
+ [CapacityBlockScheduled](#understanding-capacity-blocks-entries-capacityblockscheduled)
+ [CapacityBlockActive](#understanding-capacity-blocks-entries-capacityblockactive)
+ [CapacityBlockFailed](#understanding-capacity-blocks-entries-capacityblockfailed)
+ [CapacityBlockExpired](#understanding-capacity-blocks-entries-capacityblockexpired)
**Note**
Some fields have been redacted from the examples for data privacy.
### TerminateCapacityBlocksInstances
```
{
"eventVersion": "1.05",
"userIdentity": {
"accountId": "123456789012",
"invokedBy": "AWS Internal;"
},
"eventTime": "2023-10-02T00:06:08Z",
"eventSource": "ec2.amazonaws.com",
"eventName": "TerminateCapacityBlockInstances",
"awsRegion": "us-east-1",
"sourceIPAddress": "203.0.113.25",
"userAgent": "aws-cli/1.15.61 Python/2.7.10 Darwin/16.7.0 botocore/1.10.60",
"requestParameters": null,
"responseElements": null,
"eventID": "a1b2c3d4-EXAMPLE",
"readOnly": false,
"resources": [
{
"accountId": "123456789012",
"type": "AWS::EC2::Instance",
"ARN": "arn:aws:ec2:us-east-1:123456789012:instance/i-1234567890abcdef0"
}
{
"accountId": "123456789012",
"type": "AWS::EC2::Instance",
"ARN": "arn:aws:ec2:us-east-1:123456789012:instance/i-0598c7d356eba48d7"
}
],
"eventType": "AwsServiceEvent",
"recipientAccountId": "123456789012",
"serviceEventDetails": {
"capacityReservationId": "cr-12345678",
}
}
```
### CapacityBlockPaymentFailed
```
{
"eventVersion": "1.05",
"userIdentity": {
"accountId": "123456789012",
"invokedBy": "AWS Internal;"
},
"eventTime": "2023-10-02T00:06:08Z",
"eventSource": "ec2.amazonaws.com",
"eventName": "CapacityBlockPaymentFailed",
"awsRegion": "us-east-1",
"sourceIPAddress": "203.0.113.25",
"userAgent": "aws-cli/1.15.61 Python/2.7.10 Darwin/16.7.0 botocore/1.10.60",
"requestParameters": null,
"responseElements": null,
"eventID": "a1b2c3d4-EXAMPLE",
"readOnly": false,
"resources": [
{
"ARN": "arn:aws:ec2:us-east-1:123456789012:capacity-reservation/cr-12345678",
"accountId": "123456789012",
"type": "AWS::EC2::CapacityReservation"
}
],
"eventType": "AwsServiceEvent",
"recipientAccountId": "123456789012",
"serviceEventDetails": {
"capacityReservationId": "cr-12345678",
"capacityReservationState": "payment-failed"
}
}
```
### CapacityBlockScheduled
```
{
"eventVersion": "1.05",
"userIdentity": {
"accountId": "123456789012",
"invokedBy": "AWS Internal;"
},
"eventTime": "2023-10-02T00:06:08Z",
"eventSource": "ec2.amazonaws.com",
"eventName": "CapacityBlockScheduled",
"awsRegion": "us-east-1",
"sourceIPAddress": "203.0.113.25",
"userAgent": "aws-cli/1.15.61 Python/2.7.10 Darwin/16.7.0 botocore/1.10.60",
"requestParameters": null,
"responseElements": null,
"eventID": "a1b2c3d4-EXAMPLE",
"readOnly": false,
"resources": [
{
"ARN": "arn:aws:ec2:us-east-1:123456789012:capacity-reservation/cr-12345678",
"accountId": "123456789012",
"type": "AWS::EC2::CapacityReservation"
}
],
"eventType": "AwsServiceEvent",
"recipientAccountId": "123456789012",
"serviceEventDetails": {
"capacityReservationId": "cr-12345678",
"capacityReservationState": "scheduled"
}
}
```
### CapacityBlockActive
```
{
"eventVersion": "1.05",
"userIdentity": {
"accountId": "123456789012",
"invokedBy": "AWS Internal;"
},
"eventTime": "2023-10-02T00:06:08Z",
"eventSource": "ec2.amazonaws.com",
"eventName": "CapacityBlockActive",
"awsRegion": "us-east-1",
"sourceIPAddress": "203.0.113.25",
"userAgent": "aws-cli/1.15.61 Python/2.7.10 Darwin/16.7.0 botocore/1.10.60",
"requestParameters": null,
"responseElements": null,
"eventID": "a1b2c3d4-EXAMPLE",
"readOnly": false,
"resources": [
{
"ARN": "arn:aws:ec2:us-east-1:123456789012:capacity-reservation/cr-12345678",
"accountId": "123456789012",
"type": "AWS::EC2::CapacityReservation"
}
],
"eventType": "AwsServiceEvent",
"recipientAccountId": "123456789012",
"serviceEventDetails": {
"capacityReservationId": "cr-12345678",
"capacityReservationState": "active"
}
}
```
### CapacityBlockFailed
```
{
"eventVersion": "1.05",
"userIdentity": {
"accountId": "123456789012",
"invokedBy": "AWS Internal;"
},
"eventTime": "2023-10-02T00:06:08Z",
"eventSource": "ec2.amazonaws.com",
"eventName": "CapacityBlockFailed",
"awsRegion": "us-east-1",
"sourceIPAddress": "203.0.113.25",
"userAgent": "aws-cli/1.15.61 Python/2.7.10 Darwin/16.7.0 botocore/1.10.60",
"requestParameters": null,
"responseElements": null,
"eventID": "a1b2c3d4-EXAMPLE",
"readOnly": false,
"resources": [
{
"ARN": "arn:aws:ec2:us-east-1:123456789012:capacity-reservation/cr-12345678",
"accountId": "123456789012",
"type": "AWS::EC2::CapacityReservation"
}
],
"eventType": "AwsServiceEvent",
"recipientAccountId": "123456789012",
"serviceEventDetails": {
"capacityReservationId": "cr-12345678",
"capacityReservationState": "failed"
}
}
```
### CapacityBlockExpired
```
{
"eventVersion": "1.05",
"userIdentity": {
"accountId": "123456789012",
"invokedBy": "AWS Internal;"
},
"eventTime": "2023-10-02T00:06:08Z",
"eventSource": "ec2.amazonaws.com",
"eventName": "CapacityBlockExpired",
"awsRegion": "us-east-1",
"sourceIPAddress": "203.0.113.25",
"userAgent": "aws-cli/1.15.61 Python/2.7.10 Darwin/16.7.0 botocore/1.10.60",
"requestParameters": null,
"responseElements": null,
"eventID": "a1b2c3d4-EXAMPLE",
"readOnly": false,
"resources": [
{
"ARN": "arn:aws:ec2:us-east-1:123456789012:capacity-reservation/cr-12345678",
"accountId": "123456789012",
"type": "AWS::EC2::CapacityReservation"
}
],
"eventType": "AwsServiceEvent",
"recipientAccountId": "123456789012",
"serviceEventDetails": {
"capacityReservationId": "cr-12345678",
"capacityReservationState": "expired"
}
}
```