Creating Amazon KMS resources with Amazon CloudFormation
Amazon Key Management Service is integrated with Amazon CloudFormation, a service that helps you to model and set up your Amazon 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 Amazon CloudFormation provisions and configures those resources for you. For information about Amazon KMS support for CloudFormation, see the KMS resource type reference in the Amazon CloudFormation User Guide.
When you use Amazon CloudFormation, you can reuse your template to set up your Amazon KMS resources consistently and repeatedly. Describe your resources once, and then provision the same resources over and over in multiple Amazon Web Services accounts and Regions.
To provision and configure resources for Amazon KMS and other Amazon services, you must understand Amazon CloudFormation templates. Templates are formatted text files in JSON or YAML. These templates describe the resources that you want to provision in your Amazon CloudFormation stacks. If you're unfamiliar with JSON or YAML, you can use Amazon CloudFormation Designer to help you get started with Amazon CloudFormation templates. For more information, see What is Amazon CloudFormation Designer? in the Amazon CloudFormation User Guide.
Regions
Amazon KMS CloudFormation resources are supported in all Regions in which Amazon CloudFormation is supported.
Amazon KMS resources in Amazon CloudFormation templates
Amazon KMS supports the following Amazon CloudFormation resources.
-
AWS::KMS::Keycreates a symmetric or asymmetric KMS key. You can use this resource to create a symmetric or asymmetric multi-Region primary KMS key. To create a multi-Region replica key use theAWS::KMS::ReplicaKeyresource. You cannot use this resource to create KMS keys with imported key material or KMS keys in a custom key store. -
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 Amazon 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 Amazon 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 Amazon Web Services account. Authorized principals can use and manage the KMS keys that the template creates, either by using the template, the Amazon KMS console, or the Amazon 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 Amazon 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 Amazon 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 Amazon KMS resources, including examples, see the KMS resource type reference in the Amazon CloudFormation User Guide.
Learn more about Amazon CloudFormation
To learn more about Amazon CloudFormation, see the following resources: