openstack/nova
Code Issues Proposed changes

Removes RST documentation and moves it to openstack-manuals

Browse Source 
Avoiding redundant information and confusion.

Change-Id: Iab1913ff359699db977b74554bad6088fab6ab2f
This commit is contained in:
annegentle 2012-04-30 12:45:10 -05:00
parent ca50cf405a
commit fd6b21b948
38 changed files with 6 additions and 4005 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

123
doc/source/api_ext/ext_aggregates.rst
View File

@ -1,123 +0,0 @@
The Host Aggregates Extension
=================================================================
About this Extension
--------------------
This extension introduces the concept of aggregates into Nova. Host aggregates are different from zones and availability zones: while the former allows the partition of Nova deployments into logical groups for load balancing and instance distribution, the latter are for providing some form of physical isolation and redundancy from other availability zones (e.g. by using separate power supply and network gears). Availability zones do not necessarily mean geographic distribution whereas zones usually do. Host aggregates can be regarded as a mechanism to further partitioning an availability zone, i.e. into multiple groups of hosts that share common resources like storage and network. This enables a finer level of granularity in which to structure an entire OpenStack deployment. Aggregates allows higher availability of a single guest instance within an availability zone, it enables advanced VM placement strategies, and more importantly it enables hosts' zero-downtime upgrades (for example, via VM live migration across members of the aggregate, thus causing no disruption to guest instances).
You can use this extension when you have multiple Compute nodes installed (only XenServer/XCP via xenapi driver is currently supported), and you want to leverage the capabilities of the underlying hypervisor resource pools. For example, you want to enable VM live migration (i.e. VM migration within the pool) or enable host maintenance with zero-downtime for guest instances. Please, note that VM migration across pools (i.e. storage migration) is not yet supported in XenServer/XCP, but will be added when available. Bear in mind that the two migration techniques are not mutually exclusive and can be used in combination for a higher level of flexibility in your cloud management.
To find more about it, please read http://wiki.openstack.org/host-aggregates or quick-search for 'aggregates' on the Nova developer guide.
Pre-requisites depend on the kind of hypervisor support you are going to use. As for XenServer/XCP, the same requirements for resource pools apply.
To obtain current information the extensions available to you, issue an EXTENSION query on the OpenStack system where it is installed, such as http://example.com/v1.1/tenant/extensions.
Extension Overview
~~~~~~~~~~~~~~~~~~
Name
Host Aggregates
Namespace
http://docs.openstack.org/compute/ext/aggregates/api/v1.1
Alias
OS-AGGREGATES
Contact
Armando Migliaccio <armando.migliaccio@citrix.com>
Status
Released
Extension Version
v1.0 (2012-02-28)
Dependencies
Compute API 1.1
Doc Link (PDF)
http://
Doc Link (WADL)
http://
Short Description
This extension enables the use of hypervisor resource pools in Nova.
Sample Query Responses
~~~~~~~~~~~~~~~~~~~~~~
As shown below, responses to an EXTENSION query in XML or JSON provide basic information about the extension.
Extension Query Response: XML::
<extension name="Aggregates" namespace="http://docs.openstack.org/compute/ext/aggregates/api/v1.1" alias="os-aggregates" updated="2012-01-12T00:00:00+00:00"><description>Admin-only aggregate administration</description></extension>
Extension Query Response: JSON::
{"extension": {"updated": "2012-01-12T00:00:00+00:00", "name": "Aggregates", "links": [], "namespace": "http://docs.openstack.org/compute/ext/aggregates/api/v1.1", "alias": "os-aggregates", "description": "Admin-only aggregate administration"}}
Document Change History
~~~~~~~~~~~~~~~~~~~~~~~
============= =====================================
Revision Date Summary of Changes
2012-02-28 Initial draft
2012-03-30 Reformat of content
============= =====================================
Summary of Changes
------------------
This extension to the OpenStack Compute API allows the creation and management of host aggregates (i.e. pools of compute nodes).
This support is provided by the addition of new actions.
New Actions
~~~~~~~~~~~
When a new aggregate has been created, actions can be executed using:
POST /v1.1/<tenant-id>/os-aggregates/<aggregate-id>/action
Valid actions are:
set_metadata
add_host
remove_host
Normal response Code: 200
For example, to set metadata for an aggregate the following xml must be submitted:
{"set_metadata": {"metadata": {"foo_key": "foo_value"}}}
For example, to add a host to an aggregate, the following xml must be submitted:
{"add_host": {"host": "<host-id>"}}
For example, to remove a host from an aggregate, the following xml must be submitted:
{"remove_host": {"host": "<host-id>"}}
Error Response Code(s) conflict (409), badRequest (400), itemNotFound (404)
New Faults
~~~~~~~~~~
None
New Headers
~~~~~~~~~~~
None
New Resources
~~~~~~~~~~~~~
None
New States
~~~~~~~~~~
None
Changes to the Cloud Servers Specification
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
None

227
doc/source/api_ext/ext_config_drive.rst
View File

@ -1,227 +0,0 @@
The Config Drive Extension
=================================================================
About this Extension
--------------------
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.
To use this extension, you must have installed Compute, with libvirt or Xen using local disk.
To obtain current information the extensions available to you, issue an EXTENSION query on the OpenStack system where it is installed, such as http://example.com/v1.1/tenant/extensions.
Extension Overview
~~~~~~~~~~~~~~~~~~
Name
Config Drive
Namespace
http://docs.openstack.org/ext/config-drive/api/v1.1
Alias
ORG-EXT
Contact
Christopher MacGown <chris@pistoncloud.com>
Status
Alpha
Extension Version
v1.0 (2011-09-16)
Dependencies
Compute API 1.1
Doc Link (PDF)
http://
Doc Link (WADL)
http://
Short Description
This extension enables the assignment of config-drives to a
compute guest on instance create running in an OpenStack cloud.
Sample Query Responses
~~~~~~~~~~~~~~~~~~~~~~
As shown below, responses to an EXTENSION query in XML or JSON provide basic information about the extension.
Extension Query Response: XML::
TBD
.. todo:: Provide example of extension query XML response.
Extension Query Response: JSON::
TBD
.. todo:: Provide example of extension query JSON response.
Document Change History
~~~~~~~~~~~~~~~~~~~~~~~
============= =====================================
Revision Date Summary of Changes
2011-09-16 Initial draft
2012-03-30 Reformat of content
============= =====================================
Summary of Changes
------------------
This extension to the OpenStack Compute API allows the addition of a configuration drive to an instance.
This support is provided by the addition of new resources.
New Actions
~~~~~~~~~~~
None
New Faults
~~~~~~~~~~
None
New Headers
~~~~~~~~~~~
None
New Resources
~~~~~~~~~~~~~
This extension to the OpenStack Compute API adds the following resources:
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.
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.
Upon instance create, a guest built with an imageRef config_drive attribute will create a local volume from the image.
New States
~~~~~~~~~~
None
Changes to the Cloud Servers Specification
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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:
Example XML with config_drive attribute = True:
::
<?xml version="1.0" encoding="UTF-8"?>
<server xmlns="http://docs.openstack.org/compute/api/v1.1"
imageRef="http://servers.api.openstack.org/1234/images/52415800-8b69-11e0-9b19-734f6f006e54"
flavorRef="52415800-8b69-11e0-9b19-734f1195ff37"
name="new-server-test"
config=drive="True"
>
<metadata>
<meta key="My Server Name">Apache1</meta>
</metadata>
<personality>
<file path="/etc/banner.txt">
ICAgICAgDQoiQSBjbG91ZCBkb2VzIG5vdCBrbm93IHdoeSBp
dCBtb3ZlcyBpbiBqdXN0IHN1Y2ggYSBkaXJlY3Rpb24gYW5k
IGF0IHN1Y2ggYSBzcGVlZC4uLkl0IGZlZWxzIGFuIGltcHVs
c2lvbi4uLnRoaXMgaXMgdGhlIHBsYWNlIHRvIGdvIG5vdy4g
QnV0IHRoZSBza3kga25vd3MgdGhlIHJlYXNvbnMgYW5kIHRo
ZSBwYXR0ZXJucyBiZWhpbmQgYWxsIGNsb3VkcywgYW5kIHlv
dSB3aWxsIGtub3csIHRvbywgd2hlbiB5b3UgbGlmdCB5b3Vy
c2VsZiBoaWdoIGVub3VnaCB0byBzZWUgYmV5b25kIGhvcml6
b25zLiINCg0KLVJpY2hhcmQgQmFjaA==
</file>
</personality>
</server>
Example XML with config_drive attribute is an imageRef:
::
<?xml version="1.0" encoding="UTF-8"?>
<server xmlns="http://docs.openstack.org/compute/api/v1.1"
imageRef="http://servers.api.openstack.org/1234/images/
52415800-8b69-11e0-9b19-734f6f006e54"
flavorRef="52415800-8b69-11e0-9b19-734f1195ff37"
name="new-server-test"
config_drive="http://servers.api.openstack.org/1234/images/52415800-8b69-1341-9b19-734f6f006e54"
>
<metadata>
<meta key="My Server Name">Apache1</meta>
</metadata>
<personality>
<file path="/etc/banner.txt">
ICAgICAgDQoiQSBjbG91ZCBkb2VzIG5vdCBrbm93IHdoeSBp
dCBtb3ZlcyBpbiBqdXN0IHN1Y2ggYSBkaXJlY3Rpb24gYW5k
IGF0IHN1Y2ggYSBzcGVlZC4uLkl0IGZlZWxzIGFuIGltcHVs
c2lvbi4uLnRoaXMgaXMgdGhlIHBsYWNlIHRvIGdvIG5vdy4g
QnV0IHRoZSBza3kga25vd3MgdGhlIHJlYXNvbnMgYW5kIHRo
ZSBwYXR0ZXJucyBiZWhpbmQgYWxsIGNsb3VkcywgYW5kIHlv
dSB3aWxsIGtub3csIHRvbywgd2hlbiB5b3UgbGlmdCB5b3Vy
c2VsZiBoaWdoIGVub3VnaCB0byBzZWUgYmV5b25kIGhvcml6
b25zLiINCg0KLVJpY2hhcmQgQmFjaA==
</file>
</personality>
</server>
Example JSON with config_drive attribute is true:
::
{
"server" : {
"name" : "new-server-test",
"imageRef" : "http://servers.api.openstack.org/1234/images/52415800-8b69-11e0-9b19-734f6f006e54",
"flavorRef" : "52415800-8b69-11e0-9b19-734f1195ff37",
"config_drive" : "true",
"metadata" : {
"My Server Name" : "Apache1"
},
"personality" : [
{
"path" : "/etc/banner.txt",
"contents" : "ICAgICAgDQoiQSBjbG91ZCBkb2VzIG5vdCBrbm93IHdoeSBp
dCBtb3ZlcyBpbiBqdXN0IHN1Y2ggYSBkaXJlY3Rpb24gYW5k
IGF0IHN1Y2ggYSBzcGVlZC4uLkl0IGZlZWxzIGFuIGltcHVs
c2lvbi4uLnRoaXMgaXMgdGhlIHBsYWNlIHRvIGdvIG5vdy4g
QnV0IHRoZSBza3kga25vd3MgdGhlIHJlYXNvbnMgYW5kIHRo
ZSBwYXR0ZXJucyBiZWhpbmQgYWxsIGNsb3VkcywgYW5kIHlv
dSB3aWxsIGtub3csIHRvbywgd2hlbiB5b3UgbGlmdCB5b3Vy
c2VsZiBoaWdoIGVub3VnaCB0byBzZWUgYmV5b25kIGhvcml6
b25zLiINCg0KLVJpY2hhcmQgQmFjaA=="
}
]
}
}
Example JSON with config_drive attribute is an imageRef:
::
{
"server" : {
"name" : "new-server-test",
"imageRef" : "http://servers.api.openstack.org/1234/images/52415800-8b69-11e0-9b19-734f6f006e54",
"flavorRef" : "52415800-8b69-11e0-9b19-734f1195ff37",
"config_drive" : "http://servers.api.openstack.org/1234/images/52415800-8b69-11e0-9b19-734f6f006e54",
"metadata" : {
"My Server Name" : "Apache1"
},
"personality" : [
{
"path" : "/etc/banner.txt",
"contents" : "ICAgICAgDQoiQSBjbG91ZCBkb2VzIG5vdCBrbm93IHdoeSBp
dCBtb3ZlcyBpbiBqdXN0IHN1Y2ggYSBkaXJlY3Rpb24gYW5k
IGF0IHN1Y2ggYSBzcGVlZC4uLkl0IGZlZWxzIGFuIGltcHVs
c2lvbi4uLnRoaXMgaXMgdGhlIHBsYWNlIHRvIGdvIG5vdy4g
QnV0IHRoZSBza3kga25vd3MgdGhlIHJlYXNvbnMgYW5kIHRo
ZSBwYXR0ZXJucyBiZWhpbmQgYWxsIGNsb3VkcywgYW5kIHlv
dSB3aWxsIGtub3csIHRvbywgd2hlbiB5b3UgbGlmdCB5b3Vy
c2VsZiBoaWdoIGVub3VnaCB0byBzZWUgYmV5b25kIGhvcml6
b25zLiINCg0KLVJpY2hhcmQgQmFjaA=="
}
]
}
}

203
doc/source/api_ext/ext_floating_ip_dns.rst
View File

