Newton Installation Guide¶

Scope of basic install guide¶

The content of the basic install guide will cover the infrastructure and centralized projects that every cloud needs. This includes the defcore projects defined as starter-kit:compute plus a few others:

• Compute service (nova): Part of starter-kit:compute.
• Image service (glance): Part of starter-kit:compute.
• Identity service (keystone): Part of starter-kit:compute.
• Networking service (neutron): Part of starter-kit:compute.
• Block storage service (cinder): Part of current install guide and expected by most users.
• Dashboard (horizon): Part of current install guide and expected by most users.

No further projects will be added to the guide unless they are required by one of the existing projects or generally required to run an OpenStack based cloud.

The documentation team updates and tests the basic install guide for each release.

The install guide will be enhanced to link to additional project specific install guides. For this, it will have in a separate chapter for each official project a small section where each official project can give a short summary of their project together with a link to their own install guide. The chapter will also explain that all these projects are first-class citizens of the big tent of OpenStack.

For example, Orchestration could store their install guide in the heat repository, and publish to http://docs.openstack.org/project-install-guide/mitaka/orchestration/ .

Then the chapter “Additional projects” would contain a small section to introduce the service and link to it:

Orchestration service (heat)
============================

The Orchestration service ...

Installation is documented at
http://docs.openstack.org/project-install-guide/mitaka/orchestration
.

Docs.openstack.org index¶

The project specific install guides will be listed not only in the install guide but also be found from the docs.openstack.org web page. An exact location will need to be found based on the number of guides.

Alternatives¶

• Packaged install guides separated out, with no single-sourced install guide: each distribution publishes their own installation guide. These guides can be published to docs.openstack.org/install or to a web domain they own, sourced and reviewed from their own repositories with their teams. These teams can set their own publishing schedule. This alternative solution does not address the project teams needs, but alleviates the resource drain on a centralized docs team.

• Stop writing package-based install guides in the OpenStack git namespace entirely. Instead, have a central team write a starter-kit-based guide that describes the multiple available deployment options and publish to docs.openstack.org. This solution may be already available when readers browse the distro marketplace at https://www.openstack.org/marketplace/distros/.

• Each project team can write an “installation from source” installation guide that includes all the basic project infrastructure set up.

• Change scope of install guide, add a few more or less projects as proposed in this spec to it. This does not address the current single- sourcing with packages problem described, however.

• Status quo: One central install guide that is maintained by the documentation team and no project specific guides for those projects that are not part of the central guide. This approach does not scale unless we receive a commitment of resources from each project in the installation guide.

• One central guide that is reviewed by the documentation team - like today - and only projects are documented when the project team has committed writing, testing, and updating the chapter.

  This does not scale since reviewing would still be done by the documentation team. Experience in the past has shown that project teams need to be reminded of their commitment, so in the end the documentation team would play a large coordination and shepherding role for such a large guide - instead of following the enablement role that is sought by this proposal.

Assignee(s)¶

• Lana Brindley (loquacities) - Docs PTL
• Andreas Jaeger (AJaeger) - Infrastructure
• Install Guide Speciality Team

Work Items¶

• Update the title (what to?) to reflect that it is for training and not production, and add preamble to explain that purpose.
• Document from packages to best use existing content, but continue to revisit this problem over time, as more data emerges about which installation method users prefer.
• Edit the existing content so that it uses manual configuration only.
• Create scripts that can be run and automatically tested and include snippets of these scripts verbatim in the guide. This will accelerate testing of the guide.
• Create a ‘cookie cutter’ template that can be used for all services (AJaeger): https://review.openstack.org/#/c/314229/
• Document the process of adding a big tent project under the new governance, including what tests and dependencies are required.
• Move Shared File Systems (Manila), Object Storage (Swift), Orchestration (Heat), Telemetry (Ceilometer), Database (Trove) to project repositories and link them in the “Additional projects” chapter.