# Fargate task ephemeral storage for Amazon ECS
When provisioned, each Amazon ECS task hosted on Linux containers on AWS Fargate receives the following ephemeral storage for bind mounts. This can be mounted and shared among containers that use the `volumes`, `mountPoints`, and `volumesFrom` parameters in the task definition. This isn't supported for Windows containers on AWS Fargate.
## Fargate Linux container platform versions
### Version 1.4.0 or later
By default, Amazon ECS tasks that are hosted on Fargate using platform version `1.4.0` or later receive a minimum of 20 GiB of ephemeral storage. The total amount of ephemeral storage can be increased, up to a maximum of 200 GiB. You can do this by specifying the `ephemeralStorage` parameter in your task definition.
The pulled, compressed, and the uncompressed container image for the task is stored on the ephemeral storage. To determine the total amount of ephemeral storage your task has to use, you must subtract the amount of storage your container image uses from the total amount of ephemeral storage your task is allocated.
For tasks that use platform version `1.4.0` or later that are launched on May 28, 2020 or later, the ephemeral storage is encrypted with an AES-256 encryption algorithm. This algorithm uses an AWS owned encryption key, or you can create your own customer managed key. For more information, see [Customer managed keys for AWS Fargate ephemeral storage](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/fargate-storage-encryption.html).
For tasks that use platform version `1.4.0` or later that are launched on November 18, 2022 or later, the ephemeral storage usage is reported through the task metadata endpoint. Your applications in your tasks can query the task metadata endpoint version 4 to get their ephemeral storage reserved size and the amount used.
Additionally, the ephemeral storage reserved size and the amount used are sent to Amazon CloudWatch Container Insights if you turn on Container Insights.
**Note**
Fargate reserves space on disk. It is only used by Fargate. You aren't billed for it. It isn't shown in these metrics. However, you can see this additional storage in other tools such as `df`.
### Version 1.3.0 or earlier
For Amazon ECS on Fargate tasks that use platform version `1.3.0` or earlier, each task receives the following ephemeral storage.
+ 10 GB of Docker layer storage
**Note**
This amount includes both compressed and uncompressed container image artifacts.
+ An additional 4 GB for volume mounts. This can be mounted and shared among containers that use the `volumes`, `mountPoints`, and `volumesFrom` parameters in the task definition.
## Fargate Windows container platform versions
### Version 1.0.0 or later
By default, Amazon ECS tasks that are hosted on Fargate using platform version `1.0.0` or later receive a minimum of 20 GiB of ephemeral storage. The total amount of ephemeral storage can be increased, up to a maximum of 200 GiB. You can do this by specifying the `ephemeralStorage` parameter in your task definition.
The pulled, compressed, and the uncompressed container image for the task is stored on the ephemeral storage. To determine the total amount of ephemeral storage that your task has to use, you must subtract the amount of storage that your container image uses from the total amount of ephemeral storage your task is allocated.
For more information, see [Use bind mounts with Amazon ECS](bind-mounts.md).
# Customer managed keys for AWS Fargate ephemeral storage for Amazon ECS
AWS Fargate supports customer managed keys to encrypt data for Amazon ECS tasks stored in ephemeral storage to help regulation-sensitive customers meet their internal security policies. Customers still get the serverless benefit of Fargate, while giving enhanced visibility on self-managed storage encryption to compliance auditors. While Fargate has Fargate-managed ephemeral storage encryption by default, customers can also use their own self-managed keys when encrypting sensitive data like financial or health related information.
You can import your own keys into AWS KMS or create the keys in AWS KMS. These self-managed keys are stored in AWS KMS and perform standard AWS KMS lifecycle actions such as rotate, disable, and delete. You can audit key access and usage in CloudTrail logs.
By default, KMS key supports 50,000 grants per key. Fargate uses a single AWS KMS grant per customer managed key task, so it supports up to 50,000 concurrent tasks for a key. If you want to increase this number, you can ask for a limit increase, which is approved on a case-by-case basis.
Fargate doesn't charge anything extra for using customer managed keys. You're only charged the standard price for using AWS KMS keys for storage and API requests.
**Topics**
+ [Create an encryption key for Fargate ephemeral storage for Amazon ECS](fargate-create-storage-key.md)
+ [Managing AWS KMS keys for Fargate ephemeral storage for Amazon ECS](fargate-managing-kms-key.md)
# Create an encryption key for Fargate ephemeral storage for Amazon ECS
Create a customer managed key to encrypt data stored on Fargate ephemeral storage.
**Note**
Fargate ephemeral storage encryption with customer managed keys isn't available for Windows task clusters.
Fargate ephemeral storage encryption with customer managed keys isn't available on `platformVersions` earlier than `1.4.0`.
Fargate reserves space on an ephemeral storage that's only used by Fargate, and you're not billed for the space. Allocation might differ from non-customer managed key tasks, but the total space remains the same. You can view this change in tools like `df`.
Multi-Region keys are not supported for Fargate ephemeral storage.
KMS key aliases are not supported for Fargate ephemeral storage.
To create a customer managed key (CMK) to encrypt ephemeral storage for Fargate in AWS KMS, follow these steps.
1. Navigate to the [https://console.aws.amazon.com/kms](https://console.aws.amazon.com/kms).
1. Follow the instructions for [Creating Keys](https://docs.aws.amazon.com/kms/latest/developerguide/create-keys.html) in the [AWS Key Management Service Developer Guide](https://docs.aws.amazon.com/kms/latest/developerguide/overview.html).
1. When creating your AWS KMS key, make sure to provide Fargate service relevant AWS KMS operation permissions in the key policies. The following API operations must be permitted in the policy to use your customer managed key with your Amazon ECS cluster resources.
+ `kms:GenerateDataKeyWithoutPlainText` ‐ Call `GenerateDataKeyWithoutPlainText` to generate an encrypted data key from the provided AWS KMS key.
+ `kms:CreateGrant` ‐ Adds a grant to a customer managed key. Grants control access to a specified AWS KMS key, which allows access to grant operations that Amazon ECS Fargate requires. For more information about [Using Grants](https://docs.aws.amazon.com/kms/latest/developerguide/grants.html), see the [AWS Key Management Service Developer Guide](https://docs.aws.amazon.com/kms/latest/developerguide/overview.html). This allows Amazon ECS Fargate to do the following:
+ Call `Decrypt` to AWS KMS to get the encryption key to decrypt the ephemeral storage data.
+ Set up a retiring principal to allow the service to `RetireGrant`.
+ `kms:DescribeKey` ‐ Provides the customer managed key details to allow Amazon ECS to validate the key if it's symmetric and enabled.
The following example shows a AWS KMS key policy that you would apply to the target key for encryption. To use the example policy statements, replace the *user input placeholders* with your own information. As always, only configure the permissions that you need, but you'll need to provide AWS KMS with permissions to at least one user to avoid errors.
```
{
"Sid": "Allow generate data key access for Fargate tasks.",
"Effect": "Allow",
"Principal": { "Service":"fargate.amazonaws.com" },
"Action": [
"kms:GenerateDataKeyWithoutPlaintext"
],
"Condition": {
"StringEquals": {
"kms:EncryptionContext:aws:ecs:clusterAccount": [
"customerAccountId"
],
"kms:EncryptionContext:aws:ecs:clusterName": [
"clusterName"
]
}
},
"Resource": "*"
},
{
"Sid": "Allow grant creation permission for Fargate tasks.",
"Effect": "Allow",
"Principal": { "Service":"fargate.amazonaws.com" },
"Action": [
"kms:CreateGrant"
],
"Condition": {
"StringEquals": {
"kms:EncryptionContext:aws:ecs:clusterAccount": [
"customerAccountId"
],
"kms:EncryptionContext:aws:ecs:clusterName": [
"clusterName"
]
},
"ForAllValues:StringEquals": {
"kms:GrantOperations": [
"Decrypt"
]
}
},
"Resource": "*"
},
{
"Sid": "Allow describe key permission for cluster operator - CreateCluster and UpdateCluster.",
"Effect": "Allow",
"Principal": { "AWS":"arn:aws:iam::customerAccountId:role/customer-chosen-role" },
"Action": [
"kms:DescribeKey"
],
"Resource": "*"
}
```
Fargate tasks use the `aws:ecs:clusterAccount` and `aws:ecs:clusterName` encryption context keys for cryptographic operations with the key. Customers should add these permissions to restrict access to a specific account and/or cluster. Use the cluster name and not the ARN when you specify the cluster.
For more information, see [Encryption context](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#encrypt_context) in the [AWS KMS Developer Guide](https://docs.aws.amazon.com/kms/latest/developerguide/overview.html).
When creating or updating a cluster, you have the option to use the condition key `fargateEphemeralStorageKmsKeyId`. This condition key allows customers to have more granular control of the IAM policies. Updates to the `fargateEphemeralStorageKmsKeyId` configuration only take effect on new service deployments.
The following is an example of allowing customers to grant permissions to only a specific set of approved AWS KMS keys.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ecs:CreateCluster",
"ecs:UpdateCluster"
],
"Resource": "*",
"Condition": {
"StringEquals": {
"ecs:fargate-ephemeral-storage-kms-key": "arn:aws:kms:us-west-2:111122223333:key/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111"
}
}
}
]
}
```
------
Next is an example for denying attempts to remove AWS KMS keys that are already associated with a cluster.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": {
"Effect": "Deny",
"Action": [
"ecs:CreateCluster",
"ecs:UpdateCluster"
],
"Resource": "*",
"Condition": {
"Null": {
"ecs:fargate-ephemeral-storage-kms-key": "true"
}
}
}
}
```
------
Customers can see if their unmanaged tasks or service tasks are encrypted using the key by using the AWS CLI `describe-tasks`, `describe-cluster`, or `describe-services` commands.
For more information, see [Condition keys for AWS KMS](https://docs.aws.amazon.com/kms/latest/developerguide/policy-conditions.html) in the [AWS KMS Developer Guide](https://docs.aws.amazon.com/kms/latest/developerguide/overview.html).
------
#### [ AWS Management Console ]
1. Open the console at [https://console.aws.amazon.com/ecs/v2](https://console.aws.amazon.com/ecs/v2).
1. Choose **Clusters** in the left navigation and either **Create cluster** in the top right, or choose an existing cluster. For an existing cluster, choose **Update cluster** in the top right.
1. Under the **Encryption** section of the workflow, you'll have the option to select your AWS KMS key under **Managed storage** and **Fargate ephemeral storage**. You can also choose to **Create an AWS KMS key** from here.
1. Choose **Create** once you finish creating your new cluster or **Update**, if you were updating an existing one.
------
#### [ AWS CLI ]
The following is an example of creating a cluster and configuring your Fargate ephemeral storage using the AWS CLI (replace the *red* values with your own):
```
aws ecs create-cluster --cluster clusterName \
--configuration '{"managedStorageConfiguration":{"fargateEphemeralStorageKmsKeyId":"arn:aws:kms:us-west-2:012345678901:key/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111"}}'
{
"cluster": {
"clusterArn": "arn:aws:ecs:us-west-2:012345678901:cluster/clusterName",
"clusterName": "clusterName",
"configuration": {
"managedStorageConfiguration": {
"fargateEphemeralStorageKmsKeyId": "arn:aws:kms:us-west-2:012345678901:key/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111"
}
},
"status": "ACTIVE",
"registeredContainerInstancesCount": 0,
"runningTasksCount": 0,
"pendingTasksCount": 0,
"activeServicesCount": 0,
"statistics": [],
"tags": [],
"settings": [],
"capacityProviders": [],
"defaultCapacityProviderStrategy": []
},
"clusterCount": 5
}
```
------
#### [ CloudFormation ]
The following is an example template of creating a cluster and configuring your Fargate ephemeral storage using the CloudFormation (replace the *red* values with your own):
```
AWSTemplateFormatVersion: 2010-09-09
Resources:
MyCluster:
Type: AWS::ECS::Cluster
Properties:
ClusterName: "clusterName"
Configuration:
ManagedStorageConfiguration:
FargateEphemeralStorageKmsKeyId: "arn:aws:kms:us-west-2:012345678901:key/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111"
```
------
# Managing AWS KMS keys for Fargate ephemeral storage for Amazon ECS
After creating or importing your AWS KMS key to encrypt your Fargate ephemeral storage, you manage it the same way you would any other AWS KMS key.
**Automatic rotation of AWS KMS keys**
You can enable automatic key rotation or rotate them manually. Automatic key rotation rotates the key for you yearly by generating new cryptographic material for the key. AWS KMS also saves all previous versions of the cryptographic material, so you'll be able to decrypt any data that used the earlier key versions. Any rotated material won't be deleted by AWS KMS until you delete the key.
Automatic key rotation is optional and can be enabled or disabled at any time.
**Disabling or revoking AWS KMS keys**
If you disable a customer managed key in AWS KMS, it doesn't have any impact on running tasks, and they continue to function through their lifecycle. If a new task uses the disabled or revoked key, the task fails since it can't access the key. You should set a CloudWatch alarm or similar to make sure a disabled key is never needed to decrypt already encrypted data.
**Deleting AWS KMS keys**
Deleting keys should always be a last resort and should only be done if you're certain the deleted key is never needed again. New tasks that try to use the deleted key will fail because they can't access it. AWS KMS advises disabling a key instead of deleting it. If you feel it's necessary to delete a key, we suggest disabling it first and setting a CloudWatch alarm to make sure it isn't needed. If you do delete a key, AWS KMS supplies at least seven days to change your mind.
**Auditing AWS KMS key access**
You can use CloudTrail logs to audit access to your AWS KMS key. You're able to check the AWS KMS operations `CreateGrant`, `GenerateDataKeyWithoutPlaintext`, and `Decrypt`. These operations also show the `aws:ecs:clusterAccount` and `aws:ecs:clusterName` as part of the `EncryptionContext` logged in CloudTrail.
The following are example CloudTrail events for `GenerateDataKeyWithoutPlaintext`, `GenerateDataKeyWithoutPlaintext (DryRun)`, `CreateGrant`, `CreateGrant (DryRun)`, and `RetireGrant` (replace the *red* values with your own).
------
#### [ GenerateDataKeyWithoutPlaintext ]
```
{
"eventVersion": "1.08",
"userIdentity": {
"type": "AWSService",
"invokedBy": "ec2-frontend-api.amazonaws.com"
},
"eventTime": "2024-04-23T18:08:13Z",
"eventSource": "kms.amazonaws.com",
"eventName": "GenerateDataKeyWithoutPlaintext",
"awsRegion": "us-west-2",
"sourceIPAddress": "ec2-frontend-api.amazonaws.com",
"userAgent": "ec2-frontend-api.amazonaws.com",
"requestParameters": {
"numberOfBytes": 64,
"keyId": "arn:aws:kms:us-west-2:account-id:key/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111",
"encryptionContext": {
"aws:ecs:clusterAccount": "account-id",
"aws:ebs:id": "vol-xxxxxxx",
"aws:ecs:clusterName": "cluster-name"
}
},
"responseElements": null,
"requestID": "a1b2c3d4-5678-90ab-cdef-EXAMPLE22222",
"eventID": "a1b2c3d4-5678-90ab-cdef-EXAMPLE33333",
"readOnly": true,
"resources": [
{
"accountId": "AWS Internal",
"type": "AWS::KMS::Key",
"ARN": "arn:aws:kms:us-west-2:account-id:key/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111"
}
],
"eventType": "AwsApiCall",
"managementEvent": true,
"recipientAccountId": "account-id",
"sharedEventID": "a1b2c3d4-5678-90ab-cdef-EXAMPLEaaaaa",
"eventCategory": "Management"
}
```
------
#### [ GenerateDataKeyWithoutPlaintext (DryRun) ]
```
{
"eventVersion": "1.08",
"userIdentity": {
"type": "AWSService",
"invokedBy": "fargate.amazonaws.com"
},
"eventTime": "2024-04-23T18:08:11Z",
"eventSource": "kms.amazonaws.com",
"eventName": "GenerateDataKeyWithoutPlaintext",
"awsRegion": "us-west-2",
"sourceIPAddress": "fargate.amazonaws.com",
"userAgent": "fargate.amazonaws.com",
"errorCode": "DryRunOperationException",
"errorMessage": "The request would have succeeded, but the DryRun option is set.",
"requestParameters": {
"keyId": "arn:aws:kms:us-west-2:account-id:key/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111",
"dryRun": true,
"numberOfBytes": 64,
"encryptionContext": {
"aws:ecs:clusterAccount": "account-id",
"aws:ecs:clusterName": "cluster-name"
}
},
"responseElements": null,
"requestID": "a1b2c3d4-5678-90ab-cdef-EXAMPLE22222",
"eventID": "a1b2c3d4-5678-90ab-cdef-EXAMPLE33333",
"readOnly": true,
"resources": [
{
"accountId": "AWS Internal",
"type": "AWS::KMS::Key",
"ARN": "arn:aws:kms:us-west-2:account-id:key/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111"
}
],
"eventType": "AwsApiCall",
"managementEvent": true,
"recipientAccountId": "account-id",
"sharedEventID": "a1b2c3d4-5678-90ab-cdef-EXAMPLEaaaaa",
"eventCategory": "Management"
}
```
------
#### [ CreateGrant ]
```
{
"eventVersion": "1.08",
"userIdentity": {
"type": "AWSService",
"invokedBy": "ec2-frontend-api.amazonaws.com"
},
"eventTime": "2024-04-23T18:08:13Z",
"eventSource": "kms.amazonaws.com",
"eventName": "CreateGrant",
"awsRegion": "us-west-2",
"sourceIPAddress": "ec2-frontend-api.amazonaws.com",
"userAgent": "ec2-frontend-api.amazonaws.com",
"requestParameters": {
"keyId": "arn:aws:kms:us-west-2:account-id:key/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111",
"granteePrincipal": "fargate.us-west-2.amazonaws.com",
"operations": [
"Decrypt"
],
"constraints": {
"encryptionContextSubset": {
"aws:ecs:clusterAccount": "account-id",
"aws:ebs:id": "vol-xxxx",
"aws:ecs:clusterName": "cluster-name"
}
},
"retiringPrincipal": "ec2.us-west-2.amazonaws.com"
},
"responseElements": {
"grantId": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
"keyId": "arn:aws:kms:us-west-2:account-id:key/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111"
},
"requestID": "a1b2c3d4-5678-90ab-cdef-EXAMPLE22222",
"eventID": "a1b2c3d4-5678-90ab-cdef-EXAMPLE33333",
"readOnly": false,
"resources": [
{
"accountId": "AWS Internal",
"type": "AWS::KMS::Key",
"ARN": "arn:aws:kms:us-west-2:account-id:key/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111"
}
],
"eventType": "AwsApiCall",
"managementEvent": true,
"recipientAccountId": "account-id",
"sharedEventID": "a1b2c3d4-5678-90ab-cdef-EXAMPLEaaaaa",
"eventCategory": "Management"
}
```
------
#### [ CreateGrant (DryRun) ]
```
{
"eventVersion": "1.08",
"userIdentity": {
"type": "AWSService",
"invokedBy": "fargate.amazonaws.com"
},
"eventTime": "2024-04-23T18:08:11Z",
"eventSource": "kms.amazonaws.com",
"eventName": "CreateGrant",
"awsRegion": "us-west-2",
"sourceIPAddress": "fargate.amazonaws.com",
"userAgent": "fargate.amazonaws.com",
"errorCode": "DryRunOperationException",
"errorMessage": "The request would have succeeded, but the DryRun option is set.",
"requestParameters": {
"keyId": "arn:aws:kms:us-west-2:account-id:key/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111",
"granteePrincipal": "fargate.us-west-2.amazonaws.com",
"dryRun": true,
"operations": [
"Decrypt"
],
"constraints": {
"encryptionContextSubset": {
"aws:ecs:clusterAccount": "account-id",
"aws:ecs:clusterName": "cluster-name"
}
}
},
"responseElements": null,
"requestID": "a1b2c3d4-5678-90ab-cdef-EXAMPLE22222",
"eventID": "a1b2c3d4-5678-90ab-cdef-EXAMPLE33333",
"readOnly": false,
"resources": [
{
"accountId": "AWS Internal",
"type": "AWS::KMS::Key",
"ARN": "arn:aws:kms:us-west-2:account-id:key/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111"
}
],
"eventType": "AwsApiCall",
"managementEvent": true,
"recipientAccountId": "account-id",
"sharedEventID": "a1b2c3d4-5678-90ab-cdef-EXAMPLEaaaaa",
"eventCategory": "Management"
}
```
------
#### [ RetireGrant ]
```
{
"eventVersion": "1.08",
"userIdentity": {
"type": "AWSService",
"invokedBy": "AWS Internal"
},
"eventTime": "2024-04-20T18:37:38Z",
"eventSource": "kms.amazonaws.com",
"eventName": "RetireGrant",
"awsRegion": "us-west-2",
"sourceIPAddress": "AWS Internal",
"userAgent": "AWS Internal",
"requestParameters": null,
"responseElements": {
"keyId": "arn:aws:kms:us-west-2:account-id:key/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111"
},
"additionalEventData": {
"grantId": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
},
"requestID": "a1b2c3d4-5678-90ab-cdef-EXAMPLE22222",
"eventID": "a1b2c3d4-5678-90ab-cdef-EXAMPLE33333",
"readOnly": false,
"resources": [
{
"accountId": "AWS Internal",
"type": "AWS::KMS::Key",
"ARN": "arn:aws:kms:us-west-2:account-id:key/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111"
}
],
"eventType": "AwsApiCall",
"managementEvent": true,
"recipientAccountId": "account-id",
"sharedEventID": "a1b2c3d4-5678-90ab-cdef-EXAMPLEaaaaa",
"eventCategory": "Management"
}
```
------