aws.rst 34 KB

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192939495969798991001011021031041051061071081091101111121131141151161171181191201211221231241251261271281291301311321331341351361371381391401411421431441451461471481491501511521531541551561571581591601611621631641651661671681691701711721731741751761771781791801811821831841851861871881891901911921931941951961971981992002012022032042052062072082092102112122132142152162172182192202212222232242252262272282292302312322332342352362372382392402412422432442452462472482492502512522532542552562572582592602612622632642652662672682692702712722732742752762772782792802812822832842852862872882892902912922932942952962972982993003013023033043053063073083093103113123133143153163173183193203213223233243253263273283293303313323333343353363373383393403413423433443453463473483493503513523533543553563573583593603613623633643653663673683693703713723733743753763773783793803813823833843853863873883893903913923933943953963973983994004014024034044054064074084094104114124134144154164174184194204214224234244254264274284294304314324334344354364374384394404414424434444454464474484494504514524534544554564574584594604614624634644654664674684694704714724734744754764774784794804814824834844854864874884894904914924934944954964974984995005015025035045055065075085095105115125135145155165175185195205215225235245255265275285295305315325335345355365375385395405415425435445455465475485495505515525535545555565575585595605615625635645655665675685695705715725735745755765775785795805815825835845855865875885895905915925935945955965975985996006016026036046056066076086096106116126136146156166176186196206216226236246256266276286296306316326336346356366376386396406416426436446456466476486496506516526536546556566576586596606616626636646656666676686696706716726736746756766776786796806816826836846856866876886896906916926936946956966976986997007017027037047057067077087097107117127137147157167177187197207217227237247257267277287297307317327337347357367377387397407417427437447457467477487497507517527537547557567577587597607617627637647657667677687697707717727737747757767777787797807817827837847857867877887897907917927937947957967977987998008018028038048058068078088098108118128138148158168178188198208218228238248258268278288298308318328338348358368378388398408418428438448458468478488498508518528538548558568578588598608618628638648658668678688698708718728738748758768778788798808818828838848858868878888898908918928938948958968978988999009019029039049059069079089099109119129139149159169179189199209219229239249259269279289299309319329339349359369379389399409419429439449459469479489499509519529539549559569579589599609619629639649659669679689699709719729739749759769779789799809819829839849859869879889899909919929939949959969979989991000100110021003100410051006100710081009101010111012101310141015101610171018101910201021102210231024102510261027102810291030103110321033103410351036103710381039104010411042104310441045104610471048104910501051105210531054105510561057105810591060106110621063106410651066106710681069107010711072107310741075107610771078107910801081108210831084108510861087108810891090
  1. ============================
  2. Getting Started With AWS EC2
  3. ============================
  4. Amazon EC2 is a very widely used public cloud platform and one of the core
  5. platforms Salt Cloud has been built to support.
  6. Previously, the suggested driver for AWS EC2 was the ``aws`` driver. This
  7. has been deprecated in favor of the ``ec2`` driver. Configuration using the
  8. old ``aws`` driver will still function, but that driver is no longer in
  9. active development.
  10. Dependencies
  11. ============
  12. This driver requires the Python ``requests`` library to be installed.
  13. Configuration
  14. =============
  15. The following example illustrates some of the options that can be set. These
  16. parameters are discussed in more detail below.
  17. .. code-block:: yaml
  18. # Note: This example is for /etc/salt/cloud.providers or any file in the
  19. # /etc/salt/cloud.providers.d/ directory.
  20. my-ec2-southeast-public-ips:
  21. # Set up the location of the salt master
  22. #
  23. minion:
  24. master: saltmaster.example.com
  25. # Set up grains information, which will be common for all nodes
  26. # using this provider
  27. grains:
  28. node_type: broker
  29. release: 1.0.1
  30. # Specify whether to use public or private IP for deploy script.
  31. #
  32. # Valid options are:
  33. # private_ips - The salt-cloud command is run inside the EC2
  34. # public_ips - The salt-cloud command is run outside of EC2
  35. #
  36. ssh_interface: public_ips
  37. # Optionally configure the Windows credential validation number of
  38. # retries and delay between retries. This defaults to 10 retries
  39. # with a one second delay betwee retries
  40. win_deploy_auth_retries: 10
  41. win_deploy_auth_retry_delay: 1
  42. # Set the EC2 access credentials (see below)
  43. #
  44. id: 'use-instance-role-credentials'
  45. key: 'use-instance-role-credentials'
  46. # Make sure this key is owned by corresponding user (default 'salt') with permissions 0400.
  47. #
  48. private_key: /etc/salt/my_test_key.pem
  49. keyname: my_test_key
  50. securitygroup: default
  51. # Optionally configure default region
  52. # Use salt-cloud --list-locations <provider> to obtain valid regions
  53. #
  54. location: ap-southeast-1
  55. availability_zone: ap-southeast-1b
  56. # Configure which user to use to run the deploy script. This setting is
  57. # dependent upon the AMI that is used to deploy. It is usually safer to
  58. # configure this individually in a profile, than globally. Typical users
  59. # are:
  60. #
  61. # Amazon Linux -> ec2-user
  62. # RHEL -> ec2-user
  63. # CentOS -> ec2-user
  64. # Ubuntu -> ubuntu
  65. # Debian -> admin
  66. #
  67. ssh_username: ec2-user
  68. # Optionally add an IAM profile
  69. iam_profile: 'arn:aws:iam::123456789012:instance-profile/ExampleInstanceProfile'
  70. driver: ec2
  71. my-ec2-southeast-private-ips:
  72. # Set up the location of the salt master
  73. #
  74. minion:
  75. master: saltmaster.example.com
  76. # Specify whether to use public or private IP for deploy script.
  77. #
  78. # Valid options are:
  79. # private_ips - The salt-master is also hosted with EC2
  80. # public_ips - The salt-master is hosted outside of EC2
  81. #
  82. ssh_interface: private_ips
  83. # Optionally configure the Windows credential validation number of
  84. # retries and delay between retries. This defaults to 10 retries
  85. # with a one second delay betwee retries
  86. win_deploy_auth_retries: 10
  87. win_deploy_auth_retry_delay: 1
  88. # Set the EC2 access credentials (see below)
  89. #
  90. id: 'use-instance-role-credentials'
  91. key: 'use-instance-role-credentials'
  92. # Make sure this key is owned by root with permissions 0400.
  93. #
  94. private_key: /etc/salt/my_test_key.pem
  95. keyname: my_test_key
  96. # This one should NOT be specified if VPC was not configured in AWS to be
  97. # the default. It might cause an error message which says that network
  98. # interfaces and an instance-level security groups may not be specified
  99. # on the same request.
  100. #
  101. securitygroup: default
  102. # Optionally configure default region
  103. #
  104. location: ap-southeast-1
  105. availability_zone: ap-southeast-1b
  106. # Configure which user to use to run the deploy script. This setting is
  107. # dependent upon the AMI that is used to deploy. It is usually safer to
  108. # configure this individually in a profile, than globally. Typical users
  109. # are:
  110. #
  111. # Amazon Linux -> ec2-user
  112. # RHEL -> ec2-user
  113. # CentOS -> ec2-user
  114. # Ubuntu -> ubuntu
  115. #
  116. ssh_username: ec2-user
  117. # Optionally add an IAM profile
  118. iam_profile: 'my other profile name'
  119. driver: ec2
  120. .. note::
  121. .. versionchanged:: 2015.8.0
  122. The ``provider`` parameter in cloud provider definitions was renamed to ``driver``. This
  123. change was made to avoid confusion with the ``provider`` parameter that is used in cloud profile
  124. definitions. Cloud provider definitions now use ``driver`` to refer to the Salt cloud module that
  125. provides the underlying functionality to connect to a cloud host, while cloud profiles continue
  126. to use ``provider`` to refer to provider configurations that you define.
  127. Access Credentials
  128. ==================
  129. The ``id`` and ``key`` settings may be found in the Security Credentials area
  130. of the AWS Account page:
  131. https://portal.aws.amazon.com/gp/aws/securityCredentials
  132. Both are located in the Access Credentials area of the page, under the Access
  133. Keys tab. The ``id`` setting is labeled Access Key ID, and the ``key`` setting
  134. is labeled Secret Access Key.
  135. Note: if either ``id`` or ``key`` is set to 'use-instance-role-credentials' it is
  136. assumed that Salt is running on an AWS instance, and the instance role
  137. credentials will be retrieved and used. Since both the ``id`` and ``key`` are
  138. required parameters for the AWS ec2 provider, it is recommended to set both
  139. to 'use-instance-role-credentials' for this functionality.
  140. A "static" and "permanent" Access Key ID and Secret Key can be specified,
  141. but this is not recommended. Instance role keys are rotated on a regular
  142. basis, and are the recommended method of specifying AWS credentials.
  143. Windows Deploy Timeouts
  144. =======================
  145. For Windows instances, it may take longer than normal for the instance to be
  146. ready. In these circumstances, the provider configuration can be configured
  147. with a ``win_deploy_auth_retries`` and/or a ``win_deploy_auth_retry_delay``
  148. setting, which default to 10 retries and a one second delay between retries.
  149. These retries and timeouts relate to validating the Administrator password
  150. once AWS provides the credentials via the AWS API.
  151. Key Pairs
  152. =========
  153. In order to create an instance with Salt installed and configured, a key pair
  154. will need to be created. This can be done in the EC2 Management Console, in the
  155. Key Pairs area. These key pairs are unique to a specific region. Keys in the
  156. us-east-1 region can be configured at:
  157. https://console.aws.amazon.com/ec2/home?region=us-east-1#s=KeyPairs
  158. Keys in the us-west-1 region can be configured at
  159. https://console.aws.amazon.com/ec2/home?region=us-west-1#s=KeyPairs
  160. ...and so on. When creating a key pair, the browser will prompt to download a
  161. pem file. This file must be placed in a directory accessible by Salt Cloud,
  162. with permissions set to either 0400 or 0600.
  163. Security Groups
  164. ===============
  165. An instance on EC2 needs to belong to a security group. Like key pairs, these
  166. are unique to a specific region. These are also configured in the EC2
  167. Management Console. Security groups for the us-east-1 region can be configured
  168. at:
  169. https://console.aws.amazon.com/ec2/home?region=us-east-1#s=SecurityGroups
  170. ...and so on.
  171. A security group defines firewall rules which an instance will adhere to. If
  172. the salt-master is configured outside of EC2, the security group must open the
  173. SSH port (usually port 22) in order for Salt Cloud to install Salt.
  174. IAM Profile
  175. ===========
  176. Amazon EC2 instances support the concept of an `instance profile`_, which
  177. is a logical container for the IAM role. At the time that you launch an EC2
  178. instance, you can associate the instance with an instance profile, which in
  179. turn corresponds to the IAM role. Any software that runs on the EC2 instance
  180. is able to access AWS using the permissions associated with the IAM role.
  181. Scaffolding the profile is a 2-step configuration process:
  182. 1. Configure an IAM Role from the `IAM Management Console`_.
  183. 2. Attach this role to a new profile. It can be done with the `AWS CLI`_:
  184. .. code-block:: bash
  185. > aws iam create-instance-profile --instance-profile-name PROFILE_NAME
  186. > aws iam add-role-to-instance-profile --instance-profile-name PROFILE_NAME --role-name ROLE_NAME
  187. Once the profile is created, you can use the **PROFILE_NAME** to configure
  188. your cloud profiles.
  189. .. _`IAM Management Console`: https://console.aws.amazon.com/iam/home?#roles
  190. .. _`AWS CLI`: http://docs.aws.amazon.com/cli/latest/index.html
  191. .. _`instance profile`: http://docs.aws.amazon.com/IAM/latest/UserGuide/instance-profiles.html
  192. Cloud Profiles
  193. ==============
  194. Set up an initial profile at ``/etc/salt/cloud.profiles``:
  195. .. code-block:: yaml
  196. base_ec2_private:
  197. provider: my-ec2-southeast-private-ips
  198. image: ami-e565ba8c
  199. size: t2.micro
  200. ssh_username: ec2-user
  201. base_ec2_public:
  202. provider: my-ec2-southeast-public-ips
  203. image: ami-e565ba8c
  204. size: t2.micro
  205. ssh_username: ec2-user
  206. base_ec2_db:
  207. provider: my-ec2-southeast-public-ips
  208. image: ami-e565ba8c
  209. size: m1.xlarge
  210. ssh_username: ec2-user
  211. volumes:
  212. - { size: 10, device: /dev/sdf }
  213. - { size: 10, device: /dev/sdg, type: io1, iops: 1000 }
  214. - { size: 10, device: /dev/sdh, type: io1, iops: 1000 }
  215. - { size: 10, device: /dev/sdi, tags: {"Environment": "production"} }
  216. # optionally add tags to profile:
  217. tag: {'Environment': 'production', 'Role': 'database'}
  218. # force grains to sync after install
  219. sync_after_install: grains
  220. base_ec2_vpc:
  221. provider: my-ec2-southeast-public-ips
  222. image: ami-a73264ce
  223. size: m1.xlarge
  224. ssh_username: ec2-user
  225. script: /etc/salt/cloud.deploy.d/user_data.sh
  226. network_interfaces:
  227. - DeviceIndex: 0
  228. PrivateIpAddresses:
  229. - Primary: True
  230. #auto assign public ip (not EIP)
  231. AssociatePublicIpAddress: True
  232. SubnetId: subnet-813d4bbf
  233. SecurityGroupId:
  234. - sg-750af413
  235. del_root_vol_on_destroy: True
  236. del_all_vol_on_destroy: True
  237. volumes:
  238. - { size: 10, device: /dev/sdf }
  239. - { size: 10, device: /dev/sdg, type: io1, iops: 1000 }
  240. - { size: 10, device: /dev/sdh, type: io1, iops: 1000 }
  241. tag: {'Environment': 'production', 'Role': 'database'}
  242. sync_after_install: grains
  243. The profile can now be realized with a salt command:
  244. .. code-block:: bash
  245. # salt-cloud -p base_ec2 ami.example.com
  246. # salt-cloud -p base_ec2_public ami.example.com
  247. # salt-cloud -p base_ec2_private ami.example.com
  248. This will create an instance named ``ami.example.com`` in EC2. The minion that
  249. is installed on this instance will have an ``id`` of ``ami.example.com``. If
  250. the command was executed on the salt-master, its Salt key will automatically be
  251. signed on the master.
  252. Once the instance has been created with salt-minion installed, connectivity to
  253. it can be verified with Salt:
  254. .. code-block:: bash
  255. # salt 'ami.example.com' test.version
  256. Required Settings
  257. =================
  258. The following settings are always required for EC2:
  259. .. code-block:: yaml
  260. # Set the EC2 login data
  261. my-ec2-config:
  262. id: HJGRYCILJLKJYG
  263. key: 'kdjgfsgm;woormgl/aserigjksjdhasdfgn'
  264. keyname: test
  265. securitygroup: quick-start
  266. private_key: /root/test.pem
  267. driver: ec2
  268. Optional Settings
  269. =================
  270. EC2 allows a userdata file to be passed to the instance to be created. This
  271. functionality was added to Salt in the 2015.5.0 release.
  272. .. code-block:: yaml
  273. my-ec2-config:
  274. # Pass userdata to the instance to be created
  275. userdata_file: /etc/salt/my-userdata-file
  276. .. note::
  277. From versions 2016.11.0 and 2016.11.3, this file was passed through the
  278. master's :conf_master:`renderer` to template it. However, this caused
  279. issues with non-YAML data, so templating is no longer performed by default.
  280. To template the userdata_file, add a ``userdata_template`` option to the
  281. cloud profile:
  282. .. code-block:: yaml
  283. my-ec2-config:
  284. # Pass userdata to the instance to be created
  285. userdata_file: /etc/salt/my-userdata-file
  286. userdata_template: jinja
  287. If no ``userdata_template`` is set in the cloud profile, then the master
  288. configuration will be checked for a :conf_master:`userdata_template` value.
  289. If this is not set, then no templating will be performed on the
  290. userdata_file.
  291. To disable templating in a cloud profile when a
  292. :conf_master:`userdata_template` has been set in the master configuration
  293. file, simply set ``userdata_template`` to ``False`` in the cloud profile:
  294. .. code-block:: yaml
  295. my-ec2-config:
  296. # Pass userdata to the instance to be created
  297. userdata_file: /etc/salt/my-userdata-file
  298. userdata_template: False
  299. EC2 allows a location to be set for servers to be deployed in. Availability
  300. zones exist inside regions, and may be added to increase specificity.
  301. .. code-block:: yaml
  302. my-ec2-config:
  303. # Optionally configure default region
  304. location: ap-southeast-1
  305. availability_zone: ap-southeast-1b
  306. EC2 instances can have a public or private IP, or both. When an instance is
  307. deployed, Salt Cloud needs to log into it via SSH to run the deploy script.
  308. By default, the public IP will be used for this. If the salt-cloud command is
  309. run from another EC2 instance, the private IP should be used.
  310. .. code-block:: yaml
  311. my-ec2-config:
  312. # Specify whether to use public or private IP for deploy script
  313. # private_ips or public_ips
  314. ssh_interface: public_ips
  315. Many EC2 instances do not allow remote access to the root user by default.
  316. Instead, another user must be used to run the deploy script using sudo. Some
  317. common usernames include ec2-user (for Amazon Linux), ubuntu (for Ubuntu
  318. instances), admin (official Debian) and bitnami (for images provided by
  319. Bitnami).
  320. .. code-block:: yaml
  321. my-ec2-config:
  322. # Configure which user to use to run the deploy script
  323. ssh_username: ec2-user
  324. Multiple usernames can be provided, in which case Salt Cloud will attempt to
  325. guess the correct username. This is mostly useful in the main configuration
  326. file:
  327. .. code-block:: yaml
  328. my-ec2-config:
  329. ssh_username:
  330. - ec2-user
  331. - ubuntu
  332. - admin
  333. - bitnami
  334. Multiple security groups can also be specified in the same fashion:
  335. .. code-block:: yaml
  336. my-ec2-config:
  337. securitygroup:
  338. - default
  339. - extra
  340. EC2 instances can be added to an `AWS Placement Group`_ by specifying the
  341. ``placementgroup`` option:
  342. .. code-block:: yaml
  343. my-ec2-config:
  344. placementgroup: my-aws-placement-group
  345. .. _`AWS Placement Group`: http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/placement-groups.html
  346. Your instances may optionally make use of EC2 Spot Instances. The
  347. following example will request that spot instances be used and your
  348. maximum bid will be $0.10. Keep in mind that different spot prices
  349. may be needed based on the current value of the various EC2 instance
  350. sizes. You can check current and past spot instance pricing via the
  351. EC2 API or AWS Console.
  352. .. code-block:: yaml
  353. my-ec2-config:
  354. spot_config:
  355. spot_price: 0.10
  356. By default, the spot instance type is set to 'one-time', meaning it will
  357. be launched and, if it's ever terminated for whatever reason, it will not
  358. be recreated. If you would like your spot instances to be relaunched after
  359. a termination (by you or AWS), set the ``type`` to 'persistent'.
  360. NOTE: Spot instances are a great way to save a bit of money, but you do
  361. run the risk of losing your spot instances if the current price for the
  362. instance size goes above your maximum bid.
  363. The following parameters may be set in the cloud configuration file to
  364. control various aspects of the spot instance launching:
  365. * ``wait_for_spot_timeout``: seconds to wait before giving up on spot instance
  366. launch (default=600)
  367. * ``wait_for_spot_interval``: seconds to wait in between polling requests to
  368. determine if a spot instance is available (default=30)
  369. * ``wait_for_spot_interval_multiplier``: a multiplier to add to the interval in
  370. between requests, which is useful if AWS is throttling your requests
  371. (default=1)
  372. * ``wait_for_spot_max_failures``: maximum number of failures before giving up
  373. on launching your spot instance (default=10)
  374. If you find that you're being throttled by AWS while polling for spot
  375. instances, you can set the following in your core cloud configuration
  376. file that will double the polling interval after each request to AWS.
  377. .. code-block:: yaml
  378. wait_for_spot_interval: 1
  379. wait_for_spot_interval_multiplier: 2
  380. See the `AWS Spot Instances`_ documentation for more information.
  381. Block device mappings enable you to specify additional EBS volumes or instance
  382. store volumes when the instance is launched. This setting is also available on
  383. each cloud profile. Note that the number of instance stores varies by instance
  384. type. If more mappings are provided than are supported by the instance type,
  385. mappings will be created in the order provided and additional mappings will be
  386. ignored. Consult the `AWS documentation`_ for a listing of the available
  387. instance stores, and device names.
  388. .. code-block:: yaml
  389. my-ec2-config:
  390. block_device_mappings:
  391. - DeviceName: /dev/sdb
  392. VirtualName: ephemeral0
  393. - DeviceName: /dev/sdc
  394. VirtualName: ephemeral1
  395. You can also use block device mappings to change the size of the root device at the
  396. provisioning time. For example, assuming the root device is '/dev/sda', you can set
  397. its size to 100G by using the following configuration.
  398. .. code-block:: yaml
  399. my-ec2-config:
  400. block_device_mappings:
  401. - DeviceName: /dev/sda
  402. Ebs.VolumeSize: 100
  403. Ebs.VolumeType: gp2
  404. Ebs.SnapshotId: dummy0
  405. - DeviceName: /dev/sdb
  406. # required for devices > 2TB
  407. Ebs.VolumeType: gp2
  408. Ebs.VolumeSize: 3001
  409. Existing EBS volumes may also be attached (not created) to your instances or
  410. you can create new EBS volumes based on EBS snapshots. To simply attach an
  411. existing volume use the ``volume_id`` parameter.
  412. .. code-block:: yaml
  413. device: /dev/xvdj
  414. volume_id: vol-12345abcd
  415. Or, to create a volume from an EBS snapshot, use the ``snapshot`` parameter.
  416. .. code-block:: yaml
  417. device: /dev/xvdj
  418. snapshot: snap-abcd12345
  419. Note that ``volume_id`` will take precedence over the ``snapshot`` parameter.
  420. Tags can be set once an instance has been launched.
  421. .. code-block:: yaml
  422. my-ec2-config:
  423. tag:
  424. tag0: value
  425. tag1: value
  426. .. _`AWS documentation`: http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/InstanceStorage.html
  427. .. _`AWS Spot Instances`: http://aws.amazon.com/ec2/purchasing-options/spot-instances/
  428. Setting up a Master inside EC2
  429. ------------------------------
  430. Salt Cloud can configure Salt Masters as well as Minions. Use the ``make_master`` setting to use
  431. this functionality.
  432. .. code-block:: yaml
  433. my-ec2-config:
  434. # Optionally install a Salt Master in addition to the Salt Minion
  435. make_master: True
  436. When creating a Salt Master inside EC2 with ``make_master: True``, or when the Salt Master is already
  437. located and configured inside EC2, by default, minions connect to the master's public IP address during
  438. Salt Cloud's provisioning process. Depending on how your security groups are defined, the minions
  439. may or may not be able to communicate with the master. In order to use the master's private IP in EC2
  440. instead of the public IP, set the ``salt_interface`` to ``private_ips``.
  441. .. code-block:: yaml
  442. my-ec2-config:
  443. # Optionally set the IP configuration to private_ips
  444. salt_interface: private_ips
  445. Modify EC2 Tags
  446. ===============
  447. One of the features of EC2 is the ability to tag resources. In fact, under the
  448. hood, the names given to EC2 instances by salt-cloud are actually just stored
  449. as a tag called Name. Salt Cloud has the ability to manage these tags:
  450. .. code-block:: bash
  451. salt-cloud -a get_tags mymachine
  452. salt-cloud -a set_tags mymachine tag1=somestuff tag2='Other stuff'
  453. salt-cloud -a del_tags mymachine tag1,tag2,tag3
  454. It is possible to manage tags on any resource in EC2 with a Resource ID, not
  455. just instances:
  456. .. code-block:: bash
  457. salt-cloud -f get_tags my_ec2 resource_id=af5467ba
  458. salt-cloud -f set_tags my_ec2 resource_id=af5467ba tag1=somestuff
  459. salt-cloud -f del_tags my_ec2 resource_id=af5467ba tags=tag1,tag2,tag3
  460. Rename EC2 Instances
  461. ====================
  462. As mentioned above, EC2 instances are named via a tag. However, renaming an
  463. instance by renaming its tag will cause the salt keys to mismatch. A rename
  464. function exists which renames both the instance, and the salt keys.
  465. .. code-block:: bash
  466. salt-cloud -a rename mymachine newname=yourmachine
  467. Rename on Destroy
  468. =================
  469. When instances on EC2 are destroyed, there will be a lag between the time that
  470. the action is sent, and the time that Amazon cleans up the instance. During
  471. this time, the instance still retains a Name tag, which will cause a collision
  472. if the creation of an instance with the same name is attempted before the
  473. cleanup occurs. In order to avoid such collisions, Salt Cloud can be configured
  474. to rename instances when they are destroyed. The new name will look something
  475. like:
  476. .. code-block:: bash
  477. myinstance-DEL20f5b8ad4eb64ed88f2c428df80a1a0c
  478. In order to enable this, add rename_on_destroy line to the main
  479. configuration file:
  480. .. code-block:: yaml
  481. my-ec2-config:
  482. rename_on_destroy: True
  483. Listing Images
  484. ==============
  485. Normally, images can be queried on a cloud provider by passing the
  486. ``--list-images`` argument to Salt Cloud. This still holds true for EC2:
  487. .. code-block:: bash
  488. salt-cloud --list-images my-ec2-config
  489. However, the full list of images on EC2 is extremely large, and querying all of
  490. the available images may cause Salt Cloud to behave as if frozen. Therefore,
  491. the default behavior of this option may be modified, by adding an ``owner``
  492. argument to the provider configuration:
  493. .. code-block:: yaml
  494. owner: aws-marketplace
  495. The possible values for this setting are ``amazon``, ``aws-marketplace``,
  496. ``self``, ``<AWS account ID>`` or ``all``. The default setting is ``amazon``.
  497. Take note that ``all`` and ``aws-marketplace`` may cause Salt Cloud to appear
  498. as if it is freezing, as it tries to handle the large amount of data.
  499. It is also possible to perform this query using different settings without
  500. modifying the configuration files. To do this, call the ``avail_images``
  501. function directly:
  502. .. code-block:: bash
  503. salt-cloud -f avail_images my-ec2-config owner=aws-marketplace
  504. EC2 Images
  505. ==========
  506. The following are lists of available AMI images, generally sorted by OS. These
  507. lists are on 3rd-party websites, are not managed by Salt Stack in any way. They
  508. are provided here as a reference for those who are interested, and contain no
  509. warranty (express or implied) from anyone affiliated with Salt Stack. Most of
  510. them have never been used, much less tested, by the Salt Stack team.
  511. * `Arch Linux`__
  512. .. __: https://wiki.archlinux.org/index.php/Arch_Linux_AMIs_for_Amazon_Web_Services
  513. * `FreeBSD`__
  514. .. __: http://www.daemonology.net/freebsd-on-ec2/
  515. * `Fedora`__
  516. .. __: https://fedoraproject.org/wiki/Cloud_images
  517. * `CentOS`__
  518. .. __: http://wiki.centos.org/Cloud/AWS
  519. * `Ubuntu`__
  520. .. __: http://cloud-images.ubuntu.com/locator/ec2/
  521. * `Debian`__
  522. .. __: https://wiki.debian.org/Cloud/AmazonEC2Image
  523. * `OmniOS`__
  524. .. __: http://omnios.omniti.com/wiki.php/Installation#IntheCloud
  525. * `All Images on Amazon`__
  526. .. __: https://aws.amazon.com/marketplace
  527. show_image
  528. ==========
  529. This is a function that describes an AMI on EC2. This will give insight as to
  530. the defaults that will be applied to an instance using a particular AMI.
  531. .. code-block:: bash
  532. $ salt-cloud -f show_image ec2 image=ami-fd20ad94
  533. show_instance
  534. =============
  535. This action is a thin wrapper around ``--full-query``, which displays details on a
  536. single instance only. In an environment with several machines, this will save a
  537. user from having to sort through all instance data, just to examine a single
  538. instance.
  539. .. code-block:: bash
  540. $ salt-cloud -a show_instance myinstance
  541. ebs_optimized
  542. =============
  543. This argument enables switching of the EbsOptimized setting which default
  544. to 'false'. Indicates whether the instance is optimized for EBS I/O. This
  545. optimization provides dedicated throughput to Amazon EBS and an optimized
  546. configuration stack to provide optimal Amazon EBS I/O performance. This
  547. optimization isn't available with all instance types. Additional usage
  548. charges apply when using an EBS-optimized instance.
  549. This setting can be added to the profile or map file for an instance.
  550. If set to True, this setting will enable an instance to be EbsOptimized
  551. .. code-block:: yaml
  552. ebs_optimized: True
  553. This can also be set as a cloud provider setting in the EC2 cloud
  554. configuration:
  555. .. code-block:: yaml
  556. my-ec2-config:
  557. ebs_optimized: True
  558. del_root_vol_on_destroy
  559. =======================
  560. This argument overrides the default DeleteOnTermination setting in the AMI for
  561. the EBS root volumes for an instance. Many AMIs contain 'false' as a default,
  562. resulting in orphaned volumes in the EC2 account, which may unknowingly be
  563. charged to the account. This setting can be added to the profile or map file
  564. for an instance.
  565. If set, this setting will apply to the root EBS volume
  566. .. code-block:: yaml
  567. del_root_vol_on_destroy: True
  568. This can also be set as a cloud provider setting in the EC2 cloud
  569. configuration:
  570. .. code-block:: yaml
  571. my-ec2-config:
  572. del_root_vol_on_destroy: True
  573. del_all_vols_on_destroy
  574. =======================
  575. This argument overrides the default DeleteOnTermination setting in the AMI for
  576. the not-root EBS volumes for an instance. Many AMIs contain 'false' as a
  577. default, resulting in orphaned volumes in the EC2 account, which may
  578. unknowingly be charged to the account. This setting can be added to the profile
  579. or map file for an instance.
  580. If set, this setting will apply to any (non-root) volumes that were created
  581. by salt-cloud using the 'volumes' setting.
  582. The volumes will not be deleted under the following conditions
  583. * If a volume is detached before terminating the instance
  584. * If a volume is created without this setting and attached to the instance
  585. .. code-block:: yaml
  586. del_all_vols_on_destroy: True
  587. This can also be set as a cloud provider setting in the EC2 cloud
  588. configuration:
  589. .. code-block:: yaml
  590. my-ec2-config:
  591. del_all_vols_on_destroy: True
  592. The setting for this may be changed on all volumes of an existing instance
  593. using one of the following commands:
  594. .. code-block:: bash
  595. salt-cloud -a delvol_on_destroy myinstance
  596. salt-cloud -a keepvol_on_destroy myinstance
  597. salt-cloud -a show_delvol_on_destroy myinstance
  598. The setting for this may be changed on a volume on an existing instance
  599. using one of the following commands:
  600. .. code-block:: bash
  601. salt-cloud -a delvol_on_destroy myinstance device=/dev/sda1
  602. salt-cloud -a delvol_on_destroy myinstance volume_id=vol-1a2b3c4d
  603. salt-cloud -a keepvol_on_destroy myinstance device=/dev/sda1
  604. salt-cloud -a keepvol_on_destroy myinstance volume_id=vol-1a2b3c4d
  605. salt-cloud -a show_delvol_on_destroy myinstance device=/dev/sda1
  606. salt-cloud -a show_delvol_on_destroy myinstance volume_id=vol-1a2b3c4d
  607. EC2 Termination Protection
  608. ==========================
  609. EC2 allows the user to enable and disable termination protection on a specific
  610. instance. An instance with this protection enabled cannot be destroyed. The EC2
  611. driver adds a show_term_protect action to the regular EC2 functionality.
  612. .. code-block:: bash
  613. salt-cloud -a show_term_protect mymachine
  614. salt-cloud -a enable_term_protect mymachine
  615. salt-cloud -a disable_term_protect mymachine
  616. Alternate Endpoint
  617. ==================
  618. Normally, EC2 endpoints are build using the region and the service_url. The
  619. resulting endpoint would follow this pattern:
  620. .. code-block:: bash
  621. ec2.<region>.<service_url>
  622. This results in an endpoint that looks like:
  623. .. code-block:: bash
  624. ec2.us-east-1.amazonaws.com
  625. There are other projects that support an EC2 compatibility layer, which this
  626. scheme does not account for. This can be overridden by specifying the endpoint
  627. directly in the main cloud configuration file:
  628. .. code-block:: yaml
  629. my-ec2-config:
  630. endpoint: myendpoint.example.com:1138/services/Cloud
  631. Volume Management
  632. =================
  633. The EC2 driver has several functions and actions for management of EBS volumes.
  634. Creating Volumes
  635. ----------------
  636. A volume may be created, independent of an instance. A zone must be specified.
  637. A size or a snapshot may be specified (in GiB). If neither is given, a default
  638. size of 10 GiB will be used. If a snapshot is given, the size of the snapshot
  639. will be used.
  640. The following parameters may also be set (when providing a snapshot OR size):
  641. * ``type``: choose between standard (magnetic disk), gp2 (SSD), or io1 (provisioned IOPS).
  642. (default=standard)
  643. * ``iops``: the number of IOPS (only applicable to io1 volumes) (default varies on volume size)
  644. * ``encrypted``: enable encryption on the volume (default=false)
  645. .. code-block:: bash
  646. salt-cloud -f create_volume ec2 zone=us-east-1b
  647. salt-cloud -f create_volume ec2 zone=us-east-1b size=10
  648. salt-cloud -f create_volume ec2 zone=us-east-1b snapshot=snap12345678
  649. salt-cloud -f create_volume ec2 size=10 type=standard
  650. salt-cloud -f create_volume ec2 size=10 type=gp2
  651. salt-cloud -f create_volume ec2 size=10 type=io1 iops=1000
  652. Attaching Volumes
  653. -----------------
  654. Unattached volumes may be attached to an instance. The following values are
  655. required; name or instance_id, volume_id, and device.
  656. .. code-block:: bash
  657. salt-cloud -a attach_volume myinstance volume_id=vol-12345 device=/dev/sdb1
  658. Show a Volume
  659. -------------
  660. The details about an existing volume may be retrieved.
  661. .. code-block:: bash
  662. salt-cloud -a show_volume myinstance volume_id=vol-12345
  663. salt-cloud -f show_volume ec2 volume_id=vol-12345
  664. Detaching Volumes
  665. -----------------
  666. An existing volume may be detached from an instance.
  667. .. code-block:: bash
  668. salt-cloud -a detach_volume myinstance volume_id=vol-12345
  669. Deleting Volumes
  670. ----------------
  671. A volume that is not attached to an instance may be deleted.
  672. .. code-block:: bash
  673. salt-cloud -f delete_volume ec2 volume_id=vol-12345
  674. Managing Key Pairs
  675. ==================
  676. The EC2 driver has the ability to manage key pairs.
  677. Creating a Key Pair
  678. -------------------
  679. A key pair is required in order to create an instance. When creating a key pair
  680. with this function, the return data will contain a copy of the private key.
  681. This private key is not stored by Amazon, will not be obtainable past this
  682. point, and should be stored immediately.
  683. .. code-block:: bash
  684. salt-cloud -f create_keypair ec2 keyname=mykeypair
  685. Importing a Key Pair
  686. --------------------
  687. .. code-block:: bash
  688. salt-cloud -f import_keypair ec2 keyname=mykeypair file=/path/to/id_rsa.pub
  689. Show a Key Pair
  690. ---------------
  691. This function will show the details related to a key pair, not including the
  692. private key itself (which is not stored by Amazon).
  693. .. code-block:: bash
  694. salt-cloud -f show_keypair ec2 keyname=mykeypair
  695. Delete a Key Pair
  696. -----------------
  697. This function removes the key pair from Amazon.
  698. .. code-block:: bash
  699. salt-cloud -f delete_keypair ec2 keyname=mykeypair
  700. Launching instances into a VPC
  701. ==============================
  702. Simple launching into a VPC
  703. ---------------------------
  704. In the amazon web interface, identify the id or the name of the subnet into
  705. which your image should be created. Then, edit your cloud.profiles file like
  706. so:-
  707. .. code-block:: yaml
  708. profile-id:
  709. provider: provider-name
  710. subnetid: subnet-XXXXXXXX
  711. image: ami-XXXXXXXX
  712. size: m1.medium
  713. ssh_username: ubuntu
  714. securitygroupid:
  715. - sg-XXXXXXXX
  716. securitygroupname:
  717. - AnotherSecurityGroup
  718. - AndThirdSecurityGroup
  719. Note that 'subnetid' takes precedence over 'subnetname', but 'securitygroupid'
  720. and 'securitygroupname' are merged together to generate a single list for
  721. SecurityGroups of instances.
  722. Specifying interface properties
  723. -------------------------------
  724. .. versionadded:: 2014.7.0
  725. Launching into a VPC allows you to specify more complex configurations for
  726. the network interfaces of your virtual machines, for example:-
  727. .. code-block:: yaml
  728. profile-id:
  729. provider: provider-name
  730. image: ami-XXXXXXXX
  731. size: m1.medium
  732. ssh_username: ubuntu
  733. # Do not include either 'subnetid', 'subnetname', 'securitygroupid' or
  734. # 'securitygroupname' here if you are going to manually specify
  735. # interface configuration
  736. #
  737. network_interfaces:
  738. - DeviceIndex: 0
  739. SubnetId: subnet-XXXXXXXX
  740. SecurityGroupId:
  741. - sg-XXXXXXXX
  742. # Uncomment this line if you would like to set an explicit private
  743. # IP address for the ec2 instance
  744. #
  745. # PrivateIpAddress: 192.168.1.66
  746. # Uncomment this to associate an existing Elastic IP Address with
  747. # this network interface:
  748. #
  749. # associate_eip: eipalloc-XXXXXXXX
  750. # You can allocate more than one IP address to an interface. Use the
  751. # 'ip addr list' command to see them.
  752. #
  753. # SecondaryPrivateIpAddressCount: 2
  754. # Uncomment this to allocate a new Elastic IP Address to this
  755. # interface (will be associated with the primary private ip address
  756. # of the interface
  757. #
  758. # allocate_new_eip: True
  759. # Uncomment this instead to allocate a new Elastic IP Address to
  760. # both the primary private ip address and each of the secondary ones
  761. #
  762. allocate_new_eips: True
  763. # Uncomment this if you're creating NAT instances. Allows an instance
  764. # to accept IP packets with destinations other than itself.
  765. # SourceDestCheck: False
  766. - DeviceIndex: 1
  767. subnetname: XXXXXXXX-Subnet
  768. securitygroupname:
  769. - XXXXXXXX-SecurityGroup
  770. - YYYYYYYY-SecurityGroup
  771. Note that it is an error to assign a 'subnetid', 'subnetname', 'securitygroupid'
  772. or 'securitygroupname' to a profile where the interfaces are manually configured
  773. like this. These are both really properties of each network interface, not of
  774. the machine itself.