boto3_ec2

Connection module for Amazon EC2 using boto3.

Renamed from boto_ec2 to boto3_ec2 and rewritten to use the boto3 ec2 client APIs directly via saltext.boto3.utils.boto3mod. The legacy boto2 code path (object-style access, retry loops) has been removed.

depends:

• boto3 >= 1.28.0

• botocore >= 1.31.0

configuration:

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

A region may also be specified in the configuration:

ec2.region: us-east-1

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

Added in version 1.0.0.

saltext.boto3.modules.boto3_ec2.get_all_eip_addresses(addresses=None, allocation_ids=None, region=None, key=None, keyid=None, profile=None)

Get public addresses of some, or all EIPs associated with the current account.

CLI Example:

salt-call boto3_ec2.get_all_eip_addresses

saltext.boto3.modules.boto3_ec2.get_unassociated_eip_address(domain='standard', region=None, key=None, keyid=None, profile=None)

Return the first unassociated EIP (public IP string), or None.

CLI Example:

salt-call boto3_ec2.get_unassociated_eip_address

saltext.boto3.modules.boto3_ec2.get_eip_address_info(addresses=None, allocation_ids=None, region=None, key=None, keyid=None, profile=None)

Get ‘interesting’ info about some, or all EIPs associated with the account.

CLI Example:

salt-call boto3_ec2.get_eip_address_info

saltext.boto3.modules.boto3_ec2.allocate_eip_address(domain=None, region=None, key=None, keyid=None, profile=None)

Allocate a new Elastic IP address and return dict of details, or False.

CLI Example:

salt-call boto3_ec2.allocate_eip_address

saltext.boto3.modules.boto3_ec2.release_eip_address(public_ip=None, allocation_id=None, region=None, key=None, keyid=None, profile=None)

Free an Elastic IP address. Returns True on success.

CLI Example:

salt-call boto3_ec2.release_eip_address

saltext.boto3.modules.boto3_ec2.associate_eip_address(instance_id=None, instance_name=None, public_ip=None, allocation_id=None, network_interface_id=None, network_interface_name=None, private_ip_address=None, allow_reassociation=False, region=None, key=None, keyid=None, profile=None)

Associate an Elastic IP address with a running instance or network interface. Returns True on success.

CLI Example:

salt-call boto3_ec2.associate_eip_address

saltext.boto3.modules.boto3_ec2.disassociate_eip_address(public_ip=None, association_id=None, region=None, key=None, keyid=None, profile=None)

Disassociate an Elastic IP address. Returns True on success.

CLI Example:

salt-call boto3_ec2.disassociate_eip_address

saltext.boto3.modules.boto3_ec2.assign_private_ip_addresses(network_interface_name=None, network_interface_id=None, private_ip_addresses=None, secondary_private_ip_address_count=None, allow_reassignment=False, region=None, key=None, keyid=None, profile=None)

Assign secondary private IP addresses to an ENI. Returns True on success.

CLI Example:

salt-call boto3_ec2.assign_private_ip_addresses

saltext.boto3.modules.boto3_ec2.unassign_private_ip_addresses(network_interface_name=None, network_interface_id=None, private_ip_addresses=None, region=None, key=None, keyid=None, profile=None)

Unassign secondary private IP addresses from an ENI. Returns True on success.

CLI Example:

salt-call boto3_ec2.unassign_private_ip_addresses

saltext.boto3.modules.boto3_ec2.get_zones(region=None, key=None, keyid=None, profile=None)

Get the list of AZ names for the configured region.

CLI Example:

salt-call boto3_ec2.get_zones

saltext.boto3.modules.boto3_ec2.find_instances(instance_id=None, name=None, tags=None, region=None, key=None, keyid=None, profile=None, return_objs=False, in_states=None, filters=None)

Given instance properties, find and return matching instance ids (default) or the raw boto3 instance dicts (when return_objs is True).

CLI Example:

salt-call boto3_ec2.find_instances

saltext.boto3.modules.boto3_ec2.create_image(ami_name, instance_id=None, instance_name=None, tags=None, region=None, key=None, keyid=None, profile=None, description=None, no_reboot=False, dry_run=False, filters=None)

Create an AMI from a single matched instance. Returns AMI id or False.

CLI Example:

salt-call boto3_ec2.create_image

saltext.boto3.modules.boto3_ec2.find_images(ami_name=None, executable_by=None, owners=None, image_ids=None, tags=None, region=None, key=None, keyid=None, profile=None, return_objs=False)

Return matching AMI ids, or objects when return_objs is True. Returns False when no images are found.

CLI Example:

salt-call boto3_ec2.find_images

saltext.boto3.modules.boto3_ec2.terminate(instance_id=None, name=None, region=None, key=None, keyid=None, profile=None, filters=None)

