# salt.cloud.clouds.ec2

## The EC2 Cloud Module

The EC2 cloud module is used to interact with the Amazon Elastic Compute Cloud.

To use the EC2 cloud module, set up the cloud configuration at

  `/etc/salt/cloud.providers` or `/etc/salt/cloud.providers.d/ec2.conf`:

    my-ec2-config:
      # EC2 API credentials: Access Key ID and Secret Access Key.
      # Alternatively, to use IAM Instance Role credentials available via
      # EC2 metadata set both id and key to 'use-instance-role-credentials'
      id: GKTADJGHEIQSXMKKRBJ08H
      key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs

      # If 'role_arn' is specified the above credentials are used to
      # to assume to the role. By default, role_arn is set to None.
      role_arn: arn:aws:iam::012345678910:role/SomeRoleName

      # The ssh keyname to use
      keyname: default
      # The amazon security group
      securitygroup: ssh_open
      # The location of the private key which corresponds to the keyname
      private_key: /root/default.pem

      # Be default, service_url is set to amazonaws.com. If you are using this
      # driver for something other than Amazon EC2, change it here:
      service_url: amazonaws.com

      # The endpoint that is ultimately used is usually formed using the region
      # and the service_url. If you would like to override that entirely, you
      # can explicitly define the endpoint:
      endpoint: myendpoint.example.com:1138/services/Cloud

      # SSH Gateways can be used with this provider. Gateways can be used
      # when a salt-master is not on the same private network as the instance
      # that is being deployed.

      # Defaults to None
      # Required
      ssh_gateway: gateway.example.com

      # Defaults to port 22
      # Optional
      ssh_gateway_port: 22

      # Defaults to root
      # Optional
      ssh_gateway_username: root

      # Default to nc -q0 %h %p
      # Optional
      ssh_gateway_command: "-W %h:%p"

      # One authentication method is required. If both
      # are specified, Private key wins.

      # Private key defaults to None
      ssh_gateway_private_key: /path/to/key.pem

      # Password defaults to None
      ssh_gateway_password: ExamplePasswordHere

      driver: ec2

      # Pass userdata to the instance to be created
      userdata_file: /etc/salt/my-userdata-file

      # Instance termination protection setting
      # Default is disabled
      termination_protection: False

depends:

  requests

salt.cloud.clouds.ec2.attach_volume(name=None, kwargs=None, instance_id=None, call=None)

  Attach a volume to an instance

salt.cloud.clouds.ec2.avail_images(kwargs=None, call=None)

  Return a dict of all available VM images on the cloud provider.

salt.cloud.clouds.ec2.avail_locations(call=None)

  List all available locations

salt.cloud.clouds.ec2.avail_sizes(call=None)

  Return a dict of all available VM sizes on the cloud provider with relevant data. Latest version can be found at:

  http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/instance-types.html

salt.cloud.clouds.ec2.block_device_mappings(vm_)

  Return the block device mapping:

      [{'DeviceName': '/dev/sdb', 'VirtualName': 'ephemeral0'},
        {'DeviceName': '/dev/sdc', 'VirtualName': 'ephemeral1'}]

salt.cloud.clouds.ec2.copy_snapshot(kwargs=None, call=None)

  Copy a snapshot

salt.cloud.clouds.ec2.create(vm_=None, call=None)

  Create a single VM from a data dict

salt.cloud.clouds.ec2.create_attach_volumes(name, kwargs, call=None, wait_to_finish=True)

  Create and attach volumes to created node

salt.cloud.clouds.ec2.create_keypair(kwargs=None, call=None)

  Create an SSH keypair

salt.cloud.clouds.ec2.create_snapshot(kwargs=None, call=None, wait_to_finish=False)

  Create a snapshot.

  volume_id

    The ID of the Volume from which to create a snapshot.

  description

    The optional description of the snapshot.

  CLI Exampe:

      salt-cloud -f create_snapshot my-ec2-config volume_id=vol-351d8826
      salt-cloud -f create_snapshot my-ec2-config volume_id=vol-351d8826 \
          description="My Snapshot Description"

