nodepool/doc/source/gce.rst

293 lines
9.1 KiB
ReStructuredText

.. _gce-driver:
.. default-domain:: zuul
Google Cloud Compute Engine (GCE) Driver
----------------------------------------
Selecting the gce driver adds the following options to the :attr:`providers`
section of the configuration.
.. attr-overview::
:prefix: providers.[gce]
:maxdepth: 3
.. attr:: providers.[gce]
:type: list
A GCE provider's resources are partitioned into groups called `pool`
(see :attr:`providers.[gce].pools` for details), and within a pool,
the node types which are to be made available are listed
(see :attr:`providers.[gce].pools.labels` for details).
See `Application Default Credentials`_ for information on how to
configure credentials and other settings for GCE access in
Nodepool's runtime environment.
.. note:: For documentation purposes the option names are prefixed
``providers.[gce]`` to disambiguate from other
drivers, but ``[gce]`` is not required in the
configuration (e.g. below
``providers.[gce].pools`` refers to the ``pools``
key in the ``providers`` section when the ``gce``
driver is selected).
Example:
.. code-block:: yaml
- name: gce-uscentral1
driver: gce
project: nodepool-123456
region: us-central1
zone: us-central1-a
cloud-images:
- name: debian-stretch
image-project: debian-cloud
image-family: debian-9
username: zuul
key: ssh-rsa ...
pools:
- name: main
max-servers: 8
labels:
- name: debian-stretch
instance-type: f1-micro
cloud-image: debian-stretch
volume-type: standard
volume-size: 10
.. attr:: name
:required:
A unique name for this provider configuration.
.. attr:: region
:required:
Name of the region to use; see `GCE regions and zones`_.
.. attr:: zone
:required:
Name of the zone to use; see `GCE regions and zones`_.
.. attr:: boot-timeout
:type: int seconds
:default: 60
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-retries
:default: 3
The number of times to retry launching a node before considering
the job failed.
.. attr:: cloud-images
:type: list
Each entry in this section must refer to an entry in the
:attr:`labels` section.
.. code-block:: yaml
cloud-images:
- name: debian-stretch
image-project: debian-cloud
image-family: debian-9
username: zuul
key: ssh-rsa ...
Each entry is a dictionary with the following keys:
.. attr:: name
:type: string
:required:
Identifier to refer this cloud-image from
:attr:`providers.[gce].pools.labels` section.
.. attr:: image-id
:type: str
If this is provided, it is used to select the image from the cloud
provider by ID.
.. attr:: image-project
:type: str
If :attr:`providers.[gce].cloud-images.image-id` is not
provided, this is used along with
:attr:`providers.[gce].cloud-images.image-family` to find an
image.
.. attr:: image-family
:type: str
If :attr:`providers.[gce].cloud-images.image-id` is not
provided, this is used along with
:attr:`providers.[gce].cloud-images.image-project` to find an
image.
.. attr:: username
:type: str
The username that a consumer should use when connecting to the node.
.. attr:: key
:type: str
An SSH public key to add to the instance (project global keys
are added automatically).
.. 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:: shell-type
:type: str
:default: sh
The shell type of the node's default shell executable. Used by Zuul
to set ``ansible_shell_type``. This setting should only be used
- For a windows image with the experimental `connection-type` ``ssh``
in which case ``cmd`` or ``powershell`` should be set
and reflect the node's ``DefaultShell`` configuration.
- If the default shell is not Bourne compatible (sh), but instead
e.g. ``csh`` or ``fish``, and the user is aware that there is a
long-standing issue with ``ansible_shell_type`` in combination
with ``become``
.. attr:: connection-type
:type: str
The connection type that a consumer should use when connecting to the
node. For most images 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:: pools
:type: list
A pool defines a group of resources from an GCE provider. Each pool has a
maximum number of nodes which can be launched from it, along with a number
of cloud-related attributes used when launching nodes.
.. attr:: name
:required:
A unique name within the provider for this pool of resources.
.. attr:: priority
:type: int
:default: 100
The priority of this provider pool (a lesser number is a higher
priority). Nodepool launchers will yield requests to other
provider pools with a higher priority as long as they are not
paused. This means that in general, higher priority pools will
reach quota first before lower priority pools begin to be used.
This setting may be specified at the provider level in order
to apply to all pools within that provider, or it can be
overridden here for a specific pool.
.. attr:: node-attributes
:type: dict
A dictionary of key-value pairs that will be stored with the node data
in ZooKeeper. The keys and values can be any arbitrary string.
.. attr:: host-key-checking
:type: bool
:default: True
Whether to validate SSH host keys. When true, this helps ensure
that nodes are ready to receive SSH connections before they are
supplied to the requestor. When set to false, nodepool-launcher
will not attempt to ssh-keyscan nodes after they are booted.
Disable this if nodepool-launcher and the nodes it launches are
on different networks, where the launcher is unable to reach the
nodes directly, or when using Nodepool with non-SSH node
platforms. The default value is true.
.. attr:: use-internal-ip
:default: False
Whether to access the instance with the internal or external IP
address.
.. attr:: labels
:type: list
Each entry in a pool's `labels` section indicates that the
corresponding label is available for use in this pool. When creating
nodes for a label, the flavor-related attributes in that label's
section will be used.
.. code-block:: yaml
labels:
- name: debian
instance-type: f1-micro
cloud-image: debian-stretch
Each entry is a dictionary with the following keys
.. attr:: name
:type: str
:required:
Identifier to refer this label.
.. 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. See :attr:`providers.[gce].cloud-images`.
.. attr:: instance-type
:type: str
:required:
Name of the flavor to use. See `GCE machine types`_.
.. attr:: volume-type
:type: string
If given, the root volume type (``pd-standard`` or
``pd-ssd``).
.. attr:: volume-size
:type: int
If given, the size of the root volume, in GiB.
.. _`Application Default Credentials`: https://cloud.google.com/docs/authentication/production
.. _`GCE regions and zones`: https://cloud.google.com/compute/docs/regions-zones/
.. _`GCE machine types`: https://cloud.google.com/compute/docs/machine-types