# 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 Amazon KMS, follow these steps. 1. Navigate to the [https://console.amazonaws.cn/kms](https://console.amazonaws.cn/kms). 1. Follow the instructions for [Creating Keys](https://docs.amazonaws.cn/kms/latest/developerguide/create-keys.html) in the [Amazon Key Management Service Developer Guide](https://docs.amazonaws.cn/kms/latest/developerguide/overview.html). 1. When creating your Amazon KMS key, make sure to provide Fargate service relevant Amazon 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 Amazon KMS key. + `kms:CreateGrant` ‐ Adds a grant to a customer managed key. Grants control access to a specified Amazon KMS key, which allows access to grant operations that Amazon ECS Fargate requires. For more information about [Using Grants](https://docs.amazonaws.cn/kms/latest/developerguide/grants.html), see the [Amazon Key Management Service Developer Guide](https://docs.amazonaws.cn/kms/latest/developerguide/overview.html). This allows Amazon ECS Fargate to do the following: + Call `Decrypt` to Amazon 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 Amazon 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 Amazon 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.amazonaws.cn/kms/latest/developerguide/concepts.html#encrypt_context) in the [Amazon KMS Developer Guide](https://docs.amazonaws.cn/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 Amazon 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-cn:kms:{{us-west-2}}:{{111122223333}}:key/{{a1b2c3d4-5678-90ab-cdef-EXAMPLE11111}}" } } } ] } ``` ------ Next is an example for denying attempts to remove Amazon 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 Amazon CLI `describe-tasks`, `describe-cluster`, or `describe-services` commands. For more information, see [Condition keys for Amazon KMS](https://docs.amazonaws.cn/kms/latest/developerguide/policy-conditions.html) in the [Amazon KMS Developer Guide](https://docs.amazonaws.cn/kms/latest/developerguide/overview.html). ------ #### [ Amazon Web Services Management Console ] 1. Open the console at [https://console.amazonaws.cn/ecs/v2](https://console.amazonaws.cn/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 Amazon KMS key under **Managed storage** and **Fargate ephemeral storage**. You can also choose to **Create an Amazon KMS key** from here. 1. Choose **Create** once you finish creating your new cluster or **Update**, if you were updating an existing one. ------ #### [ Amazon CLI ] The following is an example of creating a cluster and configuring your Fargate ephemeral storage using the Amazon 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 } ``` ------ #### [ Amazon CloudFormation ] The following is an example template of creating a cluster and configuring your Fargate ephemeral storage using the Amazon 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}}" ``` ------