x/cloudbase-init
Code Issues Proposed changes
cloudbase-init/doc/source/tutorial.rst
Lucian Petrut 0d8b9ec347 docs: add automatically generated list of cfg opts 
This change will include an automatically generated list of
config options in the cloudbase-init docs.

It's useful as some config options are not currently mentioned in
the docs and it's also nice to be able to have a quick overview
of all available options without having to go through the code.
You can also send links to certain config options or groups.

Note that long config opt lines are not wrapped and look quite bad,
especially with the current theme (may consider switching to some
other theme, maybe the "alabaster" one included by default by
sphinx). Still better than not having this at all though.

We're also adding the zuul jobs that validate release notes and
docs, required for testing this patch.

Change-Id: Ibaff3a91e7f1345aaaac0c29b995e7c25b9e4669
2019-06-07 16:45:02 +03:00

4.8 KiB
Raw Blame History

Tutorial

First, download your desired type of installer from here <download>, then install it and fill in configuration options which suits you best. Based on the current selected cloudbase-init installer architecture, it'll be available under C:\Program Files or C:\Program Files (x86) as Cloudbase Solutions\Cloudbase-Init directory. There, are located some folders of interest like:

  • bin - Executable files and other binaries.
  • conf - Configuration files holding miscellaneous options.
  • log - Here are the cloudbase-init logs.
  • LocalScripts - User supplied scripts <execution>.
  • Python - Bundle of executable and library files to support Python scripts and core execution.

After install, cloudbase-init acts like a 2-step service which will read metadata using services and will pass that to the executing plugins, this way configuring all the supported things. Depending on the platform, some plugins may request reboots.

Sysprepping

The System Preparation (Sysprep) tool prepares an installation of Windows for duplication, auditing, and customer delivery. Duplication, also called imaging, enables you to capture a customized Windows image that you can reuse throughout an organization. The Sysprep phase uses the "Unattend.xml" which implies the service to run using the "cloudbase-init-unattend.conf" configuration file.

Configuration file

In the chosen installation path, under the conf directory, are present two config files named "cloudbase-init.conf" and "cloudbase-init-unattend.conf". These can hold various config options for picking up the desired available services and plugins ready for execution and also customizing user experience.

Explained example of configuration file:

[DEFAULT]
# What user to create and in which group(s) to be put.
username=Admin
groups=Administrators
inject_user_password=true  # Use password from the metadata (not random).
# Which devices to inspect for a possible configuration drive (metadata).
config_drive_raw_hhd=true
config_drive_cdrom=true
# Path to tar implementation from Ubuntu.
bsdtar_path=C:\Program Files (x86)\Cloudbase Solutions\Cloudbase-Init\bin\bsdtar.exe
# Logging debugging level.
verbose=true
debug=true
# Where to store logs.
logdir=C:\Program Files (x86)\Cloudbase Solutions\Cloudbase-Init\log\
logfile=cloudbase-init-unattend.log
default_log_levels=comtypes=INFO,suds=INFO,iso8601=WARN
logging_serial_port_settings=
# Enable MTU and NTP plugins.
mtu_use_dhcp_config=true
ntp_use_dhcp_config=true
# Where are located the user supplied scripts for execution.
local_scripts_path=C:\Program Files (x86)\Cloudbase Solutions\Cloudbase-Init\LocalScripts\
# Services that will be tested for loading until one of them succeeds.
metadata_services=cloudbaseinit.metadata.services.configdrive.ConfigDriveService,
                  cloudbaseinit.metadata.services.httpservice.HttpService,
                  cloudbaseinit.metadata.services.ec2service.EC2Service,
                  cloudbaseinit.metadata.services.maasservice.MaaSHttpService
# What plugins to execute.
plugins=cloudbaseinit.plugins.common.mtu.MTUPlugin,
        cloudbaseinit.plugins.common.sethostname.SetHostNamePlugin
# Miscellaneous.
allow_reboot=false    # allow the service to reboot the system
stop_service_on_exit=false

The "cloudbase-init-unattend.conf" configuration file is similar to the default one and is used by the Sysprepping phase. It was designed for the scenario where the minimum user intervention is required and it only runs the MTU and host name plugins, leaving the image ready for further initialization cases.

More of these explained options are available under the services, plugins and userdata documentation.

A complete list of config options can be found at config_list.

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 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.

Based on their return 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
  • 1002 - don't reboot now and run the plugin again on next boot
  • 1003 - reboot and run the plugin again on next boot