From 0ae70d5fe431f7d4b41edd48bc2cd7cb9f4978a5 Mon Sep 17 00:00:00 2001 From: Adrian Vladu Date: Fri, 15 Nov 2019 14:47:20 +0200 Subject: [PATCH] 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 --- doc/source/conf.py | 2 +- doc/source/intro.rst | 13 +- doc/source/plugins.rst | 387 ++++++++++++++++++++++++++++++++++------ doc/source/services.rst | 268 ++++++++++++++++++++-------- doc/source/tutorial.rst | 10 +- doc/source/userdata.rst | 3 +- 6 files changed, 551 insertions(+), 132 deletions(-) diff --git a/doc/source/conf.py b/doc/source/conf.py index c8ea6e8d..0e64a443 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -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 diff --git a/doc/source/intro.rst b/doc/source/intro.rst index 91d7bc31..534c0c92 100644 --- a/doc/source/intro.rst +++ b/doc/source/intro.rst @@ -10,7 +10,7 @@ It was designed to initialize and configure guest operating systems under `CloudStack `_, `MaaS `_ and many others. Under `Cloudbase `_ 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. diff --git a/doc/source/plugins.rst b/doc/source/plugins.rst index c7f22e89..bc639a18 100644 --- a/doc/source/plugins.rst +++ b/doc/source/plugins.rst @@ -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 ` +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 `_ 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 `_ 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 ` 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 ` -file in :ref:`tutorial`. diff --git a/doc/source/services.rst b/doc/source/services.rst index 437acd07..76d994a9 100644 --- a/doc/source/services.rst +++ b/doc/source/services.rst @@ -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 ` +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 `_ 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 `_, `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 `_ to secure the requests. +Metadata version used: `2012-03-01`. + Capabilities: - * instance ID - * host name + * instance id + * hostname * public keys - * authentication certificates (x509) + * `WinRM `_ 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 `_ + which runs the hooks that set the config values. + On Windows, these hooks need to be present in the root directory: + `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 `_ 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 ` -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 `_ 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 `_ 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) diff --git a/doc/source/tutorial.rst b/doc/source/tutorial.rst index ec9be210..770afdad 100644 --- a/doc/source/tutorial.rst +++ b/doc/source/tutorial.rst @@ -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 ` 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 ` 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 diff --git a/doc/source/userdata.rst b/doc/source/userdata.rst index efdbe87f..2264ab43 100644 --- a/doc/source/userdata.rst +++ b/doc/source/userdata.rst @@ -35,8 +35,7 @@ environment variable). PowerShell ---------- - -**#ps1_sysnative** (system native) +**#ps1** or **#ps1_sysnative** (system native) **#ps1_x86** (Windows On Windows 32bit)