docs: Updated and fixed various doc parts
The following documentation parts were updated:
* copyright years
* stable installer urls were added
* PowerShell userdata header added (#ps1)
* Userdata types fixed
* Updated all the services config options
* Removed deprecated options for services
* Added Packet metadata service
* Added Azure metadata service
* Replaced return code with exit code in tutorial
(return code is not correct)
* Updated all the plugins config options
* Added all the undocumented plugins
* Added retry_count / retry_count_interval info
for all http based services
Change-Id: I6fdbdcaf45dec841e4080028d7d90cbbf6a6cb75
This commit is contained in:
Adrian Vladu
parent
208405289e
commit
0ae70d5fe4
@ -55,7 +55,7 @@ master_doc = 'index'
|
||||
|
||||
# General information about the project.
|
||||
project = u'cloudbase-init'
|
||||
copyright = u'2015, Cloudbase Solutions Srl'
|
||||
copyright = u'2012-2019, Cloudbase Solutions Srl'
|
||||
author = u'Cloudbase Solutions Srl'
|
||||
|
||||
# The version info for the project you're documenting, acts as replacement for
|
||||
|
||||
@ -10,7 +10,7 @@ It was designed to initialize and configure guest operating systems under
|
||||
`CloudStack <https://cloudstack.apache.org/>`_,
|
||||
`MaaS <https://maas.ubuntu.com/>`_ and many others.
|
||||
Under `Cloudbase <http://www.cloudbase.it/cloud-init-windows/>`_ page,
|
||||
beta and stable installers can be found and the service itself is very easy to
|
||||
stable and beta installers can be found and the service itself is very easy to
|
||||
configure through configuration files. It can also customize instances based
|
||||
on user input like local scripts and data.
|
||||
|
||||
@ -34,8 +34,15 @@ used on instances running on Hyper-V, KVM, Xen, ESXi etc.
|
||||
Binaries
|
||||
--------
|
||||
|
||||
The following x64 and x86 builds are automatically generated by a Jenkins
|
||||
job at every commit:
|
||||
Stable installers:
|
||||
|
||||
* https://www.cloudbase.it/downloads/CloudbaseInitSetup_Stable_x64.msi
|
||||
* https://www.cloudbase.it/downloads/CloudbaseInitSetup_Stable_x86.msi
|
||||
|
||||
Beta installers:
|
||||
|
||||
* https://www.cloudbase.it/downloads/CloudbaseInitSetup_x64.msi
|
||||
* https://www.cloudbase.it/downloads/CloudbaseInitSetup_x86.msi
|
||||
|
||||
Use a x64 installer on 64 bit versions of Windows and the x86 one
|
||||
exclusively on 32 bit versions.
|
||||
|
||||
@ -2,87 +2,140 @@ Plugins
|
||||
=======
|
||||
|
||||
Plugins execute actions based on the metadata obtained by the loaded service.
|
||||
They are intended to actually configure your instance using data provided by
|
||||
the cloud and even by the user. There are three stages for the plugins
|
||||
execution:
|
||||
They are intended to configure the instance using data provided by the underlying cloud and
|
||||
by the user who created the instance. There are three stages for the plugins' execution:
|
||||
|
||||
1. The `pre-networking` stage (for setting up the network, before doing any
|
||||
valid web request).
|
||||
1. The **PRE_NETWORKING** stage (for setting up the network, before doing any
|
||||
valid web request.
|
||||
|
||||
2. The `pre-metadata-discovery` one (additional configuration before the
|
||||
2. The **PRE_METADATA_DISCOVERY** stage (additional configuration before the
|
||||
metadata service discovery).
|
||||
|
||||
3. The `main` set of plugins, which holds the rest of the plugins which are
|
||||
(re)executed according to their saved status.
|
||||
3. The default **MAIN** stage, which holds the rest of the plugins which are
|
||||
(re)executed according to their saved status. The metadata service loaded needs to provide
|
||||
an instance id for the plugins to be able to have a saved status. If the metadata service
|
||||
cannot provide an instance id, the plugins state from the **MAIN** stage cannot be saved,
|
||||
and therefore, all plugins will be executed at every boot.
|
||||
|
||||
Note that the first two stages (1,2) are executed each time the service
|
||||
starts.
|
||||
Note that the plugins from the two stages are executed each time the cloudbase-init service
|
||||
starts (those plugins do not have saved status).
|
||||
|
||||
Current list of supported plugins:
|
||||
Just before the **MAIN** stage, the metadata service can report to the
|
||||
cloud service that the provision started. After the **MAIN** stage ended,
|
||||
the metadata service can report to the cloud service that the provisioning completed
|
||||
successfully or failed.
|
||||
|
||||
|
||||
Setting host name *(main)*
|
||||
----
|
||||
|
||||
|
||||
Configuring selected plugins
|
||||
----------------------------
|
||||
|
||||
By default, only a subset of plugins is executed. The plugins are:
|
||||
|
||||
.. code:: python
|
||||
|
||||
[DEFAULT]
|
||||
plugins = cloudbaseinit.plugins.common.mtu.MTUPlugin, cloudbaseinit.plugins.windows.ntpclient.NTPClientPlugin, cloudbaseinit.plugins.common.sethostname.SetHostNamePlugin, cloudbaseinit.plugins.windows.createuser.CreateUserPlugin, cloudbaseinit.plugins.common.networkconfig.NetworkConfigPlugin, cloudbaseinit.plugins.windows.licensing.WindowsLicensingPlugin, cloudbaseinit.plugins.common.sshpublickeys.SetUserSSHPublicKeysPlugin, cloudbaseinit.plugins.windows.extendvolumes.ExtendVolumesPlugin, cloudbaseinit.plugins.common.userdata.UserDataPlugin, cloudbaseinit.plugins.common.setuserpassword.SetUserPasswordPlugin, cloudbaseinit.plugins.windows.winrmlistener.ConfigWinRMListenerPlugin, cloudbaseinit.plugins.windows.winrmcertificateauth.ConfigWinRMCertificateAuthPlugin, cloudbaseinit.plugins.common.localscripts.LocalScriptsPlugin
|
||||
|
||||
|
||||
A custom list of plugins can be specified through the `plugins` option in the configuration file.
|
||||
|
||||
For more details on doing this, see :ref:`configuration <config>`
|
||||
file in :ref:`tutorial`.
|
||||
|
||||
|
||||
----
|
||||
|
||||
|
||||
Setting hostname (MAIN)
|
||||
--------------------------
|
||||
|
||||
.. class:: cloudbaseinit.plugins.common.sethostname.SetHostNamePlugin
|
||||
|
||||
Sets the instance's hostname. It may be truncated to 15 characters for Netbios
|
||||
compatibility reasons using the option below.
|
||||
Sets the instance hostname. The hostname gets truncated to 15 characters for
|
||||
Netbios compatibility reasons if `netbios_host_name_compatibility` is set.
|
||||
|
||||
Config options:
|
||||
|
||||
* netbios_host_name_compatibility (bool: True)
|
||||
|
||||
.. warning:: This may require a system restart.
|
||||
Notes:
|
||||
|
||||
* Requires support in the metadata service.
|
||||
* May require a system restart.
|
||||
|
||||
|
||||
Creating user *(main)*
|
||||
Creating user (MAIN)
|
||||
----------------------
|
||||
|
||||
.. class:: cloudbaseinit.plugins.windows.createuser.CreateUserPlugin
|
||||
|
||||
Creates (or updates if existing) a new user and adds it to a
|
||||
set of provided local groups. By default, it creates the user "Admin" under
|
||||
"Administrators" group, but this can be changed under configuration file.
|
||||
"Administrators" group, but this can be changed in the configuration file.
|
||||
|
||||
A random user password is set for the user. The password length is by default set
|
||||
to 20 and can be customized using the `user_password_length` configuration option.
|
||||
|
||||
If `rename_admin_user` is set to `True`, the user `Administrator` is renamed
|
||||
to the `username` config value or to the metadata service provided value.
|
||||
|
||||
Config options:
|
||||
|
||||
* username (string: "Admin")
|
||||
* groups (list of strings: ["Administrators"])
|
||||
* user_password_length (int: 20)
|
||||
* rename_admin_user (bool: false)
|
||||
|
||||
Notes:
|
||||
|
||||
* The metadata service can provide the username. If the metadata service
|
||||
provides the admin username, it will override the `username` configuration
|
||||
value.
|
||||
|
||||
|
||||
Setting password *(main)*
|
||||
Setting password (MAIN)
|
||||
-------------------------
|
||||
|
||||
.. class:: cloudbaseinit.plugins.common.setuserpassword.SetUserPasswordPlugin
|
||||
|
||||
Sets the cloud user's password. If a password has been provided in the metadata
|
||||
during boot it will be used, otherwise a random password will be generated,
|
||||
encrypted with the user's SSH public key and posted to the metadata provider
|
||||
(currently supported only by the OpenStack HTTP metadata provider).
|
||||
encrypted with the user's SSH public key and posted to the metadata provider.
|
||||
|
||||
An option called `inject_user_password` is set *True* by default to make
|
||||
available the use of metadata password which is found under the "admin_pass"
|
||||
field or through an URL request. If the option is set to *False* or if the
|
||||
password isn't found in metadata, then an attempt of using an already set
|
||||
password is done (usually a random value by the `createuser` plugin).
|
||||
password is done (usually a random value by the CreateUserPlugin plugin).
|
||||
With `first_logon_behaviour` you can control what happens with the password at
|
||||
the next logon. If this option is set to "always", the user will be forced to
|
||||
change the password at the next logon.
|
||||
|
||||
If it is set to "clear_text_injected_only",
|
||||
the user will be forced to change the password only if the password is a
|
||||
clear text password, coming from the metadata. The last option is "no",
|
||||
when the user is never forced.
|
||||
when the user is never forced to change the password.
|
||||
|
||||
Config options:
|
||||
|
||||
* username (string: "Admin")
|
||||
* inject_user_password (bool: True)
|
||||
* first_logon_behaviour (string: "clear_text_injected_only")
|
||||
* user_password_length (int: 20)
|
||||
|
||||
.. note:: This plugin can run multiple times (for posting the password if the
|
||||
metadata service supports this).
|
||||
Notes:
|
||||
|
||||
* The metadata service may provide the username. If the metadata service
|
||||
provides the admin username, it will override the `username` configuration
|
||||
value.
|
||||
* May run at every boot to (re)set and post the password if the
|
||||
metadata service supports this behaviour.
|
||||
|
||||
|
||||
Static networking *(main)*
|
||||
Static networking (MAIN)
|
||||
--------------------------
|
||||
|
||||
.. class:: cloudbaseinit.plugins.common.networkconfig.NetworkConfigPlugin
|
||||
@ -95,10 +148,15 @@ too if they are enabled and exposed to the metadata.
|
||||
The purpose of this plugin is to configure network adapters, for which the
|
||||
DHCP server is disabled, to have internet access and static IPs.
|
||||
|
||||
.. warning:: This may require a system restart.
|
||||
NIC teaming (bonding) is supported and uses `NetLBFO <https://docs.microsoft.com/en-us/windows-server/networking/technologies/nic-teaming/nic-teaming>`_ implementation.
|
||||
|
||||
Notes:
|
||||
|
||||
* Requires support in the metadata service.
|
||||
* May require a system restart.
|
||||
|
||||
|
||||
Saving public keys *(main)*
|
||||
Saving public keys (MAIN)
|
||||
---------------------------
|
||||
|
||||
.. class:: cloudbaseinit.plugins.common.sshpublickeys.SetUserSSHPublicKeysPlugin
|
||||
@ -111,8 +169,16 @@ Config options:
|
||||
|
||||
* username (string: "Admin")
|
||||
|
||||
Notes:
|
||||
|
||||
Volume expanding *(main)*
|
||||
* Requires support in the metadata service. The metadata service provides
|
||||
the SSH public keys.
|
||||
* The metadata service can provide the username. If the metadata service
|
||||
provides the admin username, it will override the `username` configuration
|
||||
value.
|
||||
|
||||
|
||||
Volume expanding (MAIN)
|
||||
-------------------------
|
||||
|
||||
.. class:: cloudbaseinit.plugins.windows.extendvolumes.ExtendVolumesPlugin
|
||||
@ -126,10 +192,12 @@ Config options:
|
||||
|
||||
* volumes_to_extend (list of integers: None)
|
||||
|
||||
.. note:: This plugin will run at every boot.
|
||||
Notes:
|
||||
|
||||
* Runs at every boot.
|
||||
|
||||
|
||||
WinRM listener *(main)*
|
||||
WinRM listener (MAIN)
|
||||
-----------------------
|
||||
|
||||
.. class:: cloudbaseinit.plugins.windows.winrmlistener.ConfigWinRMListenerPlugin
|
||||
@ -138,17 +206,28 @@ Configures a WinRM HTTPS listener to allow remote management via
|
||||
`WinRM <https://msdn.microsoft.com/en-us/library/aa384426(v=vs.85).aspx>`_
|
||||
or PowerShell.
|
||||
|
||||
If `winrm_enable_basic_auth` is set to True, it enables basic authentication
|
||||
(authentication using username and password) for the WinRM listeners.
|
||||
|
||||
If `winrm_configure_http_listener` is set to True, the WinRM http listener will also
|
||||
be enabled.
|
||||
|
||||
Config options:
|
||||
|
||||
* winrm_enable_basic_auth (bool: True)
|
||||
* winrm_configure_https_listener (bool: True)
|
||||
* winrm_configure_http_listener (bool: False)
|
||||
|
||||
.. note:: This plugin will run until a full and proper configuration
|
||||
will take place.
|
||||
Notes:
|
||||
* The metadata service can provide the listeners configuration (protocol
|
||||
and certificate thumbprint).
|
||||
* May run at every boot. If the `WinRM` Windows service does not exist,
|
||||
it will run at the next boot.
|
||||
|
||||
|
||||
.. _certificate:
|
||||
|
||||
WinRM certificate *(main)*
|
||||
WinRM certificate (MAIN)
|
||||
--------------------------
|
||||
|
||||
.. class:: cloudbaseinit.plugins.windows.winrmcertificateauth.ConfigWinRMCertificateAuthPlugin
|
||||
@ -160,18 +239,28 @@ Config options:
|
||||
|
||||
* username (string: "Admin")
|
||||
|
||||
.. note:: http://www.cloudbase.it/windows-without-passwords-in-openstack/
|
||||
Notes
|
||||
|
||||
* Requires support in the metadata service.
|
||||
The metadata service must provide the certificate metadata.
|
||||
The admin user password needs to be present, either from the metadata,
|
||||
either as shared data set by running CreateUserPlugin or SetUserPasswordPlugin.
|
||||
The metadata service can provide the username. If the metadata service
|
||||
provides the admin username, it will override the `username` configuration
|
||||
value.
|
||||
* How to use this feature: http://www.cloudbase.it/windows-without-passwords-in-openstack/
|
||||
|
||||
|
||||
.. _scripts:
|
||||
|
||||
Scripts execution *(main)*
|
||||
--------------------------
|
||||
Local Scripts execution (MAIN)
|
||||
--------------------------------
|
||||
|
||||
.. class:: cloudbaseinit.plugins.common.localscripts.LocalScriptsPlugin
|
||||
|
||||
Executes any script (powershell, batch, python etc.) located in the following
|
||||
path indicated by `local_scripts_path` option.
|
||||
|
||||
More details about the supported scripts and content can be found
|
||||
in :ref:`tutorial` on :ref:`file execution <execution>` subject.
|
||||
|
||||
@ -179,25 +268,40 @@ Config options:
|
||||
|
||||
* local_scripts_path (string: None)
|
||||
|
||||
.. warning:: This may require a system restart.
|
||||
Notes:
|
||||
|
||||
.. note:: This plugin may run multiple times (depending on the script(s)
|
||||
return code).
|
||||
* May require a system restart.
|
||||
* May run at every boot. It depends on the exit codes of the scripts.
|
||||
|
||||
|
||||
Licensing *(main)*
|
||||
Licensing (MAIN)
|
||||
------------------
|
||||
|
||||
.. class:: cloudbaseinit.plugins.windows.licensing.WindowsLicensingPlugin
|
||||
|
||||
Activates the Windows instance if the `activate_windows` option is *True*.
|
||||
If `set_kms_product_key` or `set_avma_product_key` are set, it will use that
|
||||
KMS or AVMA product key in Windows.
|
||||
|
||||
If `kms_host` is set, it will set the provided host as the KMS licensing server.
|
||||
|
||||
Config options:
|
||||
|
||||
* activate_windows (bool: False)
|
||||
* set_kms_product_key (bool: False)
|
||||
* set_avma_product_key (bool: False)
|
||||
* kms_host (string: None)
|
||||
* log_licensing_info (bool: True)
|
||||
|
||||
Notes:
|
||||
|
||||
* The metadata service can provide the KMS host, overriding the configuration
|
||||
option `kms_host`.
|
||||
The metadata service can provide the avma_product_key, overriding the configuration
|
||||
option `set_avma_product_key`.
|
||||
|
||||
|
||||
Clock synchronization *(pre-networking)*
|
||||
Clock synchronization (PRE_NETWORKING)
|
||||
----------------------------------------
|
||||
|
||||
.. class:: cloudbaseinit.plugins.windows.ntpclient.NTPClientPlugin
|
||||
@ -206,14 +310,23 @@ Applies NTP client info based on the DHCP server options, if available. This
|
||||
behavior is enabled only when the `ntp_use_dhcp_config` option is set
|
||||
to *True* (which by default is *False*).
|
||||
|
||||
If `real_time_clock_utc` is set to True, it will set the real time clock to use
|
||||
universal time. If set to `False`, it will set the real time clock to use the
|
||||
local time.
|
||||
|
||||
Config options:
|
||||
|
||||
* ntp_use_dhcp_config (bool: False)
|
||||
* real_time_clock_utc (bool: False)
|
||||
* ntp_enable_service (bool: True)
|
||||
|
||||
.. note:: This plugin will run until the NTP client is configured.
|
||||
Notes:
|
||||
|
||||
* May require a reboot.
|
||||
* May run at every boot.
|
||||
|
||||
|
||||
MTU customization *(pre-metadata-discovery)*
|
||||
MTU customization (PRE_METADATA_DISCOVERY)
|
||||
--------------------------------------------
|
||||
|
||||
.. class:: cloudbaseinit.plugins.common.mtu.MTUPlugin
|
||||
@ -227,10 +340,12 @@ Config options:
|
||||
|
||||
* mtu_use_dhcp_config (bool: True)
|
||||
|
||||
.. note:: This plugin will run at every boot.
|
||||
Notes:
|
||||
|
||||
* Runs at every boot.
|
||||
|
||||
|
||||
User data *(main)*
|
||||
User data (MAIN)
|
||||
------------------
|
||||
|
||||
.. class:: cloudbaseinit.plugins.common.userdata.UserDataPlugin
|
||||
@ -239,13 +354,183 @@ Executes custom scripts provided by user data metadata as plain text or
|
||||
compressed with Gzip.
|
||||
More details, examples and possible formats here: :ref:`userdata`.
|
||||
|
||||
----
|
||||
|
||||
Configuring selected plugins
|
||||
Trim Config (MAIN)
|
||||
------------------
|
||||
|
||||
.. class:: cloudbaseinit.plugins.common.trim.TrimConfigPlugin
|
||||
|
||||
Enables or disables TRIM delete notifications for the underlying
|
||||
storage device.
|
||||
|
||||
Config options:
|
||||
|
||||
* trim_enabled (bool: False)
|
||||
|
||||
|
||||
San Policy Config (MAIN)
|
||||
------------------------
|
||||
|
||||
.. class:: cloudbaseinit.plugins.windows.sanpolicy.SANPolicyPlugin
|
||||
|
||||
If not None, the SAN policy is set to the given value of the configuration
|
||||
option `san_policy`. The possible values are: OnlineAll, OfflineAll or OfflineShared.
|
||||
|
||||
Config options:
|
||||
|
||||
* san_policy (string: None)
|
||||
|
||||
|
||||
RDP Settings Config (MAIN)
|
||||
--------------------------
|
||||
|
||||
.. class:: cloudbaseinit.plugins.windows.rdp.RDPSettingsPlugin
|
||||
|
||||
Sets the registry key `KeepAliveEnable`, to enable or disable the RDP keep alive functionality.
|
||||
|
||||
Config options:
|
||||
|
||||
* rdp_set_keepalive (bool: False)
|
||||
|
||||
|
||||
RDP Post Certificate Thumbprint (MAIN)
|
||||
--------------------------------------
|
||||
|
||||
.. class:: cloudbaseinit.plugins.windows.rdp.RDPPostCertificateThumbprintPlugin
|
||||
|
||||
Posts the RDP certificate thumbprint to the metadata service endpoint.
|
||||
|
||||
Notes:
|
||||
|
||||
* Requires support in the metadata service.
|
||||
The metadata service should expose an HTTP endpoint where the certificate
|
||||
thumbprint can be posted.
|
||||
|
||||
|
||||
Page Files (MAIN)
|
||||
-----------------
|
||||
|
||||
.. class:: cloudbaseinit.plugins.windows.pagefiles.PageFilesPlugin
|
||||
|
||||
Sets custom page files according to the config options.
|
||||
|
||||
Config options:
|
||||
|
||||
* page_file_volume_labels (array: [])
|
||||
* page_file_volume_mount_points (array: [])
|
||||
|
||||
Notes:
|
||||
|
||||
* May require a reboot.
|
||||
If the page file is configured, a reboot is required.
|
||||
* Runs at every boot.
|
||||
|
||||
|
||||
Display Idle Timeout Config (MAIN)
|
||||
----------------------------------
|
||||
|
||||
.. class:: cloudbaseinit.plugins.windows.displayidletimeout.DisplayIdleTimeoutConfigPlugin
|
||||
|
||||
Sets the idle timeout, in seconds, before powering off the display.
|
||||
Set 0 to leave the display always on.
|
||||
|
||||
Config options:
|
||||
|
||||
* display_idle_timeout (int: 0)
|
||||
|
||||
|
||||
Boot Status Policy Config (MAIN)
|
||||
--------------------------------
|
||||
|
||||
.. class:: cloudbaseinit.plugins.windows.bootconfig.BootStatusPolicyPlugin
|
||||
|
||||
Sets the Windows BCD boot status policy according to the config option.
|
||||
When set, the only possible value for `bcd_boot_status_policy` is `ignoreallfailures`.
|
||||
|
||||
Config options:
|
||||
|
||||
* bcd_boot_status_policy (string: None)
|
||||
|
||||
|
||||
BCD Config (MAIN)
|
||||
-----------------------
|
||||
|
||||
.. class:: cloudbaseinit.plugins.windows.bootconfig.BCDConfigPlugin
|
||||
|
||||
A unique disk ID is needed to avoid disk signature collisions.
|
||||
This plugin resets the boot disk id and enables auto-recovery in the
|
||||
BCD store.
|
||||
|
||||
Config options:
|
||||
|
||||
* set_unique_boot_disk_id (bool: False)
|
||||
* bcd_enable_auto_recovery (bool: False)
|
||||
|
||||
|
||||
Ephemeral Disk Config (MAIN)
|
||||
----------------------------
|
||||
|
||||
By default, all plugins are executed, but a custom list of them can be
|
||||
specified through the `plugins` option in the configuration file.
|
||||
.. class:: cloudbaseinit.plugins.common.ephemeraldisk.EphemeralDiskPlugin
|
||||
|
||||
Sets the ephemeral disk data loss warning file.
|
||||
On public clouds like Azure, the ephemeral disk should contain a read only
|
||||
file with data loss warning text, that warns the user to not use the
|
||||
ephemeral disk as a persistent storage disk.
|
||||
|
||||
Config options:
|
||||
|
||||
* ephemeral_disk_volume_label (string: None)
|
||||
* ephemeral_disk_volume_mount_point (string: None)
|
||||
* ephemeral_disk_data_loss_warning_path (string: None)
|
||||
|
||||
Notes:
|
||||
|
||||
* Requires support in the metadata service.
|
||||
The metadata service should provide the disk data loss warning text.
|
||||
|
||||
|
||||
Windows Auto Updates (MAIN)
|
||||
---------------------------
|
||||
|
||||
.. class:: cloudbaseinit.plugins.windows.updates.WindowsAutoUpdatesPlugin
|
||||
|
||||
Enables automatic Windows updates based on the user configuration or
|
||||
the metadata service information. The metadata service setting takes
|
||||
priority over the configuration option.
|
||||
|
||||
Config options:
|
||||
|
||||
* enable_automatic_updates (bool: False)
|
||||
|
||||
Notes:
|
||||
|
||||
* If the metadata service provides the information needed to enable the
|
||||
automatic updates, it will override the `enable_automatic_updates`
|
||||
configuration value.
|
||||
|
||||
|
||||
Server Certificates (MAIN)
|
||||
--------------------------
|
||||
|
||||
.. class:: cloudbaseinit.plugins.windows.certificates.ServerCertificatesPlugin
|
||||
|
||||
Imports X509 certificates into the desired store location. The metadata service
|
||||
provides the certificate and key in a PFX archive, their store location and store name.
|
||||
|
||||
Notes:
|
||||
|
||||
* Requires support in the metadata service.
|
||||
|
||||
|
||||
Azure Guest Agent (MAIN)
|
||||
------------------------
|
||||
|
||||
.. class:: cloudbaseinit.plugins.windows.azureguestagent.AzureGuestAgentPlugin
|
||||
|
||||
Installs Azure Guest agent, which is required for the Azure cloud platform.
|
||||
|
||||
Notes:
|
||||
|
||||
* Requires support in the metadata service.
|
||||
Azure metadata service should provide the agent package provisioning data.
|
||||
|
||||
For more details on doing this, see :ref:`configuration <config>`
|
||||
file in :ref:`tutorial`.
|
||||
|
||||
@ -1,13 +1,29 @@
|
||||
Services
|
||||
========
|
||||
|
||||
A **metadata service** has the role of pulling the guest provided data
|
||||
A **metadata service** has the role of getting 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.
|
||||
configuration options documented below.
|
||||
|
||||
Supported metadata services (cloud specific):
|
||||
|
||||
------
|
||||
|
||||
|
||||
Configuring available services
|
||||
------------------------------
|
||||
|
||||
Any 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 in the defined order and load the first
|
||||
one that is available.
|
||||
|
||||
For more details on doing this, see :ref:`configuration <config>`
|
||||
file in :ref:`tutorial`.
|
||||
|
||||
|
||||
------
|
||||
|
||||
|
||||
.. _httpservice:
|
||||
@ -17,29 +33,37 @@ 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
|
||||
A complete service which supports password related capabilities and
|
||||
can be usually accessed at the http://169.254.169.254/ magic URL.
|
||||
The magic URL can be customized using the `metadata_base_url` config option.
|
||||
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.
|
||||
|
||||
Metadata version used: `latest`.
|
||||
|
||||
Capabilities:
|
||||
|
||||
* instance ID
|
||||
* host name
|
||||
* instance id
|
||||
* hostname
|
||||
* public keys
|
||||
* authentication certificates (metadata + user data)
|
||||
* static network configuration addresses
|
||||
* admin password
|
||||
* `WinRM <https://docs.microsoft.com/en-us/windows/win32/winrm/authentication-for-remote-connections#client-certificate-based-authentication>`_ authentication certificates
|
||||
* static network configuration
|
||||
* admin user password
|
||||
* post admin user password (only once)
|
||||
* user data
|
||||
* user content (additional files)
|
||||
* ability to post passwords
|
||||
|
||||
Config options:
|
||||
Config options for `openstack` section:
|
||||
|
||||
* metadata_base_url (string: "http://169.254.169.254/")
|
||||
* add_metadata_private_ip_route (bool: True)
|
||||
* https_allow_insecure (bool: False)
|
||||
* https_ca_bundle (string: None)
|
||||
|
||||
Config options for `default` section:
|
||||
|
||||
* retry_count (integer: 5)
|
||||
* retry_count_interval (integer: 4)
|
||||
|
||||
|
||||
.. _configdrive:
|
||||
@ -54,44 +78,39 @@ 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
|
||||
Use the `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`
|
||||
`locations` option.
|
||||
|
||||
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)
|
||||
*mtools* (specified by the `mtools_path` option in the `Default` section)
|
||||
|
||||
The interesting part with this service is the fact that is quite fast in
|
||||
comparison with the HTTP twin.
|
||||
This service is usually faster than the HTTP twin, as there is no timeout
|
||||
waiting for the network to be up.
|
||||
|
||||
Metadata version used: `latest`.
|
||||
|
||||
Capabilities:
|
||||
|
||||
* instance ID
|
||||
* host name
|
||||
* public keys (search in the entire metadata)
|
||||
* authentication certificates (metadata + user data)
|
||||
* static network configuration addresses
|
||||
* admin password
|
||||
* instance id
|
||||
* hostname
|
||||
* public keys
|
||||
* authentication certificates
|
||||
* static network configuration
|
||||
* admin user password
|
||||
* user data
|
||||
* user content (additional files)
|
||||
|
||||
Config options:
|
||||
Config options for `config_drive` section:
|
||||
|
||||
* config_drive_types (list: ["vfat", "iso"])
|
||||
* config_drive_locations (list: ["cdrom", "hdd", "partition"])
|
||||
* mtools_path (string: None)
|
||||
* raw_hdd (bool: True)
|
||||
* cdrom (bool: True)
|
||||
* vfat (bool: True)
|
||||
* types (list: ["vfat", "iso"])
|
||||
* locations (list: ["cdrom", "hdd", "partition"])
|
||||
|
||||
|
||||
Amazon EC2
|
||||
@ -100,18 +119,28 @@ 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.
|
||||
format for metadata endpoints and has general capabilities.
|
||||
|
||||
Metadata version used: `2009-04-04`.
|
||||
|
||||
Capabilities:
|
||||
|
||||
* instance ID
|
||||
* host name
|
||||
* instance id
|
||||
* hostname
|
||||
* public keys
|
||||
* user data
|
||||
|
||||
Config options:
|
||||
Config options for `ec2` section:
|
||||
|
||||
* ec2_metadata_base_url (string: "http://169.254.169.254/")
|
||||
* ec2_add_metadata_private_ip_route (bool: True)
|
||||
* metadata_base_url (string: "http://169.254.169.254/")
|
||||
* add_metadata_private_ip_route (bool: True)
|
||||
* https_allow_insecure (bool: False)
|
||||
* https_ca_bundle (string: None)
|
||||
|
||||
Config options for `default` section:
|
||||
|
||||
* retry_count (integer: 5)
|
||||
* retry_count_interval (integer: 4)
|
||||
|
||||
.. note:: http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-metadata.html
|
||||
|
||||
@ -122,19 +151,30 @@ Apache CloudStack
|
||||
.. class:: cloudbaseinit.metadata.services.cloudstack.CloudStack
|
||||
|
||||
Another web-based service which usually uses "10.1.1.1" or DHCP addresses for
|
||||
retrieving content.
|
||||
retrieving content. If no metadata can be found at the `metadata_base_url`,
|
||||
the service will look for the metadata at the DHCP server URL.
|
||||
|
||||
Capabilities:
|
||||
|
||||
* instance ID
|
||||
* host name
|
||||
* instance id
|
||||
* hostname
|
||||
* public keys
|
||||
* admin password (retrieval/deletion/polling)
|
||||
* admin user password
|
||||
* poll for, post, delete admin user password (each reboot)
|
||||
* user data
|
||||
|
||||
Config options:
|
||||
Config options for `cloudstack` section:
|
||||
|
||||
* cloudstack_metadata_ip (string: "10.1.1.1")
|
||||
* metadata_base_url (string: "http://10.1.1.1/")
|
||||
* password_server_port (int: 8080)
|
||||
* add_metadata_private_ip_route (bool: True)
|
||||
* https_allow_insecure (bool: False)
|
||||
* https_ca_bundle (string: None)
|
||||
|
||||
Config options for `default` section:
|
||||
|
||||
* retry_count (integer: 5)
|
||||
* retry_count_interval (integer: 4)
|
||||
|
||||
.. note:: By design, this service can update the password anytime, so it will
|
||||
cause the `setuserpassword` plugin to run at every boot and
|
||||
@ -154,30 +194,59 @@ details are exposed as bash variables gathered in a shell script.
|
||||
|
||||
Capabilities:
|
||||
|
||||
* instance ID (not present; usually a constant is returned)
|
||||
* host name
|
||||
* hardcoded instance id to `iid-dsopennebula`
|
||||
* hostname
|
||||
* public keys
|
||||
* static network configuration addresses
|
||||
* static network configuration
|
||||
* user data
|
||||
|
||||
Config options for `default` section:
|
||||
|
||||
* retry_count (integer: 5)
|
||||
* retry_count_interval (integer: 4)
|
||||
|
||||
|
||||
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
|
||||
This metadata service usually works with instances on baremetal and
|
||||
uses web requests for retrieving the available exposed metadata. It uses
|
||||
`OAuth <http://oauth.net/>`_ to secure the requests.
|
||||
|
||||
Metadata version used: `2012-03-01`.
|
||||
|
||||
Capabilities:
|
||||
|
||||
* instance ID
|
||||
* host name
|
||||
* instance id
|
||||
* hostname
|
||||
* public keys
|
||||
* authentication certificates (x509)
|
||||
* `WinRM <https://docs.microsoft.com/en-us/windows/win32/winrm/authentication-for-remote-connections#client-certificate-based-authentication>`_ authentication certificates
|
||||
* static network configuration
|
||||
* user data
|
||||
|
||||
Config options for `maas` section:
|
||||
|
||||
* metadata_base_url (string: None)
|
||||
* oauth_consumer_key (string: None)
|
||||
* oauth_consumer_secret (string: None)
|
||||
* oauth_token_key (string: None)
|
||||
* oauth_token_secret (string: None)
|
||||
* https_allow_insecure (bool: False)
|
||||
* https_ca_bundle (string: None)
|
||||
|
||||
Config options for `default` section:
|
||||
|
||||
* retry_count (integer: 5)
|
||||
* retry_count_interval (integer: 4)
|
||||
|
||||
.. note:: By design, the configuration options are set by an agent
|
||||
called `curtin <https://curtin.readthedocs.io/en/latest/topics/overview.html>`_
|
||||
which runs the hooks that set the config values.
|
||||
On Windows, these hooks need to be present in the root directory:
|
||||
`Windows curtin hooks <https://github.com/cloudbase/windows-curtin-hooks>`_.
|
||||
|
||||
|
||||
Open Virtualization Format (OVF)
|
||||
--------------------------------
|
||||
@ -187,10 +256,12 @@ Open Virtualization Format (OVF)
|
||||
The *OVF* provider searches data from OVF environment ISO transport.
|
||||
|
||||
Capabilities:
|
||||
* instance ID
|
||||
* host name
|
||||
|
||||
* instance id (hardcoded to `iid-ovf` if not present)
|
||||
* hostname
|
||||
* public keys
|
||||
* admin password
|
||||
* admin user name
|
||||
* admin user password
|
||||
* user data
|
||||
|
||||
Config options:
|
||||
@ -199,14 +270,71 @@ Config options:
|
||||
* drive_label (string: "OVF ENV")
|
||||
* ns (string: "oe")
|
||||
|
||||
----
|
||||
Packet Service
|
||||
--------------
|
||||
|
||||
Configuring available services
|
||||
------------------------------
|
||||
.. class:: cloudbaseinit.metadata.services.packet.PacketService
|
||||
|
||||
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.
|
||||
`Packet <packet.net>`_ metadata service provides the metadata for baremetal servers
|
||||
at the magic URL `https://metadata.packet.net/`.
|
||||
|
||||
For more details on doing this, see :ref:`configuration <config>`
|
||||
file in :ref:`tutorial`.
|
||||
Capabilities:
|
||||
|
||||
* instance id
|
||||
* hostname
|
||||
* public keys
|
||||
* user data
|
||||
|
||||
Config options for `packet` section:
|
||||
|
||||
* metadata_base_url (string: "https://metadata.packet.net/")
|
||||
* https_allow_insecure (bool: False)
|
||||
* https_ca_bundle (string: None)
|
||||
|
||||
Config options for `default` section:
|
||||
|
||||
* retry_count (integer: 5)
|
||||
* retry_count_interval (integer: 4)
|
||||
|
||||
|
||||
Azure Service
|
||||
--------------
|
||||
|
||||
.. class:: cloudbaseinit.metadata.services.azureservice.AzureService
|
||||
|
||||
`Azure <https://azure.microsoft.com/>`_ metadata service provides the metadata
|
||||
for Microsoft Azure cloud platform.
|
||||
|
||||
Azure metadata is offered via multiple sources like HTTP metadata, config-drive metadata
|
||||
and KVP (Hyper-V Key-Value Pair Data Exchange).
|
||||
This implementation uses only HTTP and config-drive metadata sources.
|
||||
|
||||
Azure service implements the interface to notify the cloud provider when the instance
|
||||
has started provisioning, completed provisioning and if the provisioning failed.
|
||||
|
||||
Metadata version used: `2015-04-05`.
|
||||
|
||||
Capabilities:
|
||||
|
||||
* instance id
|
||||
* hostname
|
||||
* public keys
|
||||
* `WinRM <https://docs.microsoft.com/en-us/windows/win32/winrm/authentication-for-remote-connections#client-certificate-based-authentication>`_ authentication certificates
|
||||
* admin user name
|
||||
* admin user password
|
||||
* user data
|
||||
* post RDP certificate thumbprint
|
||||
* provisioning status
|
||||
* Windows Update status
|
||||
* VM agent configuration
|
||||
* licensing configuration
|
||||
* ephemeral disk warning
|
||||
|
||||
Config options for `azure` section:
|
||||
|
||||
* transport_cert_store_name (string: Windows Azure Environment")
|
||||
|
||||
Config options for `default` section:
|
||||
|
||||
* retry_count (integer: 5)
|
||||
* retry_count_interval (integer: 4)
|
||||
|
||||
@ -101,12 +101,12 @@ File execution
|
||||
Cloudbase-init has the ability to execute user provided scripts, usually
|
||||
found in the default path
|
||||
*C:\\Program Files (x86)\\Cloudbase Solutions\\Cloudbase-Init\\LocalScripts*,
|
||||
through a specific :ref:`plugin <scripts>` for doing this stuff. Depending on
|
||||
the platform used, the files should be valid MZPEs, PowerShell, Python,
|
||||
Batch or Bash scripts, containing the actual code. The user data plugin is
|
||||
also capable of executing various script types and return code value handling.
|
||||
through a specific :ref:`plugin <scripts>` for doing it. Depending on
|
||||
the platform used, the files should be valid PowerShell, Python, Batch or Bash scripts.
|
||||
The userdata can be also a PEM certificate, in a cloud-config format or a MIME content.
|
||||
The user data plugin is capable of executing various script types and exit code value handling.
|
||||
|
||||
Based on their return codes, you can instruct the system to reboot or even
|
||||
Based on their exit codes, you can instruct the system to reboot or even
|
||||
re-execute the plugin on the next boot:
|
||||
|
||||
* 1001 - reboot and don't run the plugin again on next boot
|
||||
|
||||
@ -35,8 +35,7 @@ environment variable).
|
||||
|
||||
PowerShell
|
||||
----------
|
||||
|
||||
**#ps1_sysnative** (system native)
|
||||
**#ps1** or **#ps1_sysnative** (system native)
|
||||
|
||||
**#ps1_x86** (Windows On Windows 32bit)
|
||||
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user