Launch EC2 Instance

This is an interactive task that allows the user to configure & launch a new EC2 instance.

An email approval step is included before the instance is launched.

Playbook Files

# The task was built to work with these plugin versions.
plugins:
  aws: ~2.2
  ppa: ~3.2
  ppa_tools: ~3.4
  hashicorp_vault: ~4


set:
  # The user will be asked to supply values for each tag defined in this list.
  tag_names:
    - environment
    - team
  # The supplied values are added to this dictionary.
  tag_values: {}

  # The following region & AMI ID are for Amazon Linux 2 in London, but you can change both to match what you need.
  ami_id: ami-0a669382ea0feb73a
  ec2_region: eu-west-2

  # This is the approval email HTML template.
  approval_template: >
    <html>
      <head>
          <p style="text-align:center;">
              {icon}
          </p>
          <br/>
      </head>

      <body>
          <p style="text-align: center; font-weight: bold; font-size: 20;">
            New EC2 Instance Request
          </p>

          <p style="text-align:center; font-size: 19;">
            <strong>AMI ID:</strong> {ami_id}
          </p>

          <p style="text-align:center; font-size: 19;">
            <strong>Region:</strong> {region}
          </p>

          <p style="text-align:center; font-size: 19;">
            <strong>Instance Name:</strong> {instance_name}
          </p>

          <p style="text-align:center; font-size: 19;">
            <strong>Instance Type:</strong> {instance_type}
          </p>
          </p>

          <p style="text-align:center; font-size: 19;">
            <strong>Key Pair:</strong> {key_pair}
          </p>

          <p style="text-align:center; font-size: 19;">
            <strong>Tags:</strong>
          </p>

          <div style="margin: auto;">
            {tag_display}
          </div>

          <p style="text-align: center; font-size: 19;">
              Please click <a style="color: green; font-weight: bold; text-decoration: none;" href="{approve_url}">approve</a> or <a style='color: red; font-weight: bold; text-decoration: none;' href='{reject_url}'>reject</a> to respond.
          </p>

          <footer>
            <br/>
            <br/>
            <p style="text-align:center;font-weight:lighter;font-size:10;">
              Email generated and delivered by Osirium PPA.
            </p>
          </footer>

      </body>
    </html>


steps:

  - name: Greeting
    actions:

      - ppa.ui.output_markdown:
          doc: >
            {{ globals.icons.aws.full }}


            #### EC2 - Launch Amazon Linux Instance


            Use this task to launch a new Amazon Linux EC2 instance.


            You will need to:


            - Supply a name for the instance

            - Choose the instance type

            - Select a key pair

            - Provide values for any required tags


            __Note:__ You will be asked to supply an email address for the approval process.


      - ppa.ui.input_accept:
          text: Start


  - name: Get AWS Secrets
    actions:

      - hashicorp_vault.key_value.read_secret_keys:
          secret: aws
          keys:
            - aws_access_key_id
          sensitive_keys:
            - aws_secret_access_key
          create_missing: true
          reason: Getting AWS connection details
        save: aws_client


  - name: Choose Type & Key Pair
    actions:

      - aws.ec2.instance_types.get_all:
        load:
          region_name: ec2_region
          aws_client: aws_client
        save: instance_types

      - aws.ec2.instance_types.input_table:
          text: Select an Instance Type
          minimum: 1
          maximum: 1
        load:
          types: instance_types
        save: selected_instance_types

      - ppa_tools.lists.get_first_item:
        load:
          items: selected_instance_types
        save: instance_type

      - ppa.ui.input_text:
          text: Instance Name
          required: true
        save: instance_name

      - aws.ec2.key_pairs.get_all:
        load:
          region_name: ec2_region
          aws_client: aws_client
        save: all_key_pairs

      - aws.ec2.key_pairs.input_table:
          text: Select a key pair
          minimum: 1
          maximum: 1
        load:
          key_pairs: all_key_pairs
        save: key_pair

      - ppa_tools.lists.get_first_item:
        load:
          items: key_pair
        save: key_pair


  - name: Supply Tags
    sequence: tag_names
    actions:

      - ppa.ui.input_text:
          text: Supply a value for tag '{{loop.step.item.value }}' ({{ loop.step.item.index + 1 }} of {{ tag_names | length }})
          required: true
        save: tag_value

      - ppa_tools.dictionaries.insert:
        load:
          name: loop.step.item.value
          value: tag_value
          dictionary: tag_values
        save: tag_values


  - name: Confirm Changes
    actions:

      - ppa.ui.output_markdown:
          doc: >
            ### New Instance Details


            __AMI:__ Amazon Linux 2


            __Name:__ {{ instance_name }}


            __Region:__ {{ ec2_region }}


            __Type:__ {{ instance_type.name }}


            __Key Pair:__ {{ key_pair.name }}


            __Tags:__

            {% for name, value in tag_values.items() %}

            - {{ name }}: _{{ value }}_

            {% endfor %}

      - ppa.ui.input_confirm:
          text: Please choose an option
          confirm: Submit for Approval
          cancel: Cancel
        save: submit_for_approval


  - name: Exit if Not Submitted
    when: not submit_for_approval
    actions:

      - ppa.ui.output_info:
          text: The new instance will not be created. Goodbye!

      - exit:
          exit_code: 4


  - name: Submit for Approval
    when: submit_for_approval
    actions:

      - ppa.ui.output_progress:
          text: Generating approval request...
          percent: null
          element_id: generating_approval_request

      - ppa.events.create_approval_request:
        save: approval_request

      - format_template:
          key_values:
            ami_id: "{{ ami_id }}"
            icon: "{{ globals.icons.ppa.full }}"
            region: "{{ ec2_region }}"
            instance_name: "{{ instance_name }}"
            instance_type: "{{ instance_type.name }}"
            key_pair: "{{ key_pair.name }}"
            tag_display: >
              {% for name, value in tag_values.items() %}
              <p style="text-align:center; font-size: 17;">
                <strong>{{ name }}:</strong> {{ value }}
              </p>
              {% endfor %}
            approve_url: "{{ approval_request.approve_url }}"
            reject_url: "{{ approval_request.reject_url }}"
        load:
          template: approval_template
        save: formatted_approval_email

      - ppa.ui.output_progress:
          text: Waiting for approval email address...
          percent: null
          element_id: generating_approval_request

      - ppa.ui.input_email:
          text: Approval email address
        save: approval_email_address

      - ppa.ui.output_progress:
          text: Sending approval email...
          percent: null
          element_id: generating_approval_request

      - ppa.events.send_email:
          subject: New EC2 Instance Request
          reason: Sending approval request email
          recipients:
            - "{{ approval_email_address }}"
        load:
          html: formatted_approval_email
        rescue:
          - ppa.ui.output_progress:
              text: Failed to send approval email
              percent: 0
              element_id: generating_approval_request
          - ppa.ui.output_error:
              text: Failed to send email report. SMTP is not configured in PPA.
            when: rescue.type == "EventNotConfigured"
          - exit:
              exit_code: 2
            when: rescue.type == "EventNotConfigured"
          - ppa.ui.output_error:
              text: Failed to send email report. Please view the logs for more information.
          - exit:
              exit_code: 2

      - ppa.ui.output_progress:
          text: Sent approval email
          percent: 100
          element_id: generating_approval_request

      - ppa.events.wait_approval_response:
          text: Waiting for approval response...
          approved_message: The requested changes will now be applied.
          rejected_message: The requested changes will be cancelled.
        load:
          approval_request: approval_request
        save: approval_response


  - name: Exit if Request Rejected
    when: not approval_response.approved
    actions:

      - ppa.ui.output_error:
          text: The request was rejected by {{ approval_response.responder }}.

      - exit:
          exit_code: 3


  - name: Launch Instance
    actions:

      - ppa.ui.output_progress:
          text: Launching new instance...
          percent: null
          element_id: launching_instance

      - aws.ec2.instances.launch:
        load:
          instance_type: instance_type.name
          image_id: ami_id
          name: instance_name
          region_name: ec2_region
          aws_client: aws_client
          key_name: key_pair.name
        save: new_instance

      - ppa.ui.output_progress:
          text: Tagging new instance...
          percent: null
          element_id: launching_instance

      - aws.ec2.instances.tag:
        load:
          tags: tag_values
          instance_id: new_instance.instance_id
          region_name: ec2_region
          aws_client: aws_client

      - ppa.ui.output_progress:
          text: New instance has been launched & tagged
          percent: 100
          element_id: launching_instance


  - name: Summary
    actions:

      - ppa.ui.output_progress:
          text: Getting new instance...
          percent: null
          element_id: getting_new_instance

      - aws.ec2.instances.get_by_id:
        load:
          instance_id: new_instance.instance_id
          region_name: ec2_region
          aws_client: aws_client
        save: new_tagged_instance

      - ppa.ui.output_progress:
          text: Got new instance
          percent: 100
          element_id: getting_new_instance

      - aws.ec2.instances.output_table:
          text: New instance
        load:
          instances: new_tagged_instance

      - ppa.ui.output_info:
          text: All operations completed succesfully.

      - ppa.ui.input_accept:
          text: Done

