nova/doc/source/index.rst
Balazs Gibizer 612c36034b [Community goal] Update contributor documentation
As the Ussuri goal we have an OpenStack project wide contributing
documentation template [1]. Nova has its own contributor documentation
so this patch adds the new contributing.rst according to the global
template and links the sections in it to the existing Nova contributor
documentation.

Also the top level CONTRIBUTING.rst template has been changed in the
cookiecutter repo[2]. So this patch updates the CONTRIBUTING.rst according
to the new template.

[1] https://opendev.org/openstack/cookiecutter/src/branch/master/%7b%7bcookiecutter.repo_name%7d%7d/doc/source/contributor/contributing.rst
[2] https://review.opendev.org/#/c/696001

Change-Id: Ia12cd4acbb63f192fcaf0790b72f8e977025a9dc
Story: #2007236
Task: #38541
2020-03-25 12:01:37 +00:00

9.6 KiB

OpenStack Compute (nova)

What is nova?

Nova is the OpenStack project that provides a way to provision compute instances (aka virtual servers). Nova supports creating virtual machines, baremetal servers (through the use of ironic), and has limited support for system containers. Nova runs as a set of daemons on top of existing Linux servers to provide that service.

It requires the following additional OpenStack services for basic function:

  • Keystone <>: This provides identity and authentication for all OpenStack services.
  • Glance <>: This provides the compute image repository. All compute instances launch from glance images.
  • Neutron <>: This is responsible for provisioning the virtual or physical networks that compute instances connect to on boot.
  • Placement <>: This is responsible for tracking inventory of resources available in a cloud and assisting in choosing which provider of those resources will be used when creating a virtual machine.

It can also integrate with other services to include: persistent block storage, encrypted disks, and baremetal compute instances.

For End Users

As an end user of nova, you'll use nova to create and manage servers with either tools or the API directly.

user/index

Tools for using Nova

  • Horizon <user/launch-instances.html>: The official web UI for the OpenStack Project.
  • OpenStack Client <>: The official CLI for OpenStack Projects. You should use this as your CLI for most things, it includes not just nova commands but also commands for most of the projects in OpenStack.
  • Nova Client <user/shell.html>: For some very advanced features (or administrative commands) of nova you may need to use nova client. It is still supported, but the openstack cli is recommended.

Writing to the API

All end user (and some administrative) features of nova are exposed via a REST API, which can be used to build more complicated logic or automation with nova. This can be consumed directly, or via various SDKs. The following resources will help you get started with consuming the API directly.

  • Compute API Guide: The concept guide for the API. This helps lay out the concepts behind the API to make consuming the API reference easier.
  • Compute API Reference: The complete reference for the compute API, including all methods and request / response parameters and their meaning.
  • Compute API Microversion History </reference/api-microversion-history>: The compute API evolves over time through Microversions. This provides the history of all those changes. Consider it a "what's new" in the compute API.
  • Block Device Mapping </user/block-device-mapping>: One of the trickier parts to understand is the Block Device Mapping parameters used to connect specific block devices to computes. This deserves its own deep dive.
  • Metadata </user/metadata>: Provide information to the guest instance when it is created.

Nova can be configured to emit notifications over RPC.

  • Versioned Notifications <versioned_notification_samples>: This provides the list of existing versioned notifications with sample payloads.

Other end-user guides can be found under /user/index.

For Operators

Architecture Overview

  • Nova architecture </user/architecture>: An overview of how all the parts in nova fit together.

user/architecture

Installation

The detailed install guide for nova. A functioning nova will also require having installed keystone <install/>, glance <install/>, neutron <install/>, and placement <install/>. Ensure that you follow their install guides first.

install/index

Deployment Considerations

There is information you might want to consider before doing your deployment, especially if it is going to be a larger deployment. For smaller deployments the defaults from the install guide </install/index> will be sufficient.

  • Compute Driver Features Supported: While the majority of nova deployments use libvirt/kvm, you can use nova with other compute drivers. Nova attempts to provide a unified feature set across these, however, not all features are implemented on all backends, and not all features are equally well tested.
    • Feature Support by Use Case </user/feature-classification>: A view of what features each driver supports based on what's important to some large use cases (General Purpose Cloud, NFV Cloud, HPC Cloud).
    • Feature Support full list </user/support-matrix>: A detailed dive through features in each compute driver backend.
  • Cells v2 Planning </user/cellsv2-layout>: For large deployments, Cells v2 allows sharding of your compute environment. Upfront planning is key to a successful Cells v2 layout.
  • Running nova-api on wsgi <user/wsgi>: Considerations for using a real WSGI container instead of the baked-in eventlet web server.

user/feature-classification user/support-matrix user/cellsv2-layout user/wsgi

Maintenance

Once you are running nova, the following information is extremely useful.

  • Admin Guide </admin/index>: A collection of guides for administrating nova.
  • Flavors </user/flavors>: What flavors are and why they are used.
  • Upgrades </user/upgrade>: How nova is designed to be upgraded for minimal service impact, and the order you should do them in.
  • Quotas </user/quotas>: Managing project quotas in nova.
  • Aggregates </admin/aggregates>: Aggregates are a useful way of grouping hosts together for scheduling purposes.
  • Filter Scheduler </user/filter-scheduler>: How the filter scheduler is configured, and how that will impact where compute instances land in your environment. If you are seeing unexpected distribution of compute instances in your hosts, you'll want to dive into this configuration.
  • Exposing custom metadata to compute instances </admin/vendordata>: How and when you might want to extend the basic metadata exposed to compute instances (either via metadata server or config drive) for your specific purposes.

admin/index user/flavors user/upgrade user/quotas user/filter-scheduler admin/vendordata

Reference Material

  • Nova CLI Command References </cli/index>: the complete command reference for all the daemons and admin tools that come with nova.
  • Configuration Guide <configuration/index>: Information on configuring the system, including role-based access control policy rules.

cli/index configuration/index

For Contributors

  • contributor/contributing: If you are a new contributor this should help you to start contributing to Nova.
  • contributor/index: If you are new to Nova, this should help you start to understand what Nova actually does, and why.
  • reference/index: There are also a number of technical references on both current and future looking parts of our architecture. These are collected here.

contributor/index contributor/contributing reference/index

html

  • Nova document search <search>: Search the contents of this document.
  • OpenStack wide search: Search the wider set of OpenStack documentation, including forums.