Molecule Plugins

Molecule EC2 can use existing security groups or create new ones using the amazon.aws.ec2_group plugin.

• Use existing groups: Provide a list of names in the security_groups option.
• Create a new group: Provide security_group_name and security_group_description. Note that specifying a name will cause a new group to be created with that name, replacing any existing group of that name.

Customizing rules: Use security_group_rules (ingress) and security_group_rules_egress (egress) to define rules. If no rules are specified and a new group is created, the default behavior is to allow incoming SSH and ICMP, and all outgoing traffic.

Rule parameters (passed to ec2_group):

• proto: Protocol (e.g., tcp, udp, all).
• from_port / to_port: Port range.
• cidr_ip / cidr_ipv6: IP ranges.
• group_name: For referencing other groups.
• rule_desc: Description of the rule.

platforms:
  - name: debian_specify_sg
    image: ami-0f31df35880686b3f
    region: us-east-1
    security_group_name: mole-whacked
    security_group_description: Trying harder than we've tried before
    security_group_rules:
      - proto: all
        group_name: vpn
        rule_desc: only allow access from the VPN
    security_group_rules_egress:
      - proto: tcp
        from_port: 80
        to_port: 80
        cidr_ip: "0.0.0.0/0"
        rule_desc: only allow old school web browsing

You can specify an AMI for your Molecule EC2 platform in two ways:

1. Directly: Set the image parameter with a specific AMI ID.
2. Indirectly: Use discovery parameters to find an AMI via amazon.aws.ec2_ami_info.

When using indirect search, you can use:

• image_owner: Select by owner.
• image_name: Create a filter by name.
• image_filters: A dictionary of key/value pairs to filter by. If image_name is also set, the name filter is added to these filters.

If multiple images match, the one with the newest creation_date is selected.

platforms:
  - name: debian10
    image: ami-0f31df35880686b3f
    region: us-east-1
  - name: ubuntu1804
    image_owner: 099720109477
    image_name: ubuntu/images/hvm-ssd/ubuntu-bionic-18.04-amd64-server-*
  - name: kali
    image_owner: aws-marketplace
    image_filters:
      product-code: 89bab4k3h9x4rkojcm2tj8j4l
  - name: RHEL8
    image_owner: 309956199498
    image_name: RHEL-8*
    image_filters:
      architecture: arm64
      virtualization-type: hvm
    instance_type: t4g.small

You can control which VPC and Subnet the EC2 instance is created in using several methods:

VPC Selection

• Direct: Set vpc_id.
• Indirect (Subnet): Set vpc_subnet_id (this implicitly selects the VPC).
• Filters: Use vpc_filters (a dictionary) to select a VPC via amazon.aws.ec2_vpc_net_info.

Subnet Selection

• Direct: Set vpc_subnet_id.
• Filters: Use subnet_filters (a dictionary) to select a subnet via amazon.aws.ec2_vpc_subnet_info.

Note: If multiple VPCs or subnets match your criteria, the first one returned is chosen (order is not guaranteed). If vpc_id is specified, it will be used to filter subnet selection if subnet_filters are also provided.

platforms:
  - name: specify_vpc
    image: ami-0f31df35880686b3f
    region: us-east-1
    vpc_id: vpc-3f64b58
  - name: specify_subnet
    image: ami-0f31df35880686b3f
    region: us-east-1
    vpc_subnet_id: subnet-a18bfcc6
  - name: filter_vpc
    image: ami-0f31df35880686b3f
    region: us-east-1
    vpc_filters:
      "tag:Name": test_ground

Molecule EC2 supports two methods for handling SSH keys via the key_inject_method option:

1. cloud-init (Default): Injects the public key via cloud-init user data. This creates a user specified by ssh_user (defaults to ubuntu), adds the public key, and grants passwordless sudo access.
2. ec2: Creates an AWS managed key specified by key_name. The instance is associated with this key. In this mode, ssh_user is ignored; the user is the default for the image being used.

Using existing keys: To use an existing private key instead of a generated one, provide the path via private_key_path. Note that public_key_path is not used.

Connection Options: When using the ec2 method, you may need to specify the correct user in connection_options (e.g., ansible_user: admin) to match the image's default user.

platforms:
  - name: debian_as_ubuntu
    image: ami-0f31df35880686b3f
    region: us-east-1
    # Uses cloud-init (default), creates 'ubuntu' user, generates new key
  - name: debian_as_admin
    image: ami-0f31df35880686b3f
    region: us-east-1
    key_inject_method: ec2
    connection_options:
      ansible_user: admin
  - name: debian_my_key
    image: ami-0f31df35880686b3f
    region: us-east-1
    key_inject_method: ec2
    key_name: my-key
    private_key_path: ~/.ssh/id_rsa