salt.modules.boto_ec2

Connection module for Amazon EC2

2015.8.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 a pillar or 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

If a region is not specified, the default is 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
depends:

boto

salt.modules.boto_ec2.allocate_eip_address(domain=None, region=None, key=None, keyid=None, profile=None)

Allocate a new Elastic IP address and associate it with your account.

domain
(string) Optional param - if set to exactly 'vpc', the address will be allocated to the VPC. The default simply maps the EIP to your account container.
returns
(dict) dict of 'interesting' information about the newly allocated EIP, with probably the most interesting keys being 'public_ip'; and 'allocation_id' iff 'domain=vpc' was passed.

CLI Example:

salt-call boto_ec2.allocate_eip_address domain=vpc

2016.3.0 新版功能.

salt.modules.boto_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 currently running instance or a network interface. This requires exactly one of either 'public_ip' or 'allocation_id', depending on whether you’re associating a VPC address or a plain EC2 address.

instance_id
(string) – ID of the instance to associate with (exclusive with 'instance_name')
instance_name
(string) – Name tag of the instance to associate with (exclusive with 'instance_id')
public_ip
(string) – Public IP address, for standard EC2 based allocations.
allocation_id
(string) – Allocation ID for a VPC-based EIP.
network_interface_id
(string) - ID of the network interface to associate the EIP with
network_interface_name
(string) - Name of the network interface to associate the EIP with
private_ip_address
(string) – The primary or secondary private IP address to associate with the Elastic IP address.
allow_reassociation
(bool) – Allow a currently associated EIP to be re-associated with the new instance or interface.
returns
(bool) - True on success, False otherwise

CLI Example:

salt myminion boto_ec2.associate_eip_address instance_name=bubba.ho.tep allocation_id=eipalloc-ef382c8a

2016.3.0 新版功能.

salt.modules.boto_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 Elastic Network Interface.

2016.3.0 新版功能.

CLI Example:

salt myminion boto_ec2.attach_network_interface my_eni instance_name=salt-master device_index=0
salt.modules.boto_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)

Given instance properties that define exactly one instance, create AMI and return AMI-id.

CLI Examples:

salt myminion boto_ec2.create_instance ami_name instance_name=myinstance
salt myminion boto_ec2.create_instance another_ami_name tags='{"mytag": "value"}' description='this is my ami'
salt.modules.boto_ec2.create_key(key_name, save_path, region=None, key=None, keyid=None, profile=None)

Creates a key and saves it to a given path. Returns the private key.

CLI Example:

salt myminion boto_ec2.create mykey /root/
salt.modules.boto_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 Elastic Network Interface.

2016.3.0 新版功能.

CLI Example:

salt myminion boto_ec2.create_network_interface my_eni subnet-12345 description=my_eni groups=['my_group']
salt.modules.boto_ec2.delete_key(key_name, region=None, key=None, keyid=None, profile=None)

Deletes a key. Always returns True

CLI Example:

salt myminion boto_ec2.delete_key mykey
salt.modules.boto_ec2.delete_network_interface(name=None, network_interface_id=None, region=None, key=None, keyid=None, profile=None)

Create an Elastic Network Interface.

2016.3.0 新版功能.

CLI Example:

salt myminion boto_ec2.create_network_interface my_eni subnet-12345 description=my_eni groups=['my_group']
salt.modules.boto_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 Elastic Network Interface.

2016.3.0 新版功能.

CLI Example:

salt myminion boto_ec2.detach_network_interface my_eni
salt.modules.boto_ec2.disassociate_eip_address(public_ip=None, association_id=None, region=None, key=None, keyid=None, profile=None)

Disassociate an Elastic IP address from a currently running instance. This requires exactly one of either 'association_id' or 'public_ip', depending on whether you’re associating a VPC address or a plain EC2 address.

public_ip
(string) – Public IP address, for standard EC2 based allocations.
association_id
(string) – Association ID for a VPC-based EIP.
returns
(bool) - True on success, False otherwise

CLI Example:

