How do I resolve launch or start failures for an Amazon EC2 instance with encrypted Amazon EBS volumes?

Short description

Instances with launch issues might go from the Pending state to Shutting down to Terminated when you start them.

Or, you might receive the following error message in the output of the describe-instances AWS Command Line Interface (AWS CLI) command:

" "StateReason": { "Code": "Client.InternalError" "Message": "Client.InternalError: Client error on launch" }"

This issue occurs if the AWS Key Management Service (AWS KMS) key that you used for encryption isn't set to Enable. Or, the AWS Identity and Access Management (IAM) user or role that launched the instance doesn't have the required AWS KMS permissions.

Note: Even if your IAM user has full Amazon EC2 permissions, you must still grant them access to the AWS KMS key.

To resolve IAM issues, create a policy that allows access to your AWS KMS key, and then attach the policy to your IAM entity. Or, add the IAM entities to the AWS KMS key users.

Resolution

Note: If you receive errors when you run AWS CLI commands, then see Troubleshooting errors for the AWS CLI. Also, make sure that you're using the most recent AWS CLI version.

Check the AWS KMS key status

Make sure that you set your AWS KMS key to Enable.

Create a policy that allows access to your AWS KMS key, and then attach the policy to your IAM entity

Create the following IAM policy:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "VisualEditor0",
      "Effect": "Allow",
      "Action": [
        "kms:Decrypt",
        "kms:ReEncrypt*",
        "kms:Encrypt",
        "kms:GenerateDataKey*",
        "kms:DescribeKey"
      ],
      "Resource": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"
    },
    {
      "Effect": "Allow",
      "Action": "kms:CreateGrant",
      "Resource": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
      "Condition": {
        "Bool": {
          "kms:GrantIsForAWSResource": true
        }
      }
    }
  ]
} 

Note: Replace arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab with the Amazon Resource Name (ARN) of your AWS KMS key.

Then, attach the policy to your IAM role or user.

Add the IAM entities to the AWS KMS key users

Complete the following steps:

1. Open the AWS KMS console.
2. Choose Customer managed keys.
3. For Key ID, choose your key ID.
4. For Key users, choose Add.
5. For Name, choose the IAM user or role, and then choose Add.
   Note: The default key policy allows access to your AWS accounts. If you use a custom key policy instead, then the AWS KMS key policy must explicitly allow the following permissions:

   {
         "Sid": "Allow use of the key",
         "Effect": "Allow",
         "Principal": {
           "AWS": [
             "arn:aws:iam::123456789012:role/MyRoleName",
             "arn:aws:iam::123456789012:user/MyUserName"
           ]
         },
         "Action": [
           "kms:Encrypt",
           "kms:Decrypt",
           "kms:ReEncrypt*",
           "kms:GenerateDataKey*",
           "kms:DescribeKey"
         ],
         "Resource": "*"
       },
       {
         "Sid": "Allow attachment of persistent resources",
         "Effect": "Allow",
         "Principal": {
           "AWS": [
             "arn:aws:iam::123456789012:role/MyRoleName",
             "arn:aws:iam::123456789012:user/MyUserName"
           ]
         },
         "Action": [
           "kms:CreateGrant",
           "kms:ListGrants",
           "kms:RevokeGrant"
         ],
         "Resource": "*",
         "Condition": {
           "Bool": {
             "kms:GrantIsForAWSResource": "true"
           }
         }
       } 

   Note: Replace arn:aws:iam::123456789012:role/MyRoleName with your IAM role ARN and arn:aws:iam::123456789012:user/MyUserName with your IAM user ARN.

Related information

How can I verify that authenticated encryption with data encryption is used for AWS KMS API calls?

Key policies in AWS KMS

How Amazon Elastic Block Store (Amazon EBS) uses AWS KMS