@ -1,203 +0,0 @@
The Floating IP DNS Extension
=================================================================
About this Extension
--------------------
The Floating IP DNS extension provides an interface for managing DNS records associated with IP addresses
allocated by the Floating Ips extension. Requests are dispatched to a DNS driver selected at startup.
To obtain current information the extensions available to you, issue an EXTENSION query on the OpenStack system where it is installed, such as http://example.com/v1.1/tenant/extension.
Extension Overview
~~~~~~~~~~~~~~~~~~
Name
Floating IP DNS
Namespace
http://docs.openstack.org/ext/floating_ip_dns/api/v1.1
Alias
OPS-DNS
Contact
Andrew Bogott <abogott@wikimedia.org>
Status
Alpha
Extension Version
v1.0 (2011-12-22)
Dependencies
Compute API v1.1
Floating IPs Extension, v1.0
Doc Link (PDF)
http://
Doc Link (WADL)
http://
Short Description
This extension enables associated DNS entries with floating IPs.
Sample Query Responses
~~~~~~~~~~~~~~~~~~~~~~
As shown below, responses to an EXTENSION query in XML or JSON provide basic information about the extension.
Extension Query Response: XML::
None
Extension Query Response: JSON::
{'extensions':
[{'updated': '2011-12-23T00:00:00+00:00',
'name': 'Floating_ip_dns',
'links': [],
'namespace': 'http://docs.openstack.org/ext/floating_ip_dns/api/v1.1',
'alias': 'os-floating-ip_dns',
'description': 'Floating IP DNS support'}]}
Document Change History
~~~~~~~~~~~~~~~~~~~~~~~
============= =====================================
Revision Date Summary of Changes
2011-12-23 Initial draft
2012-03-30 Reformat of content
============= =====================================
Summary of Changes
------------------
This extension to the Compute API enables management of DNS entries for floating IP addresses.
This support is provided by the addition of new resources.
New Actions
~~~~~~~~~~~
None
New Faults
~~~~~~~~~~
None
New Headers
~~~~~~~~~~~
None
New Resources
~~~~~~~~~~~~~
Get a list of registered DNS Domains published by the DNS drivers::
GET /v1.1/<tenant_id>/os-floating-ip-dns/
# Sample Response:
{'domain_entries' : [
{'domain': 'domain1.example.org', 'scope': 'public', 'project': 'proj1'}
{'domain': 'domain2.example.net', 'scope': 'public', 'project': 'proj2'}
{'domain': 'example.net', 'scope': 'public', 'project': ''}
{'domain': 'example.internal', 'scope': 'private', 'availability_zone': 'zone1'}]}
Create or modify a DNS domain::
PUT /v1.1/<tenant_id>/os-floating-ip-dns/<domain>
# Sample body, public domain:
{'domain_entry' :
{'scope': 'public',
'project' : 'project1'}}
# Sample body, public (projectless) domain:
{'domain_entry' :
{'scope': 'public'}}
# Sample Response, public domain (success):
{'domain_entry' :
{'domain': 'domain1.example.org',
'scope': 'public',
'project': 'project1'}}
# Sample body, private domain:
{'domain_entry' :
{'scope': 'private',
'availability_domain': 'zone1'}}
# Sample Response, private domain (success):
{'domain_entry' :
{'domain': 'domain1.private',
'scope': 'private',
'availability_zone': 'zone1'}}
Failure Response Code: 403 (Insufficient permissions.)
Delete a DNS domain and all associated host entries::
DELETE /v1.1/<tenant_id>/os-floating-ip-dns/<domain>
Normal Response Code: 200
Failure Response Code: 404 (Domain to be deleted not found.)
Failure Response Code: 403 (Insufficient permissions to delete.)
Create or modify a DNS entry::
PUT /v1.1/<tenant_id>/os-floating-ip-dns/<domain>/entries/<name>
# Sample body:
{ 'dns_entry' :
{ 'ip': '192.168.53.11',
'dns_type': 'A' }}
# Sample Response (success):
{ 'dns_entry' :
{ 'type' : 'A',
'name' : 'instance1' }}
Find unique DNS entry for a given domain and name::
GET /v1.1/<tenant_id>/os-floating-ip-dns/<domain>/entries/<name>
# Sample Response:
{ 'dns_entry' :
{ 'ip' : '192.168.53.11',
'type' : 'A',
'domain' : <domain>,
'name' : <name> }}
Find DNS entries for a given domain and ip::
GET /v1.1/<tenant_id>/os-floating-ip-dns/<domain>/entries?ip=<ip>
# Sample Response:
{ 'dns_entries' : [
{ 'ip' : <ip>,
'type' : 'A',
'domain' : <domain>,
'name' : 'example1' }
{ 'ip' : <ip>,
'type' : 'A',
'domain' : <domain>,
'name' : 'example2' }]}
Delete a DNS entry::
DELETE /v1.1/<tenant_id>/os-floating-ip-dns/<domain>/entries/<name>
Normal Response Code: 200
Failure Response Code: 404 (Entry to be deleted not found)
New States
~~~~~~~~~~
None
Changes to the Cloud Servers Specification
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
None

165
doc/source/api_ext/ext_floating_ips.rst
View File

@ -1,165 +0,0 @@
The Floating IPs Extension
=================================================================
About this Extension
--------------------
The Floating IPs extension enables assigning and allocation of floating IP addresses to instances running in an OpenStack cloud. It is used with the OpenStack Compute 1.1 API to add or remove floating IP addresses on named instances.
To obtain current information the extensions available to you, issue an EXTENSION query on the OpenStack system where it is installed, such as http://example.com/v1.1/tenant/extension.
Extension Overview
~~~~~~~~~~~~~~~~~~
Name
Floating IPs
Namespace
http://docs.openstack.org/ext/floating_ips/api/v1.1
Alias
OPS-FLO
Contact
Anthony Young <sleepsonthefloor@gmail.com>
Status
Alpha
Extension Version
v1.0 (2011-09-14)
Dependencies
Compute API 1.1
Doc Link (PDF)
http://
Doc Link (WADL)
http://
Short Description
This extension enables assigning floating IP addresses to instances.
Sample Query Responses
~~~~~~~~~~~~~~~~~~~~~~
As shown below, responses to an EXTENSION query in XML or JSON provide basic information about the extension.
Extension Query Response: XML::
None
Extension Query Response: JSON::
{"extensions":
[{"updated": "2011-06-16T00:00:00+00:00",
"name": "Floating_ips",
"links": [],
"namespace": "http://docs.openstack.org/ext/floating_ips/api/v1.1",
"alias": "os-floating-ips",
"description": "Floating IPs support"}]}
Document Change History
~~~~~~~~~~~~~~~~~~~~~~~
============= =====================================
Revision Date Summary of Changes
2011-09-14 Initial draft
2012-03-30 Reformat of content
============= =====================================
Summary of Changes
------------------
This extension to the Compute API enables support for floating IP addresses.
This support is provided by the addition of new actions and resources.
New Actions
~~~~~~~~~~~
This extension uses POST to add or remove floating IP addresses to instances.
Normal Response Code: 202
addFloatingIp
removeFloatingIp
Include the response codes, transitions if applicable, and XML and JSON examples.
New Faults
~~~~~~~~~~
None
New Headers
~~~~~~~~~~~
None
New Resources
~~~~~~~~~~~~~
This extension provides an os-floating-ips resource extension to do the following:
List a tenant's floating ips::
GET /v1.1/tenant_id/os-floating-ips/
# Sample Response:
{ "floating_ips" : [ { "fixed_ip" : "10.0.0.3",
"id" : 1,
"instance_id" : 1,
"ip" : "10.6.0.0"
},
{ "fixed_ip" : null,
"id" : 2,
"instance_id" : null,
"ip" : "10.6.0.1"
}
] }
Normal Response Code: 200
Allocate a floating ip to a tenant::
POST /v1.1/tenant_id/os-floating-ips/
# Sample Response:
{ "floating_ip" : { "fixed_ip" : "10.0.0.3",
"id" : 1,
"instance_id" : 1,
"ip" : "10.6.0.0"
}}
If there are no floating ips available, 400 will be returned, with a
message indicating that no more floating ips are available
De-allocate a floating ip from a tenant::
DELETE /v1.1/tenant_id/os-floating-ips/id
Normal Response Code: 202
Show a floating ip::
GET /v1.1/tenant_id/os-floating-ips/id
# Sample Response:
{ "floating_ip" : { "fixed_ip" : "10.0.0.3",
"id" : 1,
"instance_id" : 1,
"ip" : "10.6.0.0"
}}
Normal Response Code: 200
New States
~~~~~~~~~~
None
Changes to the Cloud Servers Specification
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
List the specific changes to the API. For example:
In the List Addresses section of the Cloud Servers Specification: Examples 4.21 and 4.22 should be replaced with examples below.
Provide examples in XML and JSON

103
doc/source/api_ext/ext_keypairs.rst
View File

@ -1,103 +0,0 @@
The Keypairs Extension
=================================================================
About this Extension
--------------------
This extension enables you to create or import a keypair on a virtual instance. If you send the name of the instance to the API, you get a key and a private_key and fingerprint returned. You can also send a public_key to add an existing ssh key and also list the keypairs in use on instances.
To obtain current information the extensions available to you, issue an EXTENSION query on the OpenStack system where it is installed, such as http://example.com/v1.1/tenant/extensions.
Extension Overview
~~~~~~~~~~~~~~~~~~
Name
Keypairs
Namespace
http://docs.openstack.org/ext/keypairs/api/v1.1
Alias
OPS-KYP
Contact
Jesse Andrews <anotherjesse@gmail.com>
Status
Released
Extension Version
v1.0 (2011-08-09)
Dependencies
Compute API 1.1
Doc Link (PDF)
http://
Doc Link (WADL)
http://
Short Description
This extension enables keypair listing, creation, or import into an instance through a REST API.
Sample Query Responses
~~~~~~~~~~~~~~~~~~~~~~
As shown below, responses to an EXTENSION query in XML or JSON provide basic information about the extension.
Extension Query Response: XML::
TBD
.. todo:: Provide example of extension query XML response.
Extension Query Response: JSON::
{"extensions": [{"updated": "2011-08-08T00:00:00+00:00", "name": "Keypairs", "links": [], "namespace": "http://docs.openstack.org/ext/keypairs/api/v1.1", "alias": "os-keypairs", "description": "Keypair Support"}]}
Document Change History
~~~~~~~~~~~~~~~~~~~~~~~
============= =====================================
Revision Date Summary of Changes
2011-09-16 Initial draft
2012-03-30 Reformat of content
============= =====================================
Summary of Changes
------------------
This extension to the Compute API allows keypair support so that you can create or import keypairs to secure your running instances. You can also list keypairs per user.
This support is provided by the addition of new actions.
New Actions
~~~~~~~~~~~
When launching a new server, you can specify an already existing keypair with::
POST /v1.1/tenant_id/os_keypairs/keypair
To lists the keypairs on all running instances, use::
GET /v1.1/tenant_id/os_keypairs
New Faults
~~~~~~~~~~
None
New Headers
~~~~~~~~~~~
None
New Resources
~~~~~~~~~~~~~
None
New States
~~~~~~~~~~
None
Changes to the Cloud Servers Specification
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This section lists the specific changes to the Compute API, namely adding a new section to the 4.3 Server Actions section.

111
doc/source/api_ext/ext_multinic.rst
View File

@ -1,111 +0,0 @@
The Multinic Extension
=================================================================
About this Extension
--------------------
This extension enables addFixedIp and removeFixedIp actions on servers. It is used with the OpenStack Compute 1.1 API to add or remove fixed IP addresses on named instances.
To use this extension, you must have configured Compute with more than one Network Interface Card.
To obtain current information the extensions available to you, issue an EXTENSION query on the OpenStack system where it is installed, such as http://example.com/v1.1/tenant/extension.
Extension Overview
~~~~~~~~~~~~~~~~~~
Name
Multinic
Namespace
http://docs.openstack.org/ext/multinic/api/v1.1
Alias
OPS-MLT
Contact
Kevin Mitchell <kevin.mitchell@rackspace.com>
Status
Alpha
Extension Version
v1.0 (2011-09-14)
Dependencies
Compute API 1.1
Doc Link (PDF)
http://
Doc Link (WADL)
http://
Short Description
This extension enables the assignment and removal of fixed IP addresses on virtual servers running in an OpenStack Compute cloud.
Sample Query Responses
~~~~~~~~~~~~~~~~~~~~~~
As shown below, responses to an EXTENSION query in XML or JSON provide basic information about the extension.
Extension Query Response: XML::
<extensions xmlns:atom="http://www.w3.org/2005/Atom" xmlns="http://docs.openstack.org/compute/api/v1.1">
<extension name="Multinic" namespace="http://docs.openstack.org/ext/multinic/api/v1.1" alias="NMN" updated="2011-06-09T00:00:00+00:00"><description>Multiple network support</description></extension>
</extensions>
Extension Query Response: JSON::
{"extensions": [{"updated": "2011-06-09T00:00:00+00:00", "name": "Multinic", "links": [], "namespace": "http://docs.openstack.org/ext/multinic/api/v1.1", "alias": "NMN", "description": "Multiple network support"}]}
Document Change History
~~~~~~~~~~~~~~~~~~~~~~~
============= =====================================
Revision Date Summary of Changes
2011-09-14 Initial draft
2012-03-30 Reformat of content
============= =====================================
Summary of Changes
------------------
This extension to the Compute API allows addition and removal of fixed IP addresses to instances.
This support is provided by the addition of new <actions, faults, headers, resources, states, something else>.
New Actions
~~~~~~~~~~~
This extension uses POST to add or remove fixed IP addresses to instances.
add_fixed_ip
remove_fixed_ip
Normal Response Code: 202
Include the response codes, transitions if applicable, and XML and JSON examples.
New Faults
~~~~~~~~~~
None
New Headers
~~~~~~~~~~~
None
New Resources
~~~~~~~~~~~~~
None
New States
~~~~~~~~~~
None
Changes to the Cloud Servers Specification
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
List the specific changes to the API. For example:
In section 4.1.1 (List Servers) of the Cloud Servers Specification: Examples 4.1 and 4.2 should be replaced with Example 2.7 and Example 2.8 below.
Provide examples in XML and JSON

100
doc/source/api_ext/ext_quotas.rst
View File

@ -1,100 +0,0 @@
The Quotas Extension
=================================================================
About this Extension
--------------------
The quotas extension enables limiters placed on the resources used per tenant (project) for virtual instances. It is used with the OpenStack Compute API 1.1 for administrators who need to control the amount of volumes, memory, floating IP addresses, instances, or cores allowed within a defined tenant or project.
To use this extension, you need to have administrative rights to the tenants upon which you are placing quotas.
.. Are there any pre-requisites prior to using it such as special hardware or configuration?
To obtain current information the extensions available to you, issue an EXTENSION query on the OpenStack system where it is installed, such as http://example.com/v1.1/tenant/extensions.
Extension Overview
~~~~~~~~~~~~~~~~~~
Name
Quotas
Namespace
http://docs.openstack.org/ext/quotas-sets/api/v1.1
Alias
OPS-QUO
Contact
Name <jake@markupisart.com>
Status
Alpha
Extension Version
v1.0 (2011-08-16)
Dependencies
Compute API 1.1
Doc Link (PDF)
http://
Doc Link (WADL)
http://
Short Description
This extension enables quota management for OpenStack Compute servers so that resources for virtual instances are properly managed.
Sample Query Responses
~~~~~~~~~~~~~~~~~~~~~~
As shown below, responses to an EXTENSION query in XML or JSON provide basic information about the extension.
Extension Query Response: XML::
TBD
.. todo:: Provide example of extension query XML response.
Extension Query Response: JSON::
{"extensions": [{"updated": "2011-08-08T00:00:00+00:00", "name": "Quotas", "links": [], "namespace": "http://docs.openstack.org/ext/quotas-sets/api/v1.1", "alias": "os-quota-sets", "description": "Quotas management support"}]}
Document Change History
~~~~~~~~~~~~~~~~~~~~~~~
============= =====================================
Revision Date Summary of Changes
2011-09-14 Initial draft
2012-03-30 Reformat of content
============= =====================================
Summary of Changes
------------------
This extension to the OpenStack Compute API allows administrators to control quotas for tenants (formerly known as projects).
This support is provided by the addition of new <actions, faults, headers, resources, states, something else>.
New Actions
~~~~~~~~~~~
List the actions each in a section. Enter "None" if there are no changes.
Include the response codes, transitions if applicable, and XML and JSON examples.
New Faults
~~~~~~~~~~
New Headers
~~~~~~~~~~~
New Resources
~~~~~~~~~~~~~
New States
~~~~~~~~~~
Changes to the Cloud Servers Specification
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
List the specific changes to the API. For example:
In section 4.1.1 (List Servers) of the Cloud Servers Specification: Examples 4.1 and 4.2 should be replaced with Example 2.7 and Example 2.8 below.
Provide examples in XML and JSON

111
doc/source/api_ext/ext_rescue.rst
View File

