1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192939495969798991001011021031041051061071081091101111121131141151161171181191201211221231241251261271281291301311321331341351361371381391401411421431441451461471481491501511521531541551561571581591601611621631641651661671681691701711721731741751761771781791801811821831841851861871881891901911921931941951961971981992002012022032042052062072082092102112122132142152162172182192202212222232242252262272282292302312322332342352362372382392402412422432442452462472482492502512522532542552562572582592602612622632642652662672682692702712722732742752762772782792802812822832842852862872882892902912922932942952962972982993003013023033043053063073083093103113123133143153163173183193203213223233243253263273283293303313323333343353363373383393403413423433443453463473483493503513523533543553563573583593603613623633643653663673683693703713723733743753763773783793803813823833843853863873883893903913923933943953963973983994004014024034044054064074084094104114124134144154164174184194204214224234244254264274284294304314324334344354364374384394404414424434444454464474484494504514524534544554564574584594604614624634644654664674684694704714724734744754764774784794804814824834844854864874884894904914924934944954964974984995005015025035045055065075085095105115125135145155165175185195205215225235245255265275285295305315325335345355365375385395405415425435445455465475485495505515525535545555565575585595605615625635645655665675685695705715725735745755765775785795805815825835845855865875885895905915925935945955965975985996006016026036046056066076086096106116126136146156166176186196206216226236246256266276286296306316326336346356366376386396406416426436446456466476486496506516526536546556566576586596606616626636646656666676686696706716726736746756766776786796806816826836846856866876886896906916926936946956966976986997007017027037047057067077087097107117127137147157167177187197207217227237247257267277287297307317327337347357367377387397407417427437447457467477487497507517527537547557567577587597607617627637647657667677687697707717727737747757767777787797807817827837847857867877887897907917927937947957967977987998008018028038048058068078088098108118128138148158168178188198208218228238248258268278288298308318328338348358368378388398408418428438448458468478488498508518528538548558568578588598608618628638648658668678688698708718728738748758768778788798808818828838848858868878888898908918928938948958968978988999009019029039049059069079089099109119129139149159169179189199209219229239249259269279289299309319329339349359369379389399409419429439449459469479489499509519529539549559569579589599609619629639649659669679689699709719729739749759769779789799809819829839849859869879889899909919929939949959969979989991000100110021003100410051006100710081009101010111012101310141015101610171018101910201021102210231024102510261027102810291030103110321033103410351036103710381039104010411042104310441045104610471048104910501051105210531054105510561057105810591060106110621063106410651066106710681069107010711072107310741075107610771078107910801081108210831084108510861087108810891090 |
- ============================
- Getting Started With AWS EC2
- ============================
- Amazon EC2 is a very widely used public cloud platform and one of the core
- platforms Salt Cloud has been built to support.
- Previously, the suggested driver for AWS EC2 was the ``aws`` driver. This
- has been deprecated in favor of the ``ec2`` driver. Configuration using the
- old ``aws`` driver will still function, but that driver is no longer in
- active development.
- Dependencies
- ============
- This driver requires the Python ``requests`` library to be installed.
- Configuration
- =============
- The following example illustrates some of the options that can be set. These
- parameters are discussed in more detail below.
- .. code-block:: yaml
- # Note: This example is for /etc/salt/cloud.providers or any file in the
- # /etc/salt/cloud.providers.d/ directory.
- my-ec2-southeast-public-ips:
- # Set up the location of the salt master
- #
- minion:
- master: saltmaster.example.com
- # Set up grains information, which will be common for all nodes
- # using this provider
- grains:
- node_type: broker
- release: 1.0.1
- # Specify whether to use public or private IP for deploy script.
- #
- # Valid options are:
- # private_ips - The salt-cloud command is run inside the EC2
- # public_ips - The salt-cloud command is run outside of EC2
- #
- ssh_interface: public_ips
- # Optionally configure the Windows credential validation number of
- # retries and delay between retries. This defaults to 10 retries
- # with a one second delay betwee retries
- win_deploy_auth_retries: 10
- win_deploy_auth_retry_delay: 1
- # Set the EC2 access credentials (see below)
- #
- id: 'use-instance-role-credentials'
- key: 'use-instance-role-credentials'
- # Make sure this key is owned by corresponding user (default 'salt') with permissions 0400.
- #
- private_key: /etc/salt/my_test_key.pem
- keyname: my_test_key
- securitygroup: default
- # Optionally configure default region
- # Use salt-cloud --list-locations <provider> to obtain valid regions
- #
- location: ap-southeast-1
- availability_zone: ap-southeast-1b
- # Configure which user to use to run the deploy script. This setting is
- # dependent upon the AMI that is used to deploy. It is usually safer to
- # configure this individually in a profile, than globally. Typical users
- # are:
- #
- # Amazon Linux -> ec2-user
- # RHEL -> ec2-user
- # CentOS -> ec2-user
- # Ubuntu -> ubuntu
- # Debian -> admin
- #
- ssh_username: ec2-user
- # Optionally add an IAM profile
- iam_profile: 'arn:aws:iam::123456789012:instance-profile/ExampleInstanceProfile'
- driver: ec2
- my-ec2-southeast-private-ips:
- # Set up the location of the salt master
- #
- minion:
- master: saltmaster.example.com
- # Specify whether to use public or private IP for deploy script.
- #
- # Valid options are:
- # private_ips - The salt-master is also hosted with EC2
- # public_ips - The salt-master is hosted outside of EC2
- #
- ssh_interface: private_ips
- # Optionally configure the Windows credential validation number of
- # retries and delay between retries. This defaults to 10 retries
- # with a one second delay betwee retries
- win_deploy_auth_retries: 10
- win_deploy_auth_retry_delay: 1
- # Set the EC2 access credentials (see below)
- #
- id: 'use-instance-role-credentials'
- key: 'use-instance-role-credentials'
- # Make sure this key is owned by root with permissions 0400.
- #
- private_key: /etc/salt/my_test_key.pem
- keyname: my_test_key
- # This one should NOT be specified if VPC was not configured in AWS to be
- # the default. It might cause an error message which says that network
- # interfaces and an instance-level security groups may not be specified
- # on the same request.
- #
- securitygroup: default
- # Optionally configure default region
- #
- location: ap-southeast-1
- availability_zone: ap-southeast-1b
- # Configure which user to use to run the deploy script. This setting is
- # dependent upon the AMI that is used to deploy. It is usually safer to
- # configure this individually in a profile, than globally. Typical users
- # are:
- #
- # Amazon Linux -> ec2-user
- # RHEL -> ec2-user
- # CentOS -> ec2-user
- # Ubuntu -> ubuntu
- #
- ssh_username: ec2-user
- # Optionally add an IAM profile
- iam_profile: 'my other profile name'
- driver: ec2
- .. note::
- .. versionchanged:: 2015.8.0
- The ``provider`` parameter in cloud provider definitions was renamed to ``driver``. This
- change was made to avoid confusion with the ``provider`` parameter that is used in cloud profile
- definitions. Cloud provider definitions now use ``driver`` to refer to the Salt cloud module that
- provides the underlying functionality to connect to a cloud host, while cloud profiles continue
- to use ``provider`` to refer to provider configurations that you define.
- Access Credentials
- ==================
- The ``id`` and ``key`` settings may be found in the Security Credentials area
- of the AWS Account page:
- https://portal.aws.amazon.com/gp/aws/securityCredentials
- Both are located in the Access Credentials area of the page, under the Access
- Keys tab. The ``id`` setting is labeled Access Key ID, and the ``key`` setting
- is labeled Secret Access Key.
- Note: if either ``id`` or ``key`` is set to 'use-instance-role-credentials' it is
- assumed that Salt is running on an AWS instance, and the instance role
- credentials will be retrieved and used. Since both the ``id`` and ``key`` are
- required parameters for the AWS ec2 provider, it is recommended to set both
- to 'use-instance-role-credentials' for this functionality.
- A "static" and "permanent" Access Key ID and Secret Key can be specified,
- but this is not recommended. Instance role keys are rotated on a regular
- basis, and are the recommended method of specifying AWS credentials.
- Windows Deploy Timeouts
- =======================
- For Windows instances, it may take longer than normal for the instance to be
- ready. In these circumstances, the provider configuration can be configured
- with a ``win_deploy_auth_retries`` and/or a ``win_deploy_auth_retry_delay``
- setting, which default to 10 retries and a one second delay between retries.
- These retries and timeouts relate to validating the Administrator password
- once AWS provides the credentials via the AWS API.
- Key Pairs
- =========
- In order to create an instance with Salt installed and configured, a key pair
- will need to be created. This can be done in the EC2 Management Console, in the
- Key Pairs area. These key pairs are unique to a specific region. Keys in the
- us-east-1 region can be configured at:
- https://console.aws.amazon.com/ec2/home?region=us-east-1#s=KeyPairs
- Keys in the us-west-1 region can be configured at
- https://console.aws.amazon.com/ec2/home?region=us-west-1#s=KeyPairs
- ...and so on. When creating a key pair, the browser will prompt to download a
- pem file. This file must be placed in a directory accessible by Salt Cloud,
- with permissions set to either 0400 or 0600.
- Security Groups
- ===============
- An instance on EC2 needs to belong to a security group. Like key pairs, these
- are unique to a specific region. These are also configured in the EC2
- Management Console. Security groups for the us-east-1 region can be configured
- at:
- https://console.aws.amazon.com/ec2/home?region=us-east-1#s=SecurityGroups
- ...and so on.
- A security group defines firewall rules which an instance will adhere to. If
- the salt-master is configured outside of EC2, the security group must open the
- SSH port (usually port 22) in order for Salt Cloud to install Salt.
- IAM Profile
- ===========
- Amazon EC2 instances support the concept of an `instance profile`_, which
- is a logical container for the IAM role. At the time that you launch an EC2
- instance, you can associate the instance with an instance profile, which in
- turn corresponds to the IAM role. Any software that runs on the EC2 instance
- is able to access AWS using the permissions associated with the IAM role.
- Scaffolding the profile is a 2-step configuration process:
- 1. Configure an IAM Role from the `IAM Management Console`_.
- 2. Attach this role to a new profile. It can be done with the `AWS CLI`_:
- .. code-block:: bash
- > aws iam create-instance-profile --instance-profile-name PROFILE_NAME
- > aws iam add-role-to-instance-profile --instance-profile-name PROFILE_NAME --role-name ROLE_NAME
- Once the profile is created, you can use the **PROFILE_NAME** to configure
- your cloud profiles.
- .. _`IAM Management Console`: https://console.aws.amazon.com/iam/home?#roles
- .. _`AWS CLI`: http://docs.aws.amazon.com/cli/latest/index.html
- .. _`instance profile`: http://docs.aws.amazon.com/IAM/latest/UserGuide/instance-profiles.html
- Cloud Profiles
- ==============
- Set up an initial profile at ``/etc/salt/cloud.profiles``:
- .. code-block:: yaml
- base_ec2_private:
- provider: my-ec2-southeast-private-ips
- image: ami-e565ba8c
- size: t2.micro
- ssh_username: ec2-user
- base_ec2_public:
- provider: my-ec2-southeast-public-ips
- image: ami-e565ba8c
- size: t2.micro
- ssh_username: ec2-user
- base_ec2_db:
- provider: my-ec2-southeast-public-ips
- image: ami-e565ba8c
- size: m1.xlarge
- ssh_username: ec2-user
- volumes:
- - { size: 10, device: /dev/sdf }
- - { size: 10, device: /dev/sdg, type: io1, iops: 1000 }
- - { size: 10, device: /dev/sdh, type: io1, iops: 1000 }
- - { size: 10, device: /dev/sdi, tags: {"Environment": "production"} }
- # optionally add tags to profile:
- tag: {'Environment': 'production', 'Role': 'database'}
- # force grains to sync after install
- sync_after_install: grains
- base_ec2_vpc:
- provider: my-ec2-southeast-public-ips
- image: ami-a73264ce
- size: m1.xlarge
- ssh_username: ec2-user
- script: /etc/salt/cloud.deploy.d/user_data.sh
- network_interfaces:
- - DeviceIndex: 0
- PrivateIpAddresses:
- - Primary: True
- #auto assign public ip (not EIP)
- AssociatePublicIpAddress: True
- SubnetId: subnet-813d4bbf
- SecurityGroupId:
- - sg-750af413
- del_root_vol_on_destroy: True
- del_all_vol_on_destroy: True
- volumes:
- - { size: 10, device: /dev/sdf }
- - { size: 10, device: /dev/sdg, type: io1, iops: 1000 }
- - { size: 10, device: /dev/sdh, type: io1, iops: 1000 }
- tag: {'Environment': 'production', 'Role': 'database'}
- sync_after_install: grains
- The profile can now be realized with a salt command:
- .. code-block:: bash
- # salt-cloud -p base_ec2 ami.example.com
- # salt-cloud -p base_ec2_public ami.example.com
- # salt-cloud -p base_ec2_private ami.example.com
- This will create an instance named ``ami.example.com`` in EC2. The minion that
- is installed on this instance will have an ``id`` of ``ami.example.com``. If
- the command was executed on the salt-master, its Salt key will automatically be
- signed on the master.
- Once the instance has been created with salt-minion installed, connectivity to
- it can be verified with Salt:
- .. code-block:: bash
- # salt 'ami.example.com' test.version
- Required Settings
- =================
- The following settings are always required for EC2:
- .. code-block:: yaml
- # Set the EC2 login data
- my-ec2-config:
- id: HJGRYCILJLKJYG
- key: 'kdjgfsgm;woormgl/aserigjksjdhasdfgn'
- keyname: test
- securitygroup: quick-start
- private_key: /root/test.pem
- driver: ec2
- Optional Settings
- =================
- EC2 allows a userdata file to be passed to the instance to be created. This
- functionality was added to Salt in the 2015.5.0 release.
- .. code-block:: yaml
- my-ec2-config:
- # Pass userdata to the instance to be created
- userdata_file: /etc/salt/my-userdata-file
- .. note::
- From versions 2016.11.0 and 2016.11.3, this file was passed through the
- master's :conf_master:`renderer` to template it. However, this caused
- issues with non-YAML data, so templating is no longer performed by default.
- To template the userdata_file, add a ``userdata_template`` option to the
- cloud profile:
- .. code-block:: yaml
- my-ec2-config:
- # Pass userdata to the instance to be created
- userdata_file: /etc/salt/my-userdata-file
- userdata_template: jinja
- If no ``userdata_template`` is set in the cloud profile, then the master
- configuration will be checked for a :conf_master:`userdata_template` value.
- If this is not set, then no templating will be performed on the
- userdata_file.
- To disable templating in a cloud profile when a
- :conf_master:`userdata_template` has been set in the master configuration
- file, simply set ``userdata_template`` to ``False`` in the cloud profile:
- .. code-block:: yaml
- my-ec2-config:
- # Pass userdata to the instance to be created
- userdata_file: /etc/salt/my-userdata-file
- userdata_template: False
- EC2 allows a location to be set for servers to be deployed in. Availability
- zones exist inside regions, and may be added to increase specificity.
- .. code-block:: yaml
- my-ec2-config:
- # Optionally configure default region
- location: ap-southeast-1
- availability_zone: ap-southeast-1b
- EC2 instances can have a public or private IP, or both. When an instance is
- deployed, Salt Cloud needs to log into it via SSH to run the deploy script.
- By default, the public IP will be used for this. If the salt-cloud command is
- run from another EC2 instance, the private IP should be used.
- .. code-block:: yaml
- my-ec2-config:
- # Specify whether to use public or private IP for deploy script
- # private_ips or public_ips
- ssh_interface: public_ips
- Many EC2 instances do not allow remote access to the root user by default.
- Instead, another user must be used to run the deploy script using sudo. Some
- common usernames include ec2-user (for Amazon Linux), ubuntu (for Ubuntu
- instances), admin (official Debian) and bitnami (for images provided by
- Bitnami).
- .. code-block:: yaml
- my-ec2-config:
- # Configure which user to use to run the deploy script
- ssh_username: ec2-user
- Multiple usernames can be provided, in which case Salt Cloud will attempt to
- guess the correct username. This is mostly useful in the main configuration
- file:
- .. code-block:: yaml
- my-ec2-config:
- ssh_username:
- - ec2-user
- - ubuntu
- - admin
- - bitnami
- Multiple security groups can also be specified in the same fashion:
- .. code-block:: yaml
- my-ec2-config:
- securitygroup:
- - default
- - extra
- EC2 instances can be added to an `AWS Placement Group`_ by specifying the
- ``placementgroup`` option:
- .. code-block:: yaml
- my-ec2-config:
- placementgroup: my-aws-placement-group
- .. _`AWS Placement Group`: http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/placement-groups.html
- Your instances may optionally make use of EC2 Spot Instances. The
- following example will request that spot instances be used and your
- maximum bid will be $0.10. Keep in mind that different spot prices
- may be needed based on the current value of the various EC2 instance
- sizes. You can check current and past spot instance pricing via the
- EC2 API or AWS Console.
- .. code-block:: yaml
- my-ec2-config:
- spot_config:
- spot_price: 0.10
- By default, the spot instance type is set to 'one-time', meaning it will
- be launched and, if it's ever terminated for whatever reason, it will not
- be recreated. If you would like your spot instances to be relaunched after
- a termination (by you or AWS), set the ``type`` to 'persistent'.
- NOTE: Spot instances are a great way to save a bit of money, but you do
- run the risk of losing your spot instances if the current price for the
- instance size goes above your maximum bid.
- The following parameters may be set in the cloud configuration file to
- control various aspects of the spot instance launching:
- * ``wait_for_spot_timeout``: seconds to wait before giving up on spot instance
- launch (default=600)
- * ``wait_for_spot_interval``: seconds to wait in between polling requests to
- determine if a spot instance is available (default=30)
- * ``wait_for_spot_interval_multiplier``: a multiplier to add to the interval in
- between requests, which is useful if AWS is throttling your requests
- (default=1)
- * ``wait_for_spot_max_failures``: maximum number of failures before giving up
- on launching your spot instance (default=10)
- If you find that you're being throttled by AWS while polling for spot
- instances, you can set the following in your core cloud configuration
- file that will double the polling interval after each request to AWS.
- .. code-block:: yaml
- wait_for_spot_interval: 1
- wait_for_spot_interval_multiplier: 2
- See the `AWS Spot Instances`_ documentation for more information.
- Block device mappings enable you to specify additional EBS volumes or instance
- store volumes when the instance is launched. This setting is also available on
- each cloud profile. Note that the number of instance stores varies by instance
- type. If more mappings are provided than are supported by the instance type,
- mappings will be created in the order provided and additional mappings will be
- ignored. Consult the `AWS documentation`_ for a listing of the available
- instance stores, and device names.
- .. code-block:: yaml
- my-ec2-config:
- block_device_mappings:
- - DeviceName: /dev/sdb
- VirtualName: ephemeral0
- - DeviceName: /dev/sdc
- VirtualName: ephemeral1
- You can also use block device mappings to change the size of the root device at the
- provisioning time. For example, assuming the root device is '/dev/sda', you can set
- its size to 100G by using the following configuration.
- .. code-block:: yaml
- my-ec2-config:
- block_device_mappings:
- - DeviceName: /dev/sda
- Ebs.VolumeSize: 100
- Ebs.VolumeType: gp2
- Ebs.SnapshotId: dummy0
- - DeviceName: /dev/sdb
- # required for devices > 2TB
- Ebs.VolumeType: gp2
- Ebs.VolumeSize: 3001
- Existing EBS volumes may also be attached (not created) to your instances or
- you can create new EBS volumes based on EBS snapshots. To simply attach an
- existing volume use the ``volume_id`` parameter.
- .. code-block:: yaml
- device: /dev/xvdj
- volume_id: vol-12345abcd
- Or, to create a volume from an EBS snapshot, use the ``snapshot`` parameter.
- .. code-block:: yaml
- device: /dev/xvdj
- snapshot: snap-abcd12345
- Note that ``volume_id`` will take precedence over the ``snapshot`` parameter.
- Tags can be set once an instance has been launched.
- .. code-block:: yaml
- my-ec2-config:
- tag:
- tag0: value
- tag1: value
- .. _`AWS documentation`: http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/InstanceStorage.html
- .. _`AWS Spot Instances`: http://aws.amazon.com/ec2/purchasing-options/spot-instances/
- Setting up a Master inside EC2
- ------------------------------
- Salt Cloud can configure Salt Masters as well as Minions. Use the ``make_master`` setting to use
- this functionality.
- .. code-block:: yaml
- my-ec2-config:
- # Optionally install a Salt Master in addition to the Salt Minion
- make_master: True
- When creating a Salt Master inside EC2 with ``make_master: True``, or when the Salt Master is already
- located and configured inside EC2, by default, minions connect to the master's public IP address during
- Salt Cloud's provisioning process. Depending on how your security groups are defined, the minions
- may or may not be able to communicate with the master. In order to use the master's private IP in EC2
- instead of the public IP, set the ``salt_interface`` to ``private_ips``.
- .. code-block:: yaml
- my-ec2-config:
- # Optionally set the IP configuration to private_ips
- salt_interface: private_ips
- Modify EC2 Tags
- ===============
- One of the features of EC2 is the ability to tag resources. In fact, under the
- hood, the names given to EC2 instances by salt-cloud are actually just stored
- as a tag called Name. Salt Cloud has the ability to manage these tags:
- .. code-block:: bash
- salt-cloud -a get_tags mymachine
- salt-cloud -a set_tags mymachine tag1=somestuff tag2='Other stuff'
- salt-cloud -a del_tags mymachine tag1,tag2,tag3
- It is possible to manage tags on any resource in EC2 with a Resource ID, not
- just instances:
- .. code-block:: bash
- salt-cloud -f get_tags my_ec2 resource_id=af5467ba
- salt-cloud -f set_tags my_ec2 resource_id=af5467ba tag1=somestuff
- salt-cloud -f del_tags my_ec2 resource_id=af5467ba tags=tag1,tag2,tag3
- Rename EC2 Instances
- ====================
- As mentioned above, EC2 instances are named via a tag. However, renaming an
- instance by renaming its tag will cause the salt keys to mismatch. A rename
- function exists which renames both the instance, and the salt keys.
- .. code-block:: bash
- salt-cloud -a rename mymachine newname=yourmachine
- Rename on Destroy
- =================
- When instances on EC2 are destroyed, there will be a lag between the time that
- the action is sent, and the time that Amazon cleans up the instance. During
- this time, the instance still retains a Name tag, which will cause a collision
- if the creation of an instance with the same name is attempted before the
- cleanup occurs. In order to avoid such collisions, Salt Cloud can be configured
- to rename instances when they are destroyed. The new name will look something
- like:
- .. code-block:: bash
- myinstance-DEL20f5b8ad4eb64ed88f2c428df80a1a0c
- In order to enable this, add rename_on_destroy line to the main
- configuration file:
- .. code-block:: yaml
- my-ec2-config:
- rename_on_destroy: True
- Listing Images
- ==============
- Normally, images can be queried on a cloud provider by passing the
- ``--list-images`` argument to Salt Cloud. This still holds true for EC2:
- .. code-block:: bash
- salt-cloud --list-images my-ec2-config
- However, the full list of images on EC2 is extremely large, and querying all of
- the available images may cause Salt Cloud to behave as if frozen. Therefore,
- the default behavior of this option may be modified, by adding an ``owner``
- argument to the provider configuration:
- .. code-block:: yaml
- owner: aws-marketplace
- The possible values for this setting are ``amazon``, ``aws-marketplace``,
- ``self``, ``<AWS account ID>`` or ``all``. The default setting is ``amazon``.
- Take note that ``all`` and ``aws-marketplace`` may cause Salt Cloud to appear
- as if it is freezing, as it tries to handle the large amount of data.
- It is also possible to perform this query using different settings without
- modifying the configuration files. To do this, call the ``avail_images``
- function directly:
- .. code-block:: bash
- salt-cloud -f avail_images my-ec2-config owner=aws-marketplace
- EC2 Images
- ==========
- The following are lists of available AMI images, generally sorted by OS. These
- lists are on 3rd-party websites, are not managed by Salt Stack in any way. They
- are provided here as a reference for those who are interested, and contain no
- warranty (express or implied) from anyone affiliated with Salt Stack. Most of
- them have never been used, much less tested, by the Salt Stack team.
- * `Arch Linux`__
- .. __: https://wiki.archlinux.org/index.php/Arch_Linux_AMIs_for_Amazon_Web_Services
- * `FreeBSD`__
- .. __: http://www.daemonology.net/freebsd-on-ec2/
- * `Fedora`__
- .. __: https://fedoraproject.org/wiki/Cloud_images
- * `CentOS`__
- .. __: http://wiki.centos.org/Cloud/AWS
- * `Ubuntu`__
- .. __: http://cloud-images.ubuntu.com/locator/ec2/
- * `Debian`__
- .. __: https://wiki.debian.org/Cloud/AmazonEC2Image
- * `OmniOS`__
- .. __: http://omnios.omniti.com/wiki.php/Installation#IntheCloud
- * `All Images on Amazon`__
- .. __: https://aws.amazon.com/marketplace
- show_image
- ==========
- This is a function that describes an AMI on EC2. This will give insight as to
- the defaults that will be applied to an instance using a particular AMI.
- .. code-block:: bash
- $ salt-cloud -f show_image ec2 image=ami-fd20ad94
- show_instance
- =============
- This action is a thin wrapper around ``--full-query``, which displays details on a
- single instance only. In an environment with several machines, this will save a
- user from having to sort through all instance data, just to examine a single
- instance.
- .. code-block:: bash
- $ salt-cloud -a show_instance myinstance
- ebs_optimized
- =============
- This argument enables switching of the EbsOptimized setting which default
- to 'false'. Indicates 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 Amazon EBS I/O performance. This
- optimization isn't available with all instance types. Additional usage
- charges apply when using an EBS-optimized instance.
- This setting can be added to the profile or map file for an instance.
- If set to True, this setting will enable an instance to be EbsOptimized
- .. code-block:: yaml
- ebs_optimized: True
- This can also be set as a cloud provider setting in the EC2 cloud
- configuration:
- .. code-block:: yaml
- my-ec2-config:
- ebs_optimized: True
- del_root_vol_on_destroy
- =======================
- This argument overrides the default DeleteOnTermination setting in the AMI for
- the EBS root volumes for an instance. Many AMIs contain 'false' as a default,
- resulting in orphaned volumes in the EC2 account, which may unknowingly be
- charged to the account. This setting can be added to the profile or map file
- for an instance.
- If set, this setting will apply to the root EBS volume
- .. code-block:: yaml
- del_root_vol_on_destroy: True
- This can also be set as a cloud provider setting in the EC2 cloud
- configuration:
- .. code-block:: yaml
- my-ec2-config:
- del_root_vol_on_destroy: True
- del_all_vols_on_destroy
- =======================
- This argument overrides the default DeleteOnTermination setting in the AMI for
- the not-root EBS volumes for an instance. Many AMIs contain 'false' as a
- default, resulting in orphaned volumes in the EC2 account, which may
- unknowingly be charged to the account. This setting can be added to the profile
- or map file for an instance.
- If set, this setting will apply to any (non-root) volumes that were created
- by salt-cloud using the 'volumes' setting.
- The volumes will not be deleted under the following conditions
- * If a volume is detached before terminating the instance
- * If a volume is created without this setting and attached to the instance
- .. code-block:: yaml
- del_all_vols_on_destroy: True
- This can also be set as a cloud provider setting in the EC2 cloud
- configuration:
- .. code-block:: yaml
- my-ec2-config:
- del_all_vols_on_destroy: True
- The setting for this may be changed on all volumes of an existing instance
- using one of the following commands:
- .. code-block:: bash
- salt-cloud -a delvol_on_destroy myinstance
- salt-cloud -a keepvol_on_destroy myinstance
- salt-cloud -a show_delvol_on_destroy myinstance
- The setting for this may be changed on a volume on an existing instance
- using one of the following commands:
- .. code-block:: bash
- salt-cloud -a delvol_on_destroy myinstance device=/dev/sda1
- salt-cloud -a delvol_on_destroy myinstance volume_id=vol-1a2b3c4d
- salt-cloud -a keepvol_on_destroy myinstance device=/dev/sda1
- salt-cloud -a keepvol_on_destroy myinstance volume_id=vol-1a2b3c4d
- salt-cloud -a show_delvol_on_destroy myinstance device=/dev/sda1
- salt-cloud -a show_delvol_on_destroy myinstance volume_id=vol-1a2b3c4d
- EC2 Termination Protection
- ==========================
- EC2 allows the user to enable and disable termination protection on a specific
- instance. An instance with this protection enabled cannot be destroyed. The EC2
- driver adds a show_term_protect action to the regular EC2 functionality.
- .. code-block:: bash
- salt-cloud -a show_term_protect mymachine
- salt-cloud -a enable_term_protect mymachine
- salt-cloud -a disable_term_protect mymachine
- Alternate Endpoint
- ==================
- Normally, EC2 endpoints are build using the region and the service_url. The
- resulting endpoint would follow this pattern:
- .. code-block:: bash
- ec2.<region>.<service_url>
- This results in an endpoint that looks like:
- .. code-block:: bash
- ec2.us-east-1.amazonaws.com
- There are other projects that support an EC2 compatibility layer, which this
- scheme does not account for. This can be overridden by specifying the endpoint
- directly in the main cloud configuration file:
- .. code-block:: yaml
- my-ec2-config:
- endpoint: myendpoint.example.com:1138/services/Cloud
- Volume Management
- =================
- The EC2 driver has several functions and actions for management of EBS volumes.
- Creating Volumes
- ----------------
- A volume may be created, independent of an instance. A zone must be specified.
- A size or a snapshot may be specified (in GiB). If neither is given, a default
- size of 10 GiB will be used. If a snapshot is given, the size of the snapshot
- will be used.
- The following parameters may also be set (when providing a snapshot OR size):
- * ``type``: choose between standard (magnetic disk), gp2 (SSD), or io1 (provisioned IOPS).
- (default=standard)
- * ``iops``: the number of IOPS (only applicable to io1 volumes) (default varies on volume size)
- * ``encrypted``: enable encryption on the volume (default=false)
- .. code-block:: bash
- salt-cloud -f create_volume ec2 zone=us-east-1b
- salt-cloud -f create_volume ec2 zone=us-east-1b size=10
- salt-cloud -f create_volume ec2 zone=us-east-1b snapshot=snap12345678
- salt-cloud -f create_volume ec2 size=10 type=standard
- salt-cloud -f create_volume ec2 size=10 type=gp2
- salt-cloud -f create_volume ec2 size=10 type=io1 iops=1000
- Attaching Volumes
- -----------------
- Unattached volumes may be attached to an instance. The following values are
- required; name or instance_id, volume_id, and device.
- .. code-block:: bash
- salt-cloud -a attach_volume myinstance volume_id=vol-12345 device=/dev/sdb1
- Show a Volume
- -------------
- The details about an existing volume may be retrieved.
- .. code-block:: bash
- salt-cloud -a show_volume myinstance volume_id=vol-12345
- salt-cloud -f show_volume ec2 volume_id=vol-12345
- Detaching Volumes
- -----------------
- An existing volume may be detached from an instance.
- .. code-block:: bash
- salt-cloud -a detach_volume myinstance volume_id=vol-12345
- Deleting Volumes
- ----------------
- A volume that is not attached to an instance may be deleted.
- .. code-block:: bash
- salt-cloud -f delete_volume ec2 volume_id=vol-12345
- Managing Key Pairs
- ==================
- The EC2 driver has the ability to manage key pairs.
- Creating a Key Pair
- -------------------
- A key pair is required in order to create an instance. When creating a key pair
- with this function, the return data will contain a copy of the private key.
- This private key is not stored by Amazon, will not be obtainable past this
- point, and should be stored immediately.
- .. code-block:: bash
- salt-cloud -f create_keypair ec2 keyname=mykeypair
- Importing a Key Pair
- --------------------
- .. code-block:: bash
- salt-cloud -f import_keypair ec2 keyname=mykeypair file=/path/to/id_rsa.pub
- Show a Key Pair
- ---------------
- This function will show the details related to a key pair, not including the
- private key itself (which is not stored by Amazon).
- .. code-block:: bash
- salt-cloud -f show_keypair ec2 keyname=mykeypair
- Delete a Key Pair
- -----------------
- This function removes the key pair from Amazon.
- .. code-block:: bash
- salt-cloud -f delete_keypair ec2 keyname=mykeypair
- Launching instances into a VPC
- ==============================
- Simple launching into a VPC
- ---------------------------
- In the amazon web interface, identify the id or the name of the subnet into
- which your image should be created. Then, edit your cloud.profiles file like
- so:-
- .. code-block:: yaml
- profile-id:
- provider: provider-name
- subnetid: subnet-XXXXXXXX
- image: ami-XXXXXXXX
- size: m1.medium
- ssh_username: ubuntu
- securitygroupid:
- - sg-XXXXXXXX
- securitygroupname:
- - AnotherSecurityGroup
- - AndThirdSecurityGroup
- Note that 'subnetid' takes precedence over 'subnetname', but 'securitygroupid'
- and 'securitygroupname' are merged together to generate a single list for
- SecurityGroups of instances.
- Specifying interface properties
- -------------------------------
- .. versionadded:: 2014.7.0
- Launching into a VPC allows you to specify more complex configurations for
- the network interfaces of your virtual machines, for example:-
- .. code-block:: yaml
- profile-id:
- provider: provider-name
- image: ami-XXXXXXXX
- size: m1.medium
- ssh_username: ubuntu
- # Do not include either 'subnetid', 'subnetname', 'securitygroupid' or
- # 'securitygroupname' here if you are going to manually specify
- # interface configuration
- #
- network_interfaces:
- - DeviceIndex: 0
- SubnetId: subnet-XXXXXXXX
- SecurityGroupId:
- - sg-XXXXXXXX
- # Uncomment this line if you would like to set an explicit private
- # IP address for the ec2 instance
- #
- # PrivateIpAddress: 192.168.1.66
- # Uncomment this to associate an existing Elastic IP Address with
- # this network interface:
- #
- # associate_eip: eipalloc-XXXXXXXX
- # You can allocate more than one IP address to an interface. Use the
- # 'ip addr list' command to see them.
- #
- # SecondaryPrivateIpAddressCount: 2
- # Uncomment this to allocate a new Elastic IP Address to this
- # interface (will be associated with the primary private ip address
- # of the interface
- #
- # allocate_new_eip: True
- # Uncomment this instead to allocate a new Elastic IP Address to
- # both the primary private ip address and each of the secondary ones
- #
- allocate_new_eips: True
- # Uncomment this if you're creating NAT instances. Allows an instance
- # to accept IP packets with destinations other than itself.
- # SourceDestCheck: False
- - DeviceIndex: 1
- subnetname: XXXXXXXX-Subnet
- securitygroupname:
- - XXXXXXXX-SecurityGroup
- - YYYYYYYY-SecurityGroup
- Note that it is an error to assign a 'subnetid', 'subnetname', 'securitygroupid'
- or 'securitygroupname' to a profile where the interfaces are manually configured
- like this. These are both really properties of each network interface, not of
- the machine itself.
|