boto3_ec2

Manage EC2 objects using boto3.

Renamed from boto_ec2 to boto3_ec2 and updated to call the refactored boto3_ec2 execution module.

This module provides an interface to the Elastic Compute Cloud (EC2) service from AWS.

depends:

  • boto3 >= 1.28.0

  • botocore >= 1.31.0

Create and destroy EC2 instances. Be aware that this interacts with Amazon’s services, and so may incur charges.

This module uses boto3, which can be installed via package, or pip.

This module accepts explicit EC2 credentials but can also utilize IAM roles assigned to the instance through Instance Profiles. Dynamic credentials are then automatically obtained from AWS API and no further configuration is necessary. More Information available at:

http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam-roles-for-amazon-ec2.html

If IAM roles are not used you need to specify them either in the minion’s config file or as a profile. For example, to specify them in the minion’s config file:

ec2.keyid: GKTADJGHEIQSXMKKRBJ08H
ec2.key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs

It’s also possible to specify key, keyid and region via a profile, either as a passed in dict, or as a string to pull from pillars or minion config:

myprofile:
    keyid: GKTADJGHEIQSXMKKRBJ08H
    key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs
    region: us-east-1

The below code creates a key pair:

create-key-pair:
  boto3_ec2.key_present:
    - name: mykeypair
    - save_private: /root/
    - region: eu-west-1
    - keyid: GKTADJGHEIQSXMKKRBJ08H
    - key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs

import-key-pair:
   boto3_ec2.key_present:
    - name: mykeypair
    - upload_public: 'ssh-rsa AAAA'
    - keyid: GKTADJGHEIQSXMKKRBJ08H
    - key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs

You can also use salt:// in order to define the public key.

import-key-pair:
   boto3_ec2.key_present:
    - name: mykeypair
    - upload_public: salt://mybase/public_key.pub
    - keyid: GKTADJGHEIQSXMKKRBJ08H
    - key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs

The below code deletes a key pair:

delete-key-pair:
  boto3_ec2.key_absent:
    - name: mykeypair
    - region: eu-west-1
    - keyid: GKTADJGHEIQSXMKKRBJ08H
    - key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs

Added in version 1.0.0.

saltext.boto3.states.boto3_ec2.__virtual__()[source]

Only load if boto is available.

saltext.boto3.states.boto3_ec2.key_present(name, save_private=None, upload_public=None, region=None, key=None, keyid=None, profile=None)[source]

Ensure key pair is present.

Example:

ensure-key-present:
  boto3_ec2.key_present:
    - name: example
saltext.boto3.states.boto3_ec2.key_absent(name, region=None, key=None, keyid=None, profile=None)[source]

Deletes a key pair

Example:

ensure-key-absent:
  boto3_ec2.key_absent:
    - name: example
saltext.boto3.states.boto3_ec2.eni_present(name, subnet_id=None, subnet_name=None, private_ip_address=None, description=None, groups=None, source_dest_check=True, allocate_eip=None, arecords=None, region=None, key=None, keyid=None, profile=None)[source]

Ensure the EC2 ENI exists.

name

Name tag associated with the ENI.

subnet_id

The VPC subnet ID the ENI will exist within.

subnet_name

The VPC subnet name the ENI will exist within.

private_ip_address

The private ip address to use for this ENI. If this is not specified AWS will automatically assign a private IP address to the ENI. Must be specified at creation time; will be ignored afterward.

description

Description of the key.

groups

A list of security groups to apply to the ENI.

source_dest_check

Boolean specifying whether source/destination checking is enabled on the ENI.

allocate_eip

allocate and associate an EIP to the ENI. Could be ‘standard’ to allocate Elastic IP to EC2 region or ‘vpc’ to get it for a particular VPC

arecords

A list of arecord dicts with attributes needed for the DNS add_record state. By default the boto3_route53.add_record state will be used, which requires: name, zone, ttl, and identifier. See the boto3_route53 state for information about these attributes. Other DNS modules can be called by specifying the provider keyword. By default, the private ENI IP address will be used, set ‘public: True’ in the arecord dict to use the ENI’s public IP address

region

Region to connect to.

key

Secret key to be used.

keyid

Access key to be used.

profile

A dict with region, key and keyid, or a pillar key (string) that contains a dict with region, key and keyid.

Example:

ensure-eni-present:
  boto3_ec2.eni_present:
    - name: example
saltext.boto3.states.boto3_ec2.eni_absent(name, release_eip=False, region=None, key=None, keyid=None, profile=None)[source]

Ensure the EC2 ENI is absent.

name

Name tag associated with the ENI.

release_eip

True/False - release any EIP associated with the ENI

region

Region to connect to.

key

Secret key to be used.

keyid

