Improve configuration documentation
In each section, split required and optional parameters in their own
sub sections. Make it easier to craft a new configuration file from
scratch.
Have the setting explanation on its own indented paragraph to make it
easier to the eye (approved by my wife).
Add almost all missing settings based on the source code and document
some.
Document the Jenkins 'test-job' introduced in 861a5dbc by copy pasted
James E. Blair commit summary.
Change-Id: Iadaa0f70434cc254738b31359200c9fac02042bb
This commit is contained in:
Antoine Musso
parent
ba43590ffb
commit
f31b4c0af2
@ -35,6 +35,8 @@ Example::
|
||||
|
||||
script-dir: /path/to/script/dir
|
||||
|
||||
.. _elements-dir:
|
||||
|
||||
elements-dir
|
||||
------------
|
||||
|
||||
@ -106,7 +108,9 @@ Example::
|
||||
- host: zuul.example.com
|
||||
port: 4730
|
||||
|
||||
The ``port`` key is optional.
|
||||
The ``port`` key is optional (default: 4730).
|
||||
|
||||
.. _labels:
|
||||
|
||||
labels
|
||||
------
|
||||
@ -132,25 +136,42 @@ providers or images are used to create them). Example::
|
||||
providers:
|
||||
- name: provider1
|
||||
|
||||
The `name` and `image` keys are required. The `providers` list is
|
||||
also required if any nodes should actually be created (e.g., the label
|
||||
is not currently disabled). The `min-ready` key is optional and
|
||||
defaults to 2. If the value is -1 the label is considered disabled.
|
||||
``min-ready`` is best-effort based on available capacity and is not a
|
||||
guaranteed allocation.
|
||||
**required**
|
||||
|
||||
The `subnodes` key is used to configure multi-node support. If a
|
||||
`subnodes` key is supplied to an image, it indicates that the specified
|
||||
number of additional nodes of the same image type should be created
|
||||
and associated with each node for that image. Only one node from each
|
||||
such group will be added to the target, the subnodes are expected to
|
||||
communicate directly with each other. In the example above, for each
|
||||
Precise node added to the target system, two additional nodes will be
|
||||
created and associated with it.
|
||||
``name``
|
||||
Unique name used to tie jobs to those instances.
|
||||
|
||||
A script specified by `ready-script` can be used to perform any last minute
|
||||
changes to a node after it has been launched but before it is put in the READY
|
||||
state to receive jobs. For more information, see :ref:`scripts`.
|
||||
``image``
|
||||
Refers to providers images, see :ref:`images`.
|
||||
|
||||
``providers`` (list)
|
||||
Required if any nodes should actually be created (e.g., the label is not
|
||||
currently disabled, see ``min-ready`` below).
|
||||
|
||||
**optional**
|
||||
|
||||
``min-ready`` (default: 2)
|
||||
Minimum instances that should be in a ready state. Set to -1 to have the
|
||||
label considered disabled. ``min-ready`` is best-effort based on available
|
||||
capacity and is not a guaranteed allocation.
|
||||
|
||||
``subnodes``
|
||||
Used to configure multi-node support. If a `subnodes` key is supplied to
|
||||
an image, it indicates that the specified number of additional nodes of the
|
||||
same image type should be created and associated with each node for that
|
||||
image.
|
||||
|
||||
Only one node from each such group will be added to the target, the
|
||||
subnodes are expected to communicate directly with each other. In the
|
||||
example above, for each Precise node added to the target system, two
|
||||
additional nodes will be created and associated with it.
|
||||
|
||||
``ready-script``
|
||||
A script to be used to perform any last minute changes to a node after it
|
||||
has been launched but before it is put in the READY state to receive jobs.
|
||||
For more information, see :ref:`scripts`.
|
||||
|
||||
.. _diskimages:
|
||||
|
||||
diskimages
|
||||
----------
|
||||
@ -174,15 +195,30 @@ will be built using the provider snapshot approach::
|
||||
DIB_DISTRIBUTION_MIRROR: http://archive.ubuntu.com
|
||||
DIB_IMAGE_CACHE: /opt/dib_cache
|
||||
|
||||
For diskimages, the `name` is required. The `elements` section
|
||||
enumerates all the elements that will be included when building the
|
||||
image, and will point to the `elements-dir` path referenced in the
|
||||
same config file. `release` specifies the distro to be used as a base
|
||||
image to build the image using diskimage-builder. `env-vars` is an
|
||||
optional dictionary of arbitrary environment variables that will be
|
||||
available in the spawned diskimage-builder child process.
|
||||
|
||||
providers
|
||||
**required**
|
||||
|
||||
``name``
|
||||
Identifier to reference the disk image in :ref:`images` and :ref:`labels`.
|
||||
|
||||
**optional**
|
||||
|
||||
``release``
|
||||
Specifies the distro to be used as a base image to build the image using
|
||||
diskimage-builder.
|
||||
|
||||
``elements`` (list)
|
||||
Enumerates all the elements that will be included when building the image,
|
||||
and will point to the :ref:`elements-dir` path referenced in the same
|
||||
config file.
|
||||
|
||||
``env-vars`` (dict)
|
||||
Arbitrary environment variables that will be available in the spawned
|
||||
diskimage-builder child process.
|
||||
|
||||
.. _provider:
|
||||
|
||||
provider
|
||||
---------
|
||||
|
||||
Lists the OpenStack cloud providers Nodepool should use. Within each
|
||||
@ -260,36 +296,76 @@ provider, the Nodepool image types are also defined (see
|
||||
key: value
|
||||
key2: value
|
||||
|
||||
For providers, the `name`, `username`, `password`, `auth-url`,
|
||||
`project-id`, and `max-servers` keys are required.
|
||||
**required**
|
||||
|
||||
Both `boot-timeout` and `launch-timeout` keys are optional. The
|
||||
`boot-timeout` key defaults to 60 seconds and `launch-timeout` key
|
||||
will default to 3600 seconds.
|
||||
``name``
|
||||
|
||||
The optional `networks` section may be used to specify custom
|
||||
Neutron networks that get attached to each node. You can specify
|
||||
Neutron networks using either the `net-id` or `net-label`. If
|
||||
only the `net-label` is specified the network UUID is automatically
|
||||
queried via the Nova os-tenant-networks API extension (this requires
|
||||
that the cloud provider has deployed this extension).
|
||||
``username``
|
||||
|
||||
The `availability-zones` key is optional. Without it nodepool will rely
|
||||
on nova to schedule an availability zone. If it is provided the value
|
||||
should be a list of availability zone names. Nodepool will select one
|
||||
at random and provide that to nova. This should give a good distribution
|
||||
of availability zones being used. If you need more control of the
|
||||
distribution you can use multiple logical providers each providing a
|
||||
different list of availabiltiy zones.
|
||||
``password``
|
||||
|
||||
The 'pool' key is optional. This can be used to specify a floating ip
|
||||
pool in cases where the 'public' pool is unavailable or undesirable.
|
||||
``project-id``
|
||||
|
||||
The ``image-type`` specifies the image type supported by this provider.
|
||||
The disk images built by diskimage-builder will output an image for each
|
||||
``image-type`` specified by a provider using that particular diskimage.
|
||||
The default value is ``qcow2``, and values of ``vhd``, ``raw`` are also
|
||||
expected to be valid if you have a sufficiently new diskimage-builder.
|
||||
``auth-url``
|
||||
Keystone URL.
|
||||
|
||||
``max-servers``
|
||||
Maximum number of servers spawnable on this provider.
|
||||
|
||||
**optional**
|
||||
|
||||
``availability-zones`` (list)
|
||||
Without it nodepool will rely on nova to schedule an availability zone.
|
||||
|
||||
If it is provided the value should be a list of availability zone names.
|
||||
Nodepool will select one at random and provide that to nova. This should
|
||||
give a good distribution of availability zones being used. If you need more
|
||||
control of the distribution you can use multiple logical providers each
|
||||
providing a different list of availabiltiy zones.
|
||||
|
||||
``boot-timeout``
|
||||
In seconds. Default 60.
|
||||
|
||||
``launch-timeout``
|
||||
In seconds. Default 3600.
|
||||
|
||||
``image-type``
|
||||
Specifies the image type supported by this provider. The disk images built
|
||||
by diskimage-builder will output an image for each ``image-type`` specified
|
||||
by a provider using that particular diskimage.
|
||||
|
||||
The default value is ``qcow2``, and values of ``vhd``, ``raw`` are also
|
||||
expected to be valid if you have a sufficiently new diskimage-builder.
|
||||
|
||||
``keypair``
|
||||
Default None
|
||||
|
||||
``networks`` (dict)
|
||||
Specify custom Neutron networks that get attached to each node. You can
|
||||
specify Neutron networks using either the ``net-id`` or ``net-label``. If
|
||||
only the ``net-label`` is specified the network UUID is automatically
|
||||
queried via the Nova os-tenant-networks API extension (this requires that
|
||||
the cloud provider has deployed this extension).
|
||||
|
||||
``pool``
|
||||
Specify a floating ip pool in cases where the 'public' pool is unavailable
|
||||
or undesirable.
|
||||
|
||||
``api_timeout``
|
||||
Timeout for the Nova client in seconds.
|
||||
|
||||
``service-type``
|
||||
|
||||
``service-name``
|
||||
|
||||
``region-name``
|
||||
|
||||
``template-hostname``
|
||||
Hostname template to use for the spawned instance.
|
||||
Default ``{image.name}-{timestamp}.template.openstack.org``
|
||||
|
||||
``rate``
|
||||
In seconds. Default 1.0.
|
||||
|
||||
.. _images:
|
||||
|
||||
@ -311,40 +387,63 @@ Example::
|
||||
key: value
|
||||
key2: value
|
||||
|
||||
For `images`, the `name`, `base-image`, and `min-ram` keys are
|
||||
required.
|
||||
**required**
|
||||
|
||||
`base-image` is the UUID or string-name of the image to boot as
|
||||
specified by the provider.
|
||||
``name``
|
||||
Identifier to refer this image from :ref:`labels` and :ref:`provider`
|
||||
sections.
|
||||
|
||||
If the resulting images from different providers `base-image` should
|
||||
be equivalent, give them the same name; e.g. if one provider has a
|
||||
``Fedora 20`` image and another has an equivalent ``Fedora 20
|
||||
(Heisenbug)`` image, they should use a common `name`. Otherwise
|
||||
select a unique `name`.
|
||||
If the resulting images from different providers ``base-image`` should be
|
||||
equivalent, give them the same name; e.g. if one provider has a ``Fedora
|
||||
20`` image and another has an equivalent ``Fedora 20 (Heisenbug)`` image,
|
||||
they should use a common ``name``. Otherwise select a unique ``name``.
|
||||
|
||||
The `min-ram` setting will determine the flavor of `base-image` to use
|
||||
(e.g. ``m1.medium``, ``m1.large``, etc). The smallest flavor that
|
||||
meets the `min-ram` requirements will be chosen. You may specify an
|
||||
additional `name-filter` which will be required to match on the
|
||||
flavor-name (e.g. Rackspace offer a "Performance" flavour; setting
|
||||
`name-filter` to ``Performance`` will ensure the chosen flavor also
|
||||
contains this string as well as meeting `min-ram` requirements).
|
||||
``base-image``
|
||||
UUID or string-name of the image to boot as specified by the provider.
|
||||
|
||||
The `username` and `private-key` values default to the values
|
||||
indicated. Nodepool expects that user to exist after running the
|
||||
script indicated by `setup`. `setup` will be used only when not
|
||||
building images using diskimage-builder, in that case settings defined
|
||||
in the ``diskimages`` section will be used instead. See :ref:`scripts`
|
||||
for setup script details.
|
||||
``min-ram``
|
||||
Determine the flavor of ``base-image`` to use (e.g. ``m1.medium``,
|
||||
``m1.large``, etc). The smallest flavor that meets the ``min-ram``
|
||||
requirements will be chosen. To further filter by flavor name, see optional
|
||||
``name-filter`` below.
|
||||
|
||||
The `config-drive` boolean is optional and defines whether config drive
|
||||
should be used for the image.
|
||||
**optional**
|
||||
|
||||
The `meta` section is optional. It is a dict of arbitrary key/value
|
||||
metadata to store for this server using the nova metadata service. A
|
||||
maximum of five entries is allowed, and both keys and values must be
|
||||
255 characters or less.
|
||||
``name-filter``
|
||||
Additional filter complementing ``min-ram``, will be required to match on
|
||||
the flavor-name (e.g. Rackspace offer a "Performance" flavour; setting
|
||||
`name-filter` to ``Performance`` will ensure the chosen flavor also
|
||||
contains this string as well as meeting `min-ram` requirements).
|
||||
|
||||
``setup``
|
||||
Script to run to prepare the instance.
|
||||
|
||||
Used only when not building images using diskimage-builder, in that case
|
||||
settings defined in the ``diskimages`` section will be used instead. See
|
||||
:ref:`scripts` for setup script details.
|
||||
|
||||
``reset``
|
||||
See :ref:`scripts`.
|
||||
|
||||
``diskimages``
|
||||
See :ref:`diskimages`.
|
||||
|
||||
``username``
|
||||
Nodepool expects that user to exist after running the script indicated by
|
||||
``setup``. Default ``jenkins``
|
||||
|
||||
``private-key``
|
||||
Default ``/var/lib/jenkins/.ssh/id_rsa``
|
||||
|
||||
``config-drive`` (boolean)
|
||||
Whether config drive should be used for the image.
|
||||
|
||||
``meta`` (dict)
|
||||
Arbitrary key/value metadata to store for this server using the Nova
|
||||
metadata service. A maximum of five entries is allowed, and both keys and
|
||||
values must be 255 characters or less.
|
||||
|
||||
.. _targets:
|
||||
|
||||
targets
|
||||
-------
|
||||
@ -371,8 +470,46 @@ across all of the targets which are on-line::
|
||||
hostname: '{label.name}-{provider.name}-{node_id}'
|
||||
subnode-hostname: '{label.name}-{provider.name}-{node_id}-{subnode_id}'
|
||||
|
||||
For targets, the `name` is required. If using Jenkins, the `url`,
|
||||
`user`, and `apikey` keys are required. If the `credentials-id` key
|
||||
is provided, Nodepool will configure the Jenkins slave to use the
|
||||
Jenkins credential identified by that ID, otherwise it will use the
|
||||
username and ssh keys configured in the image.
|
||||
**required**
|
||||
|
||||
``name``
|
||||
Identifier for the system an instance is attached to.
|
||||
|
||||
**optional**
|
||||
|
||||
``hostname``
|
||||
Default ``{label.name}-{provider.name}-{node_id}.slave.openstack.org``
|
||||
|
||||
``subnode-hostname``
|
||||
Default ``{label.name}-{provider.name}-{node_id}-{subnode_id}.slave.openstack.org``
|
||||
|
||||
``rate``
|
||||
In seconds. Default 1.0
|
||||
|
||||
``jenkins`` (dict)
|
||||
``url``
|
||||
Url to the Jenkins REST API.
|
||||
|
||||
``user``
|
||||
Jenkins username.
|
||||
|
||||
``apikey``
|
||||
API key generated by Jenkins (not the user password).
|
||||
|
||||
``credentials-id`` (optional)
|
||||
If provided, Nodepool will configure the Jenkins slave to use the Jenkins
|
||||
credential identified by that ID, otherwise it will use the username and
|
||||
ssh keys configured in the image.
|
||||
|
||||
``test-job`` (optional)
|
||||
Setting this would cause a newly created instance to be in a TEST state.
|
||||
The job name given will then be executed with the node name as a
|
||||
parameter.
|
||||
|
||||
If the job succeeds, move the node into READY state and relabel it with
|
||||
the appropriate label (from the image name).
|
||||
|
||||
If it fails, immediately delete the node.
|
||||
|
||||
If the job never runs, the node will eventually be cleaned up by the
|
||||
periodic cleanup task.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user