← Back to branch summary

~ubuntu-branches/ubuntu/saucy/nova/saucy-proposed

« back to all changes in this revision

Viewing changes to doc/source/api_ext/ext_config_drive.rst

  • Committer: Package Import Robot
  • Author(s): Chuck Short
  • Date: 2012-05-24 13:12:53 UTC
  • mfrom: (1.1.55)
  • Revision ID: package-import@ubuntu.com-20120524131253-ommql08fg1en06ut
Tags: 2012.2~f1-0ubuntu1
https://launchpad.net/bugs/907197
* New upstream release.
* Prepare for quantal:
  - Dropped debian/patches/upstream/0006-Use-project_id-in-ec2.cloud._format_image.patch
  - Dropped debian/patches/upstream/0005-Populate-image-properties-with-project_id-again.patch
  - Dropped debian/patches/upstream/0004-Fixed-bug-962840-added-a-test-case.patch
  - Dropped debian/patches/upstream/0003-Allow-unprivileged-RADOS-users-to-access-rbd-volumes.patch
  - Dropped debian/patches/upstream/0002-Stop-libvirt-test-from-deleting-instances-dir.patch
  - Dropped debian/patches/upstream/0001-fix-bug-where-nova-ignores-glance-host-in-imageref.patch 
  - Dropped debian/patches/0001-fix-useexisting-deprecation-warnings.patch