Access key to be used.

profile

A dict with region, key and keyid, or a pillar key (string) that contains a dict with region, key and keyid.

Example:

ensure-eni-absent:
  boto3_ec2.eni_absent:
    - name: example
saltext.boto3.states.boto3_ec2.snapshot_created(name, ami_name, instance_name, wait_until_available=True, wait_timeout_seconds=300, **kwargs)[source]

Create a snapshot from the given instance

Example:

ensure-snapshot-created:
  boto3_ec2.snapshot_created:
    - name: example
saltext.boto3.states.boto3_ec2.instance_present(name, instance_name=None, instance_id=None, image_id=None, image_name=None, tags=None, key_name=None, security_groups=None, user_data=None, instance_type=None, placement=None, kernel_id=None, ramdisk_id=None, vpc_id=None, vpc_name=None, monitoring_enabled=None, subnet_id=None, subnet_name=None, private_ip_address=None, block_device_map=None, disable_api_termination=None, instance_initiated_shutdown_behavior=None, placement_group=None, client_token=None, security_group_ids=None, security_group_names=None, additional_info=None, tenancy=None, instance_profile_arn=None, instance_profile_name=None, ebs_optimized=None, network_interfaces=None, network_interface_name=None, network_interface_id=None, attributes=None, target_state=None, public_ip=None, allocation_id=None, allocate_eip=False, region=None, key=None, keyid=None, profile=None)[source]

Ensure an EC2 instance is running with the given attributes and state.

name

(string) - The name of the state definition. Recommended that this match the instance_name attribute (generally the FQDN of the instance).

instance_name

(string) - The name of the instance, generally its FQDN. Exclusive with ‘instance_id’.

instance_id

(string) - The ID of the instance (if known). Exclusive with ‘instance_name’.

image_id

(string) - The ID of the AMI image to run.

image_name

(string) - The name of the AMI image to run.

tags

(dict) - Tags to apply to the instance.

key_name

(string) - The name of the key pair with which to launch instances.

security_groups

(list of strings) - The names of the EC2 classic security groups with which to associate instances

user_data

(string) - The Base64-encoded MIME user data to be made available to the instance(s) in this reservation.

instance_type

(string) - The EC2 instance size/type. Note that only certain types are compatible with HVM based AMIs.

placement

(string) - The Availability Zone to launch the instance into.

kernel_id

(string) - The ID of the kernel with which to launch the instances.

ramdisk_id

(string) - The ID of the RAM disk with which to launch the instances.

vpc_id

(string) - The ID of a VPC to attach the instance to.

vpc_name

(string) - The name of a VPC to attach the instance to.

monitoring_enabled

(bool) - Enable detailed CloudWatch monitoring on the instance.

subnet_id

(string) - The ID of the subnet within which to launch the instances for VPC.

subnet_name

(string) - The name of the subnet within which to launch the instances for VPC.

private_ip_address

(string) - If you’re using VPC, you can optionally use this parameter to assign the instance a specific available IP address from the subnet (e.g., 10.0.0.25).

block_device_map

(boto.ec2.blockdevicemapping.BlockDeviceMapping) - A BlockDeviceMapping data structure describing the EBS volumes associated with the Image.

disable_api_termination

(bool) - If True, the instances will be locked and will not be able to be terminated via the API.

instance_initiated_shutdown_behavior

(string) - Specifies whether the instance stops or terminates on instance-initiated shutdown. Valid values are:

  • ‘stop’

  • ‘terminate’

placement_group

(string) - If specified, this is the name of the placement group in which the instance(s) will be launched.

client_token

(string) - Unique, case-sensitive identifier you provide to ensure idempotency of the request. Maximum 64 ASCII characters.

security_group_ids

(list of strings) - The IDs of the VPC security groups with which to associate instances.

security_group_names

(list of strings) - The names of the VPC security groups with which to associate instances.

additional_info

(string) - Specifies additional information to make available to the instance(s).

tenancy

(string) - The tenancy of the instance you want to launch. An instance with a tenancy of ‘dedicated’ runs on single-tenant hardware and can only be launched into a VPC. Valid values are: “default” or “dedicated”. NOTE: To use dedicated tenancy you MUST specify a VPC subnet-ID as well.

instance_profile_arn

(string) - The Amazon resource name (ARN) of the IAM Instance Profile (IIP) to associate with the instances.

instance_profile_name

(string) - The name of the IAM Instance Profile (IIP) to associate with the instances.

ebs_optimized

(bool) - Whether the instance is optimized for EBS I/O. This optimization provides dedicated throughput to Amazon EBS and a tuned configuration stack to provide optimal EBS I/O performance. This optimization isn’t available with all instance types.

network_interfaces

