In order to run an EC2 instance, which is to say an AWS virtual machine, you need to choose which virtual machine to run out of the many thousands available. Each virtual machine snapshot is called an Amazon Machine Image (AMI) and has a unique ID. It's this ID that you will add to your Puppet manifest to tell it what kind of instance to start.

It doesn't matter much for the purposes of this example which AMI you choose, but we'll be using an official Ubuntu image. To find one, follow these steps:

The hexadecimal code in the AMI-ID column, starting ami- is the AMI ID. Make a note of this for later. Click the link to see the AWS instance type selection page, and check that the AMI you've selected has a label saying Free tier eligible; these AMIs do not incur charges. If you start an instance of a non-free-tier AMI, you will be charged for it.

Now we have chosen a suitable AMI, we're ready to create an EC2 instance with Puppet.

Before we can do that, however, we need to make a couple of changes to the AWS settings, so follow these steps:

Once the status of the newly-launched instance has changed from Initializing to Running (you may need to click the refresh button on the AWS console), you can connect to it using SSH and the key file you downloaded earlier.

Congratulations! You've just created your first EC2 instance with Puppet. In the next section, we'll look at the code and examine the resources in detail.

Let's go through the example manifest and see how it works. But first, we need to know something about AWS resources.

An EC2 instance lives inside a subnet, which is a self-contained virtual network. All instances within the subnet can communicate with each other. Subnets are partitions of a Virtual Private Cloud (VPC), which is a private internal network specific to your AWS account.

An instance also has a security group, which is a set of firewall rules governing network access to the instance.

When you create an AWS account, you get a default VPC, divided into subnets for each AWS availability zone (AZ). We are using the default VPC and one of the default subnets for the example instance, but since we also need a security group, we create that first in Puppet code.

The first part of the example manifest creates the required ec2_securitygroup resource (aws_instance.pp):

ec2_securitygroup { 'pbg-sg':
  ensure      =>  present,
  description => 'PBG security group',
  region      => $region,
  vpc         => 'default-vpc',
  ingress     => [
    {
      description => 'SSH access from world',
      protocol    => 'tcp',
      port        => 22,
      cidr        => '0.0.0.0/0',
    },
    {
      description => 'Ping access from world',
      protocol    => 'icmp',
      cidr        => '0.0.0.0/0',
    },
  ],
}

First of all, an ec2_securitygroup has a title (pbg-sg) which we will use to refer to it from other resources (such as the ec2_instance resource). It also has a description, which is just to remind us what it's for.

It is part of a region and a vpc, and has an array of ingress rules. These are your firewall rules. Each firewall port or protocol you want to allow needs a separate ingress rule.

Each ingress rule is a hash like the following:

{
  description => 'SSH access from world',
  protocol    => 'tcp',
  port        => 22,
  cidr        => '0.0.0.0/0',
}

The protocol specifies the type of traffic (tcp, udp, and so on).

The port is the port number to open (22 is the SSH port, which we'll need in order to log in to the instance).

Finally, the cidr key specifies the range of network addresses to allow access to. (0.0.0.0/0 means 'all addresses'.)

The ec2_instance resource, as you'd expect, manages an individual EC2 instance. Here's the relevant section of the example manifest (aws_instance.pp):

ec2_instance { 'pbg-demo':
  ensure                      => present,
  region                      => $region,
  subnet                      => 'default-subnet',
  security_groups             => 'pbg-sg',
  image_id                    => $ami,
  instance_type               => 't1.micro',
  associate_public_ip_address => true,
  key_name                    => 'pbg',
}

First, ensure => present tells AWS that the instance should be running. (You can also use running as a synonym for present.) Setting ensure => absent will terminate and delete the instance (and any ephemeral storage attached to it).

EC2 instances can also be in a third state, stopped. Stopped instances preserve their storage and can be restarted. Because AWS bills by the instance-hour, you don't pay for instances that are stopped, so it's a good idea to stop any instances that don't need to be running right now.

The instance is part of a region and a subnet, and has one or more security_groups.

The image_id attribute tells AWS which AMI ID to use for the instance.

The instance_type attribute selects from AWS's large range of types, which more or less correspond to the computing power of the instance (different types vary in memory size and the number of virtual CPUs, and a few other factors).

As we're inside a private network, instances will not be reachable from the Internet unless we assign them a public IP address. Setting associate_public_ip_address to true enables this feature. (You should set this to false unless the instance actually needs to expose a port to the Internet.)

Finally, the instance has a key_name attribute which tells AWS which SSH key we are going to use to access it. In this case, we're using the key we created earlier in the chapter, named pbg.