Revision as of 01:30, 21 May 2014

Installation Guide Improvements

Global

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. 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?

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

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

http://docs.openstack.org/trunk/install-guide/install/apt/content/basics-ntp.html

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

http://docs.openstack.org/trunk/install-guide/install/apt/content/basics-passwords.html

1. Update password list

http://docs.openstack.org/trunk/install-guide/install/apt/content/basics-database-controller.html

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

http://docs.openstack.org/trunk/install-guide/install/apt/content/basics-database-node.html

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

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

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

http://docs.openstack.org/trunk/install-guide/install/apt/content/keystone-concepts.html

1. Review content.

http://docs.openstack.org/trunk/install-guide/install/apt/content/keystone-install.html

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.

http://docs.openstack.org/trunk/install-guide/install/apt/content/keystone-users.html

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

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

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

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

http://docs.openstack.org/trunk/install-guide/install/apt/content/ch_clients.html

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

1. Clarify content.

http://docs.openstack.org/trunk/install-guide/install/apt/content/cli_openrc.html

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.

http://docs.openstack.org/trunk/install-guide/install/apt/content/ch_clients_openrc_files.html

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

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

http://docs.openstack.org/trunk/install-guide/install/apt/content/image-service-overview.html

1. Review content.

http://docs.openstack.org/trunk/install-guide/install/apt/content/glance-install.html

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

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

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

http://docs.openstack.org/trunk/install-guide/install/apt/content/compute-service.html

1. Review content

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

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

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

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

http://docs.openstack.org/trunk/install-guide/install/apt/content/neutron-concepts.html

1. Review content.

http://docs.openstack.org/trunk/install-guide/install/apt/content/section_nova-networking.html

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

http://docs.openstack.org/trunk/install-guide/install/apt/content/nova-network-initial-network.html

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

http://docs.openstack.org/trunk/install-guide/install/apt/content/ch_horizon.html

1. Consider splitting concepts paragraph into separate section.

http://docs.openstack.org/trunk/install-guide/install/apt/content/dashboard-system-requirements.html

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

http://docs.openstack.org/trunk/install-guide/install/apt/content/install_dashboard.html

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.

http://docs.openstack.org/trunk/install-guide/install/yum/content/dashboard-sessions.html

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

http://docs.openstack.org/trunk/install-guide/install/apt/content/ch_cinder.html

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

http://docs.openstack.org/trunk/install-guide/install/apt/content/block-storage-service.html

1. Review content.

http://docs.openstack.org/trunk/install-guide/install/apt/content/cinder-controller.html

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?

http://docs.openstack.org/trunk/install-guide/install/apt/content/cinder-node.html

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?

http://docs.openstack.org/trunk/install-guide/install/apt/content/cinder-verify.html

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

http://docs.openstack.org/trunk/install-guide/install/apt/content/object-storage-service.html

1. Review content.

http://docs.openstack.org/trunk/install-guide/install/apt/content/object-storage-system-requirements.html

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

http://docs.openstack.org/trunk/install-guide/install/apt/content/object-storage-network-planning.html

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.

http://docs.openstack.org/trunk/install-guide/install/apt/content/example-object-storage-installation-architecture.html

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?

http://docs.openstack.org/trunk/install-guide/install/apt/content/installing-openstack-object-storage.html

1. Consider separating integrated installations from standalone installations.

http://docs.openstack.org/trunk/install-guide/install/apt/content/general-installation-steps-swift.html

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

http://docs.openstack.org/trunk/install-guide/install/apt/content/adding-proxy-server.html

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

http://docs.openstack.org/trunk/install-guide/install/apt/content/orchestration-service.html

1. Review content

http://docs.openstack.org/trunk/install-guide/install/apt/content/heat-install.html

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.

http://docs.openstack.org/trunk/install-guide/install/apt/content/metering-service.html

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

http://docs.openstack.org/trunk/install-guide/install/apt/content/ceilometer-install.html

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

1. Review content

http://docs.openstack.org/trunk/install-guide/install/apt/content/trove-install.html

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?

http://docs.openstack.org/trunk/install-guide/install/apt/content/trove-verify.html

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

http://docs.openstack.org/trunk/install-guide/install/apt/content/launch-instance-neutron.html

1. Add a note about SSH key passphrases.

http://docs.openstack.org/trunk/install-guide/install/apt/content/launch-instance-nova.html

1. Add a note about SSH key passphrases.