Creating Amazon KMS resources with Amazon CloudFormation - Amazon Key Management Service
Amazon KMS resources in Amazon CloudFormation templatesLearn more about Amazon CloudFormation
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

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.

  • The AWS::KMS::Key resource specifies a KMS key in Amazon 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 use AWS::KMS::Key to create multi-Region primary keys of all supported types. To replicate a multi-Region key, use the AWS::KMS::ReplicaKey resource.

  • AWS::KMS::Alias creates 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::ReplicaKey creates a multi-Region replica key. To create a multi-Region primary key, use the AWS::KMS::Key resource. 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: