Nova administration is accomplished through a tool called nova-manage. Most commands take the form
nova-manage command subcommand and any necessary arguments. At any
time, you can see help for nova-manage
by leaving off any arguments, subcommands, or commands. Here is an example
of finding help for creating a new user:
$ nova-manage
nova-manage category action [<args>]
Available categories:
user
account
project
role
shell
vpn
fixed
floating
network
vm
service
db
volume
instance_type
image
flavor
$ nova-manage user
nova-manage category action [<args>]
Available actions for user category:
admin
create
delete
exports
list
modify
revoke
$ nova-manage user create
Possible wrong number of arguments supplied
user create: creates a new user and prints exports
arguments: name [access] [secret]
2011-07-15 18:55:13,520 CRITICAL nova [-] create() takes at least 2 arguments (1 given)Do not worry about the error after the nova-manage user create—it is simply telling you that you haven’t supplied the necessary arguments.
Services can be monitored through the nova-manage command on a service or host basis. With the service, you can either view or actively manage services. For example, you can query a host for the services that it currently offers, or simply list all the services that are available. This is an essential command for testing or troubleshooting your deployment. Below is an example that walks through the full array of of service subcommands: listing services, enabling and disabling services, and describing resources on a host.
# nova-manage service list nova-controller nova-compute nova-controller nova-compute enabled :-) 2011-07-08 22:36:54 # nova-manage service disable nova-controller nova-scheduler # nova-manage service list nova-controller nova-compute enabled :-) 2011-07-08 22:38:04 nova-controller nova-network enabled XXX 2011-07-08 22:38:12 nova-controller nova-scheduler disabled :-) 2011-07-08 22:38:07 nova-controller nova-volume enabled :-) 2011-07-08 22:38:07 # nova-manage service enable nova-controller nova-scheduler # nova-manage service list nova-controller nova-compute enabled :-) 2011-07-08 22:38:24 nova-controller nova-network enabled :-) 2011-07-08 22:38:22 nova-controller nova-scheduler enabled :-) 2011-07-08 22:38:27 nova-controller nova-volume enabled :-) 2011-07-08 22:38:27 # nova-manage service describe_resource nova-controller HOST PROJECT cpu mem(mb) disk(gb) nova-controller(total) 2 3930 219 nova-controller(used) 0 368 12 nova-controller book 1 512 0
nova-manage service also allows you to update resources that are available on a particular host. This is only applies to compute hosts.
Nova can apply quotas on number of instances, total cores, total volumes, volume size, and other items on a per-project basis. Table 9-1 illustrates all quota options, their default values, and a brief description.
Table 9-1. Nova Quotas
| Quota Flag | Default Value | Description |
|---|---|---|
| quota_instances | 10 | number of instances allowed per project |
| quota_cores | 20 | number of instance cores allowed per project |
| quota_volumes | 10 | number of volumes allowed per project |
| quota_gigabytes | 1000 | number of volume gigabytes allowed per project |
| quota_floating_ips | 10 | number of floating ips allowed per project |
| quota_metadata_items | 128 | number of metadata items allowed per instance |
| quota_max_injected_files | 5 | number of injected files allowed |
| quota_max_injected_file_content_bytes | 10 * 1024 | number of bytes allowed per injected file |
| quota_max_injected_file_path_bytes | 255 | number of bytes allowed per injected file path |
These default values for all projects are set in the source code (nova/quota.py) but can be overridden for all projects or individual projects. To override the default value for all projects, simply add the appropriate flag with a new value to the /etc/nova.conf file. For example, to change the total cores available to each project, append this line to the /etc/nova.conf file:
--quota_cores=100
It is also possible to adjust quotas on particular projects with the nova-manage command. To increase the total cores allotted to a mythical “payroll” project, execute the following command:
$ nova-manage project quota payroll cores 150 metadata_items: 128 gigabytes: 1000 floating_ips: 10 instances: 100 volumes: 10 cores: 150
As you may have noticed, the flags for quotas (quota_cores) are different from the nova-manage command keys (cores). Using the flag in nova-manage or the nova-manage keys in /etc/nova.conf will have no effect.
As you can see from the command listing above, we specified the project (“payroll”), then the quota key (“cores”), and finally the new value. Executing nova-manage project quota payroll without a key and value will print out a list of the current values for all quotas.
The nova-manage db command is rarely used except for troubleshooting and upgrades. It has two subcommands: sync and version. The sync subcommand will upgrade the database scheme for new versions of Nova and the version will report the current version.
Nova uses a database abstraction library called SQL-Alchemy to
interact with its database. A complimentary package called sqlalchemy-migrate is used to manage the
database schema. Inspired by Ruby on Rails’ migrations feature, it
provides a programmatic way to handle database schema changes. For
Nova administrators, this only applies when they are upgrading
versions.
To upgrade scheme versions, use the nova-manage db sync. This should be rarely used unless you are installing from source or upgrading your installation. If there are pending scheme migrations, it will apply those to your database. If there are not, it will return nothing.
# nova-manage db sync #
To view the database scheme version, use the db version arguments:
# nova-manage db version 14
The database version for Cactus is 14
Instance types (or “flavors,” as the OpenStack API calls them) are resources granted to instances in Nova. In more specific terms, this is the size of the instance (vCPUs, RAM, Storage, etc.) that will be launched. You may recognize these by the names “m1.large” or “m1.tiny” in Amazon Web Services EC2 parlance. The OpenStack API calls these “flavors” and they tend to have names like “256 MB Server.”
Instance types or flavors are managed through nova-manage with the instance_types command and an appropriate subcommand. At the current time, instance type manipulation isn’t exposed through the APIs nor the adminclient.
You can use the flavor command as a synonym for instance_types in any of these examples.
During installation, Nova creates five instance types that mirror the basic Amazon EC2 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
Again, and just for emphasis, you could just as easily have used the flavor subcommand to get the exact same output:
$ nova-manage flavor 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
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
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
Be careful with deleting instance types, as you might need this information later. This is especially true in commercial or enterprise environments where you might be creating a bill based off the instance type’s name or configuration. Unless you truly need to prune the size of your instance_types table, you are much safer to just delete the instance type.
Nova also lets you query all the current running virtual machines, similar to how the OpenStack API or EC2 API does with their tools.
# nova-manage vm list instance node type state launched image kernel ramdisk project user zone index i-00000003 nova-controller nova.db.sqlalchemy.models.InstanceTypes object at 0x429c910 launching None 1719908888 2129281401 book ken None 0
There is a bug in nova-manage vm list in Cactus where it cannot properly decipher the instance type (the type field above). This is corrected in the upcoming version of the Nova.
nova-manage vm also has an advanced KVM feature called live_migration. Live migration allows you to move virtual machine instances between hosts if the following conditions are met:
KVM or QEMU is the virtualization technology
The volume driver is iSCSI or AoE
Live migration is invoked with an instance id and destination host as arguments:
# nova-manage live_migration i-00000003 new-host Migration of i-00000003 initiated. Check its progress using euca-describe-instances.
Nova has a trio of nova-manage networking commands: network, fixed, and floating. The nova-manage network is the most powerful. It allows you to list, create, and delete networks within the Nova database. For example:
# nova-manage network list network netmask start address DNS 10.0.0.0/25 255.255.255.128 10.0.0.2 8.8.4.4
The fixed command simply allows you to view the fixed IP address mappings to hostname, host, and MAC address. Here are the truncated results of the command (it goes on to show the every IP address in the mapping):
# nova-manage fixed list network IP address MAC address hostname host 10.0.0.0/25 10.0.0.0 None None None 10.0.0.0/25 10.0.0.1 None None None 10.0.0.0/25 10.0.0.2 02:16:3e:5f:bc:a7 i-00000003 nova-controller 10.0.0.0/25 10.0.0.3 None None None 10.0.0.0/25 10.0.0.4 None None None 10.0.0.0/25 10.0.0.5 None None None 10.0.0.0/25 10.0.0.6 None None None
The floating command is very similar to the fixed command except that it manipulates public IP addresses. The example below creates a floating range and then shows their allocation.
# nova-manage float create cactus 192.168.1.128/29 # nova-manage float list cactus 192.168.1.128 None cactus 192.168.1.129 None cactus 192.168.1.130 None cactus 192.168.1.131 None cactus 192.168.1.132 None cactus 192.168.1.133 None cactus 192.168.1.134 None cactus 192.168.1.135 None
As purely a troubleshooting command, nova-manage shell allows you to start up a Nova environment so that you can issue ad hoc Python commands. You might use this to discover your installed version:
# nova-manage shell python Python 2.6.5 (r265:79063, Apr 16 2010, 13:57:41) [GCC 4.4.3] on linux2 Type "help", "copyright", "credits" or "license" for more information. (InteractiveConsole) >>> from nova import version >>> version.version_string() '2011.2' >>> version.version_string_with_vcs() u'2011.2-LOCALBRANCH:LOCALREVISION' >>> exit()
While I have used the basic shell in this example, you can also invoke the bpython or ipython shells. nova-manage shell can also be used for more elaborate troubleshooting scenarios depending on your Nova internals knowledge.
The volume command for nova-manage should only be used when
traditional methods have failed. It supports two subcommands: reattach and delete. While both subcommands are fairly
self-explanatory, the situations where they are applicable may not
be.
The delete subcommand should only be used when traditional methods of removing it has failed. As an example, we will delete a volume that has been marked in the “error” state:
# euca-describe-volumes
VOLUME vol-00000002 1 nova error (book, nova-controller, None, None)
2011-07-10T22:57:02Z
VOLUME vol-00000003 1 nova available (book, nova-controller, None, None)
2011-07-11T00:08:34Z
# nova-manage volume delete vol-00000002
# euca-describe-volumes
VOLUME vol-00000003 1 nova available (book, nova-controller, None, None)
2011-07-11T00:08:34ZThis subcommand will not let you delete a volume that is marked with the status “in-use” (which would mean that it is attached to an instance). You will need to detach the volume from the instance before trying this subcommand.
The reattach command allows you to reconnect a volume to an instance. Most likely, this will only need to be used after a compute host has been rebooted.