How to Create and Import an AWS EC2 Key Pair With Ansible

Updated: 29 September 2026 · Applies to: ansible-core 2.21 with the amazon.aws collection 11.4 and boto3, on Ubuntu, Debian, AlmaLinux and Rocky Linux

An EC2 key pair holds the public SSH key that AWS puts on new instances. Managing it with Ansible means every region and account gets the same key, and you can rotate it with one command. The module is amazon.aws.ec2_key from the amazon.aws collection. We installed ansible-core 2.21.4 and amazon.aws 11.4.0 on Debian 13 and checked the playbook below (with test credentials, the module reached the AWS API and was refused, as expected).

1. Install Ansible, the AWS collection and boto3

Distribution packages are often older than the collection needs, so install everything in a Python virtual environment:

python3 -m venv ~/ansible-venv
~/ansible-venv/bin/pip install ansible-core boto3
~/ansible-venv/bin/ansible-galaxy collection install amazon.aws
export PATH="$HOME/ansible-venv/bin:$PATH"
ansible --version

2. Give Ansible AWS credentials

Use an IAM user or role with permission to manage key pairs (ec2:DescribeKeyPairs, ec2:ImportKeyPair, ec2:CreateKeyPair, ec2:DeleteKeyPair). The modules read the same credentials as the AWS CLI, for example from ~/.aws/credentials or the variables AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY. Do not write keys into the playbook.

3. Create an SSH key and import it

Importing your own public key is safer than letting AWS generate one, because the private key never leaves your computer:

ssh-keygen -t ed25519 -f ~/.ssh/aws_deploy

Save this as ec2-key.yml:

---
- name: Manage the EC2 key pair
  hosts: localhost
  connection: local
  gather_facts: false
  vars:
    aws_region: eu-west-2
    key_name: deploy-key
    public_key_file: "~/.ssh/aws_deploy.pub"
  tasks:
    - name: Import my public key as an EC2 key pair
      amazon.aws.ec2_key:
        name: "{{ key_name }}"
        key_material: "{{ lookup('file', public_key_file) }}"
        region: "{{ aws_region }}"
        state: present
      register: keypair

    - name: Show the fingerprint AWS stored
      ansible.builtin.debug:
        msg: "{{ keypair.key.fingerprint }}"

ansible-playbook --syntax-check ec2-key.yml
ansible-playbook ec2-key.yml

Run it again and nothing changes: Ansible reports ok instead of changed. Loop over a list of regions to create the same key pair everywhere.

Other tasks

• Let AWS generate the key: leave out key_material. AWS returns the private key only once. Save it with file_name: /path/to/key.pem (the key is then left out of the task result), or add no_log: true so it does not appear in the output.
• Key type: key_type: ed25519 for generated keys. AWS does not support ED25519 keys for Windows instances, EC2 Instance Connect or the EC2 serial console.
• Remove a key pair: state: absent. This does not remove the key from instances that already use it.
• Existing key pairs: by default (force: true) a key pair with the same name but a different key is replaced. Set force: false to never overwrite an existing key pair.

Official documentation: amazon.aws.ec2_key module and Amazon EC2 key pairs.