@ -1,111 +0,0 @@
The Rescue Extension
=================================================================
About this Extension
--------------------
The rescue extension lets you put a server into a "rescue" status when the virtual instance will be replaced with a "rescue" image and have its existing drive attached as a second disk so that a root user can log in and troubleshoot problems with the virtual server.
To put a server into "rescue" state, you do not have to be an administrator. The only requirement is that the base image used to build your instance must still be available.
To obtain current information the extensions available to you, issue an EXTENSION query on the OpenStack system where it is installed, such as http://example.com/v1.1/tenant/extensions.
Extension Overview
~~~~~~~~~~~~~~~~~~
Name
Rescue
Namespace
http://docs.openstack.org/ext/rescue/api/v1.1
Alias
OPS-RES
Contact
Josh Kearney <josh@jk0.org>
Status
Alpha
Extension Version
v1.0 (2011-08-18)
Dependencies
Compute API 1.1
Doc Link (PDF)
http://
Doc Link (WADL)
http://
Short Description
This extension enables rescue capabilities for OpenStack Compute servers so that virtual instances running in the cloud may be put in a rescue status.
Sample Query Responses
~~~~~~~~~~~~~~~~~~~~~~
As shown below, responses to an EXTENSION query in XML or JSON provide basic information about the extension.
Extension Query Response: XML::
N/A
Extension Query Response: JSON::
{"extensions": [{"updated": "2011-08-18T00:00:00+00:00", "name": "Rescue", "links": [], "namespace": "http://docs.openstack.org/ext/rescue/api/v1.1", "alias": "os-rescue", "description": "Instance rescue mode"}]}
Document Change History
~~~~~~~~~~~~~~~~~~~~~~~
============= =====================================
Revision Date Summary of Changes
2011-09-16 Initial draft
2012-03-30 Reformat of content
============= =====================================
Summary of Changes
------------------
This extension to the OpenStack Compute API enables rescue of running instances.
This support is provided by the addition of new actions and states.
New Actions
~~~~~~~~~~~
rescue
unrescue
New Faults
~~~~~~~~~~
New Headers
~~~~~~~~~~~
New Resources
~~~~~~~~~~~~~
New States
~~~~~~~~~~
RESCUING
UNRESCUING
Changes to the Cloud Servers Specification
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
A new action added to the 4.3 Server Actions section.
Rescue Server
+++++++++++++
============= ==================
Verb URI
POST /servers/id/rescue
============= ==================
Normal Response Code(s): 202
Error Response Code(s): computeFault (400, 500, …), serviceUnavailable (503), unauthorized (401), forbidden (403), badRequest (400), badMethod (405), overLimit (413), itemNotFound (404), badMediaType (415), buildInProgress (409)
Status Transition: ACTIVE -> RESCUING -> ACTIVE
This operation places the server into RESCUING status.

112
doc/source/api_ext/ext_security_group.rst
View File

@ -1,112 +0,0 @@
The Security Groups Extension
=================================================================
About this Extension
--------------------
The Security Groups extension lets you view, create, and remove security groups for instances plus set rules for security groups using the OpenStack Compute API 1.1.
.. Are there any pre-requisites prior to using it such as special hardware or configuration?
To obtain current information the extensions available to you, issue an EXTENSION query on the OpenStack system where it is installed, such as http://example.com/v1.1/tenant/extensions.
Extension Overview
~~~~~~~~~~~~~~~~~~
Name
Security Groups
Namespace
http://docs.openstack.org/ext/securitygroups/api/v1.1
Alias
OPS-SCG
Contact
Tushar Patil <tushar.vitthal.patil@gmail.com>
Status
Released
Extension Version
v1.0 (2011-08-11)
Dependencies
Compute API 1.1
Doc Link (PDF)
http://
Doc Link (WADL)
http://
Short Description
This extension enables creation and listing of security groups.
Sample Query Responses
~~~~~~~~~~~~~~~~~~~~~~
As shown below, responses to an EXTENSION query in XML or JSON provide basic information about the extension.
Extension Query Response: XML::
HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: 3295
Date: Fri, 16 Sep 2011 21:06:55 GMT
<extensions xmlns:atom="http://www.w3.org/2005/Atom" xmlns="http://docs.openstack.org/compute/api/v1.1">
<extension name="SecurityGroups" namespace="http://docs.openstack.org/ext/securitygroups/api/v1.1" alias="security_groups" updated="2011-07-21T00:00:00+00:00"><description>Security group support</description></extension>
</extensions>
Extension Query Response: JSON::
{"extensions": [{"updated": "2011-07-21T00:00:00+00:00", "name": "SecurityGroups", "links": [], "namespace": "http://docs.openstack.org/ext/securitygroups/api/v1.1", "alias": "security_groups", "description": "Security group support"}]}
Document Change History
~~~~~~~~~~~~~~~~~~~~~~~
============= =====================================
Revision Date Summary of Changes
2011-09-16 Initial draft
2012-03-30 Reformat of content
============= =====================================
Summary of Changes
------------------
This extension to the Compute API allows you to create, update, and delete security groups.
This support is provided by the addition of new actions.
New Actions
~~~~~~~~~~~
os-security-group
os-security-group-rules
Include the response codes, transitions if applicable, and XML and JSON examples.
New Faults
~~~~~~~~~~
None
New Headers
~~~~~~~~~~~
None
New Resources
~~~~~~~~~~~~~
None
New States
~~~~~~~~~~
None
Changes to the Cloud Servers Specification
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
List the specific changes to the API. For example:
In section 4.1.1 (List Servers) of the Cloud Servers Specification: Examples 4.1 and 4.2 should be replaced with Example 2.7 and Example 2.8 below.
Provide examples in XML and JSON

110
doc/source/api_ext/ext_virtual_interfaces.rst
View File

@ -1,110 +0,0 @@
The Virtual Interfaces Extension
=================================================================
About this Extension
--------------------
The Virtual Interfaces extension lets you view the virtual interfaces used in an instance.
To obtain current information the extensions available to you, issue an EXTENSION query on the OpenStack system where it is installed, such as http://example.com/v1.1/tenant/extensions.
Extension Overview
~~~~~~~~~~~~~~~~~~
Name
Virtual Interfaces
Namespace
http://docs.openstack.org/ext/virtual_interfaces/api/v1.1
Alias
MID-VRT
Contact
Name <ryu@midokura.jp>
Status
Alpha
Extension Version
v1.0 (2011-08-18)
Dependencies
Compute API 1.1
Doc Link (PDF)
http://
Doc Link (WADL)
http://
Short Description
This extension enables Virtual Interfaces capabilities for OpenStack Compute servers so that you know the interfaces for the virtual instances running in the cloud.
Sample Query Responses
~~~~~~~~~~~~~~~~~~~~~~
As shown below, responses to an EXTENSION query in XML or JSON provide basic information about the extension.
Extension Query Response: XML::
<extensions>
<extension name="VirtualInterfaces"
namespace="http://docs.openstack.org/ext/virtual_interfaces/api/v1.1"
alias="virtual_interfaces" updated="2011-08-17T00:00:00+00:00">
<description>Virtual interface support</description>
</extension>
</extensions>
Extension Query Response: JSON::
{"extensions": [{"updated": "2011-08-17T00:00:00+00:00", "name": "VirtualInterfaces", "links": [], "namespace": "http://docs.openstack.org/ext/virtual_interfaces/api/v1.1", "alias": "virtual_interfaces", "description": "Virtual interface support"}]}
Document Change History
~~~~~~~~~~~~~~~~~~~~~~~
============= =====================================
Revision Date Summary of Changes
2011-09-16 Initial draft
2012-03-30 Reformat of content
============= =====================================
Summary of Changes
------------------
This extension to the OpenStack Compute API enables listing of Virtual Interfaces of running instances.
This support is provided by the addition of new actions.
New Actions
~~~~~~~~~~~
virtual_interfaces
New Faults
~~~~~~~~~~
None
New Headers
~~~~~~~~~~~
None
New Resources
~~~~~~~~~~~~~
None
New States
~~~~~~~~~~
None
Changes to the Cloud Servers Specification
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
A new action added to the 4.3 Server Actions section.
============= ==================
Verb URI
POST /servers/id/virtual_interfaces
============= ==================
Normal Response Code(s): 202
Error Response Code(s): computeFault (400, 500, …), serviceUnavailable (503), unauthorized (401), forbidden (403), badRequest (400), badMethod (405), overLimit (413), itemNotFound (404), badMediaType (415), buildInProgress (409)

112
doc/source/api_ext/ext_volumes.rst
View File

@ -1,112 +0,0 @@
The Volumes Extension
=================================================================
About this Extension
--------------------
This extension enables volume management on virtual servers. It is used with the OpenStack Compute 1.1 API to add or remove fixed IP addresses on named instances.
To use this extension, you must have configured Compute to manage volumes.
.. Are there any pre-requisites prior to using it such as special hardware or configuration?
To obtain current information the extensions available to you, issue an EXTENSION query on the OpenStack system where it is installed, such as http://example.com/v1.1/tenant/extensions.
Extension Overview
~~~~~~~~~~~~~~~~~~
Name
Volumes
Namespace
http://docs.openstack.org/ext/volumes/api/v1.1
Alias
OPS-VOL
Contact
Name <justin@fathomdb.com>
Status
Alpha
Extension Version
v1.0 (2011-09-14)
Dependencies
Compute API 1.1
Doc Link (PDF)
http://
Doc Link (WADL)
http://
Short Description
This extension enables listing of volumes available to virtual servers running in an OpenStack cloud. You can create, attach, and detach a volume with this extension.
Sample Query Responses
~~~~~~~~~~~~~~~~~~~~~~
As shown below, responses to an EXTENSION query in XML or JSON provide basic information about the extension.
Extension Query Response: XML::
TBD
.. todo:: Provide example of XML query and response for volumes extension.
Extension Query Response: JSON::
{"extensions": [{"updated": "2011-03-25T00:00:00+00:00", "name": "Volumes", "links": [], "namespace": "http://docs.openstack.org/ext/volumes/api/v1.1", "alias": "os-volumes", "description": "Volumes support"}]}
Document Change History
~~~~~~~~~~~~~~~~~~~~~~~
============= =====================================
Revision Date Summary of Changes
2011-09-14 Initial draft
2012-03-30 Reformat of content
============= =====================================
Summary of Changes
------------------
This extension to the Compute API allows volume management through the OpenStack Compute API.
This support is provided by the addition of new actions.
New Actions
~~~~~~~~~~~
This extension uses POST to attach or detach volumes to instances.
Normal Response Code: 202
Enter "None" if there are no changes to the sections below.
Include the response codes, transitions if applicable, and XML and JSON examples.
New Faults
~~~~~~~~~~
None
New Headers
~~~~~~~~~~~
None
New Resources
~~~~~~~~~~~~~
None
New States
~~~~~~~~~~
None
Changes to the Cloud Servers Specification
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
List the specific changes to the API. For example:
In section 4.1.1 (List Servers) of the Cloud Servers Specification: Examples 4.1 and 4.2 should be replaced with Example 2.7 and Example 2.8 below.
Provide examples in XML and JSON

56
doc/source/api_ext/index.rst
View File

@ -1,56 +0,0 @@
..
Copyright 2011 United States Government as represented by the
Administrator of the National Aeronautics and Space Administration.
All Rights Reserved.
Licensed under the Apache License, Version 2.0 (the "License"); you may
not use this file except in compliance with the License. You may obtain
a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations
under the License.
Compute API Extensions
======================
In this section you will find extension reference information. If you need to write an extension's reference page, you can find an RST template in doc/source/api_ext/rst_extension_template.rst.
The Compute API specification is published to http://docs.openstack.org/api and the source is found in https://github.com/openstack/compute-api. These extensions extend the core API.
Extensions
----------
.. toctree::
:maxdepth: 3
ext_aggregates.rst
ext_config_drive.rst
ext_floating_ip_dns.rst
ext_floating_ips.rst
ext_keypairs.rst
ext_multinic.rst
ext_quotas.rst
ext_rescue.rst
ext_security_group.rst
ext_virtual_interfaces.rst
ext_volumes.rst
API Reference
-------------
.. toctree::
:maxdepth: 3
../api/autoindex
Indices and tables
------------------
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

105
doc/source/api_ext/rst_extension_template.rst
View File

@ -1,105 +0,0 @@
The <Name of Extension> Extension
=================================================================
About this Extension
--------------------
Describe the extension.
Who will use it and what project's API is it for?
How can I find out more about it?
Are there pre-requisites prior to using it such as special hardware or configuration?
To obtain current information on 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/etensions.
Extension Overview
~~~~~~~~~~~~~~~~~~
Name
Name of Extensions
Namespace
http://docs.openstack.org/<project>/api/ext/tla/v1.0
Alias
ORG-EXT
Contact
Name <email@mailingaddress.net>
Status
Alpha, Beta, or Released
Extension Version
v1.0 (year-mm-dd)
Dependencies
Name and version of API
Doc Link (PDF)
http://
Doc Link (WADL)
http://
Short Description
This extension enables ...
Sample Query Responses
~~~~~~~~~~~~~~~~~~~~~~
As shown below, responses to an EXTENSION query in XML or JSON provide basic information about the extension.
Extension Query Response: XML::
N/A
Extension Query Response: JSON::
Document Change History
~~~~~~~~~~~~~~~~~~~~~~~
============= =====================================
Revision Date Summary of Changes
yyyy-mm-dd Describe the change, one line per rev
============= =====================================
Summary of Changes
------------------
This extension to the <project> API allows ...
This support is provided by the addition of new <actions, faults, headers, resources, states, something else>.
New Actions
~~~~~~~~~~~
List each action in a section. Enter "None" if there are no changes.
Include the response codes, transitions if applicable, and XML and JSON examples.
New Faults
~~~~~~~~~~
New Headers
~~~~~~~~~~~
New Resources
~~~~~~~~~~~~~
New States
~~~~~~~~~~
Changes to the Cloud Servers Specification
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
List the specific changes to the API. For example:
In section 4.1.1 (List Servers) of the Cloud Servers Specification: Examples 4.1 and 4.2 should be replaced with Example 2.7 and Example 2.8 below.
Provide examples in XML and JSON

90
doc/source/cloud101.rst
View File

@ -1,90 +0,0 @@
..
Copyright 2010-2011 United States Government as represented by the
Administrator of the National Aeronautics and Space Administration.
All Rights Reserved.
Licensed under the Apache License, Version 2.0 (the "License"); you may
not use this file except in compliance with the License. You may obtain
a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations
under the License.
Cloud Computing 101
===================
Originally the term cloud came from a diagram that contained a cloud-like shape to contain the
services that afforded computing power that was harnessed to get work done. Much like the electrical
power we receive each day, cloud computing is a model for enabling access to a shared collection of
computing resources - networks for transfer, servers for storage, and applications or services for
completing work.
Why Cloud?
----------
Like humans supposedly only use 10% of their brain power, many of the computers in place in data
centers today are underutilized in computing power and networking bandwidth. People also may need a large
amount of computing capacity to complete a computation for example, but don't need the computing power
once the computation is done. You want cloud computing when you want a service that's available
on-demand with the flexibility to bring it up or down through automation or with little intervention.
Attributes of a Cloud
---------------------
On-demand self-service - A cloud should enable self-service, so that users can provision servers and networks with little
human intervention.
Network access - Any computing capabilities are available over the network and you can use many different
devices through standardized mechanisms.
Resource pooling - Clouds can serve multiple consumers according to demand.
Elasticity - Provisioning is rapid and scales out or in based on need.
Metered or measured service - Just like utilities that are paid for by the hour, clouds should optimize
resource use and control it for the level of service or type of servers such as storage or processing.
Types of Cloud Services
-----------------------
Cloud computing offers different service models depending on the capabilities a consumer may require.
The US-based National Institute of Standards and Technology offers definitions for cloud computing
and the service models that are emerging.
These definitions are summarized from the `U.S. National Institute of Standards and Technology (NIST) cloud computing research group <http://csrc.nist.gov/groups/SNS/cloud-computing/>`_.
SaaS - Software as a Service
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Provides the consumer the ability to use the software in a cloud environment, such as web-based email for example.
PaaS - Platform as a Service
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Provides the consumer the ability to deploy applications through a programming language or tools supported
by the cloud platform provider. An example of platform as a service is an Eclipse/Java programming
platform provided with no downloads required.
IaaS - Infrastructure as a Service
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Provides infrastructure such as computer instances, network connections, and storage so that people
can run any software or operating system.
Types of Cloud Deployments
--------------------------
When you hear terms such as public cloud or private cloud, these refer to the deployment model for the cloud. A private cloud operates for a single organization, but can be managed on-premise or off-premise. A public cloud has an infrastructure that is available to the general public or a large industry group and is likely owned by a cloud services company.
The NIST also defines community cloud as shared by several organizations supporting a specific community with shared concerns.
A hybrid cloud can be a deployment model, as a composition of both public and private clouds, or a hybrid model for cloud computing may involve both virtual and physical servers.
Work in the Clouds
------------------
What have people done with cloud computing? Cloud computing can help with large-scale computing needs or can lead consolidation efforts by virtualizing servers to make more use of existing hardware (and possibly release old hardware from service.) People also use cloud computing for collaboration because of the high availability through networked computers. Productivity suites for word processing, number crunching, and email communications, and more are also available through cloud computing. Cloud computing also avails additional storage to the cloud user, avoiding the need for additional hard drives on your desktop and enabling access to large data storage capacity online in the cloud.

