Syntax Properties Return values Examples See also

AWS::EC2::KeyPair

Specifies a key pair for an Amazon EC2 instance. The key pair can either be imported or created by Amazon EC2, as follows:

To import an existing key pair, include the PublicKeyMaterial property in the template.
To have Amazon EC2 create a new key pair, omit the PublicKeyMaterial property. When Amazon EC2 creates a new key pair, the private key is saved to an AWS Systems Manager Parameter Store. The name of the Systems Manager parameter follows the format /ec2/keypair/{key_pair_id}. For more information, see AWS Systems Manager Parameter Store in the AWS Systems Manager User Guide.

For more information, see Amazon EC2 key pairs in the Amazon EC2 User Guide.

Syntax

To declare this entity in your AWS CloudFormation template, use the following syntax:

JSON


{
  "Type" : "AWS::EC2::KeyPair",
  "Properties" : {
      "KeyName" : String,
      "KeyType" : String,
      "PublicKeyMaterial" : String,
      "Tags" : [ Tag, ... ]
    }
}

YAML


Type: AWS::EC2::KeyPair
Properties: 
  KeyName: String
  KeyType: String
  PublicKeyMaterial: String
  Tags: 
    - Tag

Properties

KeyName

A unique name for the key pair.

Constraints: Up to 255 ASCII characters

Required: Yes

Type: String

Update requires: Replacement

KeyType

The type of key pair. Note that ED25519 keys are not supported for Windows instances.

If the PublicKeyMaterial property is specified, the KeyType property is ignored, and the key type is inferred from the PublicKeyMaterial value.

Default: rsa

Required: No

Type: String

Allowed values: ed25519 | rsa

Update requires: Replacement

PublicKeyMaterial

The public key material. The PublicKeyMaterial property is used to import a key pair. If this property is not specified, then a new key pair will be created.

Required: No

Type: String

Update requires: No interruption

Tags

The tags to apply to the key pair.

Required: No

Type: List of Tag

Update requires: No interruption

Return values

Ref

When you pass the logical ID of this resource to the intrinsic Ref function, Ref returns the name of the key pair.

For more information about using the Ref function, see Ref.

Fn::GetAtt

KeyFingerprint

If you created the key pair using Amazon EC2:

For RSA key pairs, the key fingerprint is the SHA-1 digest of the DER encoded private key.
For ED25519 key pairs, the key fingerprint is the base64-encoded SHA-256 digest, which is the default for OpenSSH, starting with OpenSSH 6.8.

If you imported the key pair to Amazon EC2:

For RSA key pairs, the key fingerprint is the MD5 public key fingerprint as specified in section 4 of RFC 4716.
For ED25519 key pairs, the key fingerprint is the base64-encoded SHA-256 digest, which is the default for OpenSSH, starting with OpenSSH 6.8.

KeyPairId

The ID of the key pair.

Examples

Create a new key pair when launching an instance

The following example creates an EC2 instance and creates a new key pair. To create a new key pair, omit the PublicKeyMaterial property from the template.

When Amazon EC2 creates a new key pair, the private key is saved to an AWS Systems Manager Parameter Store. The name of the Systems Manager parameter follows the format /ec2/keypair/{key_pair_id}. For more information, see AWS Systems Manager Parameter Store in the AWS Systems Manager User Guide.

To retrieve the private key in plain text

Use the following command to retrieve the private key in plain text from the Parameter Store.

aws ssm get-parameter --name /ec2/keypair/{key_pair_id} --region {region} --with-decryption

JSON


{
    "Resources": {
        "NewKeyPair": {
            "Type": "AWS::EC2::KeyPair",
            "Properties": {
                "KeyName": "MyKeyPair"
            }
        },
        "Ec2Instance": {
            "Type": "AWS::EC2::Instance",
            "Properties": {
                "ImageId": "ami-02b92c281a4d3dc79",
                "KeyName": {
                    "Ref": "NewKeyPair"
                }
            }
        }
    }
}

YAML


Resources:
  NewKeyPair:
    Type: 'AWS::EC2::KeyPair'
    Properties:
      KeyName: MyKeyPair
  Ec2Instance:
    Type: 'AWS::EC2::Instance'
    Properties:
      ImageId: ami-02b92c281a4d3dc79
      KeyName: !Ref NewKeyPair

Import an existing key pair when launching an instance

The following example creates an EC2 instance and imports an existing key pair. To import an existing key pair, include the PublicKeyMaterial property in the template.

JSON


{
    "Resources": {
        "ImportedKeyPair": {
            "Type": "AWS::EC2::KeyPair",
            "Properties": {
                "KeyName": "NameForMyImportedKeyPair",
                "PublicKeyMaterial": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAICfp1F7DhdWZdqkYAUGCzcBsLmJeu9izpIyGpmmg7eCz example"
            }
        },
        "Ec2Instance": {
            "Type": "AWS::EC2::Instance",
            "Properties": {
                "ImageId": "ami-02b92c281a4d3dc79",
                "KeyName": {
                    "Ref": "ImportedKeyPair"
                }
            }
        }
    }
}

YAML


Resources:
  ImportedKeyPair:
    Type: AWS::EC2::KeyPair
    Properties:
      KeyName: NameForMyImportedKeyPair
      PublicKeyMaterial: ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAICfp1F7DhdWZdqkYAUGCzcBsLmJeu9izpIyGpmmg7eCz example
  Ec2Instance: 
    Type: AWS::EC2::Instance
    Properties: 
      ImageId: ami-02b92c281a4d3dc79
      KeyName: 
        Ref: ImportedKeyPair