
Document plugins, metadata services, configuration file, how the project is supposed to work and some user related usecases. Change-Id: I184a9409a9e9173c346f0ab149cb7d78ed87e0b3
4.7 KiB
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.
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