Terminate the instance described by instance_id or Name tag.

CLI Example:

salt-call boto3_ec2.terminate

saltext.boto3.modules.boto3_ec2.get_id(name=None, tags=None, region=None, key=None, keyid=None, profile=None, in_states=None, filters=None)

Return a single instance id matching the given properties, or None.

CLI Example:

salt-call boto3_ec2.get_id

saltext.boto3.modules.boto3_ec2.get_tags(instance_id=None, keyid=None, key=None, profile=None, region=None)

Return a list of {name: value} tag dicts for an instance.

CLI Example:

salt-call boto3_ec2.get_tags

saltext.boto3.modules.boto3_ec2.exists(instance_id=None, name=None, tags=None, region=None, key=None, keyid=None, profile=None, in_states=None, filters=None)

Return True if any instance matching the given properties exists.

CLI Example:

salt-call boto3_ec2.exists

saltext.boto3.modules.boto3_ec2.run(image_id, name=None, tags=None, key_name=None, security_groups=None, user_data=None, instance_type='m1.small', placement=None, kernel_id=None, ramdisk_id=None, monitoring_enabled=None, vpc_id=None, vpc_name=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_interface_id=None, network_interface_name=None, region=None, key=None, keyid=None, profile=None, network_interfaces=None)

Create and start an EC2 instance. Returns {"instance_id": ...} on success, False otherwise.

CLI Example:

salt-call boto3_ec2.run

saltext.boto3.modules.boto3_ec2.get_key(key_name, region=None, key=None, keyid=None, profile=None)

Return (name, fingerprint) if the key exists, else False.

CLI Example:

salt-call boto3_ec2.get_key

saltext.boto3.modules.boto3_ec2.create_key(key_name, save_path, region=None, key=None, keyid=None, profile=None)

Create a new key pair, save the private material to save_path and return it.

CLI Example:

salt-call boto3_ec2.create_key

saltext.boto3.modules.boto3_ec2.import_key(key_name, public_key_material, region=None, key=None, keyid=None, profile=None)

Import a key pair by public material. Returns the fingerprint or False.

CLI Example:

salt-call boto3_ec2.import_key

saltext.boto3.modules.boto3_ec2.delete_key(key_name, region=None, key=None, keyid=None, profile=None)

Delete a key pair. Returns True on success.

CLI Example:

salt-call boto3_ec2.delete_key

saltext.boto3.modules.boto3_ec2.get_keys(keynames=None, filters=None, region=None, key=None, keyid=None, profile=None)

Return a list of key pair names matching keynames and filters.

CLI Example:

salt-call boto3_ec2.get_keys

saltext.boto3.modules.boto3_ec2.get_attribute(attribute, instance_name=None, instance_id=None, region=None, key=None, keyid=None, profile=None, filters=None)

Return {attribute: value} for an EC2 instance, or False.

CLI Example:

salt-call boto3_ec2.get_attribute

saltext.boto3.modules.boto3_ec2.set_attribute(attribute, attribute_value, instance_name=None, instance_id=None, region=None, key=None, keyid=None, profile=None, filters=None)

Set an EC2 instance attribute. Returns True on success, False on failure.

CLI Example:

salt-call boto3_ec2.set_attribute

saltext.boto3.modules.boto3_ec2.get_network_interface_id(name, region=None, key=None, keyid=None, profile=None)

Return {"result": eni_id} or {"error": {...}}.

CLI Example:

salt-call boto3_ec2.get_network_interface_id

saltext.boto3.modules.boto3_ec2.get_network_interface(name=None, network_interface_id=None, region=None, key=None, keyid=None, profile=None)

Return {"result": {...}} or {"error": {...}}.

CLI Example:

salt-call boto3_ec2.get_network_interface

saltext.boto3.modules.boto3_ec2.create_network_interface(name, subnet_id=None, subnet_name=None, private_ip_address=None, description=None, groups=None, region=None, key=None, keyid=None, profile=None)

Create an ENI tagged with Name=<name>.

CLI Example:

salt-call boto3_ec2.create_network_interface

saltext.boto3.modules.boto3_ec2.delete_network_interface(name=None, network_interface_id=None, region=None, key=None, keyid=None, profile=None)

Delete an ENI.

CLI Example:

salt-call boto3_ec2.delete_network_interface

saltext.boto3.modules.boto3_ec2.attach_network_interface(device_index, name=None, network_interface_id=None, instance_name=None, instance_id=None, region=None, key=None, keyid=None, profile=None)

Attach an ENI to an instance.

CLI Example:

salt-call boto3_ec2.attach_network_interface