salt.cloud.clouds.ec2.create_volume(kwargs=None, call=None, wait_to_finish=False)

  Create a volume.

  zone

    The availability zone used to create the volume. Required. String.

  size

    The size of the volume, in GiBs. Defaults to `10`. Integer.

  snapshot

    The snapshot-id from which to create the volume. Integer.

  type

    The volume type. This can be `gp2` for General Purpose SSD, `io1` or `io2` for Provisioned IOPS SSD, `st1` for Throughput Optimized HDD, `sc1` for Cold HDD, or `standard` for Magnetic volumes. String.

  iops

    The number of I/O operations per second (IOPS) to provision for the volume, with a maximum ratio of 50 IOPS/GiB. Only valid for Provisioned IOPS SSD volumes. Integer.

    This option will only be set if `type` is also specified as `io1` or `io2`

  encrypted

    Specifies whether the volume will be encrypted. Boolean.

    If `snapshot` is also given in the list of kwargs, then this value is ignored since volumes that are created from encrypted snapshots are also automatically encrypted.

  tags

    The tags to apply to the volume during creation. Dictionary.

  call

    The `create_volume` function must be called with `-f` or `--function`. String.

  wait_to_finish

    Whether or not to wait for the volume to be available. Boolean. Defaults to `False`.

  CLI Examples:

      salt-cloud -f create_volume my-ec2-config zone=us-east-1b
      salt-cloud -f create_volume my-ec2-config zone=us-east-1b tags='{"tag1": "val1", "tag2", "val2"}'

salt.cloud.clouds.ec2.del_tags(name=None, kwargs=None, call=None, instance_id=None, resource_id=None)

  Delete tags for a resource. Normally a VM name or instance_id is passed in, but a resource_id may be passed instead. If both are passed in, the instance_id will be used.

  CLI Examples:

      salt-cloud -a del_tags mymachine tags=mytag,
      salt-cloud -a del_tags mymachine tags=tag1,tag2,tag3
      salt-cloud -a del_tags resource_id=vol-3267ab32 tags=tag1,tag2,tag3

salt.cloud.clouds.ec2.delete_keypair(kwargs=None, call=None)

  Delete an SSH keypair

salt.cloud.clouds.ec2.delete_snapshot(kwargs=None, call=None)

  Delete a snapshot

salt.cloud.clouds.ec2.delete_volume(name=None, kwargs=None, instance_id=None, call=None)

  Delete a volume

salt.cloud.clouds.ec2.delvol_on_destroy(name, kwargs=None, call=None)

  Delete all/specified EBS volumes upon instance termination

  CLI Example:

      salt-cloud -a delvol_on_destroy mymachine

salt.cloud.clouds.ec2.describe_snapshots(kwargs=None, call=None)

  Describe a snapshot (or snapshots)

  snapshot_id

    One or more snapshot IDs. Multiple IDs must be separated by ",".

  owner

    Return the snapshots owned by the specified owner. Valid values include: self, amazon, <AWS Account ID>. Multiple values must be separated by ",".

  restorable_by

    One or more AWS accounts IDs that can create volumes from the snapshot. Multiple aws account IDs must be separated by ",".

  TODO: Add all of the filters.

salt.cloud.clouds.ec2.describe_volumes(kwargs=None, call=None)

  Describe a volume (or volumes)

  volume_id

    One or more volume IDs. Multiple IDs must be separated by ",".

  TODO: Add all of the filters.

salt.cloud.clouds.ec2.destroy(name, call=None)

  Destroy a node. Will check termination protection and warn if enabled.

  CLI Example:

      salt-cloud --destroy mymachine

salt.cloud.clouds.ec2.detach_volume(name=None, kwargs=None, instance_id=None, call=None)

  Detach a volume from an instance

salt.cloud.clouds.ec2.disable_detailed_monitoring(name, call=None)

  Enable/disable detailed monitoring on a node

salt.cloud.clouds.ec2.disable_term_protect(name, call=None)

  Disable termination protection on a node

  CLI Example:

      salt-cloud -a disable_term_protect mymachine

salt.cloud.clouds.ec2.enable_detailed_monitoring(name, call=None)

  Enable/disable detailed monitoring on a node

salt.cloud.clouds.ec2.enable_term_protect(name, call=None)

  Enable termination protection on a node

  CLI Example:

      salt-cloud -a enable_term_protect mymachine

salt.cloud.clouds.ec2.get_availability_zone(vm_)

  Return the availability zone to use

salt.cloud.clouds.ec2.get_configured_provider()

  Return the first configured instance.

salt.cloud.clouds.ec2.get_console_output(name=None, location=None, instance_id=None, call=None, kwargs=None)

  Show the console output from the instance.

  By default, returns decoded data, not the Base64-encoded data that is actually returned from the EC2 API.

salt.cloud.clouds.ec2.get_dependencies()

  Warn if dependencies aren't met.

salt.cloud.clouds.ec2.get_imageid(vm_)

  Returns the ImageId to use

salt.cloud.clouds.ec2.get_location(vm_=None)
  Return the EC2 region to use, in this order:

    - CLI parameter

    - VM parameter

    - Cloud profile setting

