summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorClint Byrum <clint@fewbar.com>2019-02-04 10:10:15 -0800
committerMonty Taylor <mordred@inaugust.com>2019-02-06 14:21:59 +0000
commit6a4a8f80db8b61293ba8b5c5ed405319321a91a3 (patch)
treeaaf68fbf0bd9a130ad54dc90dfb8060c8637bead
parent81781d56bc121bf78b3ac2b18c8344fc3a6d615b (diff)
Add documentation for AWS/EC2 driver
Documentation, a thing which illuminates, the cloud, and nodepool. Change-Id: I98ec01d188a3ee18175fe3ebc97d89668ec81a20
Notes
Notes (review): Code-Review+2: David Shrewsbury <dshrewsb@redhat.com> Code-Review+1: Clint 'SpamapS' Byrum <clint@fewbar.com> Code-Review+2: Tobias Henkel <tobias.henkel@bmw.de> Workflow+1: Tobias Henkel <tobias.henkel@bmw.de> Verified+2: Zuul Submitted-by: Zuul Submitted-at: Wed, 06 Feb 2019 17:48:05 +0000 Reviewed-on: https://review.openstack.org/634769 Project: openstack-infra/nodepool Branch: refs/heads/master
-rw-r--r--doc/source/configuration.rst240
1 files changed, 240 insertions, 0 deletions
diff --git a/doc/source/configuration.rst b/doc/source/configuration.rst
index ba442c0..09f7554 100644
--- a/doc/source/configuration.rst
+++ b/doc/source/configuration.rst
@@ -364,6 +364,12 @@ Options
364 openshift driver, see the separate section 364 openshift driver, see the separate section
365 :attr:`providers.[openshift]` 365 :attr:`providers.[openshift]`
366 366
367 .. value:: aws
368
369 For details on the extra options required and provided by the
370 AWS driver, see the separate section
371 :attr:`providers.[aws]`
372
367 373
368OpenStack Driver 374OpenStack Driver
369---------------- 375----------------
@@ -1291,3 +1297,237 @@ Selecting the openshift driver adds the following options to the
1291 Only used by the 1297 Only used by the
1292 :value:`providers.[openshift].labels.type.pod` label type; 1298 :value:`providers.[openshift].labels.type.pod` label type;
1293 specifies the amount of memory in MB to request for the pod. 1299 specifies the amount of memory in MB to request for the pod.
1300
1301AWS EC2 Driver
1302--------------
1303
1304Selecting the aws driver adds the following options to the :attr:`providers`
1305section of the configuration.
1306
1307.. attr-overview::
1308 :prefix: providers.[aws]
1309 :maxdepth: 3
1310
1311.. attr:: providers.[aws]
1312 :type: list
1313
1314 An AWS provider's resources are partitioned into groups called `pool`
1315 (see :attr:`providers.[aws].pools` for details), and within a pool,
1316 the node types which are to be made available are listed
1317 (see :attr:`providers.[aws].pools.labels` for details).
1318
1319 See `Boto Configuration`_ for information on how to configure credentials
1320 and other settings for AWS access in Nodepool's runtime environment.
1321
1322 .. note:: For documentation purposes the option names are prefixed
1323 ``providers.[aws]`` to disambiguate from other
1324 drivers, but ``[aws]`` is not required in the
1325 configuration (e.g. below
1326 ``providers.[aws].pools`` refers to the ``pools``
1327 key in the ``providers`` section when the ``aws``
1328 driver is selected).
1329
1330 Example:
1331
1332 .. code-block:: yaml
1333
1334 providers:
1335 - name: ec2-us-west-2
1336 driver: aws
1337 region-name: us-west-2
1338 cloud-images:
1339 - name: debian9
1340 image-id: ami-09c308526d9534717
1341 username: admin
1342 pools:
1343 - name: main
1344 max-servers: 5
1345 subnet-id: subnet-0123456789abcdef0
1346 security-group-id: sg-01234567890abcdef
1347 labels:
1348 - name: debian9
1349 cloud-image: debian9
1350 flavor-name: t3.medium
1351 key-name: zuul
1352 - name: debian9-large
1353 cloud-image: debian9
1354 flavor-name: t3.large
1355 key-name: zuul
1356
1357 .. attr:: name
1358 :required:
1359
1360 A unique name for this provider configuration.
1361
1362 .. attr:: region
1363 :required:
1364
1365 Name of the `AWS region`_ to interact with.
1366
1367 .. attr:: profile-name
1368
1369 The AWS credentials profile to load for this provider. If unspecified the
1370 `boto3` library will select a profile.
1371
1372 See `Boto Configuration`_ for more information.
1373
1374 .. attr:: boot-timeout
1375 :type: int seconds
1376 :default: 60
1377
1378 Once an instance is active, how long to try connecting to the
1379 image via SSH. If the timeout is exceeded, the node launch is
1380 aborted and the instance deleted.
1381
1382 .. attr:: launch-retries
1383 :default: 3
1384
1385 The number of times to retry launching a node before considering
1386 the job failed.
1387
1388 .. attr:: cloud-images
1389 :type: list
1390
1391 Each entry in this section must refer to an entry in the
1392 :attr:`providers.[aws].cloud-images` section.
1393
1394 .. code-block:: yaml
1395
1396 cloud-images:
1397 - name: ubuntu1804
1398 image-id: ami-082fd9a18128c9e8c
1399 username: ubuntu
1400 - name: my-custom-win2k3
1401 connection-type: winrm
1402 username: admin
1403
1404 Each entry is a dictionary with the following keys
1405
1406 .. attr:: name
1407 :type: string
1408 :required:
1409
1410 Identifier to refer this cloud-image from :attr:`labels` section.
1411 Since this name appears elsewhere in the nodepool configuration file,
1412 you may want to use your own descriptive name here and use
1413 ``image-id`` to specify the cloud image so that if
1414 the image id changes on the cloud, the impact to your Nodepool
1415 configuration will be minimal. However, if ``image-id`` is not
1416 provided, this is assumed to be the image id in the cloud.
1417
1418 .. attr:: image-id
1419 :type: str
1420
1421 If this is provided, it is used to select the image from the cloud
1422 provider by ID.
1423
1424 .. attr:: username
1425 :type: str
1426
1427 The username that a consumer should use when connecting to the node.
1428
1429 .. attr:: connection-type
1430 :type: str
1431
1432 The connection type that a consumer should use when connecting to the
1433 node. For most images this is not necessary. However when creating
1434 Windows images this could be 'winrm' to enable access via ansible.
1435
1436 .. attr:: connection-port
1437 :type: int
1438 :default: 22/ 5986
1439
1440 The port that a consumer should use when connecting to the node. For
1441 most diskimages this is not necessary. This defaults to 22 for ssh and
1442 5986 for winrm.
1443
1444 .. attr:: pools
1445 :type: list
1446
1447 A pool defines a group of resources from an AWS provider. Each pool has a
1448 maximum number of nodes which can be launched from it, along with a number
1449 of cloud-related attributes used when launching nodes.
1450
1451 .. attr:: name
1452 :required:
1453
1454 A unique name within the provider for this pool of resources.
1455
1456 .. attr:: subnet-id
1457
1458 If provided, specifies the subnet to assign to the primary network
1459 interface of nodes.
1460
1461 .. attr:: security-group-id
1462
1463 If provided, specifies the security group ID to assign to the primary
1464 network interface of nodes.
1465
1466 .. attr:: host-key-checking
1467 :type: bool
1468 :default: True
1469
1470 Specify custom behavior of validation of SSH host keys. When set to
1471 False, nodepool-launcher will not ssh-keyscan nodes after they are
1472 booted. This might be needed if nodepool-launcher and the nodes it
1473 launches are on different networks. The default value is True.
1474
1475 .. attr:: labels
1476 :type: list
1477
1478 Each entry in a pool's `labels` section indicates that the
1479 corresponding label is available for use in this pool. When creating
1480 nodes for a label, the flavor-related attributes in that label's
1481 section will be used.
1482
1483 .. code-block:: yaml
1484
1485 labels:
1486 - name: bionic
1487 flavor-name: m5a.large
1488 console-log: True
1489
1490 Each entry is a dictionary with the following keys
1491
1492 .. attr:: name
1493 :type: str
1494 :required:
1495
1496 Identifier to refer this label.
1497
1498 .. attr:: cloud-image
1499 :type: str
1500 :required:
1501
1502 Refers to the name of an externally managed image in the
1503 cloud that already exists on the provider. The value of
1504 ``cloud-image`` should match the ``name`` of a previously
1505 configured entry from the ``cloud-images`` section of the
1506 provider. See :attr:`providers.[aws].cloud-images`.
1507
1508 .. attr:: flavor-name
1509 :type: str
1510 :required:
1511
1512 Name of the flavor to use.
1513
1514 .. attr:: key-name
1515 :type: string
1516
1517 If given, the name of a keypair that will be used when
1518 booting each server.
1519
1520 .. attr:: volume-type
1521 :type: string
1522
1523 If given, the root `EBS volume type`_
1524
1525 .. attr:: volume-size
1526 :type: int
1527
1528 If given, the size of the root EBS volume, in GiB.
1529
1530
1531.. _`EBS volume type`: https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/EBSVolumeTypes.html
1532.. _`AWS region`: https://docs.aws.amazon.com/general/latest/gr/rande.html
1533.. _`Boto configuration`: https://boto3.amazonaws.com/v1/documentation/api/latest/guide/configuration.html