Running this Playbook

Click download playbook
Import the downloaded file via the Playbooks page on PPA
Build the playbook from the Edit & Build tab
Run the playbook from the Preview & Deploy tab

* Requires PPA v2.9.x or newer

Integrations

PPA User Interface & Events
Hashicorp Vault Key-Value engine
AWS EC2 Instances, Instance Types, & Key Pairs

Email Configuration

This task contains an email approval step that requires SMTP to be configured in the PPA appliance.

Instance AMI & Region

By default the playbook is configured to use the Amazon Linux AMI in the London (eu-west-2) region.

You can change both the AMI ID & EC2 region on lines 17 & 18 of the playbook.

Instance Tags

A default list of tags is included in the playbook on line 10.

The user will be asked to supply a value for each tag.

You can change this list to suit your use case.

Required Vault Details

AWS

Access key ID
Secret access key

The key must have permissions to:

Read instances & instance types
Read key pairs
Launch instances

Vault Configuration Wizard

The first time you run a task built from this playbook, PPA will check the required Vault details exist.

If they don't exist, PPA will ask you to supply the details at the start of the task.

Below you can see a user providing details the first time they run an Active Directory task.

vault-config-wizard

Once the details are added to Vault, the task won't ask for them again.

If you don't know the required details, ask an administrator to run the task or configure Vault manually.

What the Task Does

Once started this task will:

Ask the user to select an instance type
Prompt the user for an instance name
Ask the user to select a key pair
Prompt for a value for each instance tag specified in tag_names (line 10)
Present the new instance configuration & ask the user to confirm or cancel
Prompt for an approval email address (see below for more information)
Launch the new instance if the request was approved

Approval Request

This task requires email approval before the instance is launched.

For demo purposes the task will ask the user for an email address to send the approval request to.

In production this should be changed to an alternative method, such as…

Configuring a list of approvers in the playbook
Looking up the user's manager in Active Directory (via the manager attribute)
Sending the approval email to members of an Active Directory security group
Using a private Slack channel

… or many others.

See our other playbooks

Get PPA for free!

Start automating your estate with a free 30 day trial today. No signup required!

Get PPA Express

Documentation

Installation Guide
See how easy it is to get started with our installation guide
Playbooks
View our task writing reference guide
Plugins
See how to integrate with different systems using our plugins reference guide.