zuul/nodepool
Code Issues Proposed changes

Azure: update documentation

Browse Source 
Update the documentation to match recent changes to the driver.

Also, update the driver to use the standard timeout options.

Change-Id: Iccdb4f4ce5470eebbdee9eccc403497a635e105e
This commit is contained in:
James E. Blair 2021-03-19 16:55:08 -07:00
parent 79ff141a75
commit 6b98bb8726
4 changed files with 309 additions and 41 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

331
doc/source/azure.rst
View File

@ -5,6 +5,15 @@
Azure Compute Driver
--------------------
Before using the Azure driver, make sure you have created a service
principal and saved the credential information in a JSON file. Follow
the instructions at `Azure CLI`_ and use the ``--sdk-auth`` flag::
az ad sp create-for-rbac --name nodepool --sdk-auth
You must also have created a network for Nodepool to use. Be sure to
enable IPv6 on the network if you plan to use it.
Selecting the azure driver adds the following options to the :attr:`providers`
section of the configuration.
@ -18,7 +27,6 @@ section of the configuration.
An Azure provider's resources are partitioned into groups called `pool`,
and within a pool, the node types which are to be made available are listed
.. note:: For documentation purposes the option names are prefixed
``providers.[azure]`` to disambiguate from other
drivers, but ``[azure]`` is not required in the
@ -31,14 +39,14 @@ section of the configuration.
.. code-block:: yaml
providers:
providers:
- name: azure-central-us
driver: azure
resource-group-location: centralus
location: centralus
resource-group: nodepool
auth-path: /Users/grhayes/.azure/nodepoolCreds.json
subnet-id: /subscriptions/<subscription-id>/resourceGroups/nodepool/providers/Microsoft.Network/virtualNetworks/NodePool/subnets/default
resource-group-location: centralus
auth-path: /path/to/nodepoolCreds.json
network: nodepool
cloud-images:
- name: bionic
username: zuul
@ -56,9 +64,6 @@ section of the configuration.
cloud-image: bionic
hardware-profile:
vm-size: Standard_D1_v2
tags:
department: R&D
purpose: CI/CD
.. attr:: name
:required:
@ -87,10 +92,116 @@ section of the configuration.
Path to the JSON file containing the service principal credentials.
Create with the `Azure CLI`_ and the ``--sdk-auth`` flag
.. attr:: subnet-id
.. attr:: network
:required:
Subnet to create VMs on
Network upon which to create VMs. This can either be a string,
in which case it must be the name of a network in the provider's
resource group and Nodepool will use the subnet named
``default``, or it can be a dictionary with these keys:
.. attr:: resource-group
:default: The provider's resource group
The resource group containing the network.
.. attr:: network
:required:
The name of the network.
.. attr:: subnet
:default: default
The name of the subnet within the network.
.. attr:: ipv4
:type: bool
Whether to enable IPv4 networking. Defaults to true unless ipv6
is enabled. Enabling this will attach a private IP address.
.. attr:: ipv6
:type: bool
:default: false
Whether to enable IPv6 networking. Enabling this will attach a
private IP address.
.. attr:: public-ipv4
:type: bool
Whether to attach a public IPv4 address to instances. Defaults
to true, but will change to false in a future release. Implies
``ipv4``.
.. attr:: public-ipv6
:type: bool
:default: false
Whether to attach a public IPv4 address to instances. Defaults
to true, but will change to false in a future release. Implies
``ipv6``.
.. attr:: use-internal-ip
:type: bool
:default: false
If a public IP is attached but Nodepool should prefer the
private IP, set this to true.
.. attr:: host-key-checking
:type: bool
:default: true
Specify custom behavior of validation of SSH host keys. When
set to False, nodepool-launcher will not ssh-keyscan nodes after
they are booted. This might be needed if nodepool-launcher and
the nodes it launches are on different networks. The default
value is true.
.. attr:: rate
:type: float seconds
:default: 1.0
In seconds, amount to wait between operations on the provider.
.. attr:: boot-timeout
:type: int seconds
:default: 120
Once an instance is active, how long to try connecting to the
image via SSH. If the timeout is exceeded, the node launch is
aborted and the instance deleted.
.. attr:: launch-timeout
:type: int seconds
:default: 3600
The time to wait from issuing the command to create a new instance
until that instance is reported as "active". If the timeout is
exceeded, the node launch is aborted and the instance deleted.
.. attr:: launch-retries
:type: int
:default: 3
The number of times to retry launching a server before
considering the request failed.
.. attr:: post-upload-hook
:type: string
:default: None
Filename of an optional script that can be called after an image has
been uploaded to a provider but before it is taken into use. This is
useful to perform last minute validation tests before an image is
really used for build nodes. The script will be called as follows:
``<SCRIPT> <PROVIDER> <EXTERNAL_IMAGE_ID> <LOCAL_IMAGE_FILENAME>``
If the script returns with result code 0 it is treated as successful
otherwise it is treated as failed and the image gets deleted.
.. attr:: cloud-images
:type: list
@ -130,15 +241,41 @@ section of the configuration.
.. attr:: username
:type: str
:required:
The username that a consumer should use when connecting to the
node.
The username that should be used when connecting to the node.
.. attr:: key
:type: str
The SSH public key that should be installed on the node.
.. attr:: connection-type
:type: string
The connection type that a consumer should use when connecting
to the node. For most diskimages this is not
necessary. However when creating Windows images this could be
``winrm`` to enable access via ansible.
.. attr:: connection-port
:type: int
:default: 22 / 5986
The port that a consumer should use when connecting to the
node. For most diskimages this is not necessary. This defaults
to 22 for ssh and 5986 for winrm.
.. attr:: python-path
:type: str
:default: auto
The path of the default python interpreter. Used by Zuul to set
``ansible_python_interpreter``. The special value ``auto`` will
direct Zuul to use inbuilt Ansible logic to select the
interpreter on Ansible >=2.8, and default to
``/usr/bin/python2`` for earlier versions.
.. attr:: image-reference
:type: dict
:required:
@ -167,6 +304,81 @@ section of the configuration.
Image version
.. attr:: diskimages
:type: list
Each entry in a provider's `diskimages` section must correspond
to an entry in :attr:`diskimages`. Such an entry indicates that
the corresponding diskimage should be uploaded for use in this
provider. Additionally, any nodes that are created using the
uploaded image will have the associated attributes (such as
flavor or metadata).
If an image is removed from this section, any previously uploaded
images will be deleted from the provider.
.. code-block:: yaml
diskimages:
- name: bionic
pause: False
- name: windows
connection-type: winrm
connection-port: 5986
Each entry is a dictionary with the following keys
.. attr:: name
:type: string
:required:
Identifier to refer this image from
:attr:`providers.[azure].pools.labels` and
:attr:`diskimages` sections.
.. attr:: pause
:type: bool
:default: False
When set to True, nodepool-builder will not upload the image
to the provider.
.. attr:: username
:type: str
The username that should be used when connecting to the node.
.. attr:: key
:type: str
The SSH public key that should be installed on the node.
.. attr:: connection-type
:type: string
The connection type that a consumer should use when connecting
to the node. For most diskimages this is not
necessary. However when creating Windows images this could be
``winrm`` to enable access via ansible.
.. attr:: connection-port
:type: int
:default: 22 / 5986
The port that a consumer should use when connecting to the
node. For most diskimages this is not necessary. This defaults
to 22 for ssh and 5986 for winrm.
.. attr:: python-path
:type: str
:default: auto
The path of the default python interpreter. Used by Zuul to set
``ansible_python_interpreter``. The special value ``auto`` will
direct Zuul to use inbuilt Ansible logic to select the
interpreter on Ansible >=2.8, and default to
``/usr/bin/python2`` for earlier versions.
.. attr:: pools
:type: list
@ -180,6 +392,51 @@ section of the configuration.
A unique name within the provider for this pool of resources.
.. attr:: ipv4
:type: bool
Whether to enable IPv4 networking. Defaults to true unless ipv6
is enabled. Enabling this will attach a private IP address.
.. attr:: ipv6
:type: bool
:default: false
Whether to enable IPv6 networking. Enabling this will attach a
private IP address.
.. attr:: public-ipv4
:type: bool
Whether to attach a public IPv4 address to instances. Defaults
to true, but will change to false in a future release. Implies
``ipv4``.
.. attr:: public-ipv6
:type: bool
:default: false
Whether to attach a public IPv4 address to instances. Defaults
to true, but will change to false in a future release. Implies
``ipv6``.
.. attr:: use-internal-ip
:type: bool
:default: false
If a public IP is attached but Nodepool should prefer the
private IP, set this to true.
.. attr:: host-key-checking
:type: bool
:default: true
Specify custom behavior of validation of SSH host keys. When
set to False, nodepool-launcher will not ssh-keyscan nodes after
they are booted. This might be needed if nodepool-launcher and
the nodes it launches are on different networks. The default
value is true.
.. attr:: labels
:type: list
@ -196,36 +453,44 @@ section of the configuration.
hardware-profile:
vm-size: Standard_D1_v2
Each entry is a dictionary with the following keys
Each entry is a dictionary with the following keys:
.. attr:: name
:type: str
:required:
.. attr:: name
:type: str
:required:
Identifier to refer this label.
Identifier for this label.
.. attr:: cloud-image
:type: str
:required:
.. attr:: cloud-image
:type: str
:required:
Refers to the name of an externally managed image in the
cloud that already exists on the provider. The value of
``cloud-image`` should match the ``name`` of a previously
configured entry from the ``cloud-images`` section of the
provider.
Refers to the name of an externally managed image in the
cloud that already exists on the provider. The value of
``cloud-image`` should match the ``name`` of a previously
configured entry from the ``cloud-images`` section of the
provider.
.. attr:: hardware-profile
:required:
.. attr:: diskimage
:type: str
:required:
.. attr:: vm-size
:required:
:type: str
Refers to provider's diskimages, see
:attr:`providers.[azure].diskimages`. Mutually exclusive
with :attr:`providers.[azure].pools.labels.cloud-image`
VM Size of the VMs to use in Azure. See the VM size list on `azure.microsoft.com`_
for the list of sizes availabile in each region.
.. attr:: hardware-profile
:required:
.. attr:: vm-size
:required:
:type: str
VM Size of the VMs to use in Azure. See the VM size
list on `azure.microsoft.com`_ for the list of sizes
availabile in each region.
.. _`Azure CLI`: https://docs.microsoft.com/en-us/cli/azure/create-an-azure-service-principal-azure-cli?view=azure-cli-latest
.. _azure.microsoft.com: https://azure.microsoft.com/en-us/global-infrastructure/services/?products=virtual-machines

