Jump to: navigation, search


< Documentation
Revision as of 16:17, 2 July 2014 by Dguitarbite (talk | contribs) (Adds global task to modularize XML files for reuse in training guides.)

Installation Guide Improvements


To assign yourself a global task, put your name next to the task.

  1. Replace openstack-config (crudini) commands with general configuration file editing.
  2. Change XML IDs for conventions and consistency.
  3. Unify chapter and section names.
    1. Unify concepts/overview section names.
  4. Add sample output for each command when appropriate (use discretion) and highlight particularly important components (requires patch to build process).
  5. Mention use of project and tenant.
  6. Change "MySQL" to reference generic SQL database.
  7. (jaegerandi) Standardize on RabbitMQ message broker for all distributions since RDO no longer uses Qpid.
  8. RHEL/CentOS: Consider disabling SELinux.
    1. Add options and summary for installing "openstack-selinux" or disabling completely.
    2. See also: http://openstack.redhat.com/SELinux
  9. Add Solaris 11.2 to distribution list.
    1. http://www.oracle.com/technetwork/server-storage/solaris11/technologies/openstack-2135773.html
  10. Define target audience and scope of the book.
    1. Not just install guide, every guide.
    2. See also: https://bugs.launchpad.net/openstack-manuals/+bug/1319394
  11. Mention openrc and user commands in prerequisites.
  12. Periodically reference conventions.
  13. Adjust sectioning (chunking) to reduce clicks to get through the guide. Chunk by chapter so that "next" link is only per chapter perhaps?
  14. Modularize install guides for re-use as basic install guide for training guides.(dguitarbite/Pranav Salunke)
    1. Changes XML files, should have minimal to zero impact on how install gudies look after compiling.
    2. Training guides: https://etherpad.openstack.org/p/training-guides-developing-topics
    3. Basic install gudie for training guides: https://etherpad.openstack.org/p/training-guides-install-guide

Unique (Particular Chapter/Section)

To assign yourself a chapter/section task, put your name next to the URL.

http://docs.openstack.org/trunk/install-guide/install/apt/content/ch_basics.html (Darren Chan)

  1. Rename chapter to "Basic Environment" and change IDs accordingly

http://docs.openstack.org/trunk/install-guide/install/apt/content/basics-ntp.html (Matt Kassawara) DONE

  1. Provide sample configuration for each node
  2. Compute and network nodes should reference server on controller node


  1. Update password list

http://docs.openstack.org/trunk/install-guide/install/apt/content/basics-database-controller.html (Darren Chan) Note: Maria DB content already exists for OpenSUSE

  1. Include MariaDB
  2. Provide link to PostgreSQL as an alternative database


  1. Does this section only apply to nova-net environments that require database access from compute nodes? (hopefully removed in Juno)

http://docs.openstack.org/trunk/install-guide/install/apt/content/basics-packages.html (Joseph Robinson)

  1. Clarify content.
  2. RHEL/CentOS/Fedora: Update content to include Scientific Linux.

http://docs.openstack.org/trunk/install-guide/install/apt/content/ch_keystone.html (Alexandra Settle) DONE

  1. Consider renaming chapter to "Add the Identity service".

http://docs.openstack.org/trunk/install-guide/install/apt/content/keystone-concepts.html (Alexandra Settle / Joseph Robinson) DONE

  1. Review content.

http://docs.openstack.org/trunk/install-guide/install/apt/content/keystone-install.html (Darren Chan / Matt Kassawara) DONE

  1. Should we install the client? Indicate in the text that we're assuming you're doing these on a controller node.
  2. Reorder instructions.
    1. Create database.
    2. Install packages.
    3. Generate administrative bootstrap token.
    4. Configure service.
    5. Synchronize database.
    6. Start or restart keystone service.


  1. Try to eliminate confusion over "ADMIN_TOKEN" and "$ADMIN_TOKEN".
  2. First couple of mentions, be sure to reference password/environment conventions.
  3. Does there need to be a link to conventions on every page as part of branding?

http://docs.openstack.org/trunk/install-guide/install/apt/content/keystone-services.html (Joseph Robinson)DONE

  1. Clarify content.
  2. Consider moving description to "concepts" section.

http://docs.openstack.org/trunk/install-guide/install/apt/content/keystone-verify.html (Darren Chan)

  1. Clarify content.
  2. Consider removing "openrc" content.


  1. Consider renaming chapter to "OpenStack clients".
    1. Does installing clients manually still apply?
    2. Less issues probably occur with packaged clients.
    3. The guide typically installs the packaged version when installing each service.
    4. Service packages often install the packaged version.

http://docs.openstack.org/trunk/install-guide/install/apt/content/section_cli_overview.html (Joseph Robinson) DONE

  1. Clarify content.

http://docs.openstack.org/trunk/install-guide/install/apt/content/cli_openrc.html (Alexandra Settle)

  1. Clarify content.
  2. Change "project" to "tenant" to agree with rest of guide. Agreed. If in the Juno release Keystone v3 becomes "standard" then we could change to project throughout the guide, but as long as Keystone v2.0 is used, tenant is what's in the command line parameters.


  1. Clarify content.
  2. Consider moving creation steps for all "openrc" files to this section.

http://docs.openstack.org/trunk/install-guide/install/apt/content/ch_glance.html (Darren Chan) DONE

  1. Consider renaming chapter to "Add the Image Service component".

http://docs.openstack.org/trunk/install-guide/install/apt/content/image-service-overview.html (Darren Chan) DONE

  1. Review content.

