a48c33e280
Document plugins, metadata services, configuration file, how the project is supposed to work and some user related usecases. Change-Id: I184a9409a9e9173c346f0ab149cb7d78ed87e0b3
194 lines
5.4 KiB
ReStructuredText
194 lines
5.4 KiB
ReStructuredText
.. _services:
|
|
|
|
Services
|
|
========
|
|
|
|
A **metadata service** has the role of pulling the guest provided data
|
|
(configuration information) and exposing it to the :ref:`plugins` for a
|
|
general and basic initialization of the instance.
|
|
These sub-services can change their behavior according to custom
|
|
configuration options, if they are specified, which are documented below.
|
|
|
|
Supported metadata services (cloud specific):
|
|
|
|
|
|
.. _httpservice:
|
|
|
|
OpenStack (web API)
|
|
-------------------
|
|
|
|
.. class:: cloudbaseinit.metadata.services.httpservice.HttpService
|
|
|
|
A complete service which also supports password related capabilities and
|
|
can be usually accessed with http://169.254.169.254/ magic address, which can
|
|
also be changed using `metadata_base_url` option under the config file. A
|
|
default value of *True* for `add_metadata_private_ip_route` option is used
|
|
to add a route for the IP address to the gateway. This is needed for supplying
|
|
a bridge between different VLANs in order to get access to the web server.
|
|
|
|
Capabilities:
|
|
|
|
* instance ID
|
|
* host name
|
|
* public keys
|
|
* authentication certificates (metadata + user data)
|
|
* static network configuration addresses
|
|
* admin password
|
|
* user data
|
|
* user content (additional files)
|
|
* ability to post passwords
|
|
|
|
Config options:
|
|
|
|
* metadata_base_url (string: "http://169.254.169.254/")
|
|
* add_metadata_private_ip_route (bool: True)
|
|
|
|
|
|
.. _configdrive:
|
|
|
|
OpenStack (configuration drive)
|
|
-------------------------------
|
|
|
|
.. class:: cloudbaseinit.metadata.services.configdrive.ConfigDriveService
|
|
|
|
This is similar to the web API, but it "serves" its files locally without
|
|
requiring network access. The data is generally retrieved from a
|
|
`cdrom <https://en.wikipedia.org/wiki/ISO_9660>`_,
|
|
`vfat <https://en.wikipedia.org/wiki/File_Allocation_Table#VFAT>`_ or
|
|
*raw* disks/partitions by enabling selective lookup across different devices.
|
|
Use the `config_drive_types` option to specify which types of config drive
|
|
content the service will search for and also on which devices using the
|
|
`config_drive_locations` option.
|
|
|
|
.. warning:: *deprecated options*
|
|
|
|
Using the option:
|
|
|
|
a. `config_drive_cdrom`
|
|
b. `config_drive_raw_hhd`
|
|
c. `config_drive_vfat`
|
|
|
|
It will search for metadata:
|
|
|
|
a. in mounted optical units
|
|
b. directly in the physical disk bytes
|
|
c. by exploring the physical disk as a vfat drive; which requires
|
|
*mtools* (specified by the `mtools_path` option)
|
|
|
|
The interesting part with this service is the fact that is quite fast in
|
|
comparison with the HTTP twin.
|
|
|
|
Capabilities:
|
|
|
|
* instance ID
|
|
* host name
|
|
* public keys (search in the entire metadata)
|
|
* authentication certificates (metadata + user data)
|
|
* static network configuration addresses
|
|
* admin password
|
|
* user data
|
|
* user content (additional files)
|
|
|
|
Config options:
|
|
|
|
* config_drive_types (list: ["vfat", "iso"])
|
|
* config_drive_locations (list: ["cdrom", "hdd", "partition"])
|
|
* mtools_path (string: None)
|
|
|
|
|
|
Amazon EC2
|
|
----------
|
|
|
|
.. class:: cloudbaseinit.metadata.services.ec2service.EC2Service
|
|
|
|
This is similar to the OpenStack HTTP service but is using a different
|
|
format for URLs and is having general capabilities.
|
|
|
|
Capabilities:
|
|
|
|
* instance ID
|
|
* host name
|
|
* public keys
|
|
|
|
Config options:
|
|
|
|
* ec2_metadata_base_url (string: "http://169.254.169.254/")
|
|
* ec2_add_metadata_private_ip_route (bool: True)
|
|
|
|
.. note:: http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-metadata.html
|
|
|
|
|
|
CloudStack
|
|
----------
|
|
|
|
.. class:: cloudbaseinit.metadata.services.cloudstack.CloudStack
|
|
|
|
Another web-based service which usually uses "10.1.1.1" or DHCP addresses for
|
|
retrieving content.
|
|
|
|
Capabilities:
|
|
|
|
* instance ID
|
|
* host name
|
|
* public keys
|
|
* admin password (retrieval/deletion/polling)
|
|
* user data
|
|
|
|
Config options:
|
|
|
|
* cloudstack_metadata_ip (string: "10.1.1.1")
|
|
|
|
.. note:: By design, this service can update the password anytime, so it will
|
|
cause the `setuserpassword` plugin to run at every boot and
|
|
by security concerns, the password is deleted right after retrieval
|
|
and no updating will occur until a new password is available on the
|
|
server.
|
|
|
|
|
|
OpenNebula
|
|
----------
|
|
|
|
.. class:: cloudbaseinit.metadata.services.opennebulaservice.OpenNebulaService
|
|
|
|
The *OpenNebula* provider is related to configuration drive and searches for
|
|
a specific context file which holds all the available info. The provided
|
|
details are exposed as bash variables gathered in a shell script.
|
|
|
|
Capabilities:
|
|
|
|
* instance ID (not present; usually a constant is returned)
|
|
* host name
|
|
* public keys
|
|
* static network configuration addresses
|
|
* user data
|
|
|
|
|
|
Ubuntu MaaS
|
|
-----------
|
|
|
|
.. class:: cloudbaseinit.metadata.services.maasservice.MaaSHttpService
|
|
|
|
This one works with instances on bare metal and uses web requests for
|
|
retrieving the available exposed metadata. It uses
|
|
`OAuth <http://oauth.net/>`_ to secure the requests.
|
|
|
|
Capabilities:
|
|
|
|
* instance ID
|
|
* host name
|
|
* public keys
|
|
* authentication certificates (x509)
|
|
* user data
|
|
|
|
----
|
|
|
|
Configuring available services
|
|
------------------------------
|
|
|
|
Some of these classes can be specified manually in the configuration file
|
|
under `metadata_services` option. Based on this option, the service loader
|
|
will search across these providers and try to load the most suitable one.
|
|
|
|
For more details on doing this, see :ref:`configuration <config>`
|
|
file in :ref:`tutorial`.
|