AssociateDatasetKmsKey - Amazon CloudWatch
Request ParametersErrorsSee Also
Services or capabilities described in AWS documentation might vary by Region. To see the differences applicable to the AWS European Sovereign Cloud Region, see the AWS European Sovereign Cloud User Guide.

AssociateDatasetKmsKey

Associates an AWS Key Management Service (AWS KMS) customer managed key with the specified dataset. After this operation completes, all data published to the dataset is encrypted at rest using the specified KMS key. Callers must have kms:Decrypt permission on the key to read the encrypted data.

Only the default dataset is supported. The default dataset is implicit for every account in every Region — you do not need to create it before calling this operation.

You can call AssociateDatasetKmsKey on a dataset that is already associated with a KMS key to replace the existing key with a different one. To replace a key, the caller must have kms:Decrypt permission on both the current key and the new key.

The KMS key that you specify must meet all of the following requirements:

  • It must be a symmetric encryption KMS key (key spec SYMMETRIC_DEFAULT, key usage ENCRYPT_DECRYPT). Asymmetric keys, HMAC keys, and key material types other than SYMMETRIC_DEFAULT are not supported.

  • It must be enabled and not pending deletion.

  • Its key policy must grant the CloudWatch service principal (cloudwatch.amazonaws.com) these permissions: kms:DescribeKey, kms:GenerateDataKey, kms:Encrypt, kms:Decrypt, and kms:ReEncrypt*. Amazon CloudWatch requires these permissions to manage the data on your behalf.

  • The calling principal must have kms:Decrypt permission on the key.

  • It must be specified as a fully qualified key ARN. Key IDs, aliases, and alias ARNs are not accepted.

  • It must be in the same AWS Region as the dataset.

Before completing the association, Amazon CloudWatch validates the key by performing a series of dry-run KMS operations. Service-principal checks run first to verify that the key policy grants the required access to Amazon CloudWatch. These checks include kms:DescribeKey, kms:GenerateDataKey, kms:Encrypt, kms:Decrypt, and kms:ReEncrypt*. After those succeed, a kms:Decrypt dry-run is run with the caller's credentials to verify that the calling principal can use the key. When you are replacing an existing key, the caller's kms:Decrypt dry-run is run on the current key first, and only then on the new key.

If any of these checks fails, the operation fails and the existing key association (if any) remains unchanged. Common failure causes include the key being disabled, the key policy not granting the required permissions to Amazon CloudWatch, or the caller lacking kms:Decrypt permission on the key.

For more information about using customer managed keys with Amazon CloudWatch, see Encryption at rest with customer managed keys in the Amazon CloudWatch User Guide.

Request Parameters

DatasetIdentifier

Specifies the identifier of the dataset that you want to associate the KMS key with. For the default dataset, you can specify either default or the full dataset Amazon Resource Name (ARN) in the format arn:aws:cloudwatch:Region:account-id:dataset/default.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 2048.

Pattern: (default|arn:[a-zA-Z0-9-]+:cloudwatch:[a-zA-Z0-9-]*:\d{12}:dataset/default)

Required: Yes

KmsKeyArn

Specifies the Amazon Resource Name (ARN) of the customer managed KMS key to associate with the dataset. The key must be a symmetric encryption KMS key (SYMMETRIC_DEFAULT) in the same AWS Region as the dataset.

The ARN must be in the format arn:aws:kms:Region:account-id:key/key-id . Key IDs, aliases, and alias ARNs are not accepted.

For more information about KMS key ARNs, see Key ARN in the AWS Key Management Service Developer Guide.

Type: String

Length Constraints: Minimum length of 20. Maximum length of 2048.

Pattern: arn:[a-zA-Z0-9-]+:kms:[a-zA-Z0-9-]+:\d{12}:key/[a-f0-9-]+

Required: Yes

Errors

For information about the errors that are common to all actions, see Common Error Types.

ConflictException

This operation attempted to create a resource that already exists.

HTTP Status Code: 409

KmsAccessDeniedException

The operation was denied because either the calling principal lacks the required AWS Key Management Service (AWS KMS) permission on the key, or the key policy does not grant Amazon CloudWatch the permissions it needs to use the key. Verify that the caller has kms:Decrypt permission on the key, and that the key policy grants the CloudWatch service principal the kms:DescribeKey, kms:GenerateDataKey, kms:Encrypt, kms:Decrypt, and kms:ReEncrypt* permissions described in AssociateDatasetKmsKey.

HTTP Status Code: 400

KmsKeyDisabledException

The specified AWS Key Management Service (AWS KMS) key is disabled or pending deletion. Re-enable the key (or restore it, if it is pending deletion) and retry the operation.

HTTP Status Code: 400

KmsKeyNotFoundException

The specified AWS Key Management Service (AWS KMS) key could not be found. Verify that the key Amazon Resource Name (ARN) is correct, that the key exists, and that it is in the same AWS Region as the resource.

HTTP Status Code: 400

ResourceNotFoundException

The named resource does not exist.

HTTP Status Code: 404

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the following: