Creating AWS KMS resources with AWS CloudFormation
AWS Key Management Service is integrated with AWS CloudFormation, a service that helps you to model and set up your AWS resources so that you can spend less time creating and managing your resources and infrastructure. You create a template that describes KMS keys and aliases, and AWS CloudFormation provisions and configures those resources for you. For information about AWS KMS support for CloudFormation, see the KMS resource type reference in the AWS CloudFormation User Guide.
When you use AWS CloudFormation, you can reuse your template to set up your AWS KMS resources consistently and repeatedly. Describe your resources once, and then provision the same resources over and over in multiple AWS accounts and Regions.
To provision and configure resources for AWS KMS and other AWS services, you must understand AWS CloudFormation templates. Templates are formatted text files in JSON or YAML. These templates describe the resources that you want to provision in your AWS CloudFormation stacks. If you're unfamiliar with JSON or YAML, you can use AWS CloudFormation Designer to help you get started with AWS CloudFormation templates. For more information, see What is AWS CloudFormation Designer? in the AWS CloudFormation User Guide.
Regions
AWS KMS CloudFormation resources are supported in all Regions in which AWS CloudFormation is supported.
AWS KMS resources in AWS CloudFormation templates
AWS KMS supports the following AWS CloudFormation resources.
-
The
AWS::KMS::Keyresource specifies a KMS key in AWS Key Management Service. You can use this resource to create symmetric encryption KMS keys, asymmetric KMS keys for encryption or signing, and symmetric HMAC KMS keys. You can useAWS::KMS::Keyto create multi-Region primary keys of all supported types. To replicate a multi-Region key, use theAWS::KMS::ReplicaKeyresource. -
AWS::KMS::Aliascreates an alias and associates it with a KMS key. The KMS key can be defined in the template, or created by another mechanism. -
AWS::KMS::ReplicaKeycreates a multi-Region replica key. To create a multi-Region primary key, use theAWS::KMS::Keyresource. You cannot use this resource to replicate multi-Region keys with imported key material. For details about multi-Region keys, see Multi-Region keys in AWS KMS.
Important
If you change the value of the KeyUsage, KeySpec, or
MultiRegion property of an existing KMS key, the existing KMS key is
scheduled for deletion and a new KMS key is created with the specified value.
While scheduled for deletion, the existing KMS key becomes unusable. If you don't cancel the scheduled deletion of the existing KMS key outside of AWS CloudFormation, all data encrypted under the existing KMS key becomes unrecoverable when the KMS key is deleted.
The KMS keys that the template creates are actual resources in your AWS account. Authorized principals can use and manage the KMS keys that the template creates, either by using the template, the AWS KMS console, or the AWS KMS APIs. When you delete a KMS key from your template, the KMS key is scheduled for deletion using a waiting period that you specify in advance.
For example, you can use an AWS CloudFormation template to create a test KMS key with a key policy, key spec, key usage, aliases, and tags you prefer. You can run it through your test suite, review your results, and then use the template to schedule the test key for deletion. Later, you can run the template again to create a test key with the same properties.
Or you can use an AWS CloudFormation template to define a particular KMS key configuration that satisfies your business rules and security standards. Then you can use that template any time you need to create a KMS key. You don't have to worry about misconfigured keys. If your preferred configuration changes, you can use your template to update your KMS keys. For example, the template makes it easy to programmatically enable automatic key rotation on all KMS keys that the template defines.
For more information about AWS KMS resources, including examples, see the KMS resource type reference in the AWS CloudFormation User Guide.
Learn more about AWS CloudFormation
To learn more about AWS CloudFormation, see the following resources:
