Browse Source

Add documentation for AWS/EC2 driver

Documentation,
a thing which illuminates,
the cloud, and nodepool.

Change-Id: I98ec01d188a3ee18175fe3ebc97d89668ec81a20
tags/3.5.0
Clint Byrum 6 months ago
parent
commit
6a4a8f80db
1 changed files with 240 additions and 0 deletions
  1. 240
    0
      doc/source/configuration.rst

+ 240
- 0
doc/source/configuration.rst View File

@@ -364,6 +364,12 @@ Options
364 364
          openshift driver, see the separate section
365 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
 
368 374
 OpenStack Driver
369 375
 ----------------
@@ -1291,3 +1297,237 @@ Selecting the openshift driver adds the following options to the
1291 1297
          Only used by the
1292 1298
          :value:`providers.[openshift].labels.type.pod` label type;
1293 1299
          specifies the amount of memory in MB to request for the pod.
1300
+
1301
+AWS EC2 Driver
1302
+--------------
1303
+
1304
+Selecting the aws driver adds the following options to the :attr:`providers`
1305
+section 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

Loading…
Cancel
Save