2
nodepool/driver/azure/adapter.py
View File

@ -281,7 +281,7 @@ class AzureAdapter(statemachine.Adapter):
self.resource_group = self.provider.resource_group
self.resource_group_location = self.provider.resource_group_location
self.rate_limiter = RateLimiter(self.provider.name,
self.provider.rate_limit)
self.provider.rate)
with open(self.provider.auth_path) as f:
self.azul = azul.AzureCloud(json.load(f))
if provider_config.subnet_id:

7
nodepool/driver/azure/config.py
View File

@ -205,7 +205,7 @@ class AzureProviderConfig(ProviderConfig):
def __init__(self, driver, provider):
super().__init__(provider)
self._pools = {}
self.rate_limit = None
self.rate = None
self.launch_retries = None
@property
@ -225,9 +225,10 @@ class AzureProviderConfig(ProviderConfig):
self.image_name_format = '{image_name}-{timestamp}'
self.post_upload_hook = self.provider.get('post-upload-hook')
self.rate_limit = self.provider.get('rate-limit', 1)
self.rate = self.provider.get('rate', 1)
self.launch_retries = self.provider.get('launch-retries', 3)
self.boot_timeout = self.provider.get('boot-timeout', 60)
self.launch_timeout = self.provider.get('launch-timeout', 3600)
self.boot_timeout = self.provider.get('boot-timeout', 120)
# TODO(corvus): remove
self.zuul_public_key = self.provider.get('zuul-public-key')