* debian/control: Add python-keystone as a dependency. (LP: #907197)
* debian/patches/kombu_tests_timeout.patch: Refreshed.
* debian/nova.conf, debian/nova-common.postinst: Convert to new ini
  file configuration
* debian/patches/nova-manage_flagfile_location.patch: Refreshed

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/source/api_ext/ext_config_drive.rst
1
 
The Config Drive Extension
2
 
=================================================================
3
 
About this Extension
4
 
--------------------
5
 
The config-drive extension enables attaching a separate drive to the Compute guest on instance create. It is used with the OpenStack Compute 1.1 API to write configuration data into guest for those guests whose root filesystems cannot be mounted by the Compute host.
6
 
 
7
 
To use this extension, you must have installed Compute, with libvirt or Xen using local disk.
8
 
 
9
 
To obtain current information the extensions available to you, issue an EXTENSION query on the OpenStack system where it is installed, such as http://mycloud.com/v1.1/tenant/extensions.
10
 
 
11
 
Extension Overview
12
 
~~~~~~~~~~~~~~~~~~
13
 
 
14
 
Name
15
 
    Config Drive
16
 
        
17
 
Namespace
18
 
        http://docs.openstack.org/ext/config-drive/api/v1.1
19
 
 
20
 
Alias
21
 
        ORG-EXT
22
 
        
23
 
Contact
24
 
    Christopher MacGown <chris@pistoncloud.com>
25
 
        
26
 
Status
27
 
        Alpha
28
 
        
29
 
Extension Version
30
 
        v1.0 (2011-09-16)
31
 
 
32
 
Dependencies
33
 
    Compute API 1.1
34
 
        
35
 
Doc Link (PDF)
36
 
        http://
37
 
        
38
 
Doc Link (WADL)
39
 
        http://
40
 
        
41
 
Short Description
42
 
        This extension enables the assignment of config-drives to a
43
 
        compute guest on instance create running in an OpenStack cloud.
44
 
 
45
 
Sample Query Responses
46
 
~~~~~~~~~~~~~~~~~~~~~~
47
 
 
48
 
As shown below, responses to an EXTENSION query in XML or JSON provide basic information about the extension. 
49
 
 
50
 
Extension Query Response: XML::
51
 
 
52
 
  TBD
53
 
 
54
 
.. todo:: Provide example of extension query XML response.
55
 
 
56
 
Extension Query Response: JSON::
57
 
 
58
 
  TBD
59
 
 
60
 
.. todo:: Provide example of extension query JSON response.
61
 
 
62
 
Document Change History
63
 
~~~~~~~~~~~~~~~~~~~~~~~
64
 
 
65
 
============= =====================================
66
 
Revision Date Summary of Changes
67
 
2011-09-16    Initial draft
68
 
2012-03-30    Reformat of content
69
 
============= =====================================
70
 
 
71
 
 
72
 
Summary of Changes
73
 
------------------
74
 
This extension to the OpenStack Compute API allows the addition of a configuration drive to an instance.
75
 
 
76
 
This support is provided by the addition of new resources.
77
 
 
78
 
New Actions
79
 
~~~~~~~~~~~
80
 
None
81
 
 
82
 
New Faults
83
 
~~~~~~~~~~
84
 
None
85
 
 
86
 
New Headers
87
 
~~~~~~~~~~~
88
 
None
89
 
 
90
 
New Resources
91
 
~~~~~~~~~~~~~
92
 
This extension to the OpenStack Compute API adds the following resources:
93
 
 
94
 
A config_drive attribute to the servers API that is None by default, but can optionally be True or the imageRef of a config-drive image.
95
 
 
96
 
Upon instance create, a guest built with a True config_drive attribute will create a local volume and partition it as a fat32 drive, all passed in metadata, networks, and keys will be written to the config_drive which is associated as the last available disk on the instance.
97
 
Upon instance create, a guest built with an imageRef config_drive attribute will create a local volume from the image.
98
 
 
99
 
New States
100
 
~~~~~~~~~~
101
 
None
102
 
 
103
 
Changes to the Cloud Servers Specification
104
 
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
105
 
 
106
 
In section 4.1.2 (Create Servers) of the API Specification: Examples 4.3 and 4.4 should optionally add the config-drive attribute as in the below examples:
107
 
 
108
 
 
109
 
Example XML with config_drive attribute = True:
110
 
 
111
 
::
112
 
 
113
 
    <?xml version="1.0" encoding="UTF-8"?>
114
 
    <server xmlns="http://docs.openstack.org/compute/api/v1.1"
115
 
            imageRef="http://servers.api.openstack.org/1234/images/52415800-8b69-11e0-9b19-734f6f006e54"
116
 
            flavorRef="52415800-8b69-11e0-9b19-734f1195ff37"
117
 
            name="new-server-test"
118
 
            config=drive="True"
119
 
            >
120
 
      <metadata>
121
 
        <meta key="My Server Name">Apache1</meta>
122
 
      </metadata>
123
 
      <personality>
124
 
        <file path="/etc/banner.txt">
125
 
            ICAgICAgDQoiQSBjbG91ZCBkb2VzIG5vdCBrbm93IHdoeSBp
126
 
            dCBtb3ZlcyBpbiBqdXN0IHN1Y2ggYSBkaXJlY3Rpb24gYW5k
127
 
            IGF0IHN1Y2ggYSBzcGVlZC4uLkl0IGZlZWxzIGFuIGltcHVs
128
 
            c2lvbi4uLnRoaXMgaXMgdGhlIHBsYWNlIHRvIGdvIG5vdy4g
129
 
            QnV0IHRoZSBza3kga25vd3MgdGhlIHJlYXNvbnMgYW5kIHRo
130
 
            ZSBwYXR0ZXJucyBiZWhpbmQgYWxsIGNsb3VkcywgYW5kIHlv
131
 
            dSB3aWxsIGtub3csIHRvbywgd2hlbiB5b3UgbGlmdCB5b3Vy
132
 
            c2VsZiBoaWdoIGVub3VnaCB0byBzZWUgYmV5b25kIGhvcml6
133
 
            b25zLiINCg0KLVJpY2hhcmQgQmFjaA==
134
 
        </file>
135
 
      </personality>
136
 
    </server>
137
 
 
138
 
Example XML with config_drive attribute is an imageRef:
139
 
 
140
 
::
141
 
 
142
 
    <?xml version="1.0" encoding="UTF-8"?>
143
 
    <server xmlns="http://docs.openstack.org/compute/api/v1.1"
144
 
            imageRef="http://servers.api.openstack.org/1234/images/
145
 
    52415800-8b69-11e0-9b19-734f6f006e54"
146
 
            flavorRef="52415800-8b69-11e0-9b19-734f1195ff37"
147
 
            name="new-server-test"
148
 
            config_drive="http://servers.api.openstack.org/1234/images/52415800-8b69-1341-9b19-734f6f006e54"
149
 
            >
150
 
      <metadata>
151
 
        <meta key="My Server Name">Apache1</meta>
152
 
      </metadata>
153
 
      <personality>
154
 
        <file path="/etc/banner.txt">
155
 
            ICAgICAgDQoiQSBjbG91ZCBkb2VzIG5vdCBrbm93IHdoeSBp
156
 
            dCBtb3ZlcyBpbiBqdXN0IHN1Y2ggYSBkaXJlY3Rpb24gYW5k
157
 
            IGF0IHN1Y2ggYSBzcGVlZC4uLkl0IGZlZWxzIGFuIGltcHVs
158
 
            c2lvbi4uLnRoaXMgaXMgdGhlIHBsYWNlIHRvIGdvIG5vdy4g
159
 
            QnV0IHRoZSBza3kga25vd3MgdGhlIHJlYXNvbnMgYW5kIHRo
160
 
            ZSBwYXR0ZXJucyBiZWhpbmQgYWxsIGNsb3VkcywgYW5kIHlv
161
 
            dSB3aWxsIGtub3csIHRvbywgd2hlbiB5b3UgbGlmdCB5b3Vy
162
 
            c2VsZiBoaWdoIGVub3VnaCB0byBzZWUgYmV5b25kIGhvcml6
163
 
            b25zLiINCg0KLVJpY2hhcmQgQmFjaA==
164
 
        </file>
165
 
      </personality>
166
 
    </server>
167
 
 
168
 
 
169
 
Example JSON with config_drive attribute is true:
170
 
 
171
 
::
172
 
 
173
 
    {
174
 
        "server" : {
175
 
            "name" : "new-server-test",
176
 
            "imageRef" : "http://servers.api.openstack.org/1234/images/52415800-8b69-11e0-9b19-734f6f006e54",
177
 
            "flavorRef" : "52415800-8b69-11e0-9b19-734f1195ff37",
178
 
            "config_drive" : "true",
179
 
            "metadata" : {
180
 
                "My Server Name" : "Apache1"
181
 
            },
182
 
            "personality" : [
183
 
                {
184
 
                    "path" : "/etc/banner.txt",
185
 
                    "contents" : "ICAgICAgDQoiQSBjbG91ZCBkb2VzIG5vdCBrbm93IHdoeSBp
186
 
     dCBtb3ZlcyBpbiBqdXN0IHN1Y2ggYSBkaXJlY3Rpb24gYW5k
187
 
     IGF0IHN1Y2ggYSBzcGVlZC4uLkl0IGZlZWxzIGFuIGltcHVs
188
 
     c2lvbi4uLnRoaXMgaXMgdGhlIHBsYWNlIHRvIGdvIG5vdy4g
189
 
     QnV0IHRoZSBza3kga25vd3MgdGhlIHJlYXNvbnMgYW5kIHRo
190
 
     ZSBwYXR0ZXJucyBiZWhpbmQgYWxsIGNsb3VkcywgYW5kIHlv
191
 
     dSB3aWxsIGtub3csIHRvbywgd2hlbiB5b3UgbGlmdCB5b3Vy
192
 
     c2VsZiBoaWdoIGVub3VnaCB0byBzZWUgYmV5b25kIGhvcml6
193
 
     b25zLiINCg0KLVJpY2hhcmQgQmFjaA=="
194
 
                }
195
 
            ]
196
 
        }
197
 
    }
198
 
 
199
 
Example JSON with config_drive attribute is an imageRef:
200
 
 
201
 
::
202
 
 
203
 
    {
204
 
        "server" : {
205
 
            "name" : "new-server-test",
206
 
            "imageRef" : "http://servers.api.openstack.org/1234/images/52415800-8b69-11e0-9b19-734f6f006e54",
207
 
            "flavorRef" : "52415800-8b69-11e0-9b19-734f1195ff37",
208
 
            "config_drive" : "http://servers.api.openstack.org/1234/images/52415800-8b69-11e0-9b19-734f6f006e54",
209
 
            "metadata" : {
210
 
                "My Server Name" : "Apache1"
211
 
            },
212
 
            "personality" : [
213
 
                {
214
 
                    "path" : "/etc/banner.txt",
215
 
                    "contents" : "ICAgICAgDQoiQSBjbG91ZCBkb2VzIG5vdCBrbm93IHdoeSBp
216
 
     dCBtb3ZlcyBpbiBqdXN0IHN1Y2ggYSBkaXJlY3Rpb24gYW5k
217
 
     IGF0IHN1Y2ggYSBzcGVlZC4uLkl0IGZlZWxzIGFuIGltcHVs
218
 
     c2lvbi4uLnRoaXMgaXMgdGhlIHBsYWNlIHRvIGdvIG5vdy4g
219
 
     QnV0IHRoZSBza3kga25vd3MgdGhlIHJlYXNvbnMgYW5kIHRo
220
 
     ZSBwYXR0ZXJucyBiZWhpbmQgYWxsIGNsb3VkcywgYW5kIHlv
221
 
     dSB3aWxsIGtub3csIHRvbywgd2hlbiB5b3UgbGlmdCB5b3Vy
222
 
     c2VsZiBoaWdoIGVub3VnaCB0byBzZWUgYmV5b25kIGhvcml6
223
 
     b25zLiINCg0KLVJpY2hhcmQgQmFjaA=="
224
 
                }
225
 
            ]
226
 
        }
227
 
    }