On Wed, Dec 11, 2013 at 5:02 PM, Jose A. Lopes <[email protected]> wrote: > Add the document describing a new design for the OS installation process for > new instances. > > Signed-off-by: Michele Tartara <[email protected]> > Signed-off-by: Jose A. Lopes <[email protected]> > --- > doc/design-os.rst | 104 > +++++++++++++++++++++++++++--------------------------- > 1 file changed, 52 insertions(+), 52 deletions(-) > > diff --git a/doc/design-os.rst b/doc/design-os.rst > index a26801a..60bccd9 100644 > --- a/doc/design-os.rst > +++ b/doc/design-os.rst > @@ -4,9 +4,9 @@ Ganeti OS installation redesign > > .. contents:: :depth: 3 > > -This is a design document detailing a new OS installation procedure, more > -secure, able to provide more features and easier to use for many common tasks > -w.r.t. the current one. > +This is a design document detailing a new OS installation procedure, which is > +more secure, able to provide more features and easier to use for many common > +tasks w.r.t. the current one. > > Current state and shortcomings > ============================== > @@ -19,10 +19,10 @@ the disks of the instance being created, > exporting/importing the instance, > renaming it). > > These scripts receive, as environment variables, a fixed set of parameters > -describing the instance (such as the hypervisor, the name of the instance, > the > -number of disks, and their location) and a set of user defined parameters. > Each > -of these parameters is also written into the configuration file of Ganeti, to > -allow for future reinstalls of the instance, and in various log files, > namely: > +related to the instance (such as the hypervisor, the name of the instance, > the > +number of disks, and their location) and a set of user defined parameters. > +These parameters are also written in the configuration file of Ganeti, to > allow > +future reinstalls of the instance, and in various log files, namely: > > * node daemon log file: contains DEBUG strings of the ``/os_validate``, > ``/instance_os_add`` and ``/instance_start`` RPC calls. > @@ -33,15 +33,15 @@ allow for future reinstalls of the instance, and in > various log files, namely: > * commands log: the CLI commands that create a new instance, including their > parameters, are logged here. > > -* RAPI log: the RAPI commands that create a new instances, including their > +* RAPI log: the RAPI commands that create a new instance, including their > parameters, are logged here. > > -* job logs: the job files stored in the job queue or in its archive contain > the > - parameters. > +* job logs: the job files stored in the job queue, or in its archive, contain > + the parameters. > > The current situation presents a number of shortcomings: > > -* Having the installation scripts run with root power on the nodes doesn't > allow > +* Having the installation scripts run as root on the nodes doesn't allow > user-defined OS scripts, as they would pose a huge security issue. > Furthermore, even a script without malicious intentions might end up > distrupting a node because of a bug in it. > @@ -83,15 +83,15 @@ following changes: > via RAPI. > > * ``secret``: the parameter is not saved inside the Ganeti configuration. > - Reinstall are impossible unless the data is passed again. The parameter > will > + Reinstalls are impossible unless the data is passed again. The parameter > will > not appear in any log file. When a functionality is performed jointly by > multiple daemons (such as MasterD and LuxiD), currently Ganeti sometimes > serializes jobs on disk and later reloads them. Secret parameters will > not be > - serialized on disk. They will be passed around as part of the LUXI calls > + serialized to disk. They will be passed around as part of the LUXI calls > exchanged by the daemons, and only kept in memory, in order to reduce > their > - accessibility as much as possible. In case of a failure of the master > node, > + accessibility as much as possible. In case of failure of the master node, > these parameters will be lost and cannot be recovered because they are not > - serialized on file, therefore the job cannot taken over by the new master. > + serialized. As a result, the job cannot be taken over by the new master. > This is an expected and accepted side effect of jobs with secret > parameters: > if they fail, they'll have to be restarted manually. > > @@ -116,26 +116,25 @@ following changes: > parameters for configuring it (its network interfaces, IP address, > hostname, > etc.) from a set of metadata provided by Ganeti (e.g.: using an approach > comparable to the one of the ``cloud-init`` tool). When this installation > - mode is used, no OS installation script is required. In order for > + mode is used, no OS installation script is required. In order for the > installation of an OS from an image to be possible, the ``--os-type`` > parameter will be extended to support a new additional format: > ``--os-type > - image:<URL>`` will instruct ganeti to take an image from the specified > + image:<URL>`` will instruct Ganeti to take an image from the specified > position. For the initial implementation, URL can be either a filename > or a > - publically accessible http or ftp resource. Once the instance image is > - received, it will be dd-ed on the first disk of the instance. > - When an image is specified, ``--os-parameters`` can still be used, > - and its content will be passed to the instance as part of the metadata. > Nota > - that as part of the OS scripts there is a file specifying what parameters > - are expected. With OS images, though, none of the traditional structure > of > - OS scripts is in place, so there will be no check regarding what > parameters > - can be specified: they will all be passed, as long as the > - ``--os-parameters`` string is syntactically valid. > - The set of ``self_install`` parameters will be stored as part of the > - instance configuration, so that they can be used to reinstall the > instance. > - It will be the user's responsibility to ensure that the OS image or any > - installation media is still available in the proper position when a > - reinstall happens. After the first run, the instance will revert to > - ``default`` mode. > + publically accessible HTTP or FTP resource. Once the instance image is > + received, it will be dd-ed onto the first disk of the instance. When an > + image is specified, ``--os-parameters`` can still be used, and its > content > + will be passed to the instance as part of the metadata. Note that, as > part > + of the OS scripts, there is a file specifying what parameters are > + expected. With OS images, though, none of the traditional structure of OS > + scripts is in place, so there will be no check regarding what parameters > can > + be specified: they will all be passed, as long as the ``--os-parameters`` > + string is syntactically valid. The set of ``self_install`` parameters > will > + be stored as part of the instance configuration, so that they can be > used to > + reinstall the instance. It will be the user's responsibility to ensure > that > + the OS image or any installation media is still available in the proper > + position when a reinstall happens. After the first run, the instance will > + revert to ``default`` mode. > > * ``install``: Ganeti will start the instance using a virtual appliance > specifically made for installing Ganeti instances. Scripts analogous to > the > @@ -175,14 +174,14 @@ following changes: > extesion to identify the file format (in order to allow for more formats > to be > supported in the future). The URL will be stored as part of the > configuration > of the instance (therefore, the URL should not contain confidential > - information, but the file there available can). It is up to the system > + information, but the files there available can). It is up to the system > administrator to ensure that a package is actually available at that URL at > install and reinstall time. The content of the package is allowed to > change. > E.g.: a system administrator might create a package containing the private > keys of the instance being created. When the instance is reinstalled, a new > package with new keys can be made available there, therefore allowing > instance > reinstall without the need to store keys. Together with the URL, a > username > - and a password can be specified to. If the URL is a http(s) URL, they will > be > + and a password can be specified to. If the URL is a HTTP(S) URL, they will > be > used as basic access authentication credentials to access that URL. The > username and password will not be saved in the config, and will have to be > provided again in case a reinstall is requested. The downloaded > @@ -209,7 +208,7 @@ of increasing impact on the system and, in some cases, > dependent on each other: > > Some of these steps need to be more deeply specified w.r.t. what is already > written in the `Proposed changes`_ Section. Extra details will be provided in > -the following Subsections. > +the following subsections. > > Communication mechanism and metadata service > ++++++++++++++++++++++++++++++++++++++++++++ > @@ -232,10 +231,10 @@ to receive metadata. The value of this parameter will > be saved as part of the > configuration of the instance. > > When the communication mechanism is enabled, Ganeti will create a new network > -interface inside the instance. This extra network interface will be the last > one > -of the instance, after all the user defined ones. On the host side, this > -interface will be only accessible to the host itself, and not be routed > outside > -the machine. > +interface inside the instance. This additional network interface will be the > +last one in the instance, after all the user defined ones. On the host side, > +this interface will only be accessible to the host itself, and not routed > +outside the machine. > On this network interface, the instance will connect using the IP: > 169.254.169.1 and netmask 255.255.255.0. > The host will be on the same network, with the IP address: 169.254.169.254. > @@ -255,12 +254,13 @@ reachable on port 80. > In Xen, unfortunately, such a capability is not present, and an actual > network > interface has to be created on the host (using the ``vif`` parameter of the > Xen > configuration file). Each instance will have its corresponding ``vif`` > network > -interface on the host. These interface will not be connected to each other in > +interface on the host. These interfaces will not be connected to each other > in > any way, and Ganeti will not configure them to allow traffic to be forwarded > -beyond the host machine. The ``vif-route`` script of xen might be helpful in > +beyond the host machine. The ``vif-route`` script of Xen might be helpful in > implementing this. > -It will be the system administrator to ensure that extra firewalling and > routing > -rules specified on the host don't allow this accidentally. > +It will be the system administrator's responsibility to ensure that the extra > +firewalling and routing rules specified on the host don't allow this > +accidentally. > > The instance will be able to connect to 169.254.169.254:80, and issue GET > requests to an HTTP server that will provide the instance metadata. > @@ -299,7 +299,7 @@ and to send data to the host by a POST request at:: > http://169.254.169.254/ganeti/<version>/write > > As in a pipe, once the data are read, they will not be in the buffer > anymore, so > -subsequent get request to ``read`` will not return the same data twice. > +subsequent GET requests to ``read`` will not return the same data twice. > Unlike a pipe, though, it will not be possible to perform blocking I/O > operations. > > @@ -375,14 +375,14 @@ running on the host, leaving only the ones running in > the VM. > Ganeti will provide a script to be run at install time that can be used to > create the virtualized environment that will perform the OS installation of > new > instances. > -This script will build a debootstrapped basic debian system including > including > -a software that will read the metadata, setup the environment variables and > -launch the installation scripts inside the virtualized environment. The > script > -will also provide hooks for personalization. > - > -It will also be possible to use other self-made virtualized environment, as > long > -as they connect to ganeti over the described communication mechanism and they > -know how to read and use the provided metadata to create a new instance. > +This script will build a debootstrapped basic debian system including a > software > +that will read the metadata, setup the environment variables and launch the > +installation scripts inside the virtualized environment. The script will also > +provide hooks for personalization. > + > +It will also be possible to use other self-made virtualized environments, as > +long as they connect to Ganeti over the described communication mechanism and > +they know how to read and use the provided metadata to create a new instance. > > While performing an installation in the virtualized environment, a > personalizable timeout will be used to detect possible problems with the > -- > 1.8.5.1 >
Thanks for the suggested corrections, Jose. I'll apply them and resend the patch for review. Cheers, Michele -- Google Germany GmbH Dienerstr. 12 80331 München Registergericht und -nummer: Hamburg, HRB 86891 Sitz der Gesellschaft: Hamburg Geschäftsführer: Graham Law, Christine Elizabeth Flores
