Jump to: navigation, search

Difference between revisions of "Documentation/Guide conventions"

 
(One intermediate revision by one other user not shown)
Line 1: Line 1:
 
{{OpenStack_Documentation_Navbar}}
 
{{OpenStack_Documentation_Navbar}}
 
{{OpenStack_Conventions_Navbar}}
 
{{OpenStack_Conventions_Navbar}}
 +
 +
{{Warning|header=Warning|body=This page is deprecated. It is left here for reference.}}
  
 
The following lists conventions used for writing specific guides. In general we want to be consistent between guides, especially since some guides include the same files.
 
The following lists conventions used for writing specific guides. In general we want to be consistent between guides, especially since some guides include the same files.
Line 16: Line 18:
 
* Use <code>block''X''</code> instead of the block storage node management interface IP address for block storage nodes. Replace X with a number starting from 1. The management interface IP address of the first block storage node is 10.0.0.41, the second 10.0.0.42, etc.
 
* Use <code>block''X''</code> instead of the block storage node management interface IP address for block storage nodes. Replace X with a number starting from 1. The management interface IP address of the first block storage node is 10.0.0.41, the second 10.0.0.42, etc.
 
* Use <code>object''X''</code> instead of the object storage node management interface IP address for object storage nodes. Replace X with a number starting from 1. The management interface IP address of the first object storage node is 10.0.0.51, the second 10.0.0.52, etc.
 
* Use <code>object''X''</code> instead of the object storage node management interface IP address for object storage nodes. Replace X with a number starting from 1. The management interface IP address of the first object storage node is 10.0.0.51, the second 10.0.0.52, etc.
 +
* For Juno and beyond on Fedora/RHEL/CentOS, use systemctl rather than service restart or chkconfig <service> on, for example, due to the upgrade to version 7.
 
* Try to reference the name of a network interface as described in the architecture chapter. For example, say "configure the management interface IP address as 10.0.0.51" rather than "configure eth0 as 10.0.0.51".
 
* Try to reference the name of a network interface as described in the architecture chapter. For example, say "configure the management interface IP address as 10.0.0.51" rather than "configure eth0 as 10.0.0.51".
 
* The example IP addressing structure allows up to 10 controller nodes, network nodes, compute nodes, block storage nodes, and object storage nodes.
 
* The example IP addressing structure allows up to 10 controller nodes, network nodes, compute nodes, block storage nodes, and object storage nodes.

Latest revision as of 13:49, 27 March 2018

Warning icon.svg Warning

This page is deprecated. It is left here for reference.

The following lists conventions used for writing specific guides. In general we want to be consistent between guides, especially since some guides include the same files.

General

  • Mentioning Bugs. If there is a bug that causes some workaround or limitation to be documented, the link to the bug report should be included. This makes it easier to maintain and update such notes.

Installation Guide

  • Use controller instead of the controller node management interface IP address 10.0.0.11. Use replaceable for it like <replaceable>controller</replaceable>.
  • Use computeX instead of the compute node management interface IP address for compute nodes. Replace X with a number starting from 1. The management interface IP address of the first compute node is 10.0.0.31, the second is 10.0.0.32, etc.
  • Use blockX instead of the block storage node management interface IP address for block storage nodes. Replace X with a number starting from 1. The management interface IP address of the first block storage node is 10.0.0.41, the second 10.0.0.42, etc.
  • Use objectX instead of the object storage node management interface IP address for object storage nodes. Replace X with a number starting from 1. The management interface IP address of the first object storage node is 10.0.0.51, the second 10.0.0.52, etc.
  • For Juno and beyond on Fedora/RHEL/CentOS, use systemctl rather than service restart or chkconfig <service> on, for example, due to the upgrade to version 7.
  • Try to reference the name of a network interface as described in the architecture chapter. For example, say "configure the management interface IP address as 10.0.0.51" rather than "configure eth0 as 10.0.0.51".
  • The example IP addressing structure allows up to 10 controller nodes, network nodes, compute nodes, block storage nodes, and object storage nodes.
  • Database passwords are written as SERVICE_DBPASS, e.g. NOVA_DBPASS
  • Keystone passwords are written as USERNAME_PASS, e.g. GLANCE_PASS
  • rabbit_userid is guest
  • Networking services
    • Use "OpenStack Networking (neutron)" for chapter/section titles and first instance. Use "OpenStack Networking" or "Networking" for additional instances.
    • Use "legacy networking (nova-network)" for chapter/section titles and first instance. Use "legacy networking" for additional instances.
  • Structure for steps that involve commands:
