diff --git a/doc/source/configuration.rst b/doc/source/configuration.rst index a13f8f6bc..474ca86e9 100644 --- a/doc/source/configuration.rst +++ b/doc/source/configuration.rst @@ -26,6 +26,7 @@ The following drivers are available. aws azure gce + ibmvpc kubernetes openshift openshift-pods diff --git a/doc/source/ibmvpc.rst b/doc/source/ibmvpc.rst new file mode 100644 index 000000000..435ac3976 --- /dev/null +++ b/doc/source/ibmvpc.rst @@ -0,0 +1,671 @@ +.. _ibmvpc-driver: + +.. default-domain:: zuul + +IBM VPC Driver +-------------- + +This driver is for use with the Virtual Private Cloud (VPC) service of +IBM Cloud. + +Preparation +~~~~~~~~~~~ +Note the following caveats: + +* IBM Cloud VPC does not support IPv6 addressing. + +* IBM Cloud VPC does not supply quota information via its API (but if + you know the values, you can supply them in the Nodepool + configuration). + +* Per-instance floating IP addresses are required for in-bound + connections from the Internet (but are not required for + outbound-only access). As of the time of this writing, floating IP + addresses are billed monthly and are not pro-rated. Because + Nodepool allocates and deallocates a floating IP address for each + instance, this means that every instance will incur at least a + full-month's charge for floating IP use even if it is used only + briefly. + +* IBM Cloud does not provide a facility for atomically associating + metadata with instances, which Nodepool generally relies upon for + detecting and cleaning up leaked resources. To approximate this + functionality, the `ibmvpc` driver will create all instances and + associated resources within resource groups that it will expect to + control. These groups begin with either the string ``np_`` or + ``npimages_``. Do not create any resource groups matching these + names, and do not create any resources within these groups. To do + so runs the risk of Nodepool mistaking your resource for one that it + controls and automatically deleting it. + +Before using this driver, attend to the following pre-requisites: + +* `Create an SSH key `_ +* `Create a VPC and subnet `_ + +Authentication +~~~~~~~~~~~~~~ + +Several authentication methods are available. The one which will work +in the widest circumstances is using an API key. The console can be +used to `create an API key `_. + +The API key (or other authentication information) may be provided to +Nodepool either through environment variables, or stored in a file. +If a file is used, the content is exactly the same as the environment +variable definition. To use an API key, the content would be: + +.. code-block:: shell + + VPC_AUTH_TYPE=iam + VPC_APIKEY=api-key-goes-here + +Either set these environment variables when running the Nodepool +process, or write them to a file and specify the path with the +:attr:`providers.[ibmvpc].credentials-file` provider attribute. + +.. note:: + + Several other authentication types are available; their + configuration is outside the scope of this document. While + `nodepool-launcher` should work with any auth type supported by the + IBM Cloud Python SDK, `nodepool-builder` is only compatible with + the ``iam`` auth type. + +Image Building +~~~~~~~~~~~~~~ + +Custom images in IBM cloud require the use of `Cloud Object Storage` +which is not integrated with the VPC API. To use `nodepool-builder`, the following additional steps are required: + +`Create a Cloud Object Storage instance +`_ +and grant access to the VPC service. + +Create a bucket within the `Cloud Object Storage` instance. + +Select an `endpoint `_ +for use with Nodepool. + +Note the name of the `Cloud Object Storage` instance, the endpoint, +and the name of the bucket you created for use when configuring +Nodepool. + +Configuration +~~~~~~~~~~~~~ + +Selecting the ibmvpc driver adds the following options to the :attr:`providers` +section of the configuration. + +.. attr-overview:: + :prefix: providers.[ibmvpc] + :maxdepth: 3 + +.. attr:: providers.[ibmvpc] + :type: list + + A provider's resources are partitioned into groups called `pools`, + 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.[ibmvpc]`` to disambiguate from other + drivers, but ``[ibmvpc]`` is not required in the + configuration (e.g. below + ``providers.[ibmvpc].pools`` refers to the ``pools`` + key in the ``providers`` section when the ``ibmvpc`` + driver is selected). + + Example: + + .. code-block:: yaml + + providers: + - name: ibmvpc-us-south + driver: ibmvpc + credentials-file: /path/to/creds.env + vpc: nodepool + region: us-south + subnet: sn-nodepool + cloud-images: + - name: bionic + username: zuul + keys: + - zuul-ssh-key + image-name: ibm-ubuntu-20-04-3-minimal-amd64-1 + pools: + - name: main + zone: us-south-1 + max-servers: 10 + host-key-checking: false + labels: + - name: bionic + cloud-image: bionic + profile: cx2-2x4 + + .. attr:: name + :required: + + A unique name for this provider configuration. The name may not + contain underscores. + + .. attr:: vpc + :required: + + The name of the VPC for this provider. + + .. attr:: region + :required: + + Name of the IBM Cloud region to interact with (e.g., ``us-south``). + + .. attr:: zone + + Name of the IBM Cloud region zone to interact with (e.g., + ``us-south-1``). This field may be omitted if + :attr:`providers.[ibmvpc].pools.zone` is supplied. + + .. attr:: credentials-file + + Path to the file containing the authentication information. + Required unless the information is supplied via environment + variables. + + .. attr:: subnet + + The name of the network upon which to create VMs. This field + may be omitted if :attr:`providers.[ibmvpc].pools.subnet` is + supplied. + + .. attr:: public-ipv4 + :type: bool + :default: false + + Whether to attach a public IPv4 address to instances. + + .. warning:: + + As of the time of this writing, floating IP addresses are + billed monthly and are not pro-rated. Enabling this option + can lead to high usage charges. + + .. 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: + + ``