class CfnReplicaKey (construct)
Language | Type name |
---|---|
![]() | Amazon.CDK.AWS.KMS.CfnReplicaKey |
![]() | github.com/aws/aws-cdk-go/awscdk/v2/awskms#CfnReplicaKey |
![]() | software.amazon.awscdk.services.kms.CfnReplicaKey |
![]() | aws_cdk.aws_kms.CfnReplicaKey |
![]() | aws-cdk-lib » aws_kms » CfnReplicaKey |
Implements
IConstruct
, IDependable
, IInspectable
, ITaggable
The AWS::KMS::ReplicaKey
resource specifies a multi-Region replica key that is based on a multi-Region primary key.
Multi-Region keys are an AWS KMS feature that lets you create multiple interoperable KMS keys in different AWS Regions . Because these KMS keys have the same key ID, key material, and other metadata, you can use them to encrypt data in one AWS Region and decrypt it in a different AWS Region without making a cross-Region call or exposing the plaintext data. For more information, see Multi-Region keys in the AWS Key Management Service Developer Guide .
A multi-Region primary key is a fully functional symmetric encryption KMS key, HMAC KMS key, or asymmetric KMS key that is also the model for replica keys in other AWS Regions . To create a multi-Region primary key, add an AWS::KMS::Key resource to your CloudFormation stack. Set its MultiRegion
property to true.
A multi-Region replica key is a fully functional KMS key that has the same key ID and key material as a multi-Region primary key, but is located in a different AWS Region of the same AWS partition. There can be multiple replicas of a primary key, but each must be in a different AWS Region .
When you create a replica key in AWS CloudFormation , the replica key is created in the AWS Region represented by the endpoint you use for the request. If you try to replicate a multi-Region key into a Region in which the key type is not supported, the request will fail.
A primary key and its replicas have the same key ID and key material. They also have the same key spec, key usage, key material origin, and automatic key rotation status. These properties are known as shared properties . If they change, AWS KMS synchronizes the change to all related multi-Region keys. All other properties of a replica key can differ, including its key policy, tags, aliases, and key state. AWS KMS does not synchronize these properties.
Regions
AWS KMS CloudFormation resources are available in all AWS Regions in which AWS KMS and AWS CloudFormation are supported. You can use the AWS::KMS::ReplicaKey
resource to create replica keys in all Regions that support multi-Region KMS keys. For details, see Multi-Region keys in AWS KMS in the ** .
See also: http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-kms-replicakey.html
Example
// The code below shows an example of how to instantiate this type.
// The values are placeholders you should change.
import { aws_kms as kms } from 'aws-cdk-lib';
declare const keyPolicy: any;
const cfnReplicaKey = new kms.CfnReplicaKey(this, 'MyCfnReplicaKey', {
keyPolicy: keyPolicy,
primaryKeyArn: 'primaryKeyArn',
// the properties below are optional
description: 'description',
enabled: false,
pendingWindowInDays: 123,
tags: [{
key: 'key',
value: 'value',
}],
});
Initializer
new CfnReplicaKey(scope: Construct, id: string, props: CfnReplicaKeyProps)
Parameters
- scope
Construct
— Scope in which this resource is defined. - id
string
— Construct identifier for this resource (unique in its scope). - props
Cfn
— Resource properties.Replica Key Props
Construct Props
Name | Type | Description |
---|---|---|
key | any | The key policy that authorizes use of the replica key. |
primary | string | Specifies the multi-Region primary key to replicate. |
description? | string | A description of the KMS key. |
enabled? | boolean | IResolvable | Specifies whether the replica key is enabled. Disabled KMS keys cannot be used in cryptographic operations. |
pending | number | Specifies the number of days in the waiting period before AWS KMS deletes a replica key that has been removed from a CloudFormation stack. |
tags? | Cfn [] | Assigns one or more tags to the replica key. |
keyPolicy
Type:
any
The key policy that authorizes use of the replica key.
The key policy is not a shared property of multi-Region keys. You can specify the same key policy or a different key policy for each key in a set of related multi-Region keys. AWS KMS does not synchronize this property.
The key policy must conform to the following rules.
- The key policy must give the caller PutKeyPolicy permission on the KMS key. This reduces the risk that the KMS key becomes unmanageable. For more information, refer to the scenario in the Default key policy section of the AWS Key Management Service Developer Guide .
- Each statement in the key policy must contain one or more principals. The principals in the key policy must exist and be visible to AWS KMS . When you create a new AWS principal (for example, an IAM user or role), you might need to enforce a delay before including the new principal in a key policy because the new principal might not be immediately visible to AWS KMS . For more information, see Changes that I make are not always immediately visible in the AWS Identity and Access Management User Guide .
A key policy document can include only the following characters:
- Printable ASCII characters from the space character (
\u0020
) through the end of the ASCII character range. - Printable characters in the Basic Latin and Latin-1 Supplement character set (through
\u00FF
). - The tab (
\u0009
), line feed (\u000A
), and carriage return (\u000D
) special characters
Minimum : 1
Maximum : 32768
primaryKeyArn
Type:
string
Specifies the multi-Region primary key to replicate.
The primary key must be in a different AWS Region of the same AWS partition. You can create only one replica of a given primary key in each AWS Region .
If you change the
PrimaryKeyArn
value of a replica key, the existing replica key is scheduled for deletion and a new replica key is created based on the specified primary key. While it is scheduled for deletion, the existing replica key becomes unusable. You can cancel the scheduled deletion of the key outside of CloudFormation.However, if you inadvertently delete a replica key, you can decrypt ciphertext encrypted by that replica key by using any related multi-Region key. If necessary, you can recreate the replica in the same Region after the previous one is completely deleted. For details, see Deleting multi-Region keys in the AWS Key Management Service Developer Guide
Specify the key ARN of an existing multi-Region primary key. For example, arn:aws:kms:us-east-2:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab
.
description?
Type:
string
(optional)
A description of the KMS key.
The default value is an empty string (no description).
The description is not a shared property of multi-Region keys. You can specify the same description or a different description for each key in a set of related multi-Region keys. AWS Key Management Service does not synchronize this property.
enabled?
Type:
boolean |
IResolvable
(optional)
Specifies whether the replica key is enabled. Disabled KMS keys cannot be used in cryptographic operations.
When Enabled
is true
, the key state of the KMS key is Enabled
. When Enabled
is false
, the key state of the KMS key is Disabled
. The default value is true
.
The actual key state of the replica might be affected by actions taken outside of CloudFormation, such as running the EnableKey , DisableKey , or ScheduleKeyDeletion operations. Also, while the replica key is being created, its key state is Creating
. When the process is complete, the key state of the replica key changes to Enabled
.
For information about the key states of a KMS key, see Key state: Effect on your KMS key in the AWS Key Management Service Developer Guide .
pendingWindowInDays?
Type:
number
(optional)
Specifies the number of days in the waiting period before AWS KMS deletes a replica key that has been removed from a CloudFormation stack.
Enter a value between 7 and 30 days. The default value is 30 days.
When you remove a replica key from a CloudFormation stack, AWS KMS schedules the replica key for deletion and starts the mandatory waiting period. The PendingWindowInDays
property determines the length of waiting period. During the waiting period, the key state of replica key is Pending Deletion
, which prevents it from being used in cryptographic operations. When the waiting period expires, AWS KMS permanently deletes the replica key.
If the KMS key is a multi-Region primary key with replica keys, the waiting period begins when the last of its replica keys is deleted. Otherwise, the waiting period begins immediately.
You cannot use a CloudFormation template to cancel deletion of the replica after you remove it from the stack, regardless of the waiting period. However, if you specify a replica key in your template that is based on the same primary key as the original replica key, CloudFormation creates a new replica key with the same key ID, key material, and other shared properties of the original replica key. This new replica key can decrypt ciphertext that was encrypted under the original replica key, or any related multi-Region key.
For detailed information about deleting multi-Region keys, see Deleting multi-Region keys in the AWS Key Management Service Developer Guide .
For information about the PendingDeletion
key state, see Key state: Effect on your KMS key in the AWS Key Management Service Developer Guide . For more information about deleting KMS keys, see the ScheduleKeyDeletion operation in the AWS Key Management Service API Reference and Deleting KMS keys in the AWS Key Management Service Developer Guide .
tags?
Type:
Cfn
[]
(optional)
Assigns one or more tags to the replica key.
Tagging or untagging a KMS key can allow or deny permission to the KMS key. For details, see ABAC for AWS KMS in the AWS Key Management Service Developer Guide .
Tags are not a shared property of multi-Region keys. You can specify the same tags or different tags for each key in a set of related multi-Region keys. AWS KMS does not synchronize this property.
Each tag consists of a tag key and a tag value. Both the tag key and the tag value are required, but the tag value can be an empty (null) string. You cannot have more than one tag on a KMS key with the same tag key. If you specify an existing tag key with a different tag value, AWS KMS replaces the current tag value with the specified one.
When you assign tags to an AWS resource, AWS generates a cost allocation report with usage and costs aggregated by tags. Tags can also be used to control access to a KMS key. For details, see Tagging keys .
Properties
Name | Type | Description |
---|---|---|
attr | string | The Amazon Resource Name (ARN) of the replica key, such as arn:aws:kms:us-west-2:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab . |
attr | string | The key ID of the replica key, such as mrk-1234abcd12ab34cd56ef1234567890ab . |
cfn | ICfn | Options for this resource, such as condition, update policy etc. |
cfn | { [string]: any } | |
cfn | string | AWS resource type. |
creation | string[] | |
key | any | The key policy that authorizes use of the replica key. |
logical | string | The logical ID for this CloudFormation stack element. |
node | Node | The tree node. |
primary | string | Specifies the multi-Region primary key to replicate. |
ref | string | Return a string that will be resolved to a CloudFormation { Ref } for this element. |
stack | Stack | The stack in which this element is defined. |
tags | Tag | Tag Manager which manages the tags for this resource. |
description? | string | A description of the KMS key. |
enabled? | boolean | IResolvable | Specifies whether the replica key is enabled. |
pending | number | Specifies the number of days in the waiting period before AWS KMS deletes a replica key that has been removed from a CloudFormation stack. |
tags | Cfn [] | Assigns one or more tags to the replica key. |
static CFN_RESOURCE_TYPE_NAME | string | The CloudFormation resource type name for this resource class. |
attrArn
Type:
string
The Amazon Resource Name (ARN) of the replica key, such as arn:aws:kms:us-west-2:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab
.
The key ARNs of related multi-Region keys differ only in the Region value. For information about the key ARNs of multi-Region keys, see How multi-Region keys work in the AWS Key Management Service Developer Guide .
attrKeyId
Type:
string
The key ID of the replica key, such as mrk-1234abcd12ab34cd56ef1234567890ab
.
Related multi-Region keys have the same key ID. For information about the key IDs of multi-Region keys, see How multi-Region keys work in the AWS Key Management Service Developer Guide .
cfnOptions
Type:
ICfn
Options for this resource, such as condition, update policy etc.
cfnProperties
Type:
{ [string]: any }
cfnResourceType
Type:
string
AWS resource type.
creationStack
Type:
string[]
keyPolicy
Type:
any
The key policy that authorizes use of the replica key.
logicalId
Type:
string
The logical ID for this CloudFormation stack element.
The logical ID of the element is calculated from the path of the resource node in the construct tree.
To override this value, use overrideLogicalId(newLogicalId)
.
node
Type:
Node
The tree node.
primaryKeyArn
Type:
string
Specifies the multi-Region primary key to replicate.
ref
Type:
string
Return a string that will be resolved to a CloudFormation { Ref }
for this element.
If, by any chance, the intrinsic reference of a resource is not a string, you could
coerce it to an IResolvable through Lazy.any({ produce: resource.ref })
.
stack
Type:
Stack
The stack in which this element is defined.
CfnElements must be defined within a stack scope (directly or indirectly).
tags
Type:
Tag
Tag Manager which manages the tags for this resource.
description?
Type:
string
(optional)
A description of the KMS key.
enabled?
Type:
boolean |
IResolvable
(optional)
Specifies whether the replica key is enabled.
Disabled KMS keys cannot be used in cryptographic operations.
pendingWindowInDays?
Type:
number
(optional)
Specifies the number of days in the waiting period before AWS KMS deletes a replica key that has been removed from a CloudFormation stack.
tagsRaw?
Type:
Cfn
[]
(optional)
Assigns one or more tags to the replica key.
static CFN_RESOURCE_TYPE_NAME
Type:
string
The CloudFormation resource type name for this resource class.
Methods
Name | Description |
---|---|
add | Syntactic sugar for addOverride(path, undefined) . |
add | Indicates that this resource depends on another resource and cannot be provisioned unless the other resource has been successfully provisioned. |
add | Indicates that this resource depends on another resource and cannot be provisioned unless the other resource has been successfully provisioned. |
add | Add a value to the CloudFormation Resource Metadata. |
add | Adds an override to the synthesized CloudFormation resource. |
add | Adds an override that deletes the value of a property from the resource definition. |
add | Adds an override to a resource property. |
apply | Sets the deletion policy of the resource based on the removal policy specified. |
get | Returns a token for an runtime attribute of this resource. |
get | Retrieve a value value from the CloudFormation Resource Metadata. |
inspect(inspector) | Examines the CloudFormation resource and discloses attributes. |
obtain | Retrieves an array of resources this resource depends on. |
obtain | Get a shallow copy of dependencies between this resource and other resources in the same stack. |
override | Overrides the auto-generated logical ID with a specific ID. |
remove | Indicates that this resource no longer depends on another resource. |
replace | Replaces one dependency with another. |
to | Returns a string representation of this construct. |
protected render |
addDeletionOverride(path)
public addDeletionOverride(path: string): void
Parameters
- path
string
— The path of the value to delete.
Syntactic sugar for addOverride(path, undefined)
.
addDependency(target)
public addDependency(target: CfnResource): void
Parameters
- target
Cfn
Resource
Indicates that this resource depends on another resource and cannot be provisioned unless the other resource has been successfully provisioned.
This can be used for resources across stacks (or nested stack) boundaries and the dependency will automatically be transferred to the relevant scope.
addDependsOn(target)
public addDependsOn(target: CfnResource): void
⚠️ Deprecated: use addDependency
Parameters
- target
Cfn
Resource
Indicates that this resource depends on another resource and cannot be provisioned unless the other resource has been successfully provisioned.
addMetadata(key, value)
public addMetadata(key: string, value: any): void
Parameters
- key
string
- value
any
Add a value to the CloudFormation Resource Metadata.
Note that this is a different set of metadata from CDK node metadata; this metadata ends up in the stack template under the resource, whereas CDK node metadata ends up in the Cloud Assembly.](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/metadata-section-structure.html
Note that this is a different set of metadata from CDK node metadata; this metadata ends up in the stack template under the resource, whereas CDK node metadata ends up in the Cloud Assembly.)
addOverride(path, value)
public addOverride(path: string, value: any): void
Parameters
- path
string
— - The path of the property, you can use dot notation to override values in complex types. - value
any
— - The value.
Adds an override to the synthesized CloudFormation resource.
To add a
property override, either use addPropertyOverride
or prefix path
with
"Properties." (i.e. Properties.TopicName
).
If the override is nested, separate each nested level using a dot (.) in the path parameter. If there is an array as part of the nesting, specify the index in the path.
To include a literal .
in the property name, prefix with a \
. In most
programming languages you will need to write this as "\\."
because the
\
itself will need to be escaped.
For example,
cfnResource.addOverride('Properties.GlobalSecondaryIndexes.0.Projection.NonKeyAttributes', ['myattribute']);
cfnResource.addOverride('Properties.GlobalSecondaryIndexes.1.ProjectionType', 'INCLUDE');
would add the overrides
"Properties": {
"GlobalSecondaryIndexes": [
{
"Projection": {
"NonKeyAttributes": [ "myattribute" ]
...
}
...
},
{
"ProjectionType": "INCLUDE"
...
},
]
...
}
The value
argument to addOverride
will not be processed or translated
in any way. Pass raw JSON values in here with the correct capitalization
for CloudFormation. If you pass CDK classes or structs, they will be
rendered with lowercased key names, and CloudFormation will reject the
template.
addPropertyDeletionOverride(propertyPath)
public addPropertyDeletionOverride(propertyPath: string): void
Parameters
- propertyPath
string
— The path to the property.
Adds an override that deletes the value of a property from the resource definition.
addPropertyOverride(propertyPath, value)
public addPropertyOverride(propertyPath: string, value: any): void
Parameters
- propertyPath
string
— The path of the property. - value
any
— The value.
Adds an override to a resource property.
Syntactic sugar for addOverride("Properties.<...>", value)
.
applyRemovalPolicy(policy?, options?)
public applyRemovalPolicy(policy?: RemovalPolicy, options?: RemovalPolicyOptions): void
Parameters
- policy
Removal
Policy - options
Removal
Policy Options
Sets the deletion policy of the resource based on the removal policy specified.
The Removal Policy controls what happens to this resource when it stops being managed by CloudFormation, either because you've removed it from the CDK application or because you've made a change that requires the resource to be replaced.
The resource can be deleted (RemovalPolicy.DESTROY
), or left in your AWS
account for data recovery and cleanup later (RemovalPolicy.RETAIN
). In some
cases, a snapshot can be taken of the resource prior to deletion
(RemovalPolicy.SNAPSHOT
). A list of resources that support this policy
can be found in the following link:
getAtt(attributeName, typeHint?)
public getAtt(attributeName: string, typeHint?: ResolutionTypeHint): Reference
Parameters
- attributeName
string
— The name of the attribute. - typeHint
Resolution
Type Hint
Returns
Returns a token for an runtime attribute of this resource.
Ideally, use generated attribute accessors (e.g. resource.arn
), but this can be used for future compatibility
in case there is no generated attribute.
getMetadata(key)
public getMetadata(key: string): any
Parameters
- key
string
Returns
any
Retrieve a value value from the CloudFormation Resource Metadata.
Note that this is a different set of metadata from CDK node metadata; this metadata ends up in the stack template under the resource, whereas CDK node metadata ends up in the Cloud Assembly.](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/metadata-section-structure.html
Note that this is a different set of metadata from CDK node metadata; this metadata ends up in the stack template under the resource, whereas CDK node metadata ends up in the Cloud Assembly.)
inspect(inspector)
public inspect(inspector: TreeInspector): void
Parameters
- inspector
Tree
— tree inspector to collect and process attributes.Inspector
Examines the CloudFormation resource and discloses attributes.
obtainDependencies()
public obtainDependencies(): Stack | CfnResource[]
Returns
Stack
|
Cfn
Resource []
Retrieves an array of resources this resource depends on.
This assembles dependencies on resources across stacks (including nested stacks) automatically.
obtainResourceDependencies()
public obtainResourceDependencies(): CfnResource[]
Returns
Get a shallow copy of dependencies between this resource and other resources in the same stack.
overrideLogicalId(newLogicalId)
public overrideLogicalId(newLogicalId: string): void
Parameters
- newLogicalId
string
— The new logical ID to use for this stack element.
Overrides the auto-generated logical ID with a specific ID.
removeDependency(target)
public removeDependency(target: CfnResource): void
Parameters
- target
Cfn
Resource
Indicates that this resource no longer depends on another resource.
This can be used for resources across stacks (including nested stacks) and the dependency will automatically be removed from the relevant scope.
replaceDependency(target, newTarget)
public replaceDependency(target: CfnResource, newTarget: CfnResource): void
Parameters
- target
Cfn
— The dependency to replace.Resource - newTarget
Cfn
— The new dependency to add.Resource
Replaces one dependency with another.
toString()
public toString(): string
Returns
string
Returns a string representation of this construct.
protected renderProperties(props)
protected renderProperties(props: { [string]: any }): { [string]: any }
Parameters
- props
{ [string]: any }
Returns
{ [string]: any }