salt myminion boto_ec2.disassociate_eip_address association_id=eipassoc-e3ba2d16

2016.3.0 新版功能.

salt.modules.boto_ec2.exists(instance_id=None, name=None, tags=None, region=None, key=None, keyid=None, profile=None, in_states=None)

Given a instance id, check to see if the given instance id exists.

Returns True if the given an instance with the given id, name, or tags exists; otherwise, False is returned.

CLI Example:

salt myminion boto_ec2.exists myinstance
salt.modules.boto_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)

Given image properties, find and return matching AMI ids

CLI Examples:

salt myminion boto_ec2.find_instances tags='{"mytag": "value"}'
salt.modules.boto_ec2.find_instances(instance_id=None, name=None, tags=None, region=None, key=None, keyid=None, profile=None, return_objs=False, in_states=None)

Given instance properties, find and return matching instance ids

CLI Examples:

salt myminion boto_ec2.find_instances # Lists all instances
salt myminion boto_ec2.find_instances name=myinstance
salt myminion boto_ec2.find_instances tags='{"mytag": "value"}'
salt.modules.boto_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.

addresses
(list) - Optional list of addresses. If provided, only the addresses associated with those in the list will be returned.
allocation_ids
(list) - Optional list of allocation IDs. If provided, only the addresses associated with the given allocation IDs will be returned.
returns
(list) - A list of the requested EIP addresses

CLI Example:

salt-call boto_ec2.get_all_eip_addresses

2016.3.0 新版功能.

salt.modules.boto_ec2.get_attribute(attribute, instance_name=None, instance_id=None, region=None, key=None, keyid=None, profile=None)

Get an EC2 instance attribute.

CLI Example:

salt myminion boto_ec2.get_attribute sourceDestCheck instance_name=my_instance
Available attributes:
  • instanceType
  • kernel
  • ramdisk
  • userData
  • disableApiTermination
  • instanceInitiatedShutdownBehavior
  • rootDeviceName
  • blockDeviceMapping
  • productCodes
  • sourceDestCheck
  • groupSet
  • ebsOptimized
  • sriovNetSupport
salt.modules.boto_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 current account.

addresses
(list) - Optional list of addresses. If provided, only the addresses associated with those in the list will be returned.
allocation_ids
(list) - Optional list of allocation IDs. If provided, only the addresses associated with the given allocation IDs will be returned.
returns
(list of dicts) - A list of dicts, each containing the info for one of the requested EIPs.

CLI Example:

salt-call boto_ec2.get_eip_address_info addresses=52.4.2.15

2016.3.0 新版功能.

salt.modules.boto_ec2.get_id(name=None, tags=None, region=None, key=None, keyid=None, profile=None, in_states=None)

Given instace properties, return the instance id if it exist.

CLI Example:

salt myminion boto_ec2.get_id myinstance
salt.modules.boto_ec2.get_key(key_name, region=None, key=None, keyid=None, profile=None)

Check to see if a key exists. Returns fingerprint and name if it does and False if it doesn't CLI Example:

salt myminion boto_ec2.get_key mykey
salt.modules.boto_ec2.get_keys(keynames=None, filters=None, region=None, key=None, keyid=None, profile=None)

Gets all keys or filters them by name and returns a list. keynames (list):: A list of the names of keypairs to retrieve. If not provided, all key pairs will be returned. filters (dict) :: Optional filters that can be used to limit the results returned. Filters are provided in the form of a dictionary consisting of filter names as the key and filter values as the value. The set of allowable filter names/values is dependent on the request being performed. Check the EC2 API guide for details.

CLI Example:

salt myminion boto_ec2.get_keys
salt.modules.boto_ec2.get_network_interface(name=None, network_interface_id=None, region=None, key=None, keyid=None, profile=None)

Get an Elastic Network Interface.

2016.3.0 新版功能.

CLI Example:

salt myminion boto_ec2.get_network_interface name=my_eni
salt.modules.boto_ec2.get_network_interface_id(name, region=None, key=None, keyid=None, profile=None)

Get an Elastic Network Interface id from its name tag.

