Wondering what’s next for npm?Check out our public roadmap! »

    TypeScript icon, indicating that this package has built-in type declarations

    2.2.1 • Public • Published

    CDK EC2 Key Pair

    Source Test GitHub Docs

    npm package PyPI package NuGet package

    Downloads npm PyPI NuGet

    AWS CDK L3 construct for managing EC2 Key Pairs.

    CloudFormation doesn't directly support creation of EC2 Key Pairs. This construct provides an easy interface for creating Key Pairs through a custom CloudFormation resource. The private key is stored in AWS Secrets Manager.


    This package has peer dependencies, which need to be installed along in the expected version.

    For TypeScript/NodeJS, add these to your dependencies in package.json:

    • cdk-ec2-key-pair
    • @aws-cdk/aws-ec2
    • @aws-cdk/aws-iam
    • @aws-cdk/aws-kms
    • @aws-cdk/aws-lambda

    For Python, add these to your requirements.txt:

    • cdk-ec2-key-pair
    • aws-cdk.aws-ec2
    • aws-cdk.aws-iam
    • aws-cdk.aws-kms
    • aws-cdk.aws-lambda


    import cdk = require('@aws-cdk/core');
    import ec2 = require('@aws-cdk/aws-ec2');
    import { KeyPair } from 'cdk-ec2-key-pair';
    // Create the Key Pair
    const key = new KeyPair(this, 'A-Key-Pair', {
        name: 'a-key-pair',
        description: 'This is a Key Pair',
        storePublicKey: true, // by default the public key will not be stored in Secrets Manager
    // Grant read access to the private key to a role or user
    // Grant read access to the public key to another role or user
    // Use Key Pair on an EC2 instance
    new ec2.Instance(this, 'An-Instance', {
        keyName: key.name,
        // ...

    The private (and optionally the public) key will be stored in AWS Secrets Manager. The secret names by default are prefixed with ec2-ssh-key/. The private key is suffixed with /private, the public key is suffixed with /public. So in this example they will be stored as ec2-ssh-key/a-key-pair/private and ec2-ssh-key/a-key-pair/public.

    To download the private key via AWS cli you can run:

    aws secretsmanager get-secret-value \
      --secret-id ec2-ssh-key/a-key-pair/private \
      --query SecretString \
      --output text

    Tag support

    The construct supports tagging:

    cdk.Tags.of(key).add('someTag', 'some value');

    We also use tags to restrict update/delete actions to those, the construct created itself. The Lambda function, which backs the custom CFN resource, is not able to manipulate other keys/secrets. The tag we use for identifying these resources is CreatedByCfnCustomResource with value CFN::Resource::Custom::EC2-Key-Pair.


    Since an EC2 KeyPair cannot be updated, you cannot change any property related to the KeyPair. The code has checks in place which will prevent any attempt to do so. If you try, the stack will end in a failed state. In that case you can safely continue the rollback in the AWS console and ignore the key resource.

    You can, however, change properties that only relate to the secrets. These are the KMS keys used for encryption, the secretPrefix, description and removeKeySecretsAfterDays.


    Secrets in the AWS Secrets Manager by default are encrypted with the key alias/aws/secretsmanager.

    To use a custom KMS key you can pass it to the Key Pair:

    const kmsKey = new kms.Key(this, 'KMS-key');
    const keyPair = new KeyPair(this, 'A-Key-Pair', {
        name: 'a-key-pair',
        kms: kmsKey,

    This KMS key needs to be created in the same stack. You cannot use a key imported via ARN, because the keys access policy will need to be modified.

    To use different KMS keys for the private and public key, use the kmsPrivateKey and kmsPublicKey instead:

    const kmsKeyPrivate = new kms.Key(this, 'KMS-key-private');
    const kmsKeyPublic = new kms.Key(this, 'KMS-key-public');
    const keyPair = new KeyPair(this, 'A-Key-Pair', {
        name: 'a-key-pair',
        kmsPrivateKey: kmsKeyPrivate,
        kmsPublicKey: kmsKeyPublic


    npm i cdk-ec2-key-pair

    DownloadsWeekly Downloads






    Unpacked Size

    2.66 MB

    Total Files


    Last publish


    • avatar