salt.cloud.clouds.ec2.get_password_data(name=None, kwargs=None, instance_id=None, call=None)

  Return password data for a Windows instance.

  By default only the encrypted password data will be returned. However, if a key_file is passed in, then a decrypted password will also be returned.

  Note that the key_file references the private key that was used to generate the keypair associated with this instance. This private key will _not_ be transmitted to Amazon; it is only used internally inside of Salt Cloud to decrypt data _after_ it has been received from Amazon.

  CLI Examples:

      salt-cloud -a get_password_data mymachine
      salt-cloud -a get_password_data mymachine key_file=/root/ec2key.pem

  Note: PKCS1_v1_5 was added in PyCrypto 2.5

salt.cloud.clouds.ec2.get_placementgroup(vm_)

  Returns the PlacementGroup to use

salt.cloud.clouds.ec2.get_provider(vm_=None)

  Extract the provider name from vm

salt.cloud.clouds.ec2.get_spot_config(vm_)

  Returns the spot instance configuration for the provided vm

salt.cloud.clouds.ec2.get_ssh_gateway_config(vm_)

  Return the ssh_gateway configuration.

salt.cloud.clouds.ec2.get_subnetid(vm_)

  Returns the SubnetId to use

salt.cloud.clouds.ec2.get_tags(name=None, instance_id=None, call=None, location=None, kwargs=None, resource_id=None)

  Retrieve tags for a resource. Normally a VM name or instance_id is passed in, but a resource_id may be passed instead. If both are passed in, the instance_id will be used.

  CLI Examples:

      salt-cloud -a get_tags mymachine
      salt-cloud -a get_tags resource_id=vol-3267ab32

salt.cloud.clouds.ec2.get_tenancy(vm_)

  Returns the Tenancy to use.

  Can be "dedicated" or "default". Cannot be present for spot instances.

salt.cloud.clouds.ec2.iam_profile(vm_)

  Return the IAM profile.

  The IAM instance profile to associate with the instances. This is either the Amazon Resource Name (ARN) of the instance profile or the name of the role.

  Type: String

  Default: None

  Required: No

  Example: arn:aws:iam::111111111111:instance-profile/s3access

  Example: s3access

salt.cloud.clouds.ec2.import_keypair(kwargs=None, call=None)

  Import an SSH public key.

  New in version 2015.8.3.

salt.cloud.clouds.ec2.keepvol_on_destroy(name, kwargs=None, call=None)

  Do not delete all/specified EBS volumes upon instance termination

  CLI Example:

      salt-cloud -a keepvol_on_destroy mymachine

salt.cloud.clouds.ec2.keyname(vm_)

  Return the keyname

salt.cloud.clouds.ec2.list_availability_zones(vm_=None)

  List all availability zones in the current region

salt.cloud.clouds.ec2.list_nodes(call=None)

  Return a list of the VMs that are on the provider

salt.cloud.clouds.ec2.list_nodes_full(location=None, call=None)

  Return a list of the VMs that are on the provider

salt.cloud.clouds.ec2.list_nodes_min(location=None, call=None)

  Return a list of the VMs that are on the provider. Only a list of VM names, and their state, is returned. This is the minimum amount of information needed to check for existing VMs.

salt.cloud.clouds.ec2.list_nodes_select(call=None)

  Return a list of the VMs that are on the provider, with select fields

salt.cloud.clouds.ec2.optimize_providers(providers)

  Return an optimized list of providers.

  We want to reduce the duplication of querying the same region.

  If a provider is using the same credentials for the same region the same data will be returned for each provider, thus causing un-wanted duplicate data and API calls to EC2.

salt.cloud.clouds.ec2.query(params=None, setname=None, requesturl=None, location=None, return_url=False, return_root=False)

salt.cloud.clouds.ec2.query_instance(vm_=None, call=None)

  Query an instance upon creation from the EC2 API

salt.cloud.clouds.ec2.queue_instances(instances)

  Queue a set of instances to be provisioned later. Expects a list.

  Currently this only queries node data, and then places it in the cloud cache (if configured). If the salt-cloud-reactor is being used, these instances will be automatically provisioned using that.

  For more information about the salt-cloud-reactor, see:

  https://github.com/saltstack-formulas/salt-cloud-reactor

salt.cloud.clouds.ec2.reboot(name, call=None)

  Reboot a node.

  CLI Example:

      salt-cloud -a reboot mymachine

salt.cloud.clouds.ec2.register_image(kwargs=None, call=None)

  Create an ami from a snapshot

  CLI Example:

      salt-cloud -f register_image my-ec2-config ami_name=my_ami description="my description"
              root_device_name=/dev/xvda snapshot_id=snap-xxxxxxxx

salt.cloud.clouds.ec2.rename(name, kwargs, call=None)

  Properly rename a node. Pass in the new name as "new name".

  CLI Example:

      salt-cloud -a rename mymachine newname=yourmachine

salt.cloud.clouds.ec2.request_instance(vm_=None, call=None)

  Put together all of the information necessary to request an instance on EC2, and then fire off the request the instance.

  Returns data about the instance

