User Tools
This is an old revision of the document!
Table of Contents
[] - these are my comments
Installation of Cloudbase-Init
Short description:
Given the increasing demand in automated configurations for virtual instances at an early initialization for Windows guests, the open source, Apache 2 licensed project called cloudbase-init has been set out to do just that. Hence, following the logical thread of the cloud-init project, which enables configurations for various Linux distributions, our package release helps configure Windows instances.
What can it do? <=> Capabilities
The primary capabilities of the package consist of: creating a user enabling password injection configuring static network setting up a hostname attaching public keys to the users for their connection to the server; the path at which they are found: C:\Users\Admin.ssh\authorized-keys execution of User Data scripts either from the setup[but how can you do that from the setup?] or [?maybe] in the command line, or through a file path specified in the metadata service[ ? or provider].
Which Windows distros can support it? <=> Availability
So far, the Windows distributions that can support its installation are: [use bullets] Windows Server 2003 Windows Server 2003 R2 Windows Server 2008 Windows Server 2008 R2 Windows Server 2012 Windows 7 *Windows 8. The addresses at which you can get your hand on the installer are the x64 version or x86 version We have available a Windows Server 2012 R2 image on which cloudbase-init is pre-installed. This image can be obtained at this address http://www.cloudbase.it/ws2012r2/ and, after accepting the Microsoft Licence Agreement, one can download the .iso file and the instance is good to boot. In our case, it is meant to work as a hypervisor machine, having HyperV or KVM installed.
Formats:
The user data provided with the metadata service should be written in one of these formats, as seen in the userdataplugins directory. *Note:* there are a few formats which do not have an implementation [?just yet? or this: given the fact that Heat can provide configurations or? file/command execution based on these types, there is no need for their implementation anymore]: cloudboothook, cloudconfig and multipartmixed.
Gzip Compressed File
The userdata content is provided in gzip compression format. The given file will be uncompressed and used afterwards in the configuration process. [in the cloud-init we have this as well "This is typically is useful because user-data is limited to ~16384 [1] bytes." Is this true for all userdata?]
Part Handler File
The part-handler is provided as a mime type "text/part-handler"
which will be loaded in a temporary generated file.
In case the generated part handler file has the list_types()
method and the handle_part attribute [in the cloud-init it is a method,
as well], the PartHandlerPlugin will provide a dictionary with the
handled parts for each type returned from the list_types()
[each type is a mime].
[apparently, in the cloud-init handle-type, which I believe is
handle-part, is called by cloud-init outside the "plugin"]
Shell Script File
Generally used for execution of shell scripts. A temporary file
is created and loaded with the user-data, then it is executed and,
finally, is erased from the temp directory.
Heat File
Saves heat configurations in the "C:\\cfn" directory and executes
the corresponding script out of the following: command, bash, python, or powershell.
Directory layout
The default installation path for the cloudbase-init files is <Root-Directory>\Program Files (x86)\Cloudbase\Cloudbase-Init. Here one can find the directories containing the config and log files, a freshly installed python environment which also contains a cloudbase-init-script.py through which the cloudbase-init.exe gets run. [TODO layout for these] The code which is executed when running the cloudbase-init.exe is placed in the following hierarchy:[maybe directory tree]
./cludbaseinit
Folder where the cloudbase-init subfolders are located. Also, init.py is the file containing the main method, configure_host().
./cloudbaseinit/metadata
In this folder are the available services for reading metadata from various providers: HTTP, ConfigDrive, EC2, Maas (and such). [Guess specifying what they're gonna read is in order... assuming users don't know what a metadata is and what it should provide]. Among the information provided are the host name, network configuration, access to the administrator's password and retrieval of the user data executed at early boot.
./cloudbaseinit/openstack/common
Here we can find the utils that deal with the specifics for remote data transmission, data formats and serialization. Issues that are approached are custom thread creation , event handling, synchronization between machines using rpc and URL retrieval.
./cloudbaseinit/osutils
System-specific functions can be found in this directory. It aids service enabligs/ disablings, user login, network communication and driver type for proper installations.
./cloudbaseinit/utils/windows
Here are the tools for accessing OS details, such as physical or virtual disk properties, APIs for crypting and IP rendition [should use other word], network configuration and remote access to resources. The operating system interfaces viewed are POSIX and Windows.
./cloudbaseinit/plugins [Here I think I'll explain the plugins individually.... except userdataplugins and userdata]
This directory holds the plugins for custom configurations; for the time being, there is only an implementation for Windows hosts. The plugins which come to our aid are the following: User Creation Plugin (createuser.py) - creates a user in case he does not exist and attaches a temporary password to the user Volume Extension Plugin (extendvolumes.py) - gets the list of volumes which need extending and interogates the disk for available contiguous space. By default all available volumes can be extended. Volumes are specified through a comma separated list of volume indexes, e.g.: "1,2" File Execution Plugin (fileexecutils.py) - executes the given script according to its type Licensing Plugin (licensing.py) - plugin which activates Windows automatically Local Script Execution Plugin (localscripts.py) - scripts are placed in a separate folder and get executed once the plugin is invoked Maximum Transmission Unit Plugin (mtu.py) - helps configure the network interfaces MTU base on the values provided from the DHCP server Network Configuration Plugin (networkconfig.py) - configures the network adapter specified in the metadata, rebooting the system if required; in case the network adapter has not been specified, the first available ethernet adapter will be chosen Network Time Protocol Client Plugin (ntpclient.py) - helps configure the NTP client time synchronization using the NTP servers provided via DHCP Host Name Setting Plugin (sethostname.py) - takes the hostname from the metadata and truncates it if the string is larger than 15 characters for Netbios compatibility Password Setting Plugin (setpassword.py) - sets the password provided in the configuration. If False or no password is provided a random one will be chosen. SSH Public Key Setting Plugin (sshpublickeys.py) - sets a user's public key if specified in the metadata User Data Plugin (userdata.py) [I've explained some userdata functionality above- what else is there to add?] User Data Script Execution (userdatautils.py) - executes the userdata scripts according to their types WinRM Certificate Authentification Plugin (winrmcertificateauth.py - plugin which sets the WinRM certificate mapping for the specified user winrmlistener.py - enables basic authentication for the WinRM HTTPS listener
./cloudbaseinit/tests [self-explanatory -> should they even be specified?]
[What is in the Cloud-Init Documentation:
Datasources (Metadata) ?Merging (something with MIME)]
Datasources:
The use of the two datasource types: metadata and userdata is virtual machine configuration. The metadata is used to set the host name, password and configure the network adapters whereas the userdata consists of user defined scripts which are specified for execution at the cloudbase-init installation.These scripts may contain regular shell commands, package installation and other custom executions, unrelated to the raw operating system specifications met with[another verb] in the metadata. There are several ways in which you can access these datasources. In the metadata_factory.py file the services are verified consecutively and the first available service will be used to retrieve the metadata and the userdata as well. The services which cloudbase-init can support are, in the order in which they are accessed:
Config Drive Service:
[here I have used some sentences from the config-drive documetation on openstack and the cloud-init] As its name suggests, the Config Drive enables the configuration of a newly created instance at boot time. Its purpose is to retrieve metadata without a network connection being required, but by simply mounting the disk onto the operating system and reading the available information. The operating system [Windows distribution] must support mounting of an ISO9660 or VFAT file system. [as a side note, all Windows distributions, starting from Windows 95, support VFAT] The default format is ISO9660, but it can be changed specifying this in the configuration options: config_drive_format=vfat [maybe too obvious]Should cloudbase-init not be installed after the VM has been created, there is an alternative for its automatic configuration through Config Drive by setting the --config-drive=true parameter when executing nova boot; additional arguments may be files from where to retrieve [copy-paste] user-data, metadata or key/value metadata pairs. The config drive will contain several files with the userdata and metadata in JSON format. There may be more versions of these datasources therefore it is advised that the latest supported version by date be accessed first and afterwards, should it fail, try out an earlier version. [? should I provide a list with what a config drive contains? e.g.: ec2/2009-04-04/meta-data.json ec2/2009-04-04/user-data ec2/latest/meta-data.json ec2/latest/user-data openstack/2012-08-10/meta_data.json openstack/2012-08-10/user_data openstack/content openstack/content/0000 openstack/content/0001 openstack/latest/meta_data.json openstack/latest/user_data
]
HTTP Service:
This service provides a set of config files which can be accessed by the newly created instance by typing in the special IP: 169.254.169.254. At this address one can find information regarding the versions provided for the instance: [show content] Also, one can retrieve the metadata by accessing the following address from inside the instance's browser: http://169.254.169.254/<version-date>/meta-data/ [show content] In case there is userdata provided, it can be accessed at this URL e.g.: http://169.254.169.254/<version-date>/user-data [show content]
EC2 Service:[when accessing the magic ip there might be necessary to type
in the password] The way in which the metadata is accessed through EC2 does not differ much from HTTP. The datasources are retrieved by accessing the same IP, 169.254.169.254 and using the same addresses for accessing the metadata, userdata and latest versions. There might be slight differences in the information the metadata provides. [TODO MaaS]
Cloudbase-init installation process
Once the desired installer version has been downloaded the Cloudbase-Init Setup can commence. [add picture here] Inside the configuration options one can specify the Username, the default being Admin, a comma separated list with local groups of the user the default is Administrators, if the user should use a metadata password for the instance, which is the default behavior, or if the password will be provided through the user-data or from the dashboard. Another setting is the configuration of the network adapter. All these options may be set during the setup or later, by editing a newly created configuration file: cloudbase-init.conf. One way of accessing the user password is by executing nova get-password <instance-name or instance-id> /root/.ssh/id_rsa which returns the randomly generated password. What this does is link the content of the public key id_rsa.pub in the controller node with the content of <username>/.ssh/authorized_keys from the instance. The file contents retrieval is done bidirectionally, meaning that both the server and the client will compare the keys received from the other machine and, in case of a match, the server will display the password. [These actions are required because of security issues, in case a third machine might try to gain access to the VM there will be some interference in the public key message transmission and the client will be announced that the traffic is listened, this suggesting malware behavior; source: http://askubuntu.com/questions/30788/does-ssh-key-need-to-be-named-id-rsa]
At the end of the setup a new service will appear called "Cloud Initialization Service" which will start running at the next boot. This time, the service will run the commands provided in cloudbase-init.conf file found at the C:\Program Files (x86)\Cloudbase Solutions\Cloudbase-Init\conf path. Hence, one may choose to change the user name or password. Also, in the cloudbase-init-unattended.conf file are the available metadata services and the order in which they are executed, looking first for a ConfigDrive then for the metadata distributing URL, 169.254.169.254, where the HTTP or EC2 information may be found. After retrieving the metadata, the service executes the list of plugins above mentioned, also existing the possibility of disabling the running of some by specifying so in the config file. [But how? : plugins= cloudbaseinit.plugins.windows.sethostname.SetHostNamePlugin?]
[the installer provides a ready-made Unattend.xml file used for the sysprep]
To let the virtual machine know that it must not execute the plugins at reboot, the service saves a value [gen_state=7 -> Sysprep Completed] in the Windows Registry Editor after Sysprep Completion at this registry key:
HKEY_LOCAL_MACHINE\Software\Cloudbase Solutions\Cloudbase-Init
for an x32 version or at
HKEY_LOCAL_MACHINE\Software\Wow6432Node\Cloudbase Solutions\Cloudbase-Init
for the x64 version
Hence, to execute the configuration scripts once more this key should be deleted and the service restarted or machine rebooted.
One can also install the .msi file in unattended mode by executing the following command: msiexec /i CloudbaseInitSetup.msi /qn /l*v log.txt adding a log file to show that the installation went well. There is also the possibility to specify the network adapter to be configured:
msiexec /i CloudbaseInitSetup.msi /qn /l*v log.txt NETWORKADAPTERNAME="Intel(R) PRO/1000 MT Network Connection"
