Latest revision as of 02:25, 6 November 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. (Joseph Robinson) DONE
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. (Andreas Jaeger) DONE
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 guide for training guides: https://etherpad.openstack.org/p/training-guides-install-guide
15. Replace auth_port and auth_protocol with identity_uri, and auth_host with auth_uri

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 (Matt Kassawara / Joseph Robinson) DONE

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

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

1. Update password list

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

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 (Matt Kassawara) DONE

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

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

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 (Matt Kassawara) DONE

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

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

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 (Matt Kassawara) DONE

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 (Matt Kassawara) DONE

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) DONE

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) DONE

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) DONE

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) DONE

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.

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 (Darren Chan)

1. Do we need "memcached" for a basic installation?
2. Change the note removing Ubuntu dashboard theme from required to optional, based on the user's experience
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 (Joseph Robinson) DONE

1. Review content.

http://docs.openstack.org/trunk/install-guide/install/apt/content/cinder-controller.html (Darren Chan / 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.
2. Ubuntu: Also install "python-cinderclient" package?

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

1. Reorder instructions. DONE
2. Remove openstack-config commands DONE
3. Replace auth_port and auth_protocol with identity_uri, and auth_host with auth_uri DONE
4. Add diagram and configuration for additional node.
5. Do cinder volume nodes require direct access to the database?
6. Ubuntu: Should we explicitly install the iscsi utilities?

http://docs.openstack.org/trunk/install-guide/install/apt/content/cinder-verify.html (Darren Chan) CHANGE IGNORED :This is the demo-openrc.sh file referenced in http://docs.openstack.org/trunk/install-guide/install/zypper/content/ch_clients_openrc_files.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 (Darren Chan)

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 (Darren Chan / 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.

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 (Darren Chan/ Matt Kassawara) DONE

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/ceilometer-install-nova.html (Darren Chan)

1. Stuff

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

1. Review content

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

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 (Darren Chan)

1. Review content
2. 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.