Revision b6cc971c

b/doc/design-2.1.rst
84 84
External interface changes
85 85
--------------------------
86 86

  
87
OS API
88
~~~~~~
89

  
90
The OS API of Ganeti 2.0 has been built with extensibility in mind. Since we
91
pass everything as environment variables it's a lot easier to send new
92
information to the OSes without breaking retrocompatibility. This section of
93
the design outlines the proposed extensions to the API and their
94
implementation.
95

  
96
API Version Compatibility Handling
97
++++++++++++++++++++++++++++++++++
98

  
99
In 2.1 there will be a new OS API version (eg. 15), which should be mostly
100
compatible with api 10, except for some new added variables. Since it's easy
101
not to pass some variables we'll be able to handle Ganeti 2.0 OSes by just
102
filtering out the newly added piece of information. We will still encourage
103
OSes to declare support for the new API after checking that the new variables
104
don't provide any conflict for them, and we will drop api 10 support after
105
ganeti 2.1 has released.
106

  
107
New Environment variables
108
+++++++++++++++++++++++++
109

  
110
Some variables have never been added to the OS api but would definitely be
111
useful for the OSes. We plan to add an INSTANCE_HYPERVISOR variable to allow
112
the OS to make changes relevant to the virtualization the instance is going to
113
use. Since this field is immutable for each instance, the os can tight the
114
install without caring of making sure the instance can run under any
115
virtualization technology.
116

  
117
We also want the OS to know the particular hypervisor parameters, to be able to
118
customize the install even more.  Since the parameters can change, though, we
119
will pass them only as an "FYI": if an OS ties some instance functionality to
120
the value of a particular hypervisor parameter manual changes or a reinstall
121
may be needed to adapt the instance to the new environment. This is not a
122
regression as of today, because even if the OSes are left blind about this
123
information, sometimes they still need to make compromises and cannot satisfy
124
all possible parameter values.
125

  
126
OS Parameters
127
+++++++++++++
128

  
129
Currently we are assisting to some degree of "os proliferation" just to change
130
a simple installation behavior. This means that the same OS gets installed on
131
the cluster multiple times, with different names, to customize just one
132
installation behavior. Usually such OSes try to share as much as possible
133
through symlinks, but this still causes complications on the user side,
134
especially when multiple parameters must be cross-matched.
135

  
136
For example today if you want to install debian etch, lenny or squeeze you
137
probably need to install the debootstrap OS multiple times, changing its
138
configuration file, and calling it debootstrap-etch, debootstrap-lenny or
139
debootstrap-squeeze. Furthermore if you have for example a "server" and a
140
"development" environment which installs different packages/configuration files
141
and must be available for all installs you'll probably end  up with
142
deboostrap-etch-server, debootstrap-etch-dev, debootrap-lenny-server,
143
debootstrap-lenny-dev, etc. Crossing more than two parameters quickly becomes
144
not manageable.
145

  
146
In order to avoid this we plan to make OSes more customizable, by allowing
147
arbitrary flags to be passed to them. These will be special "OS parameters"
148
which will be handled by Ganeti mostly as hypervisor or be parameters. This
149
slightly complicates the interface, but allows one OS (for example
150
"debootstrap" to be customizable and not require copies to perform different
151
cations).
152

  
153
Each OS will be able to declare which parameters it supports by listing them
154
one per line in a special "parameters" file in the OS dir. The parameters can
155
have a per-os cluster default, or be specified at instance creation time.  They
156
will then be passed to the OS scripts as: INSTANCE_OS_PARAMETER_<NAME> with
157
their specified value. The only value checking that will be performed is that
158
the os parameter value is a string, with only "normal" characters in it.
159

  
160
It will be impossible to change parameters for an instance, except at reinstall
161
time. Upon reinstall with a different OS the parameters will be by default
162
discarded and reset to the default (or passed) values, unless a special
163
--keep-known-os-parameters flag is passed.
164

  

Also available in: Unified diff