2016.3.0 新版功能.

CLI Example:

salt myminion boto_ec2.get_network_interface_id name=my_eni
salt.modules.boto_ec2.get_unassociated_eip_address(domain='standard', region=None, key=None, keyid=None, profile=None)

Return the first unassociated EIP

domain
Indicates whether the address is a EC2 address or a VPC address (standard|vpc).

CLI Example:

salt-call boto_ec2.get_unassociated_eip_address

2016.3.0 新版功能.

salt.modules.boto_ec2.get_zones(region=None, key=None, keyid=None, profile=None)

Get a list of AZs for the configured region.

CLI Example:

salt myminion boto_ec2.get_zones
salt.modules.boto_ec2.import_key(key_name, public_key_material, region=None, key=None, keyid=None, profile=None)

Imports the public key from an RSA key pair that you created with a third-party tool. Supported formats: - OpenSSH public key format (e.g., the format in ~/.ssh/authorized_keys) - Base64 encoded DER format - SSH public key file format as specified in RFC4716 - DSA keys are not supported. Make sure your key generator is set up to create RSA keys. Supported lengths: 1024, 2048, and 4096.

CLI Example:

salt myminion boto_ec2.import mykey publickey
salt.modules.boto_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 attribute of an Elastic Network Interface.

2016.3.0 新版功能.

CLI Example:

salt myminion boto_ec2.modify_network_interface_attribute my_eni attr=description value='example description'
salt.modules.boto_ec2.release_eip_address(public_ip=None, allocation_id=None, region=None, key=None, keyid=None, profile=None)

Free an Elastic IP address. Pass either a public IP address to release a 'standard' EC2 Elastic IP address, or an AllocationId to release a VPC Elastic IP address.

public_ip
(string) - The public IP address - for EC2 elastic IPs.
allocation_id
(string) - The Allocation ID - for VPC elastic IPs.
returns
(bool) - True on success, False on failure

CLI Example:

salt myminion boto_ec2.release_eip_address allocation_id=eipalloc-ef382c8a

2016.3.0 新版功能.

salt.modules.boto_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 True if the instance was created; otherwise False.

CLI Example:

salt myminion boto_ec2.run ami-b80c2b87 name=myinstance
image_id
(string) – The ID of the image to run.
name
(string) - The name of the instance.
tags
(dict of key: value pairs) - 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 type of instance to run. Note that some image types (e.g. hvm) only run on some instance types.
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.
monitoring_enabled
(bool) – Enable detailed CloudWatch monitoring on the instance.
vpc_id
(string) - ID of a VPC to bind the instance to. Exclusive with vpc_name.
vpc_name
(string) - Name of a VPC to bind the instance to. Exclusive with vpc_id.
subnet_id
(string) – The subnet ID within which to launch the instances for VPC.
subnet_name
(string) – The name of a 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 ID(s) of the VPC security groups with which to associate instances.
security_group_names
(list of strings) – The name(s) 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 an optimized 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_id
(string) - ID of the network interface to attach to the instance
network_interface_name
(string) - Name of the network interface to attach to the instance
salt.modules.boto_ec2.set_attribute(attribute, attribute_value, instance_name=None, instance_id=None, region=None, key=None, keyid=None, profile=None)

Set an EC2 instance attribute. Returns whether the operation succeeded or not.

CLI Example:

salt myminion boto_ec2.set_attribute sourceDestCheck False instance_name=my_instance
Available attributes:
  • instanceType
  • kernel
  • ramdisk
  • userData
  • disableApiTermination
  • instanceInitiatedShutdownBehavior
  • rootDeviceName
  • blockDeviceMapping
  • productCodes
  • sourceDestCheck
  • groupSet
  • ebsOptimized
  • sriovNetSupport
salt.modules.boto_ec2.terminate(instance_id=None, name=None, region=None, key=None, keyid=None, profile=None)

Terminate the instance described by instance_id or name.

CLI Example:

salt myminion boto_ec2.terminate name=myinstance
salt myminion boto_ec2.terminate instance_id=i-a46b9f