103
doc/source/community.rst
View File

@ -1,103 +0,0 @@
..
Copyright 2010-2011 United States Government as represented by the
Administrator of the National Aeronautics and Space Administration.
All Rights Reserved.
Licensed under the Apache License, Version 2.0 (the "License"); you may
not use this file except in compliance with the License. You may obtain
a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations
under the License.
Getting Involved
================
The OpenStack community for Nova is a very friendly group and there are places online to join in with the
community. Feel free to ask questions. This document points you to some of the places where you can
communicate with people.
How to Join the OpenStack Community
-----------------------------------
Our community welcomes all people interested in open source cloud computing, and there are no formal
membership requirements. The best way to join the community is to talk with others online or at a meetup
and offer contributions through Launchpad, the wiki, or blogs. We welcome all types of contributions,
from blueprint designs to documentation to testing to deployment scripts.
Contributing Code
-----------------
To contribute code, sign up for a Launchpad account and sign a contributor license agreement,
available on the `OpenStack Wiki`_. Once the CLA is signed you
can contribute code through the Bazaar version control system which is related to your Launchpad
account. See the :doc:`devref/development.environment` page to get started.
#openstack on Freenode IRC Network
----------------------------------
There is a very active chat channel at `<irc://freenode.net/#openstack>`_. This
is usually the best place to ask questions and find your way around. IRC stands for Internet Relay
Chat and it is a way to chat online in real time. You can also ask a question and come back to the
log files to read the answer later. Logs for the #openstack IRC channel are stored at
`<http://eavesdrop.openstack.org/irclogs/>`_.
OpenStack Wiki
--------------
The wiki is a living source of knowledge. It is edited by the community, and
has collections of links and other sources of information. Typically the pages are a good place
to write drafts for specs or documentation, describe a blueprint, or collaborate with others.
* `OpenStack Wiki`_
.. _OpenStack Wiki: http://wiki.openstack.org/
Nova on Github
--------------
Github is a code hosting service that hosts the Nova source code.
* `Github Nova page <http://github.com/openstack/nova>`_
Nova on Launchpad
-----------------
From Launchpad you can report bugs, ask questions, and register blueprints (feature requests).
See :doc:`devref/launchpad` for more details.
* `Launchpad Nova Page <http://launchpad.net/nova>`_
OpenStack Blog
--------------
The OpenStack blog includes a weekly newsletter that aggregates OpenStack news
from around the internet, as well as providing inside information on upcoming
events and posts from OpenStack contributors.
`OpenStack Blog <http://openstack.org/blog>`_
See also: `Planet OpenStack <http://planet.openstack.org/>`_, aggregating blogs
about OpenStack from around the internet into a single feed. If you'd like to contribute to this blog
aggregation with your blog posts, there are instructions for `adding your blog <http://wiki.openstack.org/AddingYourBlog>`_.
Twitter
-------
Because all the cool kids do it: `@openstack <http://twitter.com/openstack>`_. Also follow the
`#openstack <http://search.twitter.com/search?q=%23openstack>`_ tag for relevant tweets.
OpenStack Docs Site
-------------------
The `nova.openstack.org <http://nova.openstack.org>`_ site is geared towards developer documentation,
and the `docs.openstack.org <http://docs.openstack.org>`_ site is intended for cloud administrators
who are standing up and running OpenStack Compute in production. You can contribute to the Docs Site
by using git and Gerrit and contributing to the openstack-manuals project at http://github.com/openstack/openstack-manuals.

32
doc/source/index.rst
View File

@ -1,5 +1,5 @@
..
Copyright 2010-2011 United States Government as represented by the
Copyright 2010-2012 United States Government as represented by the
Administrator of the National Aeronautics and Space Administration.
All Rights Reserved.
@ -15,10 +15,11 @@
License for the specific language governing permissions and limitations
under the License.
Welcome to Nova's documentation!
================================
Welcome to Nova's developer documentation!
==========================================
Nova is a cloud computing fabric controller, the main part of an IaaS system.
Nova is the project name for OpenStack Compute, a cloud computing fabric
controller, the main part of an IaaS system.
Individuals and organizations can use Nova to host and manage their own cloud
computing systems. Nova originated as a project out of NASA Ames Research Laboratory.
@ -35,43 +36,22 @@ This documentation is generated by the Sphinx toolkit and lives in the source
tree. Additional draft and project documentation on Nova and other components of OpenStack can
be found on the `OpenStack wiki`_. Cloud administrators, refer to `docs.openstack.org`_.
Also see the :doc:`community` page for other ways to interact with the community.
.. _`OpenStack wiki`: http://wiki.openstack.org
.. _`docs.openstack.org`: http://docs.openstack.org
Key Concepts
============
.. toctree::
:maxdepth: 1
cloud101
nova.concepts
service.architecture
object.model
runnova/index
.. swift.concepts
.. swift.object.model
Developer Docs
==============
.. toctree::
:maxdepth: 1
quickstart
devref/index
community
API Extensions
==============
.. toctree::
:maxdepth: 1
api_ext/index
Go to http://api.openstack.org for information about Compute API extensions.
Outstanding Documentation Tasks
===============================

12
doc/source/installer.rst
View File

@ -1,12 +0,0 @@
Live CD
=======
* 3 Images
* Once you start bundling images, must be able to point to source code
* Could make part of build
* sudo nova-manage user admin newuser
* sudo nova-manage project create demo newuser
* sudo nova-manage project zipfile demo
* get images
* Web browser

231
doc/source/nova.concepts.rst
View File

@ -1,231 +0,0 @@
..
Copyright 2010-2011 United States Government as represented by the
Administrator of the National Aeronautics and Space Administration.
All Rights Reserved.
Licensed under the Apache License, Version 2.0 (the "License"); you may
not use this file except in compliance with the License. You may obtain
a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations
under the License.
Nova Concepts and Introduction
==============================
Introduction
------------
Nova, also known as OpenStack Compute, is the software that controls your Infrastructure as as Service (IaaS)
cloud computing platform. It is similar in scope to Amazon EC2 and Rackspace
Cloud Servers. Nova does not include any virtualization software, rather it
defines drivers that interact with underlying virtualization mechanisms that
run on your host operating system, and exposes functionality over a web API.
This site does not attempt to explain fundamental concepts of cloud
computing, IaaS, virtualization, or other related technologies. Instead, it
focuses on describing how Nova's implementation of those concepts is achieved.
This page outlines concepts that you will need to understand as a user or
administrator of an OpenStack installation. Each section links to more more
detailed information in the `OpenStack Compute Administration Guide`_
but you'll probably want to read this section straight-through before tackling
the specifics presented there.
.. _OpenStack Compute Administration Guide: http://docs.openstack.org/trunk/openstack-compute/admin/content/
Concept: Users and Projects
---------------------------
* access to images is limited by project
* access/secret are per user
* keypairs are per user
* quotas are per project
Concept: Virtualization
-----------------------
* KVM
* UML
* XEN
* qemu
* LXC
Concept: Instances
------------------
An 'instance' is a word for a virtual machine that runs inside the cloud.
Concept: Instance Type
----------------------
An 'instance type' describes the compute, memory and storage capacity of nova computing instances. In layman terms, this is the size (in terms of vCPUs, RAM, etc.) of the virtual server that you will be launching.
Concept: System Architecture
----------------------------
Nova consists of seven main components, with the Cloud Controller component representing the global state and interacting with all other components. API Server acts as the Web services front end for the cloud controller. Compute Controller provides compute server resources, and the Object Store component provides storage services. Auth Manager provides authentication and authorization services. Volume Controller provides fast and permanent block-level storage for the comput servers. Network Controller provides virtual networks to enable compute servers to interact with each other and with the public network. Scheduler selects the most suitable compute controller to host an instance.
.. image:: images/Novadiagram.png
Nova is built on a shared-nothing, messaging-based architecture. All of the major components, that is Compute Controller, Volume Controller, Network Controller, and Object Store can be run on multiple servers. Cloud Controller communicates with Object Store via HTTP (Hyper Text Transfer Protocol), but it communicates with Scheduler, Network Controller, and Volume Controller via AMQP (Advanced Message Queue Protocol). To avoid blocking each component while waiting for a response, Nova uses asynchronous calls, with a call-back that gets triggered when a response is received.
To achieve the shared-nothing property with multiple copies of the same component, Nova keeps all the cloud system state in a distributed data store. Updates to system state are written into this store, using atomic transactions when required. Requests for system state are read out of this store. In limited cases, the read results are cached within controllers for short periods of time (for example, the current list of system users.)
.. note:: The database schema is available on the `OpenStack Wiki <http://wiki.openstack.org/NovaDatabaseSchema>`_.
Concept: Storage
----------------
Volumes
~~~~~~~
A 'volume' is a detachable block storage device. You can think of it as a usb hard drive. It can only be attached to one instance at a time, so it does not work like a SAN. If you wish to expose the same volume to multiple instances, you will have to use an NFS or SAMBA share from an existing instance.
Local Storage
~~~~~~~~~~~~~
Every instance larger than m1.tiny starts with some local storage (up to 160GB for m1.xlarge). This storage is currently the second partition on the root drive.
Concept: Quotas
---------------
Nova supports per-project quotas. There are currently quotas for number of instances, total number of cores, number of volumes, total number of gigabytes, and number of floating ips.
Concept: RBAC
-------------
Nova provides roles based access control (RBAC) for access to api commands. A user can have a number of different :ref:`roles <auth_roles>`. Roles define which api_commands a user can perform.
It is important to know that there are user-specific (sometimes called global) roles and project-specific roles. A user's actual permissions in a particular project are the INTERSECTION of his user-specific roles and is project-specific roles.
For example: A user can access api commands allowed to the netadmin role (like allocate_address) only if he has the user-specific netadmin role AND the project-specific netadmin role.
More information about RBAC can be found in :ref:`auth`.
Concept: API
------------
* EC2
* OpenStack / Rackspace
Concept: Networking
-------------------
Nova has a concept of Fixed IPs and Floating IPs. Fixed IPs are assigned to an instance on creation and stay the same until the instance is explicitly terminated. Floating ips are ip addresses that can be dynamically associated with an instance. This address can be disassociated and associated with another instance at any time.
There are multiple strategies available for implementing fixed IPs:
Flat Mode
~~~~~~~~~
The simplest networking mode. Each instance receives a fixed ip from the pool. All instances are attached to the same bridge (br100) by default. The bridge must be configured manually. The networking configuration is injected into the instance before it is booted. Note that this currently only works on linux-style systems that keep networking configuration in /etc/network/interfaces.
Flat DHCP Mode
~~~~~~~~~~~~~~
This is similar to the flat mode, in that all instances are attached to the same bridge. In this mode Nova does a bit more configuration, it will attempt to bridge into an ethernet device (eth0 by default). It will also run dnsmasq as a dhcpserver listening on this bridge. Instances receive their fixed IPs by doing a dhcpdiscover.
VLAN DHCP Mode
~~~~~~~~~~~~~~
This is the default networking mode and supports the most features. For multiple machine installation, it requires a switch that supports host-managed vlan tagging. In this mode, Nova will create a vlan and bridge for each project. The project gets a range of private ips that are only accessible from inside the vlan. In order for a user to access the instances in their project, a special vpn instance (code named :ref:`cloudpipe <cloudpipe>`) needs to be created. Nova generates a certificate and key for the user to access the vpn and starts the vpn automatically. More information on cloudpipe can be found :ref:`here <cloudpipe>`.
The following diagram illustrates how the communication that occurs between the vlan (the dashed box) and the public internet (represented by the two clouds)
.. image:: /images/cloudpipe.png
:width: 100%
..
Concept: Binaries
-----------------
Nova is implemented by a number of related binaries. These binaries can run on the same machine or many machines. A detailed description of each binary is given in the :ref:`binaries section <binaries>` of the developer guide.
.. _manage_usage:
Concept: nova-manage
--------------------
The nova-manage command is used to perform many essential functions for
administration and ongoing maintenance of Nova, such as user creation,
vpn management, and much more.
See :doc:`runnova/nova.manage` in the Administration Guide for more
details.
Concept: Flags
--------------
Nova uses python-gflags for a distributed command line system, and the flags can either be set when running a command at the command line or within a flag file. When you install Nova packages for the Austin release, each nova service gets its own flag file. For example, nova-network.conf is used for configuring the nova-network service, and so forth. In releases beyond Austin which was released in October 2010, all flags are set in nova.conf.
Concept: Plugins
----------------
* Managers/Drivers: utils.import_object from string flag
* virt/connections: conditional loading from string flag
* db: LazyPluggable via string flag
* auth_manager: utils.import_class based on string flag
* Volumes: moving to pluggable driver instead of manager
* Network: pluggable managers
* Compute: same driver used, but pluggable at connection
Concept: IPC/RPC
----------------
Nova utilizes the AMQP messaging standard for performing communication between the various Nova services. This message queuing service is used for both local and remote communication because Nova is designed so that there is no requirement that any of the services exist on the same physical machine. Nova supports two implementations of AMQP: RabbitMQ and Qpid. More information about RabbitMQ can be found at http://www.rabbitmq.com/. More information about Qpid can be found at http://qpid.apache.org/.
Concept: Fakes
--------------
* auth
* ldap
Concept: Scheduler
------------------
* simple
* random
Concept: Security Groups
------------------------
In Nova, a security group is a named collection of network access rules, like firewall policies. These access rules specify which incoming network traffic should be delivered to all VM instances in the group, all other incoming traffic being discarded. Users can modify rules for a group at any time. The new rules are automatically enforced for all running instances and instances launched from then on.
When launching VM instances, the project manager specifies which security groups it wants to join. It will become a member of these specified security groups when it is launched. If no groups are specified, the instances is assigned to the default group, which by default allows all network traffic from other members of this group and discards traffic from other IP addresses and groups. If this does not meet a user's needs, the user can modify the rule settings of the default group.
A security group can be thought of as a security profile or a security role - it promotes the good practice of managing firewalls by role, not by machine. For example, a user could stipulate that servers with the "webapp" role must be able to connect to servers with the "mysql" role on port 3306. Going further with the security profile analogy, an instance can be launched with membership of multiple security groups - similar to a server with multiple roles. Because all rules in security groups are ACCEPT rules, it's trivial to combine them.
Each rule in a security group must specify the source of packets to be allowed, which can either be a subnet anywhere on the Internet (in CIDR notation, with 0.0.0./0 representing the entire Internet) or another security group. In the latter case, the source security group can be any user's group. This makes it easy to grant selective access to one user's instances from instances run by the user's friends, partners, and vendors.
The creation of rules with other security groups specified as sources helps users deal with dynamic IP addressing. Without this feature, the user would have had to adjust the security groups each time a new instance is launched. This practice would become cumbersome if an application running in Nova is very dynamic and elastic, for example scales up or down frequently.
Security groups for a VM are passed at launch time by the cloud controller to the compute node, and applied at the compute node when a VM is started.
Concept: Certificate Authority
------------------------------
Nova does a small amount of certificate management. These certificates are used for :ref:`project vpns <cloudpipe>` and decrypting bundled images.
Concept: Images
---------------
* launching
* bundling