salt.cloud.clouds.ec2.script(vm_)

  Return the script deployment object

salt.cloud.clouds.ec2.securitygroup(vm_)

  Return the security group

salt.cloud.clouds.ec2.securitygroupid(vm_)

  Returns the SecurityGroupId

salt.cloud.clouds.ec2.set_tags(name=None, tags=None, call=None, location=None, instance_id=None, resource_id=None, kwargs=None)

  Set tags for a resource. Normally a VM name or instance_id is passed in, but a resource_id may be passed instead. If both are passed in, the instance_id will be used.

  CLI Examples:

      salt-cloud -a set_tags mymachine tag1=somestuff tag2='Other stuff'
      salt-cloud -a set_tags resource_id=vol-3267ab32 tag=somestuff

salt.cloud.clouds.ec2.show_delvol_on_destroy(name, kwargs=None, call=None)

  Do not delete all/specified EBS volumes upon instance termination

  CLI Example:

      salt-cloud -a show_delvol_on_destroy mymachine

salt.cloud.clouds.ec2.show_detailed_monitoring(name=None, instance_id=None, call=None, quiet=False)

  Show the details from EC2 regarding cloudwatch detailed monitoring.

salt.cloud.clouds.ec2.show_image(kwargs, call=None)

  Show the details from EC2 concerning an AMI

salt.cloud.clouds.ec2.show_instance(name=None, instance_id=None, call=None, kwargs=None)

  Show the details from EC2 concerning an AMI.

  Can be called as an action (which requires a name):

      salt-cloud -a show_instance myinstance

  ...or as a function (which requires either a name or instance_id):

      salt-cloud -f show_instance my-ec2 name=myinstance
      salt-cloud -f show_instance my-ec2 instance_id=i-d34db33f

salt.cloud.clouds.ec2.show_keypair(kwargs=None, call=None)

  Show the details of an SSH keypair

salt.cloud.clouds.ec2.show_pricing(kwargs=None, call=None)

  Show pricing for a particular profile. This is only an estimate, based on unofficial pricing sources.

  CLI Examples:

      salt-cloud -f show_pricing my-ec2-config profile=my-profile

  If pricing sources have not been cached, they will be downloaded. Once they have been cached, they will not be updated automatically. To manually update all prices, use the following command:

      salt-cloud -f update_pricing <provider>

  New in version 2015.8.0.

salt.cloud.clouds.ec2.show_term_protect(name=None, instance_id=None, call=None, quiet=False)

  Show the details from EC2 concerning an instance's termination protection state

salt.cloud.clouds.ec2.show_volume(kwargs=None, call=None)

  Wrapper around describe_volumes. Here just to keep functionality. Might be depreciated later.

salt.cloud.clouds.ec2.sign(key, msg)

salt.cloud.clouds.ec2.ssh_interface(vm_)

  Return the ssh_interface type to connect to. Either 'public_ips' (default) or 'private_ips'.

salt.cloud.clouds.ec2.ssm_create_association(name=None, kwargs=None, instance_id=None, call=None)

  Associates the specified SSM document with the specified instance

  http://docs.aws.amazon.com/ssm/latest/APIReference/API_CreateAssociation.html

  CLI Examples:

      salt-cloud -a ssm_create_association ec2-instance-name ssm_document=ssm-document-name

salt.cloud.clouds.ec2.ssm_describe_association(name=None, kwargs=None, instance_id=None, call=None)

  Describes the associations for the specified SSM document or instance.

  http://docs.aws.amazon.com/ssm/latest/APIReference/API_DescribeAssociation.html

  CLI Examples:

      salt-cloud -a ssm_describe_association ec2-instance-name ssm_document=ssm-document-name

salt.cloud.clouds.ec2.start(name, call=None)

  Start a node

salt.cloud.clouds.ec2.stop(name, call=None)

  Stop a node

salt.cloud.clouds.ec2.update_pricing(kwargs=None, call=None)

  Download most recent pricing information from AWS and convert to a local JSON file.

  CLI Examples:

      salt-cloud -f update_pricing my-ec2-config
      salt-cloud -f update_pricing my-ec2-config type=linux

  New in version 2015.8.0.

salt.cloud.clouds.ec2.volume_create(**kwargs)

  Wrapper around create_volume. Here just to ensure the compatibility with the cloud module.

salt.cloud.clouds.ec2.volume_list(**kwargs)

  Wrapper around describe_volumes. Here just to ensure the compatibility with the cloud module.

salt.cloud.clouds.ec2.wait_for_instance(vm_=None, data=None, ip_address=None, display_ssh_output=True, call=None)

  Wait for an instance upon creation from the EC2 API, to become available