Merge "[DOC BLD FIX] Fix missing references in documentation"

doc/source/admin/blockstorage-manage-volumes.rst

@@ -47,7 +47,9 @@ settings for OpenStack Compute.
 
 The network mode does not interfere with OpenStack Block Storage
 operations, but you must set up networking for Block Storage to work.
-For details, see :ref:`networking`.
+For details, see `networking`_.
+
+.. _networking: https://docs.openstack.org/neutron/latest/
 
 To set up Compute to use volumes, ensure that Block Storage is
 installed along with ``lvm2``. This guide describes how to

doc/source/configuration/block-storage.rst

@@ -19,9 +19,10 @@ Cinder Service Configuration
 
 .. note::
 
-   The common configurations for shared service and libraries,
-   such as database connections and RPC messaging,
-   are described at :doc:`common-configurations`.
+   The examples of common configurations for shared
+   service and libraries, such as database connections and
+   RPC messaging, can be seen in Cinder's sample configuration
+   file: `cinder.conf.sample <_static/cinder.conf.sample>`_.
 
 The Block Storage service works with many different storage
 drivers that you can configure by using these instructions.

doc/source/configuration/block-storage/drivers/windows-iscsi-volume-driver.rst

@@ -68,6 +68,8 @@ in :ref:`configure-ntp-windows`.
 
 Next, install the requirements as described in :ref:`windows-requirements`.
 
+
+
 Getting the code
 ~~~~~~~~~~~~~~~~
 
@@ -120,3 +122,119 @@ must replace the variables with the proper paths):
 
    PS C:\> python $CinderClonePath\setup.py install
    PS C:\> cmd /c C:\python27\python.exe c:\python27\Scripts\cinder-volume" --config-file $CinderConfPath
