1.204.0

class Alias (construct)

LanguageType name
.NETAmazon.CDK.AWS.KMS.Alias
Javasoftware.amazon.awscdk.services.kms.Alias
Pythonaws_cdk.aws_kms.Alias
TypeScript (source)@aws-cdk/aws-kms » Alias

Implements IConstruct, IConstruct, IDependable, IResource, IAlias, IKey

Defines a display name for a customer master key (CMK) in AWS Key Management Service (AWS KMS).

Using an alias to refer to a key can help you simplify key management. For example, when rotating keys, you can just update the alias mapping instead of tracking and changing key IDs. For more information, see Working with Aliases in the AWS Key Management Service Developer Guide.

You can also add an alias for a key by calling key.addAlias(alias).

Example

// Passing an encrypted replication bucket created in a different stack.
const app = new App();
const replicationStack = new Stack(app, 'ReplicationStack', {
  env: {
    region: 'us-west-1',
  },
});
const key = new kms.Key(replicationStack, 'ReplicationKey');
const alias = new kms.Alias(replicationStack, 'ReplicationAlias', {
  // aliasName is required
  aliasName: PhysicalName.GENERATE_IF_NEEDED,
  targetKey: key,
});
const replicationBucket = new s3.Bucket(replicationStack, 'ReplicationBucket', {
  bucketName: PhysicalName.GENERATE_IF_NEEDED,
  encryptionKey: alias,
});

Initializer

new Alias(scope: Construct, id: string, props: AliasProps)

Parameters

Construct Props

NameTypeDescription
aliasNamestringThe name of the alias.
targetKeyIKeyThe ID of the key for which you are creating the alias.
removalPolicy?RemovalPolicyPolicy to apply when the alias is removed from this stack.

aliasName

Type: string

The name of the alias.

The name must start with alias followed by a forward slash, such as alias/. You can't specify aliases that begin with alias/AWS. These aliases are reserved.

targetKey

Type: IKey

The ID of the key for which you are creating the alias.

Specify the key's globally unique identifier or Amazon Resource Name (ARN). You can't specify another alias.

removalPolicy?

Type: RemovalPolicy (optional, default: The alias will be deleted)

Policy to apply when the alias is removed from this stack.

Properties

NameTypeDescription
aliasNamestringThe name of the alias.
aliasTargetKeyIKeyThe Key to which the Alias refers.
envResourceEnvironmentThe environment this resource belongs to.
keyArnstringThe ARN of the key.
keyIdstringThe ID of the key (the part that looks something like: 1234abcd-12ab-34cd-56ef-1234567890ab).
nodeConstructNodeThe construct tree node associated with this construct.
stackStackThe stack in which this resource is defined.

aliasName

Type: string

The name of the alias.

aliasTargetKey

Type: IKey

The Key to which the Alias refers.

env

Type: ResourceEnvironment

The environment this resource belongs to.

For resources that are created and managed by the CDK (generally, those created by creating new class instances like Role, Bucket, etc.), this is always the same as the environment of the stack they belong to; however, for imported resources (those obtained from static methods like fromRoleArn, fromBucketName, etc.), that might be different than the stack they were imported into.

keyArn

Type: string

The ARN of the key.

keyId

Type: string

The ID of the key (the part that looks something like: 1234abcd-12ab-34cd-56ef-1234567890ab).

node

Type: ConstructNode

The construct tree node associated with this construct.

stack

Type: Stack

The stack in which this resource is defined.

Methods

NameDescription
addAlias(alias)Defines a new alias for the key.
addToResourcePolicy(statement, allowNoOp?)Adds a statement to the KMS key resource policy.
applyRemovalPolicy(policy)Apply the given removal policy to this resource.
grant(grantee, ...actions)Grant the indicated permissions on this key to the given principal.
grantDecrypt(grantee)Grant decryption permissions using this key to the given principal.
grantEncrypt(grantee)Grant encryption permissions using this key to the given principal.
grantEncryptDecrypt(grantee)Grant encryption and decryption permissions using this key to the given principal.
toString()Returns a string representation of this construct.
protected generatePhysicalName()
static fromAliasAttributes(scope, id, attrs)Import an existing KMS Alias defined outside the CDK app.
static fromAliasName(scope, id, aliasName)Import an existing KMS Alias defined outside the CDK app, by the alias name.

addAlias(alias)

public addAlias(alias: string): Alias

Parameters

  • alias string

Returns

Defines a new alias for the key.

addToResourcePolicy(statement, allowNoOp?)

public addToResourcePolicy(statement: PolicyStatement, allowNoOp?: boolean): AddToResourcePolicyResult

Parameters

Returns

Adds a statement to the KMS key resource policy.

applyRemovalPolicy(policy)

public applyRemovalPolicy(policy: RemovalPolicy): void

Parameters

Apply the given removal policy to this resource.

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).

grant(grantee, ...actions)

public grant(grantee: IGrantable, ...actions: string[]): Grant

Parameters

Returns

Grant the indicated permissions on this key to the given principal.

grantDecrypt(grantee)

public grantDecrypt(grantee: IGrantable): Grant

Parameters

Returns

Grant decryption permissions using this key to the given principal.

grantEncrypt(grantee)

public grantEncrypt(grantee: IGrantable): Grant

Parameters

Returns

Grant encryption permissions using this key to the given principal.

grantEncryptDecrypt(grantee)

public grantEncryptDecrypt(grantee: IGrantable): Grant

Parameters

Returns

Grant encryption and decryption permissions using this key to the given principal.

toString()

public toString(): string

Returns

  • string

Returns a string representation of this construct.

protected generatePhysicalName()

protected generatePhysicalName(): string

Returns

  • string

static fromAliasAttributes(scope, id, attrs)

public static fromAliasAttributes(scope: Construct, id: string, attrs: AliasAttributes): IAlias

Parameters

  • scope Construct — The parent creating construct (usually this).
  • id string — The construct's name.
  • attrs AliasAttributes — the properties of the referenced KMS Alias.

Returns

Import an existing KMS Alias defined outside the CDK app.

static fromAliasName(scope, id, aliasName)

public static fromAliasName(scope: Construct, id: string, aliasName: string): IAlias

Parameters

  • scope Construct — The parent creating construct (usually this).
  • id string — The construct's name.
  • aliasName string — The full name of the KMS Alias (e.g., 'alias/aws/s3', 'alias/myKeyAlias').

Returns

Import an existing KMS Alias defined outside the CDK app, by the alias name.

This method should be used instead of 'fromAliasAttributes' when the underlying KMS Key ARN is not available. This Alias will not have a direct reference to the KMS Key, so addAlias and grant* methods are not supported.

← PreviousNext →