/Ansible_AWS_EC2_Instance

Ansible playbook to programmatically create a basic AWS EC2 instance with a Linux VM.

MIT LicenseMIT

Ansible AWS EC2 Instance Playbook

Deploy an AWS EC2 instance of a Linux VM. You may complete everything below within the AWS Free Tier. If you have never deployed an AWS EC2 instance, you should first read Deploy an EC2 Instance from the AWS Console to understand the process and the virtual private cloud (VPC) components involved.

Quick Start

  1. Clone this repository:

    git clone https://github.com/1homas/Ansible_AWS_EC2_Instance

  2. Create your Python environment and install Ansible:

    pip install --upgrade pip
pip install pipenv
pipenv install --python 3.9
pipenv install ansible boto boto3 botocore
pipenv shell

    If you have any problems installing Python or Ansible, see Installing Ansible.

  3. Export your AWS Access & Secret keys into your terminal environment:

    export AWS_REGION='us-west-1'
export AWS_ACCESS_KEY='AKIAIOSF/EXAMPLE+KEY'
export AWS_SECRET_KEY='wJalrXUtnFEMI/K7MDENG/bPxRfi/EXAMPLE+KEY'

  4. Run the Ansible playbook:

    ansible-playbook playbook.yaml

  5. SSH to your new running instance:

    ⚠ Replace the {hostname} with the dynamically assigned public IP address!

    ssh -i ./AWS_EC2_Instance_Test.private_key.pem ec2-user@{hostname}

  6. When you're done, you may terminate and remove the instances:

    ansible-playbook terminate.yaml

Create an AWS Identity and Access Management (IAM) User

In order to programmatically interact with resources in your AWS account - using REST APIs with Ansible - you must configure an Identity and Access Management (IAM) User with an API Key. If you have already done this, you may skip it.

  1. In AWS, select Services > Security, Identity, & Compliance > IAM

  2. In the left panel, select Access management > Users

  3. Click on the Add Users button

    1. Username: your_iam_username (example: aws-api)
    2. Access type: ✅ Programmatic access This generates an access key ID and secret access key for the AWS API, CLI, SDK, and other development tools.
    3. Click Next: Permissions
    4. Create a new group named APIs or something similar if you don't have one already then click Next: Tags
    5. You may add tags as key-value pairs or skip it and click Next: Review
    6. Review your settings then click Create User

  4. Copy your Access Key ID, and Secret Access Key into dot-file named with the IAM API Username in your home directory (~/.keys/aws-api.keys) :

    export AWS_REGION='us-west-1'
export AWS_ACCESS_KEY='AKIAIOSF/EXAMPLE+KEY'
export AWS_SECRET_KEY='wJalrXUtnFEMI/K7MDENG/bPxRfi/EXAMPLE+KEY'

    🛑 These credentials allow anyone to provision unlimited AWS resources and have them conveniently billed to your account - be careful about where you store them!

    💡 You may want to encrypt your keys file with Ansible Vault

  5. Once you have saved your credentials, click Close

Using AWS Credentials with Ansible

Every Ansible AWS task requires authentication for programmatic access using your access keys. This must be done in every task of your playbook.

To keep your AWS credentials safe - and keep your playbooks shorter and simpler! - the Ansible AWS Guide explains how you may use shell environment variables to do the same thing.

In your terminal session with Ansible, load the AWS_* environment variables from the ~/.keys/aws-api.keys you created with the command

source ~/.keys/aws-api.keys

The amazon.aws.* and community.aws.* modules will implicitly use the environment variables for programmatic access, eliminating 2-3 lines from every AWS-related task in your playbooks! This is the method used in this repository's playbooks.

  - name: Create SSH Key Pair
    amazon.aws.ec2_key:
      # region: "{{ region }}"
      # aws_access_key: "{{ aws_access_key }}"
      # aws_secret_key: "{{ aws_secret_key }}"
      name: my_public_key
      state: present
    register: create_key

If you would rather explicitly include the region and aws_* keys, you may put them in an Ansible vars YAML file that you include in your playbook for variable substitution. If you do this, be careful about accidentally publishing your unencrypted AWS keys in a public repository or shared directory. To secure your keys, it is recommended that you use Ansible Vault or other strong encryption mechanism to keep your credentials secure.

Resources

License

This repository is licensed under the MIT License.