77
doc/source/object.model.rst
View File

@ -1,77 +0,0 @@
..
Copyright 2010-2011 OpenStack LLC
All Rights Reserved.
Licensed under the Apache License, Version 2.0 (the "License"); you may
not use this file except in compliance with the License. You may obtain
a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations
under the License.
Object Model
============
.. graphviz::
digraph foo {
graph [rankdir="LR"]; node [fontsize=9 shape=box];
Instances -> "Public IPs" [arrowhead=crow];
Instances -> "Security Groups" [arrowhead=crow];
Users -> Projects [arrowhead=crow arrowtail=crow dir=both];
Users -> Keys [arrowhead=crow];
Instances -> Volumes [arrowhead=crow];
Projects -> "Public IPs" [arrowhead=crow];
Projects -> Instances [arrowhead=crow];
Projects -> Volumes [arrowhead=crow];
Projects -> Images [arrowhead=crow];
Images -> Instances [arrowhead=crow];
Projects -> "Security Groups" [arrowhead=crow];
"Security Groups" -> Rules [arrowhead=crow];
}
Users
-----
Each Nova User is authorized based on their access key and secret key, assigned per-user. Read more at :doc:`/runnova/managing.users`.
Projects
--------
For Nova, access to images is based on the project. Read more at :doc:`/runnova/managing.projects`.
Images
------
Images are binary files that run the operating system. Read more at :doc:`/runnova/managing.images`.
Instances
---------
Instances are running virtual servers. Read more at :doc:`/runnova/managing.instances`.
Volumes
-------
Volumes offer extra block level storage to instances. Read more at `Managing Volumes <http://docs.openstack.org/openstack-compute/admin/content/ch05s07.html>`_.
Security Groups
---------------
In Nova, a security group is a named collection of network access rules, like firewall policies. Read more at `Security Groups <http://nova.openstack.org/nova.concepts.html#concept-security-groups>`_.
VLANs
-----
VLAN is the default network mode for Nova. Read more at :doc:`/runnova/network.vlan`.
IP Addresses
------------
Nova enables floating IP management.

31
doc/source/quickstart.rst
View File

@ -1,31 +0,0 @@
..
Copyright 2010-2011 United States Government as represented by the
Administrator of the National Aeronautics and Space Administration.
All Rights Reserved.
Licensed under the Apache License, Version 2.0 (the "License"); you may
not use this file except in compliance with the License. You may obtain
a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations
under the License.
Nova Quickstart
===============
The quickest way to set up an OpenStack development environment for testing is
to use `DevStack <http://devstack.org/>`_.
Currently, there is no automated way to do a clean reset of DevStack. The
beginnings of an external cleanup script can be found at `Ron Pedde's DevStack
branch <https://github.com/rpedde/devstack/blob/master/clean.sh>`_, which
deletes instances and cleans up security groups.
To manually start over, drop the nova, glance, and keystone databases, delete
the logs, delete the IP addresses and bridges created, and then recreate the
databases and restart the services to get back to a clean state.

57
doc/source/runnova/binaries.rst
View File