(boto.ec2.networkinterface.NetworkInterfaceCollection) - A NetworkInterfaceCollection data structure containing the ENI specifications for the instance.

network_interface_name

(string) - The name of Elastic Network Interface to attach

network_interface_id

(string) - The id of Elastic Network Interface to attach

attributes

(dict) - Instance attributes and value to be applied to the instance. Available options are:

  • instanceType - A valid instance type (m1.small)

  • kernel - Kernel ID (None)

  • ramdisk - Ramdisk ID (None)

  • userData - Base64 encoded String (None)

  • disableApiTermination - Boolean (true)

  • instanceInitiatedShutdownBehavior - stop|terminate

  • blockDeviceMapping - List of strings - ie: [‘/dev/sda=false’]

  • sourceDestCheck - Boolean (true)

  • groupSet - Set of Security Groups or IDs

  • ebsOptimized - Boolean (false)

  • sriovNetSupport - String - ie: ‘simple’

target_state

(string) - The desired target state of the instance. Available options are:

  • running

  • stopped

Note that this option is currently UNIMPLEMENTED.

public_ip:

(string) - The IP of a previously allocated EIP address, which will be attached to the instance. EC2 Classic instances ONLY - for VPC pass in an allocation_id instead.

allocation_id:

(string) - The ID of a previously allocated EIP address, which will be attached to the instance. VPC instances ONLY - for Classic pass in a public_ip instead.

allocate_eip:

(bool) - Allocate and attach an EIP on-the-fly for this instance. Note you’ll want to release this address when terminating the instance, either manually or via the ‘release_eip’ flag to ‘instance_absent’.

region

(string) - Region to connect to.

key

(string) - Secret key to be used.

keyid

(string) - Access key to be used.

profile

(variable) - A dict with region, key and keyid, or a pillar key (string) that contains a dict with region, key and keyid.

Example:

ensure-instance-present:
  boto3_ec2.instance_present:
    - name: example
saltext.boto3.states.boto3_ec2.instance_absent(name, instance_name=None, instance_id=None, release_eip=False, region=None, key=None, keyid=None, profile=None, filters=None)[source]

Ensure an EC2 instance does not exist (is stopped and removed).

name

(string) - The name of the state definition.

instance_name

(string) - The name of the instance.

instance_id

(string) - The ID of the instance.

release_eip

(bool) - Release any associated EIPs during termination.

region

(string) - Region to connect to.

key

(string) - Secret key to be used.

keyid

(string) - Access key to be used.

profile

(variable) - A dict with region, key and keyid, or a pillar key (string) that contains a dict with region, key and keyid.

filters

(dict) - A dict of additional filters to use in matching the instance to delete.

YAML example fragment:

- filters:
    vpc-id: vpc-abcdef12
saltext.boto3.states.boto3_ec2.volume_absent(name, volume_name=None, volume_id=None, instance_name=None, instance_id=None, device=None, region=None, key=None, keyid=None, profile=None)[source]

Ensure the EC2 volume is detached and absent.

name

State definition name.

volume_name

Name tag associated with the volume. For safety, if this matches more than one volume, the state will refuse to apply.

volume_id

Resource ID of the volume.

instance_name

Only remove volume if it is attached to instance with this Name tag. Exclusive with ‘instance_id’. Requires ‘device’.

instance_id

Only remove volume if it is attached to this instance. Exclusive with ‘instance_name’. Requires ‘device’.

device

Match by device rather than ID. Requires one of ‘instance_name’ or ‘instance_id’.

region

Region to connect to.

key

Secret key to be used.

keyid

Access key to be used.

profile

A dict with region, key and keyid, or a pillar key (string) that contains a dict with region, key and keyid.

Example:

ensure-volume-absent:
  boto3_ec2.volume_absent:
    - name: example
saltext.boto3.states.boto3_ec2.volumes_tagged(name, tag_maps, authoritative=False, region=None, key=None, keyid=None, profile=None)[source]

Ensure EC2 volume(s) matching the given filters have the defined tags.

name

State definition name.

tag_maps

List of dicts of filters and tags, where ‘filters’ is a dict suitable for passing to the ‘filters’ argument of boto3_ec2.get_all_volumes(), and ‘tags’ is a dict of tags to be set on volumes as matched by the given filters. The filter syntax is extended to permit passing either a list of volume_ids or an instance_name (with instance_name being the Name tag of the instance to which the desired volumes are mapped). Each mapping in the list is applied separately, so multiple sets of volumes can be all tagged differently with one call to this function.

YAML example fragment:

- filters:
    attachment.instance_id: i-abcdef12
  tags:
    Name: dev-int-abcdef12.aws-foo.com