10
nodepool/driver/statemachine.py
View File

@ -33,7 +33,8 @@ import cachetools
def keyscan(node_id, interface_ip,
connection_type, connection_port):
connection_type, connection_port,
timeout):
"""A standalone function for scanning keys to pass to a thread/process
pool executor
"""
@ -46,7 +47,7 @@ def keyscan(node_id, interface_ip,
else:
gather_hostkeys = False
keys = nodescan(interface_ip, port=connection_port,
timeout=180, gather_hostkeys=gather_hostkeys)
timeout=timeout, gather_hostkeys=gather_hostkeys)
except Exception:
raise exceptions.LaunchKeyscanException(
"Can't scan instance %s key" % node_id)
@ -176,7 +177,7 @@ class StateMachineNodeLauncher(stats.StatsReporter):
now = time.monotonic()
if (now - state_machine.start_time >
self.manager.provider.boot_timeout):
self.manager.provider.launch_timeout):
raise Exception("Timeout waiting for instance creation")
instance = state_machine.advance()
self.log.debug(f"State machine for {node.id} at "
@ -195,7 +196,8 @@ class StateMachineNodeLauncher(stats.StatsReporter):
future = self.manager.keyscan_worker.submit(
keyscan,
node.id, node.interface_ip,
node.connection_type, node.connection_port)
node.connection_type, node.connection_port,
self.manager.provider.boot_timeout)
self.keyscan_future = future
except kze.SessionExpiredError:
# Our node lock is gone, leaving the node state as BUILDING.