1) Run the following command to install the components:
    a) apt-get install package1 package2
  • Structure for steps that involve configuration:
1) Edit the /etc/abc/abc.conf file:
    a) Configure database access in the [database] section:
        [database]
        ...
        connection = mysql://
    b) Configure RabbitMQ message broker access in the [DEFAULT] section:
        [DEFAULT]
        ...
        rabbit_host = controller
    c) Configure Identity service access in the [keystone_authtoken] section:
        [keystone_authtoken]
        ...
        auth_host = controller
    • Example code snippet for editing /etc/heat/heat.conf:
<procedure os="ubuntu;rhel;centos;fedora;sles;opensuse">
  <title>To configure the Orchestration components</title>
  <para>Edit the <filename>/etc/heat/heat.conf</filename> file and perform
    the following tasks:</para>
  <step>
    <para>Configure database access in the <literal>[database]</literal>
      section.</para>
    <para>Replace <replaceable>HEAT_DBPASS</replaceable> with the password
      you chose for the Orchestration database.</para>
    <programlisting language="ini">[database]
...
connection = mysql://heat:<replaceable>HEAT_DBPASS</replaceable>@<replaceable>controller</replaceable>/heat</programlisting>
  </step>
  <step os="ubuntu;sles;opensuse">
    <para>Configure <application>RabbitMQ</application> message broker
      access in the <literal>[DEFAULT]</literal> section:</para>
    <para>Replace <replaceable>RABBIT_PASS</replaceable> with the password
      you chose for the <literal>guest</literal> account in
      <application>RabbitMQ</application>.</para>
    <programlisting language="ini">[DEFAULT]
...
rpc_backend = heat.openstack.common.rpc.impl_kombu
rabbit_host = <replaceable>controller</replaceable>
rabbit_password = <replaceable>RABBIT_PASS</replaceable></programlisting>
  </step>
</procedure>

Operations Guide

The Operations Guide follows for some cases the O'Reilly style guide.

Official book titles and title abbreviations

The titles are for the HTML and PDF outputs. The title abbreviations are for the PDF output only.

Installation guides

Audience: Cloud operators

Title Title abbreviation
OpenStack Installation Guide for Debian 7.0 Install Guide for Debian
OpenStack Installation Guide for openSUSE and SUSE Linux Enterprise Server Install Guide for openSUSE and SUSE Linux Enterprise
OpenStack Installation Guide for Red Hat Enterprise Linux, CentOS, and Fedora Install Guide for Red Hat
OpenStack Installation Guide for Ubuntu 12.04 (LTS) Install Guide for Ubuntu

Administration guides

Audience: Cloud operators

Title Title abbreviation
OpenStack Architecture Design Guide Architecture Design Guide
OpenStack Cloud Administrator Guide Cloud Administrator Guide
OpenStack Configuration Reference Config Reference
OpenStack High Availability Guide High Availability Guide
OpenStack Operations Guide Ops Guide
OpenStack Security Guide Security Guide
OpenStack Virtual Machine Image Guide VM Image Guide

Application developer and user guides

Audiences:

  • Developers who build applications that run in the cloud
  • Users who manage resources and services in the cloud

Note:

The product definition in the pom.xml file affects the way the title breaks on the cover page in the PDF.

Titles:

Title Title abbreviation Product
API Quick Start N/A
OpenStack API Complete Reference (web page) N/A OpenStack
OpenStack Block Storage Service API v2 Reference Block Storage Service API Reference OpenStack Block Storage Service
OpenStack Compute API v2 and Extensions Reference Compute API and Extensions Reference OpenStack Compute
OpenStack Identity Service API v2.0 Reference Identity Service API Reference OpenStack Identity Service
OpenStack Image Service API v2 Reference Image Service API Reference OpenStack Image Service
OpenStack Networking API v2.0 Reference Networking API Reference OpenStack Networking
OpenStack Image Service API v1 Reference Image Service API Reference OpenStack Image Service
Object Storage API v1 Reference Object Storage API Reference OpenStack Object Storage
OpenStack End User Guide End User Guide OpenStack
OpenStack Admin User Guide Admin User Guide OpenStack
OpenStack Command-Line Interface Reference CLI Reference OpenStack