saltext.boto3.modules.boto3_ec2.detach_network_interface(name=None, network_interface_id=None, attachment_id=None, force=False, region=None, key=None, keyid=None, profile=None)

Detach an ENI.

CLI Example:

salt-call boto3_ec2.detach_network_interface

saltext.boto3.modules.boto3_ec2.modify_network_interface_attribute(name=None, network_interface_id=None, attr=None, value=None, region=None, key=None, keyid=None, profile=None)

Modify an ENI attribute: description, source_dest_check, groups, delete_on_termination.

CLI Example:

salt-call boto3_ec2.modify_network_interface_attribute

saltext.boto3.modules.boto3_ec2.get_all_volumes(volume_ids=None, filters=None, return_objs=False, region=None, key=None, keyid=None, profile=None)

Return a list of volume IDs or describe-volume dicts.

CLI Example:

salt-call boto3_ec2.get_all_volumes

saltext.boto3.modules.boto3_ec2.set_volumes_tags(tag_maps, authoritative=False, dry_run=False, region=None, key=None, keyid=None, profile=None)

Apply tags to EBS volumes. See legacy boto_ec2.set_volumes_tags for the schema.

CLI Example:

salt-call boto3_ec2.set_volumes_tags

saltext.boto3.modules.boto3_ec2.get_all_tags(filters=None, region=None, key=None, keyid=None, profile=None)

Describe all tags matching the filter criteria.

CLI Example:

salt-call boto3_ec2.get_all_tags

saltext.boto3.modules.boto3_ec2.create_tags(resource_ids, tags, region=None, key=None, keyid=None, profile=None)

Create metadata tags on the given resources.

CLI Example:

salt-call boto3_ec2.create_tags

saltext.boto3.modules.boto3_ec2.delete_tags(resource_ids, tags, region=None, key=None, keyid=None, profile=None)

Delete metadata tags from the given resources.

CLI Example:

salt-call boto3_ec2.delete_tags

saltext.boto3.modules.boto3_ec2.detach_volume(volume_id, instance_id=None, device=None, force=False, wait_for_detachement=False, region=None, key=None, keyid=None, profile=None)

Detach an EBS volume. Returns True on success.

CLI Example:

salt-call boto3_ec2.detach_volume

saltext.boto3.modules.boto3_ec2.delete_volume(volume_id, instance_id=None, device=None, force=False, region=None, key=None, keyid=None, profile=None)

Delete an EBS volume. Set force=True to force-detach first.

CLI Example:

salt-call boto3_ec2.delete_volume

saltext.boto3.modules.boto3_ec2.attach_volume(volume_id, instance_id, device, region=None, key=None, keyid=None, profile=None)

Attach an EBS volume. Returns True on success.

CLI Example:

salt-call boto3_ec2.attach_volume

saltext.boto3.modules.boto3_ec2.create_volume(zone_name, size=None, snapshot_id=None, volume_type=None, iops=None, encrypted=False, kms_key_id=None, wait_for_creation=False, region=None, key=None, keyid=None, profile=None)

Create an EBS volume. Returns {"result": vol_id} or {"error": ...}.

CLI Example:

salt-call boto3_ec2.create_volume

saltext.boto3.modules.boto3_ec2.describe_instance_metadata_options(instance_id, region=None, key=None, keyid=None, profile=None)

Return the current Instance Metadata Service (IMDS) options for an instance.

instance_id

The ID of the EC2 instance.

CLI Example:

salt '*' boto3_ec2.describe_instance_metadata_options i-0123456789abcdef0

saltext.boto3.modules.boto3_ec2.modify_instance_metadata_options(instance_id, http_tokens=None, http_put_response_hop_limit=None, http_endpoint=None, http_protocol_ipv6=None, instance_metadata_tags=None, region=None, key=None, keyid=None, profile=None)

Modify the Instance Metadata Service (IMDS) options for an instance.

instance_id

The ID of the EC2 instance.

http_tokens

optional or required. required enforces IMDSv2.

http_put_response_hop_limit

Integer 1-64. Desired HTTP PUT response hop limit for metadata requests.

http_endpoint

enabled or disabled.

http_protocol_ipv6

enabled or disabled.

instance_metadata_tags

enabled or disabled.

Returns {"result": <MetadataOptions>} on success, or {"error": ...}.

CLI Example:

salt '*' boto3_ec2.modify_instance_metadata_options i-01234 http_tokens=required

saltext.boto3.modules.boto3_ec2.require_imdsv2(instance_id, region=None, key=None, keyid=None, profile=None)

Convenience wrapper to enforce IMDSv2 on an instance by setting HttpTokens=required and HttpEndpoint=enabled.

instance_id

The ID of the EC2 instance.

CLI Example:

salt '*' boto3_ec2.require_imdsv2 i-0123456789abcdef0