@ -1,57 +0,0 @@
..
Copyright 2010-2011 United States Government as represented by the
Administrator of the National Aeronautics and Space Administration.
All Rights Reserved.
Licensed under the Apache License, Version 2.0 (the "License"); you may
not use this file except in compliance with the License. You may obtain
a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations
under the License.
.. _binaries:
Nova Daemons
=============
The configuration of these binaries relies on "flagfiles" using the google
gflags package::
$ nova-xxxxx --flagfile flagfile
The binaries can all run on the same machine or be spread out amongst multiple boxes in a large deployment.
nova-api
--------
Nova api receives xml requests and sends them to the rest of the system. It is a wsgi app that routes and authenticate requests. It supports the ec2 and openstack apis.
nova-objectstore
----------------
Nova objectstore is an ultra simple file-based storage system for images that replicates most of the S3 Api. It will soon be replaced with Glance (http://glance.openstack.org) and a simple image manager.
nova-compute
------------
Nova compute is responsible for managing virtual machines. It loads a Service object which exposes the public methods on ComputeManager via rpc.
nova-volume
-----------
Nova volume is responsible for managing attachable block storage devices. It loads a Service object which exposes the public methods on VolumeManager via rpc.
nova-network
------------
Nova network is responsible for managing floating and fixed ips, dhcp, bridging and vlans. It loads a Service object which exposes the public methods on one of the subclasses of NetworkManager. Different networking strategies are as simple as changing the network_manager flag::
$ nova-network --network_manager=nova.network.manager.FlatManager
IMPORTANT: Make sure that you also set the network_manager on nova-api and nova_compute, since make some calls to network manager in process instead of through rpc. More information on the interactions between services, managers, and drivers can be found :ref:`here <service_manager_driver>`

49
doc/source/runnova/euca2ools.rst
View File

@ -1,49 +0,0 @@
Euca2ools
=========
Nova is compatible with most of the euca2ools command line utilities. Both Administrators and Users will find these tools helpful for day-to-day administration.
* euca-add-group
* euca-delete-bundle
* euca-describe-instances
* euca-register
* euca-add-keypair
* euca-delete-group
* euca-describe-keypairs
* euca-release-address
* euca-allocate-address
* euca-delete-keypair
* euca-describe-regions
* euca-reset-image-attribute
* euca-associate-address
* euca-delete-snapshot
* euca-describe-snapshots
* euca-revoke
* euca-attach-volume
* euca-delete-volume
* euca-describe-volumes
* euca-run-instances
* euca-authorize
* euca-deregister
* euca-detach-volume
* euca-terminate-instances
* euca-bundle-image
* euca-describe-addresses
* euca-disassociate-address
* euca-unbundle
* euca-bundle-vol
* euca-describe-availability-zones
* euca-download-bundle
* euca-upload-bundle
* euca-confirm-product-instance
* euca-describe-groups
* euca-get-console-output
* euca-version
* euca-create-snapshot
* euca-describe-image-attribute
* euca-modify-image-attribute
* euca-create-volume
* euca-describe-images
* euca-reboot-instances

36
doc/source/runnova/flags.rst
View File

@ -1,36 +0,0 @@
..
Copyright 2010-2011 United States Government as represented by the
Administrator of the National Aeronautics and Space Administration.
All Rights Reserved.
Licensed under the Apache License, Version 2.0 (the "License"); you may
not use this file except in compliance with the License. You may obtain
a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations
under the License.
Flags and Flagfiles
===================
Nova uses a configuration file containing flags located in
``/etc/nova/nova.conf``. You can get the most recent listing of avaialble
flags by running ``nova-(servicename) --help``, for example:
::
nova-api --help
A script for generating a sample ``nova.conf`` file is located in
``<nova_root>/tools/conf/run.sh``. This script traverses through the
source code and retrieves information of every option that is
defined. A file named ``nova.conf.sample`` will be placed in the same
directory.
The OpenStack wiki has a page with the flags listed by their purpose
and use at http://wiki.openstack.org/FlagsGrouping.

96
doc/source/runnova/index.rst
View File

@ -1,96 +0,0 @@
..
Copyright 2010-2011 United States Government as represented by the
Administrator of the National Aeronautics and Space Administration.
All Rights Reserved.
Licensed under the Apache License, Version 2.0 (the "License"); you may
not use this file except in compliance with the License. You may obtain
a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations
under the License.
Running Nova
============
This guide describes the basics of running and managing Nova. This site is intended to provide developer documentation. For more administrator's documentation, refer to `docs.openstack.org <http://docs.openstack.org>`_.
Running the Cloud
-----------------
The fastest way to get a test cloud running is by following the directions in the :doc:`../quickstart`.
Nova's cloud works via the interaction of a series of daemon processes that reside persistently on the host machine(s). Fortunately, the :doc:`../quickstart` process launches sample versions of all these daemons for you. Once you are familiar with basic Nova usage, you can learn more about daemons by reading :doc:`../service.architecture` and :doc:`binaries`.
Administration Utilities
------------------------
There are two main tools that a system administrator will find useful to manage their Nova cloud:
.. toctree::
:maxdepth: 1
nova.manage
euca2ools
The nova-manage command may only be run by users with admin privileges. Commands for euca2ools can be used by all users, though specific commands may be restricted by Role Based Access Control. You can read more about creating and managing users in :doc:`managing.users`
User and Resource Management
----------------------------
The nova-manage and euca2ools commands provide the basic interface to perform a broad range of administration functions. In this section, you can read more about how to accomplish specific administration tasks.
For background on the core objects referenced in this section, see :doc:`../object.model`
.. toctree::
:maxdepth: 1
managing.users
managing.projects
managing.instances
managing.instance.types
managing.images
managing.networks
managingsecurity
.. managing.volumes
Deployment
----------
For a starting multi-node architecture, you would start with two nodes - a cloud controller node and a compute node. The cloud controller node contains the nova- services plus the Nova database. The compute node installs all the nova-services but then refers to the database installation, which is hosted by the cloud controller node. Ensure that the nova.conf file is identical on each node. If you find performance issues not related to database reads or writes, but due to the messaging queue backing up, you could add additional messaging services (rabbitmq). For instructions on multi-server installations, refer to `Installing and Configuring OpenStack Compute <http://docs.openstack.org/>`_.
.. toctree::
:maxdepth: 1
binaries
.. dbsync
Networking
^^^^^^^^^^
.. toctree::
:maxdepth: 1
network.vlan.rst
network.flat.rst
Advanced Topics
---------------
.. toctree::
:maxdepth: 1
flags
monitoring
vncconsole

26
doc/source/runnova/managing.images.rst
View File

@ -1,26 +0,0 @@
..
Copyright 2010-2011 United States Government as represented by the
Administrator of the National Aeronautics and Space Administration.
All Rights Reserved.
Licensed under the Apache License, Version 2.0 (the "License"); you may
not use this file except in compliance with the License. You may obtain
a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations
under the License.
Managing Images
===============
With Nova, you can manage images either using the built-in object store or using Glance, a related OpenStack project. Glance is a server that provides the following services:
* Ability to store and retrieve virtual machine images
* Ability to store and retrieve metadata about these virtual machine images
Refer to http://glance.openstack.org for additional details.

86
doc/source/runnova/managing.instance.types.rst
View File

@ -1,86 +0,0 @@
..
Copyright 2011 Ken Pepple
Licensed under the Apache License, Version 2.0 (the "License"); you may
not use this file except in compliance with the License. You may obtain
a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations
under the License.
Managing Instance Types and Flavors
===================================
You can manage instance types and instance flavors using the nova-manage command-line interface coupled with the instance_type subcommand for nova-manage.
What are Instance Types or Flavors ?
------------------------------------
Instance types describe the compute, memory and storage capacity of nova computing instances. In layman terms, this is the size (in terms of vCPUs, RAM, etc.) of the virtual server that you will be launching. In the EC2 API, these are called by names such as "m1.large" or "m1.tiny", while the OpenStack API terms these "flavors" with names like "512 MB Server".
In Nova, "flavor" and "instance type" are equivalent terms. When you create an EC2 instance type, you are also creating a OpenStack API flavor. To reduce repetition, for the rest of this document I will refer to these as instance types.
Instance types can be in either the active or inactive state:
* Active instance types are available to be used for launching instances
* Inactive instance types are not available for launching instances
In the current (Essex) version of nova, instance types can be created by the nova administrator through the nova-manage command, or the nova command (which uses the OpenStack API).
Basic Management
----------------
Instance types / flavor are managed through the nova-manage binary with
the "instance_type" command and an appropriate subcommand. Note that you can also use
the "flavor" command as a synonym for "instance_types".
To see all currently active instance types, use the list subcommand::
# nova-manage instance_type list
m1.medium: Memory: 4096MB, VCPUS: 2, Storage: 40GB, FlavorID: 3, Swap: 0GB, RXTX Quota: 0GB, RXTX Cap: 0MB
m1.large: Memory: 8192MB, VCPUS: 4, Storage: 80GB, FlavorID: 4, Swap: 0GB, RXTX Quota: 0GB, RXTX Cap: 0MB
m1.tiny: Memory: 512MB, VCPUS: 1, Storage: 0GB, FlavorID: 1, Swap: 0GB, RXTX Quota: 0GB, RXTX Cap: 0MB
m1.xlarge: Memory: 16384MB, VCPUS: 8, Storage: 160GB, FlavorID: 5, Swap: 0GB, RXTX Quota: 0GB, RXTX Cap: 0MB
m1.small: Memory: 2048MB, VCPUS: 1, Storage: 20GB, FlavorID: 2, Swap: 0GB, RXTX Quota: 0GB, RXTX Cap: 0MB
By default, the list subcommand only shows active instance types. To see all instance types (inactive and active), use the list subcommand with the "--all" flag::
# nova-manage instance_type list --all
m1.medium: Memory: 4096MB, VCPUS: 2, Storage: 40GB, FlavorID: 3, Swap: 0GB, RXTX Quota: 0GB, RXTX Cap: 0MB
m1.large: Memory: 8192MB, VCPUS: 4, Storage: 80GB, FlavorID: 4, Swap: 0GB, RXTX Quota: 0GB, RXTX Cap: 0MB
m1.tiny: Memory: 512MB, VCPUS: 1, Storage: 0GB, FlavorID: 1, Swap: 0GB, RXTX Quota: 0GB, RXTX Cap: 0MB
m1.xlarge: Memory: 16384MB, VCPUS: 8, Storage: 160GB, FlavorID: 5, Swap: 0GB, RXTX Quota: 0GB, RXTX Cap: 0MB
m1.small: Memory: 2048MB, VCPUS: 1, Storage: 20GB, FlavorID: 2, Swap: 0GB, RXTX Quota: 0GB, RXTX Cap: 0MB
m1.deleted: Memory: 2048MB, VCPUS: 1, Storage: 20GB, FlavorID: 2, Swap: 0GB, RXTX Quota: 0GB, RXTX Cap: 0MB, inactive
To create an instance type, use the "create" subcommand with the following positional arguments:
* memory (expressed in megabytes)
* vcpu(s) (integer)
* local storage (expressed in gigabytes)
* flavorid (unique integer)
* swap space (expressed in megabytes, defaults to zero, optional)
* RXTX quotas (expressed in gigabytes, defaults to zero, optional)
* RXTX cap (expressed in gigabytes, defaults to zero, optional)
The following example creates an instance type named "m1.xxlarge"::
# nova-manage instance_type create m1.xxlarge 32768 16 320 0 0 0
m1.xxlarge created
To delete an instance type, use the "delete" subcommand and specify the name::
# nova-manage instance_type delete m1.xxlarge
m1.xxlarge deleted
Please note that the "delete" command only marks the instance type as
inactive in the database; it does not actually remove the instance type. This is done
to preserve the instance type definition for long running instances (which may not
terminate for months or years). If you are sure that you want to delete this instance
type from the database, pass the "--purge" flag after the name::
# nova-manage instance_type delete m1.xxlarge --purge
m1.xxlarge purged

59
doc/source/runnova/managing.instances.rst
View File

@ -1,59 +0,0 @@
..
Copyright 2010-2011 United States Government as represented by the
Administrator of the National Aeronautics and Space Administration.
All Rights Reserved.
Licensed under the Apache License, Version 2.0 (the "License"); you may
not use this file except in compliance with the License. You may obtain
a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations
under the License.
Managing Instances
==================
Keypairs
--------
Images can be shared by many users, so it is dangerous to put passwords into the images. Nova therefore supports injecting ssh keys into instances before they are booted. This allows a user to login to the instances that he or she creates securely. Generally the first thing that a user does when using the system is create a keypair. Nova generates a public and private key pair, and sends the private key to the user. The public key is stored so that it can be injected into instances.
Keypairs are created through the api. They can be created on the command line using the euca2ools script euca-add-keypair. Refer to the man page for the available options. Example usage::
euca-add-keypair test > test.pem
chmod 600 test.pem
euca-run-instances -k test -t m1.tiny ami-tiny
# wait for boot
ssh -i test.pem root@ip.of.instance
Basic Management
----------------
Instance management can be accomplished with euca commands:
To run an instance:
::
euca-run-instances
To terminate an instance:
::
euca-terminate-instances
To reboot an instance:
::
euca-reboot-instances
See the euca2ools documentation for more information

92
doc/source/runnova/managing.networks.rst
View File

@ -1,92 +0,0 @@
..
Copyright 2010-2011 United States Government as represented by the
Administrator of the National Aeronautics and Space Administration.
Overview Sections Copyright 2010-2011 Citrix
All Rights Reserved.
Licensed under the Apache License, Version 2.0 (the "License"); you may
not use this file except in compliance with the License. You may obtain
a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations
under the License.
Networking Overview
===================
In Nova, users organize their cloud resources in projects. A Nova project consists of a number of VM instances created by a user. For each VM instance, Nova assigns to it a private IP address. (Currently, Nova only supports Linux bridge networking that allows the virtual interfaces to connect to the outside network through the physical interface. Other virtual network technologies, such as Open vSwitch, could be supported in the future.) The Network Controller provides virtual networks to enable compute servers to interact with each other and with the public network.
Nova Network Strategies
-----------------------
Currently, Nova supports three kinds of networks, implemented in three "Network Manager" types respectively: Flat Network Manager, Flat DHCP Network Manager, and VLAN Network Manager. The three kinds of networks can co-exist in a cloud system. However, the scheduler for selecting the type of network for a given project is not yet implemented. Here is a brief description of each of the different network strategies, with a focus on the VLAN Manager in a separate section.
Read more about Nova network strategies here:
.. toctree::
:maxdepth: 1
network.flat.rst
network.vlan.rst
Network Management Commands
---------------------------
.. todo::
Reformat command line app instructions for ``nova-manage`` using
``:command:``, ``:option:``, and ``.. program::``. (bug-947261)
Admins and Network Administrators can use the 'nova-manage' command to manage network resources:
VPN Management
~~~~~~~~~~~~~~
* vpn list: Print a listing of the VPNs for all projects.
* arguments: none
* vpn run: Start the VPN for a given project.
* arguments: project
* vpn spawn: Run all VPNs.
* arguments: none
Floating IP Management
~~~~~~~~~~~~~~~~~~~~~~
* floating create: Creates floating ips for host by range
* arguments: host ip_range
* floating delete: Deletes floating ips by range
* arguments: range
* floating list: Prints a listing of all floating ips
* arguments: none
Network Management
~~~~~~~~~~~~~~~~~~
* network create: Creates fixed ips for host by range
* arguments: [fixed_range=FLAG], [num_networks=FLAG],
[network_size=FLAG], [vlan_start=FLAG],
[vpn_start=FLAG]
* network modify: Associate/disassociate network with project and/or host.
* :option:`--fixed_range=\<IP range\>` - Specify the network to modify by
IP range. Required.
* :option:`--project=\<project name\>` - Project name to associate.
Optional.
* :option:`--host=\<host\>` - Host to associate. Optional.
* :option:`--disassociate-project` - Disassociate network from project.
Optional, mutually exclusive with :option:`--project`.
* :option:`--disassociate-host` - Disassociate host from project.
Optional, mutually exclusive with :option:`--host`.
* network delete: Deletes a network. Precisely one of :option:`--fixed_range`
or :option:`--uuid` must be specified.
* :option:`--fixed_range=\<IP range\>` - Specify the network by range.
* :option:`--uuid=\<UUID\>` - Specify the network by UUID.

77
doc/source/runnova/managing.projects.rst
View File

@ -1,77 +0,0 @@
..
Copyright 2010-2011 United States Government as represented by the
Administrator of the National Aeronautics and Space Administration.
All Rights Reserved.
Licensed under the Apache License, Version 2.0 (the "License"); you may
not use this file except in compliance with the License. You may obtain
a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations
under the License.
Managing Projects
=================
Projects are isolated resource containers forming the principal organizational structure within Nova. They consist of a separate vlan, volumes, instances, images, keys, and users.
Although the original ec2 api only supports users, nova adds the concept of projects. A user can specify which project he or she wishes to use by appending `:project_id` to his or her access key. If no project is specified in the api request, nova will attempt to use a project with the same id as the user.
The api will return NotAuthorized if a normal user attempts to make requests for a project that he or she is not a member of. Note that admins or users with special admin roles skip this check and can make requests for any project.
To create a project, use the `project create` command of nova-manage. The syntax is nova-manage project create projectname manager_id [description] You must specify a projectname and a manager_id. For example::
nova-manage project create john_project john "This is a sample project"
You can add and remove users from projects with `project add` and `project remove`::
nova-manage project add john_project john
nova-manage project remove john_project john
Project Commands
----------------
.. todo::
Reformat command line app instructions for ``nova-manage`` using
``:command:``, ``:option:``, and ``.. program::``. (bug-947261)
Admins and Project Managers can use the 'nova-manage project' command to manage project resources:
* project add: Adds user to project
* arguments: project user
* project create: Creates a new project
* arguments: name project_manager [description]
* project delete: Deletes an existing project
* arguments: project_id
* project environment: Exports environment variables to an sourcable file
* arguments: project_id user_id [filename='novarc]
* project list: lists all projects
* arguments: none
* project remove: Removes user from project
* arguments: project user
* project scrub: Deletes data associated with project
* arguments: project
* project zipfile: Exports credentials for project to a zip file
* arguments: project_id user_id [filename='nova.zip]
Setting Quotas
--------------
Nova utilizes a quota system at the project level to control resource consumption across available hardware resources. Current quota controls are available to limit the:
* Number of volumes which may be created
* Total size of all volumes within a project as measured in GB
* Number of instances which may be launched
* Number of processor cores which may be allocated
* Publicly accessible IP addresses
Use the following command to set quotas for a project
* project quota: Set or display quotas for project
* arguments: project_id [key] [value]

82
doc/source/runnova/managing.users.rst
View File

@ -1,82 +0,0 @@
Managing Users
==============
Users and Access Keys
---------------------
Access to the ec2 api is controlled by an access and secret key. The user's access key needs to be included in the request, and the request must be signed with the secret key. Upon receipt of api requests, nova will verify the signature and execute commands on behalf of the user.
In order to begin using nova, you will need a to create a user. This can be easily accomplished using the user create or user admin commands in nova-manage. `user create` will create a regular user, whereas `user admin` will create an admin user. The syntax of the command is nova-manage user create username [access] [secret]. For example::
nova-manage user create john my-access-key a-super-secret-key
If you do not specify an access or secret key, a random uuid will be created automatically.
Credentials
-----------
Nova can generate a handy set of credentials for a user. These credentials include a CA for bundling images and a file for setting environment variables to be used by euca2ools. If you don't need to bundle images, just the environment script is required. You can export one with the `project environment` command. The syntax of the command is nova-manage project environment project_id user_id [filename]. If you don't specify a filename, it will be exported as novarc. After generating the file, you can simply source it in bash to add the variables to your environment::
nova-manage project environment john_project john
. novarc
If you do need to bundle images, you will need to get all of the credentials using `project zipfile`. Note that zipfile will give you an error message if networks haven't been created yet. Otherwise zipfile has the same syntax as environment, only the default file name is nova.zip. Example usage::
nova-manage project zipfile john_project john
unzip nova.zip
. novarc
Role Based Access Control
-------------------------
Roles control the api actions that a user is allowed to perform. For example, a user cannot allocate a public ip without the `netadmin` role. It is important to remember that a users de facto permissions in a project is the intersection of user (global) roles and project (local) roles. So for john to have netadmin permissions in his project, he needs to separate roles specified. You can add roles with `role add`. The syntax is nova-manage role add user_id role [project_id]. Let's give john the netadmin role for his project::
nova-manage role add john netadmin
nova-manage role add john netadmin john_project
Role-based access control (RBAC) is an approach to restricting system access to authorized users based on an individual’s role within an organization. Various employee functions require certain levels of system access in order to be successful. These functions are mapped to defined roles and individuals are categorized accordingly. Since users are not assigned permissions directly, but only acquire them through their role (or roles), management of individual user rights becomes a matter of assigning appropriate roles to the user. This simplifies common operations, such as adding a user, or changing a user's department.
Nova’s rights management system employs the RBAC model and currently supports the following five roles:
* **Cloud Administrator.** (cloudadmin) Users of this class enjoy complete system access.
* **IT Security.** (itsec) This role is limited to IT security personnel. It permits role holders to quarantine instances.
* **System Administrator.** (sysadmin) The default for project owners, this role affords users the ability to add other users to a project, interact with project images, and launch and terminate instances.
* **Network Administrator.** (netadmin) Users with this role are permitted to allocate and assign publicly accessible IP addresses as well as create and modify firewall rules.
* **Developer.** (developer) This is a general purpose role that is assigned to users by default.
RBAC management is exposed through the dashboard for simplified user management.
User Commands
~~~~~~~~~~~~~
Users, including admins, are created through the ``user`` commands.
* user admin: creates a new admin and prints exports
* arguments: name [access] [secret]
* user create: creates a new user and prints exports
* arguments: name [access] [secret]
* user delete: deletes an existing user
* arguments: name
* user exports: prints access and secrets for user in export format
* arguments: name
* user list: lists all users
* arguments: none
* user modify: update a users keys & admin flag
* arguments: accesskey secretkey admin
* leave any field blank to ignore it, admin should be 'T', 'F', or blank
User Role Management
~~~~~~~~~~~~~~~~~~~~
* role add: adds role to user
* if project is specified, adds project specific role
* arguments: user, role [project]
* role has: checks to see if user has role
* if project is specified, returns True if user has
the global role and the project role
* arguments: user, role [project]
* role remove: removes role from user
* if project is specified, removes project specific role
* arguments: user, role [project]

37
doc/source/runnova/managingsecurity.rst
View File

@ -1,37 +0,0 @@
..
Copyright 2010-2011 United States Government as represented by the
Administrator of the National Aeronautics and Space Administration.
All Rights Reserved.
Licensed under the Apache License, Version 2.0 (the "License"); you may
not use this file except in compliance with the License. You may obtain
a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations
under the License.
Security Considerations
=======================
The goal of securing a cloud computing system involves both protecting the instances, data on the instances, and
ensuring users are authenticated for actions and that borders are understood by the users and the system.
Protecting the system from intrusion or attack involves authentication, network protections, and
compromise detection.
Key Concepts
------------
Authentication - Each instance is authenticated with a key pair.
Network - Instances can communicate with each other but you can configure the boundaries through firewall
configuration.
Monitoring - Log all API commands and audit those logs.
Encryption - Data transfer between instances is not encrypted.

27
doc/source/runnova/monitoring.rst
View File

@ -1,27 +0,0 @@
..
Copyright 2010-2011 United States Government as represented by the
Administrator of the National Aeronautics and Space Administration.
All Rights Reserved.
Licensed under the Apache License, Version 2.0 (the "License"); you may
not use this file except in compliance with the License. You may obtain
a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations
under the License.
Monitoring
==========
* components
* throughput
* exceptions
* hardware
* ganglia
* syslog

60
doc/source/runnova/network.flat.rst
View File

@ -1,60 +0,0 @@
..
Copyright 2010-2011 United States Government as represented by the
Administrator of the National Aeronautics and Space Administration.
All Rights Reserved.
Licensed under the Apache License, Version 2.0 (the "License"); you may
not use this file except in compliance with the License. You may obtain
a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations
under the License.
Flat Network Mode (Original and Flat)
=====================================
Flat network mode removes most of the complexity of VLAN mode by simply
bridging all instance interfaces onto a single network.
There are two variations of flat mode that differ mostly in how IP addresses
are given to instances.
Original Flat Mode
------------------
IP addresses for VM instances are grabbed from a subnet specified by the network administrator, and injected into the image on launch. All instances of the system are attached to the same Linux networking bridge, configured manually by the network administrator both on the network controller hosting the network and on the computer controllers hosting the instances. To recap:
* Each compute host creates a single bridge for all instances to use to attach to the external network.
* The networking configuration is injected into the instance before it is booted or it is obtained by a guest agent installed in the instance.
Note that the configuration injection currently only works on linux-style systems that keep networking
configuration in /etc/network/interfaces.
Flat DHCP Mode
--------------
IP addresses for VM instances are grabbed from a subnet specified by the network administrator. Similar to the flat network, a single Linux networking bridge is created and configured manually by the network administrator and used for all instances. A DHCP server is started to pass out IP addresses to VM instances from the specified subnet. To recap:
* Like flat mode, all instances are attached to a single bridge on the compute node.
* In addition a DHCP server is running to configure instances.
Implementation
--------------
The network nodes do not act as a default gateway in flat mode. Instances
are given public IP addresses.
Compute nodes have iptables/ebtables entries created per project and
instance to protect against IP/MAC address spoofing and ARP poisoning.
Examples
--------
.. todo:: add flat network mode configuration examples

176
doc/source/runnova/network.vlan.rst
View File

@ -1,176 +0,0 @@
..
Copyright 2010-2011 United States Government as represented by the
Administrator of the National Aeronautics and Space Administration.
All Rights Reserved.
Licensed under the Apache License, Version 2.0 (the "License"); you may
not use this file except in compliance with the License. You may obtain
a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations
under the License.
VLAN Network Mode
=================
VLAN Network Mode is the default mode for Nova. It provides a private network
segment for each project's instances that can be accessed via a dedicated
VPN connection from the Internet.
In this mode, each project gets its own VLAN, Linux networking bridge, and subnet. The subnets are specified by the network administrator, and are assigned dynamically to a project when required. A DHCP Server is started for each VLAN to pass out IP addresses to VM instances from the subnet assigned to the project. All instances belonging to one project are bridged into the same VLAN for that project. The Linux networking bridges and VLANs are created by Nova when required, described in more detail in Nova VLAN Network Management Implementation.
..
(this text revised above)
Because the flat network and flat DhCP network are simple to understand and yet do not scale well enough for real-world cloud systems, this section focuses on the VLAN network implementation by the VLAN Network Manager.
In the VLAN network mode, all the VM instances of a project are connected together in a VLAN with the specified private subnet. Each running VM instance is assigned an IP address within the given private subnet.
.. image:: /images/Novadiagram.png
:width: 790
While network traffic between VM instances belonging to the same VLAN is always open, Nova can enforce isolation of network traffic between different projects by enforcing one VLAN per project.
In addition, the network administrator can specify a pool of public IP addresses that users may allocate and then assign to VMs, either at boot or dynamically at run-time. This capability is similar to Amazon's 'elastic IPs'. A public IP address may be associated with a running instances, allowing the VM instance to be accessed from the public network. The public IP addresses are accessible from the network host and NATed to the private IP address of the project. A public IP address could be associated with a project using the euca-allocate-address commands.
This is the default networking mode and supports the most features. For multiple machine installation, it requires a switch that supports host-managed vlan tagging. In this mode, nova will create a vlan and bridge for each project. The project gets a range of private ips that are only accessible from inside the vlan. In order for a user to access the instances in their project, a special vpn instance (code named :ref:`cloudpipe <cloudpipe>`) needs to be created. Nova generates a certificate and key for the user to access the vpn and starts the vpn automatically. More information on cloudpipe can be found :ref:`here <cloudpipe>`.
The following diagram illustrates how the communication that occurs between the vlan (the dashed box) and the public internet (represented by the two clouds)
.. image:: /images/cloudpipe.png
:width: 100%
Goals
-----
For our implementation of Nova, our goal is that each project is in a protected network segment. Here are the specifications we keep in mind for meeting this goal.
* RFC-1918 IP space
* public IP via NAT
* no default inbound Internet access without public NAT
* limited (project-admin controllable) outbound Internet access
* limited (project-admin controllable) access to other project segments
* all connectivity to instance and cloud API is via VPN into the project segment
We also keep as a goal a common DMZ segment for support services, meaning these items are only visible from project segment:
* metadata
* dashboard
Limitations
-----------
We kept in mind some of these limitations:
* Projects / cluster limited to available VLANs in switching infrastructure
* Requires VPN for access to project segment
Implementation
--------------
Currently Nova segregates project VLANs using 802.1q VLAN tagging in the
switching layer. Compute hosts create VLAN-specific interfaces and bridges
as required.
The network nodes act as default gateway for project networks and contain
all of the routing and firewall rules implementing security groups. The
network node also handles DHCP to provide instance IPs for each project.
VPN access is provided by running a small instance called CloudPipe
on the IP immediately following the gateway IP for each project. The
network node maps a dedicated public IP/port to the CloudPipe instance.
Compute nodes have per-VLAN interfaces and bridges created as required.
These do NOT have IP addresses in the host to protect host access.
Compute nodes have iptables/ebtables entries created per project and
instance to protect against IP/MAC address spoofing and ARP poisoning.
The network assignment to a project, and IP address assignment to a VM instance, are triggered when a user starts to run a VM instance. When running a VM instance, a user needs to specify a project for the instances, and the security groups (described in Security Groups) when the instance wants to join. If this is the first instance to be created for the project, then Nova (the cloud controller) needs to find a network controller to be the network host for the project; it then sets up a private network by finding an unused VLAN id, an unused subnet, and then the controller assigns them to the project, it also assigns a name to the project's Linux bridge (br100 stored in the Nova database), and allocating a private IP within the project's subnet for the new instance.
If the instance the user wants to start is not the project's first, a subnet and a VLAN must have already been assigned to the project; therefore the system needs only to find an available IP address within the subnet and assign it to the new starting instance. If there is no private IP available within the subnet, an exception will be raised to the cloud controller, and the VM creation cannot proceed.
External Infrastructure
-----------------------
Nova assumes the following is available:
* DNS
* NTP
* Internet connectivity
Example
-------
This example network configuration demonstrates most of the capabilities
of VLAN Mode. It splits administrative access to the nodes onto a dedicated
management network and uses dedicated network nodes to handle all
routing and gateway functions.
It uses a 10GB network for instance traffic and a 1GB network for management.
Hardware
~~~~~~~~
* All nodes have a minimum of two NICs for management and production.
* management is 1GB
* production is 10GB
* add additional NICs for bonding or HA/performance
* network nodes should have an additional NIC dedicated to public Internet traffic
* switch needs to support enough simultaneous VLANs for number of projects
* production network configured as 802.1q trunk on switch
Operation
~~~~~~~~~
The network node controls the project network configuration:
* assigns each project a VLAN and private IP range
* starts dnsmasq on project VLAN to serve private IP range
* configures iptables on network node for default project access
* launches CloudPipe instance and configures iptables access
When starting an instance the network node:
* sets up a VLAN interface and bridge on each host as required when an
instance is started on that host
* assigns private IP to instance
* generates MAC address for instance
* update dnsmasq with IP/MAC for instance
When starting an instance the compute node:
* sets up a VLAN interface and bridge on each host as required when an
instance is started on that host
Setup
~~~~~
* Assign VLANs in the switch:
* public Internet segment
* production network
* management network
* cluster DMZ
* Assign a contiguous range of VLANs to Nova for project use.
* Configure management NIC ports as management VLAN access ports.
* Configure management VLAN with Internet access as required
* Configure production NIC ports as 802.1q trunk ports.
* Configure Nova (need to add specifics here)
* public IPs
* instance IPs
* project network size
* DMZ network

263
doc/source/runnova/nova.manage.rst
View File

@ -1,263 +0,0 @@
..
Copyright 2010-2011 United States Government as represented by the
Administrator of the National Aeronautics and Space Administration.
All Rights Reserved.
Licensed under the Apache License, Version 2.0 (the "License"); you may
not use this file except in compliance with the License. You may obtain
a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations
under the License.
The nova-manage command
=======================
Introduction
~~~~~~~~~~~~
The nova-manage command is used to perform many essential functions for
administration and ongoing maintenance of nova, such as user creation,
vpn management, and much more.
The standard pattern for executing a nova-manage command is:
``nova-manage <category> <command> [<args>]``
For example, to obtain a list of all projects:
``nova-manage project list``
Run without arguments to see a list of available command categories:
``nova-manage``
Categories are user, project, role, shell, vpn, and floating. Detailed descriptions are below.
You can also run with a category argument such as user to see a list of all commands in that category:
``nova-manage user``
These sections describe the available categories and arguments for nova-manage.
Nova Db
~~~~~~~
``nova-manage db version``
Print the current database version.
``nova-manage db sync``
Sync the database up to the most recent version. This is the standard way to create the db as well.
Nova User
~~~~~~~~~
``nova-manage user admin <username>``
Create an admin user with the name <username>.
``nova-manage user create <username>``
Create a normal user with the name <username>.
``nova-manage user delete <username>``
Delete the user with the name <username>.
``nova-manage user exports <username>``
Outputs a list of access key and secret keys for user to the screen
``nova-manage user list``
Outputs a list of all the user names to the screen.
``nova-manage user modify <accesskey> <secretkey> <admin?T/F>``
Updates the indicated user keys, indicating with T or F if the user is an admin user. Leave any argument blank if you do not want to update it.
Nova Project
~~~~~~~~~~~~
``nova-manage project add <projectname> <username>``
Add a nova project with the name <projectname> to the database that will be administered by the named user.
``nova-manage project create <projectname> <projectmanager>``
Create a new nova project with the name <projectname> (you still need to do nova-manage project add <projectname> to add it to the database). The <projectmanager> username is the administrator of the project.
``nova-manage project delete <projectname>``
Delete a nova project with the name <projectname>.
``nova-manage project environment <projectname> <username>``
Exports environment variables for the named project to a file named novarc.
``nova-manage project list``
Outputs a list of all the projects to the screen.
``nova-manage project quota <projectname>``
Outputs the size and specs of the project's instances including gigabytes, instances, floating IPs, volumes, and cores.
``nova-manage project remove <projectname>``
Deletes the project with the name <projectname>.
``nova-manage project zipfile <projectname> <username> <directory for credentials>``
Compresses all related files for a created project into a named zip file such as nova.zip.
Nova Role
~~~~~~~~~
nova-manage role <action> [<argument>]
``nova-manage role add <username> <rolename> <(optional) projectname>``
Add a user to either a global or project-based role with the indicated <rolename> assigned to the named user. Role names can be one of the following five roles: admin, itsec, projectmanager, netadmin, developer. If you add the project name as the last argument then the role is assigned just for that project, otherwise the user is assigned the named role for all projects.
``nova-manage role has <username> <projectname>``
Checks the user or project and responds with True if the user has a global role with a particular project.
``nova-manage role remove <username> <rolename>``
Remove the indicated role from the user.
Nova Shell
~~~~~~~~~~
``nova-manage shell bpython``
Starts a new bpython shell.
``nova-manage shell ipython``
Starts a new ipython shell.
``nova-manage shell python``
Starts a new python shell.
``nova-manage shell run``
Starts a new shell using python.
``nova-manage shell script <path/scriptname>``
Runs the named script from the specified path with flags set.
Nova VPN
~~~~~~~~
``nova-manage vpn list``
Displays a list of projects, their IP prot numbers, and what state they're in.
``nova-manage vpn run <projectname>``
Starts the VPN for the named project.
``nova-manage vpn spawn``
Runs all VPNs.
Nova Floating IPs
~~~~~~~~~~~~~~~~~
``nova-manage floating create <ip_range> [--pool <pool>] [--interface <interface>]``
Creates floating IP addresses for the given range, optionally specifying
a floating pool and a network interface.
``nova-manage floating delete <ip_range>``
Deletes floating IP addresses in the range given.
``nova-manage floating list``
Displays a list of all floating IP addresses.
Nova Images
~~~~~~~~~~~
``nova-manage image image_register <path> <owner>``
Registers an image with the image service.
``nova-manage image kernel_register <path> <owner>``
Registers a kernel with the image service.
``nova-manage image ramdisk_register <path> <owner>``
Registers a ramdisk with the image service.
``nova-manage image all_register <image_path> <kernel_path> <ramdisk_path> <owner>``
Registers an image kernel and ramdisk with the image service.
``nova-manage image convert <directory>``
Converts all images in directory from the old (Bexar) format to the new format.
Concept: Flags
--------------
python-gflags
Concept: Plugins
----------------
* Managers/Drivers: utils.import_object from string flag
* virt/connections: conditional loading from string flag
* db: LazyPluggable via string flag
* auth_manager: utils.import_class based on string flag
* Volumes: moving to pluggable driver instead of manager
* Network: pluggable managers
* Compute: same driver used, but pluggable at connection
Concept: IPC/RPC
----------------
Rabbit is the main messaging queue, used for all communication between Nova components and it also does the remote procedure calls and inter-process communication.
Concept: Fakes
--------------
* auth
* ldap
Concept: Scheduler
------------------
* simple
* random
Concept: Security Groups
------------------------
Security groups
Concept: Certificate Authority
------------------------------
Nova does a small amount of certificate management. These certificates are used for :ref:`project vpns <cloudpipe>` and decrypting bundled images.
Concept: Images
---------------
* launching
* bundling

271
doc/source/runnova/vncconsole.rst
View File

@ -1,271 +0,0 @@
..
Copyright 2010-2011 United States Government as represented by the
Administrator of the National Aeronautics and Space Administration.
All Rights Reserved.
Licensed under the Apache License, Version 2.0 (the "License"); you may
not use this file except in compliance with the License. You may obtain
a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations
under the License.
FAQ
===
Q: What has changed since diablo?
A: Previously, vnc support was done differently for libvirt and xen.
Now, there is unified multi-hypervisor support. To support this change,
configuration options have been added and changed. Also,
a new required service called nova-consoleauth has been added. If you
are upgrading from diablo, you will have to take these changes into
consideration when upgrading.
If you are using diablo, please see the documentation that shipped with
your code, as this information will not be relevant.
Q: What happened to diablo's nova-vncproxy?
A: nova-vncproxy was removed from the nova source tree. The essex analog for
this process is nova-novncproxy, which is provided by an external project.
Q: Why is nova-vncproxy no longer part of nova?
A: In diablo, we shipped a websocket proxy (nova-vncproxy) with nova, but
it had poor browser support. This nova-vncproxy code was dependent on external
noVNC code, so changes to that system involved updating 2 projects.
Due to the rapid evolution of websocket tech, and the tight dependence of
the websocket proxy on javscript and html components, we decided to keep that
code all in one place.
Q: What is the difference between nova-xvpvncproxy and nova-novncproxy?
A: nova-xvpvncproxy, which ships with nova, is a new proxy that supports
a simple java client. nova-novncproxy uses noVNC to provide vnc support
through a web browser.
Q: I want VNC support in horizon. What services do I need?
A: You need nova-novncproxy, nova-consoleauth, and correctly configured
compute hosts.
Q: When I use "nova get-vnc-console" or click on the vnc tab of Horizon,
it hangs. Why?
A: Make sure you are running nova-consoleauth (In addition to nova-novncproxy).
The proxies rely on nova-consoleauth to validate tokens, and will wait for
a reply it them until a timeout is reached.
Q: My vnc proxy worked fine during my All-In-One test, but now it doesn't work
on multi host. Why?
A: The default flag values work for an All-In-One install, but changes must
be made on your compute hosts once you start to build a cluster. As an
example, suppose you have 2 servers::
PROXYSERVER (public_ip=172.24.1.1, management_ip=192.168.1.1)
COMPUTESERVER (management_ip=192.168.1.2)
Your nova-compute configuration file would need the following values::
# These flags help construct a connection data structure
vncserver_proxyclient_address=192.168.1.2
novncproxy_base_url=http://172.24.1.1:6080/vnc_auto.html
xvpvncproxy_base_url=http://172.24.1.1:6081/console
# This is the address where the underlying vncserver (not the proxy)
# will listen for connections.
vncserver_listen=192.168.1.2
Note that novncproxy_base_url and novncproxy_base_url use a public ip; this
is the url that is ultimately returned to clients, who generally will not
have access to your private network. Your PROXYSERVER must be able to reach
vncserver_proxyclient_address, as that is the address over which the vnc
connection will be proxied.
See "Important nova-compute Options" for more information.
Q: My noVNC does not work with recent versions of web browsers. Why?
A: Make sure you have python-numpy installed, which is required to support
a newer version of the WebSocket protocol (HyBi-07+). Also, if you are
using diablo's nova-vncproxy, note that support for this protocol is not
provided.
Overview
========
The VNC Proxy is an OpenStack component that allows users of Nova to access
their instances through vnc clients. In essex and beyond, there is support
for for both libvirt and XenServer using both java and websocket cleints.
The VNC console Connection works as follows:
* User connects to api and gets an access_url like http://ip:port/?token=xyz
* User pastes url in browser or as client parameter
* Browser/Client connects to proxy
* Proxy talks to nova-consoleauth to authorize the user's token,
and then maps the token to the -private- host and port
of an instance's VNC server. The compute host specifies the what address
the proxy should use to connect via the flag --vncserver_proxyclient_address.
In this way, the vnc proxy works as a bridge between the public network,
and the private host network.
* Proxy initiates connection to VNC server, and continues proxying until
the session ends
Note that in general, the vnc proxy performs multiple functions:
* Bridges between public network (where clients live) and private network
(where vncservers live)
* Mediates token authentication
* Transparently deals with hypervisor-specific connection details to provide
a uniform client experience.
About nova-consoleauth
----------------------
Both client proxies leverage a shared service to manage token auth called
nova-consoleauth. This service must be running in order for for either proxy
to work. Many proxies of either type can be run against a single
nova-consoleauth service in a cluster configuration.
nova-consoleauth should not be confused with nova-console, which is a xen-specific
service that is not used by the most recent vnc proxy architecture.
Typical Deployment
==================
A typical deployment will consist of the following components:
* One nova-consoleauth process. Typically this runs on the controller host.
* One or more nova-novncproxy services. This supports browser-based novnc
clients.
For simple deployments, this service typically will run on the same machine
as nova-api, since it proxies between the public network and the private
compute host network.
* One or more nova-xvpvncproxy services. This supports the special java client
discussed in this document.
For simple deployments, this service typically will run on the same machine
as nova-api, since it proxies between the public network and the private
compute host network.
* One or more compute hosts. These compute hosts must have correctly
configured flags, as described below.
Getting an Access Url
---------------------
Nova provides the ability to create access_urls through the os-consoles extension.
Support for accessing this url is provided by novaclient:
::
nova get-vnc-console [server_id] [novnc|xvpvnc]
Specify 'novnc' to retrieve a url suitable for pasting into a web browser. Specify
'xvpvnc' for a url suitable for pasting into the java client.
So to request a web browser url:
::
nova get-vnc-console [server_id] novnc
Important nova-compute Options
------------------------------
To enable vncproxy in your cloud, in addition to to running one or both of the
proxies and nova-consoleauth, you need to configure the following flags on your
compute hosts.
* :option:`--[no]vnc_enabled` - defaults to enabled. If this flag is
disabled your instances will launch without vnc support.
* :option:`--vncserver_listen` - defaults to 127.0.0.1
This is the address that vncservers will bind, and should be overridden in
production deployments as a private address. Applies to libvirt only.
For multi-host libvirt deployments this should be set to a host
management ip on the same network as the proxies.
* :option:`--vncserver_proxyclient_address` - defaults to 127.0.0.1
This is the address of the compute host that nova will instruct
proxies to use when connecting to instance vncservers.
For all-in-one xen server domU deployments this can be set to 169.254.0.1.
For multi-host xen server domU deployments this can be set to a dom0
management ip on the same network as the proxies.
For multi-host libvirt deployments this can be set to a host
management ip on the same network as the proxies.
* :option:`--novncproxy_base_url=[base url for client connections]` -
this is the public base url to which clients will connect. "?token=abc"
will be added to this url for the purposes of auth.
When using the system as described in this document, an appropriate value is
"http://$SERVICE_HOST:6080/vnc_auto.html" where SERVICE_HOST is a public
hostname.
* :option:`--xvpvncproxy_base_url=[base url for client connections]` -
this is the public base url to which clients will connect. "?token=abc"
will be added to this url for the purposes of auth.
When using the system as described in this document, an appropriate value is
"http://$SERVICE_HOST:6081/console" where SERVICE_HOST is a public hostname.
Accessing VNC Consoles with a Java client
-----------------------------------------
To enable support for the OpenStack java vnc client in nova, nova provides the
nova-xvpvncproxy service, which you should run to enable this feature.
* :option:`--xvpvncproxy_port=[port]` - port to bind (defaults to 6081)
* :option:`--xvpvncproxy_host=[host]` - host to bind (defaults to 0.0.0.0)
As a client, you will need a special Java client, which is
a version of TightVNC slightly modified to support our token auth:
::
git clone https://github.com/cloudbuilders/nova-xvpvncviewer
cd nova-xvpvncviewer
make
Then, to create a session, first request an access url using python-novaclient
and then run the client like so:
::
# Retrieve access url
nova get-vnc-console [server_id] xvpvnc
# Run client
java -jar VncViewer.jar [access_url]
nova-vncproxy replaced with nova-novncproxy
-------------------------------------------
The previous vnc proxy, nova-vncproxy, has been removed from the nova source
tree and replaced with an improved server that can be found externally at
http://github.com/cloudbuilders/noVNC.git
To use this nova-novncproxy:
::
git clone http://github.com/cloudbuilders/noVNC.git
utils/nova-novncproxy --flagfile=[path to flagfile]
The --flagfile param should point to your nova config that includes the rabbit
server address and credentials.
By default, nova-novncproxy binds 0.0.0.0:6080. This can be configured with:
* :option:`--novncproxy_port=[port]`
* :option:`--novncproxy_host=[host]`
Accessing a vnc console through a web browser
---------------------------------------------
Retrieving an access_url for a web browser is similar to the flow for
the java client:
::
# Retrieve access url
nova get-vnc-console [server_id] novnc
# Then, paste the url into your web browser
Additionally, you can use horizon to access browser-based vnc consoles for
instances.
.. todo::
Reformat command line app instructions for commands using
``:command:``, ``:option:``, and ``.. program::``. (bug-947261)

77
doc/source/service.architecture.rst
View File

@ -1,77 +0,0 @@
..
Copyright 2010-2011 OpenStack LLC
All Rights Reserved.
Licensed under the Apache License, Version 2.0 (the "License"); you may
not use this file except in compliance with the License. You may obtain
a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations
under the License.
Service Architecture
====================
Nova’s Cloud Fabric is composed of the following major components:
* API Server
* Message Queue
* Compute Worker
* Network Controller
* Volume Worker
* Scheduler
* Image Store
.. image:: /images/fabric.png
:width: 790
API Server
--------------------------------------------------
At the heart of the cloud framework is an API Server. This API Server makes command and control of the hypervisor, storage, and networking programmatically available to users in realization of the definition of cloud computing.
The API endpoints are basic http web services which handle authentication, authorization, and basic command and control functions using various API interfaces under the Amazon, Rackspace, and related models. This enables API compatibility with multiple existing tool sets created for interaction with offerings from other vendors. This broad compatibility prevents vendor lock-in.
Message Queue
--------------------------------------------------
A messaging queue brokers the interaction between compute nodes (processing), volumes (block storage), the networking controllers (software which controls network infrastructure), API endpoints, the scheduler (determines which physical hardware to allocate to a virtual resource), and similar components. Communication to and from the cloud controller is by HTTP requests through multiple API endpoints.
A typical message passing event begins with the API server receiving a request from a user. The API server authenticates the user and ensures that the user is permitted to issue the subject command. Availability of objects implicated in the request is evaluated and, if available, the request is routed to the queuing engine for the relevant workers. Workers continually listen to the queue based on their role, and occasionally their type hostname. When such listening produces a work request, the worker takes assignment of the task and begins its execution. Upon completion, a response is dispatched to the queue which is received by the API server and relayed to the originating user. Database entries are queried, added, or removed as necessary throughout the process.
Compute Worker
--------------------------------------------------
Compute workers manage computing instances on host machines. Through the API, commands are dispatched to compute workers to:
* Run instances
* Terminate instances
* Reboot instances
* Attach volumes
* Detach volumes
* Get console output
Network Controller
--------------------------------------------------
The Network Controller manages the networking resources on host machines. The API server dispatches commands through the message queue, which are subsequently processed by Network Controllers. Specific operations include:
* Allocate Fixed IP Addresses
* Configuring VLANs for projects
* Configuring networks for compute nodes
Volume Workers
--------------------------------------------------
Volume Workers interact with iSCSI storage to manage LVM-based instance volumes. Specific functions include:
* Create Volumes
* Delete Volumes
* Establish Compute volumes
Volumes may easily be transferred between instances, but may be attached to only a single instance at a time.
.. todo:: P2: image store description

226
doc/source/vmwareapi_readme.rst
View File

@ -1,226 +0,0 @@
..
Copyright (c) 2010 Citrix Systems, Inc.
Copyright 2010 OpenStack LLC.
Licensed under the Apache License, Version 2.0 (the "License"); you may
not use this file except in compliance with the License. You may obtain
a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations
under the License.
VMware ESX/ESXi Server Support for OpenStack Compute
====================================================
Introduction
------------
A module named 'vmwareapi' is added to 'nova.virt' to add support of VMware ESX/ESXi hypervisor to OpenStack compute (Nova). Nova may now use VMware vSphere as a compute provider.
The basic requirement is to support VMware vSphere 4.1 as a compute provider within Nova. As the deployment architecture, support both ESX and ESXi. VM storage is restricted to VMFS volumes on local drives. vCenter is not required by the current design, and is not currently supported. Instead, Nova Compute talks directly to ESX/ESXi.
The 'vmwareapi' module is integrated with Glance, so that VM images can be streamed from there for boot on ESXi using Glance server for image storage & retrieval.
Currently supports Nova's flat networking model (Flat Manager) & VLAN networking model.
.. image:: images/vmwareapi_blockdiagram.jpg
System Requirements
-------------------
Following software components are required for building the cloud using OpenStack on top of ESX/ESXi Server(s):
* OpenStack
* Glance Image service
* VMware ESX v4.1 or VMware ESXi(licensed) v4.1
VMware ESX Requirements
-----------------------
* ESX credentials with administration/root privileges
* Single local hard disk at the ESX host
* An ESX Virtual Machine Port Group (For Flat Networking)
* An ESX physical network adapter (For VLAN networking)
* Need to enable "vSphere Web Access" in "vSphere client" UI at Configuration->Security Profile->Firewall
Python dependencies
-------------------
* suds-0.4
* Installation procedure on Ubuntu/Debian
::
easy_install suds==0.4
Configuration flags required for nova-compute
---------------------------------------------
::
--connection_type=vmwareapi
--vmwareapi_host_ip=<VMware ESX Host IP>
--vmwareapi_host_username=<VMware ESX Username>
--vmwareapi_host_password=<VMware ESX Password>
--vmwareapi_vlan_interface=<Physical ethernet adapter name in VMware ESX host for vlan networking E.g vmnic0> [Optional, only for VLAN Networking]
Configuration flags required for nova-network
---------------------------------------------
::
--network_manager=nova.network.manager.FlatManager [or nova.network.manager.VlanManager]
--flat_network_bridge=<ESX Virtual Machine Port Group> [Optional, only for Flat Networking]
Configuration flags required for nova-console
---------------------------------------------
::
--console_manager=nova.console.vmrc_manager.ConsoleVMRCManager
--console_driver=nova.console.vmrc.VMRCSessionConsole [Optional, only for OTP (One time Passwords) as against host credentials]
Other flags
-----------
::
--image_service=nova.image.glance.GlanceImageService
--glance_host=<Glance Host>
--vmwareapi_wsdl_loc=<http://<WEB SERVER>/vimService.wsdl>
Note:- Due to a faulty wsdl being shipped with ESX vSphere 4.1 we need a working wsdl which can to be mounted on any webserver. Follow the below steps to download the SDK,
* Go to http://www.vmware.com/support/developer/vc-sdk/
* Go to section VMware vSphere Web Services SDK 4.0
* Click "Downloads"
* Enter VMware credentials when prompted for download
* Unzip the downloaded file vi-sdk-4.0.0-xxx.zip
* Go to SDK->WSDL->vim25 & host the files "vimService.wsdl" and "vim.wsdl" in a WEB SERVER
* Set the flag "--vmwareapi_wsdl_loc" with url, "http://<WEB SERVER>/vimService.wsdl"
Debug flag
----------
.. note::
suds logging is very verbose and turned off by default. If you need to
debug the VMware API calls, change the default_log_levels flag appropriately.
VLAN Network Manager
--------------------
VLAN network support is added through a custom network driver in the nova-compute node i.e "nova.network.vmwareapi_net" and it uses a Physical ethernet adapter on the VMware ESX/ESXi host for VLAN Networking (the name of the ethernet adapter is specified as vlan_interface flag in the nova-compute configuration flag) in the nova-compute node.
Using the physical adapter name the associated Virtual Switch will be determined. In VMware ESX there can be only one Virtual Switch associated with a Physical adapter.
When VM Spawn request is issued with a VLAN ID the work flow looks like,
1. Check that a Physical adapter with the given name exists. If no, throw an error.If yes, goto next step.
2. Check if a Virtual Switch is associated with the Physical ethernet adapter with vlan interface name. If no, throw an error. If yes, goto next step.
3. Check if a port group with the network bridge name exists. If no, create a port group in the Virtual switch with the give name and VLAN id and goto step 6. If yes, goto next step.
4. Check if the port group is associated with the Virtual Switch. If no, throw an error. If yes, goto next step.
5. Check if the port group is associated with the given VLAN Id. If no, throw an error. If yes, goto next step.
6. Spawn the VM using this Port Group as the Network Name for the VM.
Guest console Support
---------------------
| VMware VMRC console is a built-in console method providing graphical control of the VM remotely.
|
| VMRC Console types supported:
| # Host based credentials
| Not secure (Sends ESX admin credentials in clear text)
|
| # OTP (One time passwords)
| Secure but creates multiple session entries in DB for each OpenStack console create request.
| Console sessions created is can be used only once.
|
| Install browser based VMware ESX plugins/activex on the client machine to connect
|
| Windows:-
| Internet Explorer:
| https://<VMware ESX Host>/ui/plugin/vmware-vmrc-win32-x86.exe
|
| Mozilla Firefox:
| https://<VMware ESX Host>/ui/plugin/vmware-vmrc-win32-x86.xpi
|
| Linux:-
| Mozilla Firefox
| 32-Bit Linux:
| https://<VMware ESX Host>/ui/plugin/vmware-vmrc-linux-x86.xpi
|
| 64-Bit Linux:
| https://<VMware ESX Host>/ui/plugin/vmware-vmrc-linux-x64.xpi
|
| OpenStack Console Details:
| console_type = vmrc+credentials | vmrc+session
| host = <VMware ESX Host>
| port = <VMware ESX Port>
| password = {'vm_id': <VMware VM ID>,'username':<VMware ESX Username>, 'password':<VMware ESX Password>} //base64 + json encoded
|
| Instantiate the plugin/activex object
| # In Internet Explorer
| <object id='vmrc' classid='CLSID:B94C2238-346E-4C5E-9B36-8CC627F35574'>
| </object>
|
| # Mozilla Firefox and other browsers
| <object id='vmrc' type='application/x-vmware-vmrc;version=2.5.0.0'>
| </object>
|
| Open vmrc connection
| # Host based credentials [type=vmrc+credentials]
| <script type="text/javascript">
| var MODE_WINDOW = 2;
| var vmrc = document.getElementById('vmrc');
| vmrc.connect(<VMware ESX Host> + ':' + <VMware ESX Port>, <VMware ESX Username>, <VMware ESX Password>, '', <VMware VM ID>, MODE_WINDOW);
| </script>
|
| # OTP (One time passwords) [type=vmrc+session]
| <script type="text/javascript">
| var MODE_WINDOW = 2;
| var vmrc = document.getElementById('vmrc');
| vmrc.connectWithSession(<VMware ESX Host> + ':' + <VMware ESX Port>, <VMware VM ID>, <VMware ESX Password>, MODE_WINDOW);
| </script>
Assumptions
-----------
1. The VMware images uploaded to the image repositories have VMware Tools installed.
FAQ
---
1. What type of disk images are supported?
* Only VMware VMDK's are currently supported and of that support is available only for thick disks, thin provisioned disks are not supported.
2. How is IP address information injected into the guest?
* IP address information is injected through 'machine.id' vmx parameter (equivalent to XenStore in XenServer). This information can be retrived inside the guest using VMware tools.
3. What is the guest tool?
* The guest tool is a small python script that should be run either as a service or added to system startup. This script configures networking on the guest. The guest tool is available at tools/esx/guest_tool.py
4. What type of consoles are supported?
* VMware VMRC based consoles are supported. There are 2 options for credentials one is OTP (Secure but creates multiple session entries in DB for each OpenStack console create request.) & other is host based credentials (It may not be secure as ESX credentials are transmitted as clear text).
5. What does 'Vim' refer to as far as vmwareapi module is concerned?
* Vim refers to VMware Virtual Infrastructure Methodology. This is not to be confused with "VIM" editor.