This shows you the differences between two versions of the page.
cloudbaseinit-doc [2014/08/19 17:03] lcaplea |
cloudbaseinit-doc [2014/08/19 20:45] |
||
---|---|---|---|
Line 1: | Line 1: | ||
- | [] - these are my comments | ||
- | < | ||
- | # | ||
- | |||
- | ##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, | ||
- | |||
- | ##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: | ||
- | ``` | ||
- | * 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](https:// | ||
- | |||
- | ##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/ | ||
- | | ||
- | ###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." | ||
- | | ||
- | ###Part Handler File | ||
- | The part-handler is provided as a mime type " | ||
- | [apparently, | ||
- | | ||
- | ###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 " | ||
- | | ||
- | ##Directory layout | ||
- | The default installation path for the cloudbase-init files is < | ||
- | | ||
- | The code which is executed when running the cloudbase-init.exe is placed in the following hierarchy: | ||
- | | ||
- | #### | ||
- | Folder where the cloudbase-init subfolders are located. Also, init.py is the file containing the main method, configure_host(). | ||
- | | ||
- | #### | ||
- | In this folder are the available services for reading metadata from various providers: HTTP, ConfigDrive, | ||
- | [Guess specifying what they' | ||
- | Among the information provided are the host name, network configuration, | ||
- | |||
- | #### | ||
- | Here we can find the utils that deal with the specifics for remote data transmission, | ||
- | |||
- | #### | ||
- | System-specific functions can be found in this directory. It aids service enabligs/ disablings, user login, network communication and driver type for proper installations. | ||
- | |||
- | #### | ||
- | 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. | ||
- | |||
- | #### | ||
- | [Here I think I'll explain the plugins individually.... except userdataplugins and userdata] | ||
- | This directory holds the plugins for custom configurations; | ||
- | |||
- | ####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.: " | ||
- | |||
- | ####File Execution Plugin | ||
- | fileexecutils.py - executes the given script according to its type | ||
- | |||
- | #### | ||
- | 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 | ||
- | |||
- | #### | ||
- | 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 Authentication Plugin | ||
- | winrmcertificateauth.py - plugin which sets the WinRM certificate mapping for the specified user | ||
- | |||
- | ####WinRM Listener Plugin | ||
- | winrmlistener.py - enables basic authentication for the WinRM HTTPS listener | ||
- | |||
- | ## | ||
- | 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, | ||
- | [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/ | ||
- | ec2/ | ||
- | ec2/ | ||
- | ec2/ | ||
- | openstack/ | ||
- | openstack/ | ||
- | openstack/ | ||
- | openstack/ | ||
- | openstack/ | ||
- | openstack/ | ||
- | openstack/ | ||
- | ] | ||
- | | ||
- | ###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' | ||
- | [http:// | ||
- | In case there is userdata provided, it can be accessed at this URL e.g.: [http:// | ||
- | |||
- | |||
- | ###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. | ||
- | | ||
- | ## | ||
- | | ||
- | 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 | ||
- | At the end of the setup a new service will appear called "Cloud Initialization Service" | ||
- | 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: | ||
- | | ||
- | for an x32 version or at | ||
- | | ||
- | 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=" | ||
- | ``` | ||
- | |||
- | </ |