User Tools

Site Tools


cloudbaseinit-doc

[] - 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:

  • 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 acquire 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]

./cloudbaseinit

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

This directory holds the plugins for custom configurations; for the time being, there is only an implementation for Windows hosts. The config file which provides information about the operating system is provided by the oslo.config module. The plugins which come to our aid are the following:

User Creation Plugin

Creates a user in case he does not exist and attaches a temporary password to the user. For the newly made user a log on session is created for other plugins to be able to access the username and password after this plugin has been executed, and before reboot which would set the changes in the instance as well. The user is by default added to the Administrators group; other membership options may be specified in the userdata, which is executed by another plugin.

Volume Extension Plugin

Gets the list of volumes which need extending and interrogates 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". The existing SW providers are interrogated for disk size availability in each of their packs in order to assess which volume can be relocated on the individual disks. For safety reasons, the volume's content is copied then transferred to the disk then the former location of the volume is emptied.

File Execution Plugin

Executes the given script according to its type. The script types are windows batch, linux bash files, python and powershell scripts and executable files. In case the file has a different extension, it will not be executed and a warning will be placed in the log. The powershell scripts are executed directly, by simply specifying the file type whereas the other scripts have a custom execution.

Licensing Plugin

Plugin that activates Windows automatically by executing the slmgr.vbs script which looks for licensing specifications by looking through the ProductKeyID, ProcessorURL,MachineURL etc.

Local Script Execution Plugin

These scripts are taken from the config file, placed in a separate folder and executed once the plugin is invoked.

Maximum Transmission Unit Plugin

Helps configure the network interfaces MTU base on the values provided from the DHCP server.

Network Configuration Plugin

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

Helps configure the NTP client time synchronization using the NTP servers provided via DHCP

Host Name Setting Plugin

Takes the hostname from the metadata and truncates it if the string is larger than 15 characters for Netbios compatibility

Password Setting Plugin

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

Sets a user's public key if specified in the metadata

User Data Plugin

Here the userdata is retrieved from the specific metadata service and decompressed in case it has been gzipped. If the userdata starts with the 'Content-Type: multipart' line then each userdata plugin will be loaded and executed, either through a part-handler file or another part processing mechanism. On the opposite side, the userdata will be executed as a singular script, with the plugin executing one of the three following scenarios, based on the return value of the script executing module: if the return value is 1001 then an automatic reboot will be done at the end, without the plugin being executed once more, if ret_val is 1002, the plugin is executed on next boot, whenever that will occur and if the return value is 1003 then the plugin will be executed on the next reboot which will be done right after the plugin execution has ceased.

User Data Script Execution

Executes the userdata scripts according to their types

WinRM Certificate Authentication Plugin

Plugin which sets the WinRM certificate mapping for the specified user

WinRM Listener Plugin

Enables basic authentication for the WinRM HTTPS listener

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 documentation 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/&lt;version-date&gt;/meta-data/ In case there is userdata provided, it can be accessed at this URL e.g.: http://169.254.169.254/&lt;version-date&gt;/user-data

EC2 Service:

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.

MaaS Service:

The API for the MaaS service resembles that of EC2 and HTTP by having in the main folder the versions list which can be further accessed to display the metadata fields. The difference between the methods is the accessed IP address; while EC2 and HTTP use a static IP for providing the metadata, MaaS sets its location during the installation of the operating system on the instance through preseeds.

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 in the controller node which returns the randomly generated password. What this does is link the content of the public key id_rsa.pub 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"
cloudbaseinit-doc.txt · Last modified: 2014/08/19 20:45 (external edit)