+
+Reference material
+------------------
+
+.. _configure-ntp-windows:
+
+Configure NTP
+-------------
+
+Network time services must be configured to ensure proper operation
+of the OpenStack nodes. To set network time on your Windows host you
+must run the following commands:
+
+.. code-block:: bat
+
+   C:\>net stop w32time
+   C:\>w32tm /config /manualpeerlist:pool.ntp.org,0x8 /syncfromflags:MANUAL
+   C:\>net start w32time
+
+Keep in mind that the node will have to be time synchronized with
+the other nodes of your OpenStack environment, so it is important to use
+the same NTP server. Note that in case of an Active Directory environment,
+you may do this only for the AD Domain Controller.
+
+
+.. _windows-requirements:
+
+Requirements
+~~~~~~~~~~~~
+
+Python
+------
+
+Python 2.7 32bit must be installed as most of the libraries are not
+working properly on the 64bit version.
+
+**Setting up Python prerequisites**
+
+#. Download and install Python 2.7 using the MSI installer from here:
+
+   `python-2.7.3.msi download
+   <https://www.python.org/ftp/python/2.7.3/python-2.7.3.msi>`_
+
+   .. code-block:: console
+
+      PS C:\> $src = "https://www.python.org/ftp/python/2.7.3/python-2.7.3.msi"
+      PS C:\> $dest = "$env:temp\python-2.7.3.msi"
+      PS C:\> Invoke-WebRequest –Uri $src –OutFile $dest
+      PS C:\> Unblock-File $dest
+      PS C:\> Start-Process $dest
+
+#. Make sure that the ``Python`` and ``Python\Scripts`` paths are set up
+   in the ``PATH`` environment variable.
+
+   .. code-block:: console
+
+      PS C:\> $oldPath = [System.Environment]::GetEnvironmentVariable("Path")
+      PS C:\> $newPath = $oldPath + ";C:\python27\;C:\python27\Scripts\"
+      PS C:\> [System.Environment]::SetEnvironmentVariable("Path", $newPath, [System.EnvironmentVariableTarget]::User
+
+Python dependencies
+-------------------
+
+The following packages need to be downloaded and manually installed:
+
+setuptools
+  https://pypi.python.org/packages/2.7/s/setuptools/setuptools-0.6c11.win32-py2.7.exe
+
+pip
+  https://pip.pypa.io/en/latest/installing/
+
+PyMySQL
+  http://codegood.com/download/10/
+
+PyWin32
+  https://sourceforge.net/projects/pywin32/files/pywin32/Build%20217/pywin32-217.win32-py2.7.exe
+
+Greenlet
+  http://www.lfd.uci.edu/~gohlke/pythonlibs/#greenlet
+
+PyCryto
+  http://www.voidspace.org.uk/downloads/pycrypto26/pycrypto-2.6.win32-py2.7.exe
+
+The following packages must be installed with pip:
+
+* ecdsa
+* amqp
+* wmi
+
+.. code-block:: console
+
+   PS C:\> pip install ecdsa
+   PS C:\> pip install amqp
+   PS C:\> pip install wmi
+
+Other dependencies
+------------------
+
+``qemu-img`` is required for some of the image related operations.
+You can get it from here: http://qemu.weilnetz.de/.
+You must make sure that the ``qemu-img`` path is set in the
+PATH environment variable.
+
+Some Python packages need to be compiled, so you may use MinGW or
+Visual Studio. You can get MinGW from here:
+http://sourceforge.net/projects/mingw/.
+You must configure which compiler is to be used for this purpose by using the
+``distutils.cfg`` file in ``$Python27\Lib\distutils``, which can contain:
+
+.. code-block:: ini
+
+   [build]
+   compiler = mingw32
+
+As a last step for setting up MinGW, make sure that the MinGW binaries'
+directories are set up in PATH.

doc/source/install/overview.rst

@@ -0,0 +1,182 @@
+========
+Overview
+========
+
+The OpenStack project is an open source cloud computing platform that
+supports all types of cloud environments. The project aims for simple
+implementation, massive scalability, and a rich set of features. Cloud
+computing experts from around the world contribute to the project.
+
+OpenStack provides an Infrastructure-as-a-Service (IaaS) solution
+through a variety of complementary services. Each service offers an
+Application Programming Interface (API) that facilitates this
+integration.
+
+This guide covers step-by-step deployment of the major OpenStack
+services using a functional example architecture suitable for
+new users of OpenStack with sufficient Linux experience. This guide is not
+intended to be used for production system installations, but to create a
+minimum proof-of-concept for the purpose of learning about OpenStack.
+
+After becoming familiar with basic installation, configuration, operation,
+and troubleshooting of these OpenStack services, you should consider the
+following steps toward deployment using a production architecture:
+
+* Determine and implement the necessary core and optional services to
+  meet performance and redundancy requirements.
+
+* Increase security using methods such as firewalls, encryption, and
+  service policies.
+
+* Implement a deployment tool such as Ansible, Chef, Puppet, or Salt
+  to automate deployment and management of the production environment.
+
+.. _overview-example-architectures:
+
+Example architecture
+~~~~~~~~~~~~~~~~~~~~
+
+The example architecture requires at least two nodes (hosts) to launch a basic
+virtual machine <virtual machine (VM)> or instance. Optional
+services such as Block Storage and Object Storage require additional nodes.
+
+.. important::
+
+   The example architecture used in this guide is a minimum configuration,
+   and is not intended for production system installations. It is designed to
+   provide a minimum proof-of-concept for the purpose of learning about
+   OpenStack. For information on creating architectures for specific
+   use cases, or how to determine which architecture is required, see the
+   `Architecture Design Guide <https://docs.openstack.org/arch-design/>`_.
+
+This example architecture differs from a minimal production architecture as
+follows:
+
+* Networking agents reside on the controller node instead of one or more
+  dedicated network nodes.
+
+* Overlay (tunnel) traffic for self-service networks traverses the management
+  network instead of a dedicated network.
+
+For more information on production architectures, see the
+`Architecture Design Guide <https://docs.openstack.org/arch-design/>`_,
+`OpenStack Operations Guide <https://docs.openstack.org/ops-guide/>`_, and
+`OpenStack Networking Guide <https://docs.openstack.org/ocata/networking-guide/>`_.
+
+.. _figure-hwreqs:
+
+.. figure:: figures/hwreqs.png
+   :alt: Hardware requirements
+
+   **Hardware requirements**
+
+Controller
+----------
+
+The controller node runs the Identity service, Image service, management
+portions of Compute, management portion of Networking, various Networking
+agents, and the Dashboard. It also includes supporting services such as
+an SQL database, message queue, and NTP <Network Time Protocol
+(NTP)>.
+
+Optionally, the controller node runs portions of the Block Storage, Object
+Storage, Orchestration, and Telemetry services.
+
+The controller node requires a minimum of two network interfaces.
+
+Compute
+-------
+
+The compute node runs the hypervisor portion of Compute that
+operates instances. By default, Compute uses the
+KVM <kernel-based VM (KVM)> hypervisor. The compute node also
+runs a Networking service agent that connects instances to virtual networks
+and provides firewalling services to instances via
+security groups <security group>.
+
+You can deploy more than one compute node. Each node requires a minimum
+of two network interfaces.
+
+Block Storage
+-------------
+
+The optional Block Storage node contains the disks that the Block
+Storage and Shared File System services provision for instances.
+
+For simplicity, service traffic between compute nodes and this node
+uses the management network. Production environments should implement
+a separate storage network to increase performance and security.
+
+You can deploy more than one block storage node. Each node requires a
+minimum of one network interface.
+
+Object Storage
+--------------
+
+The optional Object Storage node contain the disks that the
+Object Storage service uses for storing accounts, containers, and
+objects.
+
+For simplicity, service traffic between compute nodes and this node
+uses the management network. Production environments should implement
+a separate storage network to increase performance and security.
+
+This service requires two nodes. Each node requires a minimum of one
+network interface. You can deploy more than two object storage nodes.
+
+Networking
+~~~~~~~~~~
+
+Choose one of the following virtual networking options.
+
+.. _network1:
+
+Networking Option 1: Provider networks
+--------------------------------------
+
+The provider networks option deploys the OpenStack Networking service
+in the simplest way possible with primarily layer-2 (bridging/switching)
+services and VLAN segmentation of networks. Essentially, it bridges virtual
+networks to physical networks and relies on physical network infrastructure
+for layer-3 (routing) services. Additionally, a DHCP<Dynamic Host
+Configuration Protocol (DHCP)> service provides IP address information to
+instances.
+
+The OpenStack user requires more information about the underlying network
+infrastructure to create a virtual network to exactly match the
+infrastructure.
+
+.. warning::
+
+   This option lacks support for self-service (private) networks, layer-3
+   (routing) services, and advanced services such as
+   LBaaS <Load-Balancer-as-a-Service (LBaaS)> and
+   FWaaS<FireWall-as-a-Service (FWaaS)>.
+   Consider the self-service networks option below if you desire these features.
+
+.. _figure-network1-services:
+
+.. figure:: figures/network1-services.png
+   :alt: Networking Option 1: Provider networks - Service layout
+
+.. _network2:
+
+Networking Option 2: Self-service networks
+------------------------------------------
+
+The self-service networks option augments the provider networks option
+with layer-3 (routing) services that enable
+self-service networks using overlay segmentation methods such
+as VXLAN <Virtual Extensible LAN (VXLAN)>. Essentially, it routes
+virtual networks to physical networks using NAT<Network Address
+Translation (NAT)>. Additionally, this option provides the foundation for
+advanced services such as LBaaS and FWaaS.
+
+The OpenStack user can create virtual networks without the knowledge
+of underlying infrastructure on the data network. This can also include
+VLAN networks if the layer-2 plug-in is configured accordingly.
+
+.. _figure-network2-services:
+
+.. figure:: figures/network2-services.png
+   :alt: Networking Option 2: Self-service networks - Service layout