- filters:
    attachment.device: /dev/sdf
  tags:
    ManagedSnapshots: true
    BillingGroup: bubba.hotep@aws-foo.com
- filters:
    instance_name: prd-foo-01.aws-foo.com
  tags:
    Name: prd-foo-01.aws-foo.com
    BillingGroup: infra-team@aws-foo.com
- filters:
    volume_ids: [ vol-12345689, vol-abcdef12 ]
  tags:
    BillingGroup: infra-team@aws-foo.com
authoritative

Should un-declared tags currently set on matched volumes be deleted? Boolean.

region

Region to connect to.

key

Secret key to be used.

keyid

Access key to be used.

profile

A dict with region, key and keyid, or a pillar key (string) that contains a dict with region, key and keyid.

saltext.boto3.states.boto3_ec2.volume_present(name, volume_name=None, volume_id=None, instance_name=None, instance_id=None, device=None, size=None, snapshot_id=None, volume_type=None, iops=None, encrypted=False, kms_key_id=None, region=None, key=None, keyid=None, profile=None)[source]

Ensure the EC2 volume is present and attached.

name

State definition name.

volume_name

The Name tag value for the volume. If no volume with that matching name tag is found, a new volume will be created. If multiple volumes are matched, the state will fail.

volume_id

Resource ID of the volume. Exclusive with ‘volume_name’.

instance_name

Attach volume to instance with this Name tag. Exclusive with ‘instance_id’.

instance_id

Attach volume to instance with this ID. Exclusive with ‘instance_name’.

device

The device on the instance through which the volume is exposed (e.g. /dev/sdh)

size

The size of the new volume, in GiB. If you’re creating the volume from a snapshot and don’t specify a volume size, the default is the snapshot size. Optionally specified at volume creation time; will be ignored afterward. Requires ‘volume_name’.

snapshot_id

The snapshot ID from which the new Volume will be created. Optionally specified at volume creation time; will be ignored afterward. Requires ‘volume_name’.

volume_type

The type of the volume. Optionally specified at volume creation time; will be ignored afterward. Requires ‘volume_name’. Valid volume types for AWS can be found here: http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/EBSVolumeTypes.html

iops

The provisioned IOPS you want to associate with this volume. Optionally specified at volume creation time; will be ignored afterward. Requires ‘volume_name’.

encrypted

Specifies whether the volume should be encrypted. Optionally specified at volume creation time; will be ignored afterward. Requires ‘volume_name’.

kms_key_id

If encrypted is True, this KMS Key ID may be specified to encrypt volume with this key. Optionally specified at volume creation time; will be ignored afterward. Requires ‘volume_name’. e.g.: arn:aws:kms:us-east-1:012345678910:key/abcd1234-a123-456a-a12b-a123b4cd56ef

region

Region to connect to.

key

Secret key to be used.

keyid

Access key to be used.

profile

A dict with region, key and keyid, or a pillar key (string) that contains a dict with region, key and keyid.

Example:

ensure-volume-present:
  boto3_ec2.volume_present:
    - name: example
saltext.boto3.states.boto3_ec2.private_ips_present(name, network_interface_name=None, network_interface_id=None, private_ip_addresses=None, allow_reassignment=False, region=None, key=None, keyid=None, profile=None)[source]

Ensure an ENI has secondary private ip addresses associated with it

name

(String) - State definition name

network_interface_id

(String) - The EC2 network interface id, example eni-123456789

private_ip_addresses

(List or String) - The secondary private ip address(es) that should be present on the ENI.

allow_reassignment

(Boolean) - If true, will reassign a secondary private ip address associated with another ENI. If false, state will fail if the secondary private ip address is associated with another ENI.

region

(string) - Region to connect to.

key

(string) - Secret key to be used.

keyid

(string) - Access key to be used.

profile

(variable) - A dict with region, key and keyid, or a pillar key (string) that contains a dict with region, key and keyid.

Example:

ensure-private-ips-present:
  boto3_ec2.private_ips_present:
    - name: example
saltext.boto3.states.boto3_ec2.private_ips_absent(name, network_interface_name=None, network_interface_id=None, private_ip_addresses=None, region=None, key=None, keyid=None, profile=None)[source]

Ensure an ENI does not have secondary private ip addresses associated with it

name

(String) - State definition name

network_interface_id

(String) - The EC2 network interface id, example eni-123456789

private_ip_addresses

(List or String) - The secondary private ip address(es) that should be absent on the ENI.

region

(string) - Region to connect to.

key

(string) - Secret key to be used.

keyid

(string) - Access key to be used.

profile

(variable) - A dict with region, key and keyid, or a pillar key (string) that contains a dict with region, key and keyid.

Example:

ensure-private-ips-absent:
  boto3_ec2.private_ips_absent:
    - name: example