http://docs.openstack.org/trunk/install-guide/install/apt/content/glance-install.html (Matt Kassawara)

  1. Consider renaming section to "Install and configure".
  2. Source admin-openrc.sh.
  3. Reorder instructions.
    1. Create database.
    2. Create identity service credentials.
    3. Install packages.
    4. Configure service.
    5. Synchronize database.
    6. Start or restart service.

http://docs.openstack.org/trunk/install-guide/install/apt/content/glance-verify.html (Matt Kassawara)

  1. Consider renaming section to "Verify".
  2. Replace complex command instructions with simple <replaceable> values and example with output.
  3. Consider combining section into installation section.

http://docs.openstack.org/trunk/install-guide/install/apt/content/ch_nova.html (Alexandra Settle) DONE

  1. Consider renaming chapter to "Add the Compute component".

http://docs.openstack.org/trunk/install-guide/install/apt/content/compute-service.html (Darren Chan/Matt Kassawara) DONE

  1. Review content

http://docs.openstack.org/trunk/install-guide/install/apt/content/nova-controller.html (Matt Kassawara)

  1. Consider renaming section to "Controller node".
  2. Reorder instructions.
    1. Create database.
    2. Create identity service credentials.
    3. Install packages.
    4. Configure service.
    5. Synchronize database.
    6. Start or restart service.
  3. Explicitly configure 'glance_host = controller'.
  4. Consider splitting verification step into section.
  5. Include output from "nova service-list" command.

http://docs.openstack.org/trunk/install-guide/install/apt/content/nova-compute.html (Matt Kassawara)

  1. Consider renaming section to "Compute node".
  2. Ubuntu: Change package "nova-compute-kvm" to "nova-compute".
  3. Ubuntu: Consider removing "python-guestfs" package, although the "openstack-nova-compute" package for RHEL/CentOS/Fedora installs it as a dependency.
  4. Ubuntu: Consider removing the kernel permissions workaround.
  5. Consider adding verification step or section.
  6. Include output from "nova service-list" command.

http://docs.openstack.org/trunk/install-guide/install/apt/content/ch_networking.html (Darren Chan/ Andreas Jaeger / Diane Fleming) DONE

  1. Consider renaming chapter to "Add a networking component".

http://docs.openstack.org/trunk/install-guide/install/apt/content/neutron-concepts.html (Joseph Robinson) DONE

  1. Review content.


  1. If we plan to continue supporting nova-network, we should consider using an architecture that parallels the neutron architecture.


  1. Create diagram similar to section for neutron initial networks.

http://docs.openstack.org/trunk/install-guide/install/apt/content/ch_horizon.html (Joseph Robinson)

  1. Consider splitting concepts paragraph into separate section.


  1. Consider removing this section since all systems at this point should support the dashboard.


  1. Do we need "memcached" for a basic installation?
  2. Don't necessarily need to remove the Ubuntu dashboard theme, just comment it out in the configuration file.
  3. RHEL/CentOS/Fedora: Consider adding "httpd" to package list for consistency.
  4. Consider removing step 2, no longer necessary.
  5. Ubuntu: The 'ALLOWED_HOSTS' key is already commented out in local_settings.py.
  6. RHEL/CentOS/Fedora: Comment out the 'ALLOWED_HOSTS' key in local_settings.


  1. This section seems rather advanced. Does it belong in the installation guide?


  1. Consider renaming chapter to "Add Block Storage component"

http://docs.openstack.org/trunk/install-guide/install/apt/content/block-storage-service.html (Joseph Robinson) DONE

  1. Review content.


  1. Reorder instructions
    1. Create database.
    2. Create identity service credentials.
    3. Install packages.
    4. Configure service.
    5. Synchronize database.
    6. Start or restart service.
  2. Ubuntu: Also install "python-cinderclient" package?


  1. Add diagram and configuration for additional node.
  2. Do cinder volume nodes require direct access to the database?
  3. Ubuntu: Should we explicitly install the iscsi utilities?


  1. Change volume name to "demo-volume1" to agree with other portions of the guide.


  1. Review content.


  1. Consider better explanation about installations with only keystone and swift. Perhaps build another document?


  1. For object storage integrated with a full stack, we should modify this to build on content from the architecture and basic environment configuration chapters. For standalone object storage, building another document would greatly reduce confusion.


  1. Replace example with something more practical for a first installation and integrate with architecture and basic environment configuration section. Can we consolidate the number of nodes for a first installation?


  1. Consider separating integrated installations from standalone installations.


  1. Roll prerequisites into controller/proxy installation section.
  2. Does swift talk to a SQL database?


  1. Consider moving this to a more advanced configuration chapter.


  1. Review content

http://docs.openstack.org/trunk/install-guide/install/apt/content/heat-install.html (Darren Chan and Matt Kassawara) DONE

  1. Reorder instructions
    1. Create database.
    2. Create identity service credentials.
    3. Install packages.
    4. Configure service.
    5. Synchronize database.
    6. Start or restart service.


  1. Review content.
  2. Provide diagram of agent locations on each node.


  1. Consider renaming section to "Configure controller node".
  2. Reorder instructions
    1. Create prerequisites section and move installation/configuration of MongoDB to it.
    2. Create identity service credentials.
    3. Install packages.
    4. Configure service.
    5. Start or restart service.

http://docs.openstack.org/trunk/install-guide/install/apt/content/trove-service.html (Darren Chan)

  1. Review content


  1. RHEL/CentOS/Fedora: What about packages (FIXME present)?
  2. Reorder instructions
    1. Create database.
    2. Create identity service credentials.
    3. Install packages.
    4. Configure service.
    5. Synchronize database.
    6. Start or restart service.
  3. Do we need to edit api-paste.ini?


  1. Consider adding some sample SQL commands to verify operation.


  1. Add a note about SSH key passphrases.


  1. Add a note about SSH key passphrases.