From cea7ec8d4bd9f93568eb2e9e05c306535f0ec292 Mon Sep 17 00:00:00 2001 From: Sean Dague Date: Fri, 5 Aug 2016 08:29:54 -0400 Subject: [PATCH] update front page of devstack docs The devstack docs have gotten a bit meandering so even the quick start guide doesn't get you to a working setup without referencing other pages. This attempts to pull this back in a bit. Change-Id: I608331cbdae9cbe4f3e8bd3814415af0390a54d0 --- doc/source/guides.rst | 68 +++++++++++ doc/source/index.rst | 250 ++++++++++++++++++---------------------- doc/source/site-map.rst | 21 ++++ 3 files changed, 198 insertions(+), 141 deletions(-) create mode 100644 doc/source/guides.rst create mode 100644 doc/source/site-map.rst diff --git a/doc/source/guides.rst b/doc/source/guides.rst new file mode 100644 index 0000000000..c2c7b9163a --- /dev/null +++ b/doc/source/guides.rst @@ -0,0 +1,68 @@ +Guides +====== + +.. warning:: + + The guides are point in time contributions, and may not always be + up to date with the latest work in devstack. + +Walk through various setups used by stackers + +.. toctree:: + :glob: + :maxdepth: 1 + + guides/single-vm + guides/single-machine + guides/lxc + guides/multinode-lab + guides/neutron + guides/devstack-with-nested-kvm + guides/nova + guides/devstack-with-lbaas-v2 + +All-In-One Single VM +-------------------- + +Run :doc:`OpenStack in a VM `. The VMs launched in your cloud will be slow as +they are running in QEMU (emulation), but it is useful if you don't have +spare hardware laying around. :doc:`[Read] ` + +All-In-One Single Machine +------------------------- + +Run :doc:`OpenStack on dedicated hardware ` This can include a +server-class machine or a laptop at home. +:doc:`[Read] ` + +All-In-One LXC Container +------------------------- + +Run :doc:`OpenStack in a LXC container `. Beneficial for intermediate +and advanced users. The VMs launched in this cloud will be fully accelerated but +not all OpenStack features are supported. :doc:`[Read] ` + +Multi-Node Lab +-------------- + +Setup a :doc:`multi-node cluster ` with dedicated VLANs for VMs & Management. +:doc:`[Read] ` + +DevStack with Neutron Networking +-------------------------------- + +Building a DevStack cluster with :doc:`Neutron Networking `. +This guide is meant for building lab environments with a dedicated +control node and multiple compute nodes. + +DevStack with KVM-based Nested Virtualization +--------------------------------------------- + +Procedure to setup :doc:`DevStack with KVM-based Nested Virtualization +`. With this setup, Nova instances +will be more performant than with plain QEMU emulation. + +Nova and devstack +-------------------------------- + +Guide to working with nova features :doc:`Nova and devstack `. diff --git a/doc/source/index.rst b/doc/source/index.rst index 68ec174f3a..c1302eb930 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -1,163 +1,131 @@ -DevStack -======== +.. Documentation Architecture for the devstack docs. + + It is really easy for online docs to meander over time as people + attempt to add the small bit of additional information they think + people need, into an existing information architecture. In order to + prevent that we need to be a bit strict as to what's on this front + page. + + This should *only* be the quick start narrative. Which should end + with 2 sections: what you can do with devstack once it's set up, + and how to go beyond this setup. Both should be a set of quick + links to other documents to let people explore from there. + +========== + DevStack +========== .. image:: assets/images/logo-blue.png DevStack is a series of extensible scripts used to quickly bring up a -complete OpenStack environment. It is used interactively as a -development environment and as the basis for much of the OpenStack -project's functional testing. +complete OpenStack environment based on the latest versions of +everything from git master. It is used interactively as a development +environment and as the basis for much of the OpenStack project's +functional testing. The source is available at ``__. -.. toctree:: - :glob: - :maxdepth: 1 +.. warning:: - overview - configuration - plugins - plugin-registry - faq - hacking + DevStack will make substantial changes to your system during + installation. Only run DevStack on servers or virtual machines that + are dedicated to this purpose. Quick Start ------------ +=========== -#. Select a Linux Distribution - - Only Ubuntu 14.04 (Trusty), Fedora 22 (or Fedora 23) and CentOS/RHEL - 7 are documented here. OpenStack also runs and is packaged on other - flavors of Linux such as OpenSUSE and Debian. - -#. Install Selected OS - - In order to correctly install all the dependencies, we assume a - specific minimal version of the supported distributions to make it as - easy as possible. We recommend using a minimal install of Ubuntu or - Fedora server in a VM if this is your first time. - -#. Download DevStack - - :: - - git clone https://git.openstack.org/openstack-dev/devstack - - The ``devstack`` repo contains a script that installs OpenStack and - templates for configuration files - -#. Configure - - We recommend at least a :ref:`minimal-configuration` be set up. - -#. Add Stack User - - Devstack should be run as a non-root user with sudo enabled - (standard logins to cloud images such as "ubuntu" or "cloud-user" - are usually fine). - - You can quickly create a separate `stack` user to run DevStack with - - :: - - devstack/tools/create-stack-user.sh; su stack - -#. Start the install, this will take a few minutes. - - :: - - cd devstack; ./stack.sh - -Guides -====== - -Walk through various setups used by stackers - -.. toctree:: - :glob: - :maxdepth: 1 - - guides/single-vm - guides/single-machine - guides/lxc - guides/multinode-lab - guides/neutron - guides/devstack-with-nested-kvm - guides/nova - guides/devstack-with-lbaas-v2 - -All-In-One Single VM --------------------- - -Run :doc:`OpenStack in a VM `. The VMs launched in your cloud will be slow as -they are running in QEMU (emulation), but it is useful if you don't have -spare hardware laying around. :doc:`[Read] ` - -All-In-One Single Machine -------------------------- - -Run :doc:`OpenStack on dedicated hardware ` This can include a -server-class machine or a laptop at home. -:doc:`[Read] ` - -All-In-One LXC Container -------------------------- - -Run :doc:`OpenStack in a LXC container `. Beneficial for intermediate -and advanced users. The VMs launched in this cloud will be fully accelerated but -not all OpenStack features are supported. :doc:`[Read] ` - -Multi-Node Lab --------------- - -Setup a :doc:`multi-node cluster ` with dedicated VLANs for VMs & Management. -:doc:`[Read] ` - -DevStack with Neutron Networking --------------------------------- - -Building a DevStack cluster with :doc:`Neutron Networking `. -This guide is meant for building lab environments with a dedicated -control node and multiple compute nodes. - -DevStack with KVM-based Nested Virtualization ---------------------------------------------- - -Procedure to setup :doc:`DevStack with KVM-based Nested Virtualization -`. With this setup, Nova instances -will be more performant than with plain QEMU emulation. - -Nova and devstack --------------------------------- - -Guide to working with nova features :doc:`Nova and devstack `. - -DevStack Documentation -====================== - -Overview --------- - -:doc:`An overview of DevStack goals and priorities ` - -Configuration +Install Linux ------------- -:doc:`Configuring and customizing the stack ` +Start with a clean and minimal install of a Linux system. Devstack +attempts to support Ubuntu 14.04/16.04, Fedora 23/24, CentOS/RHEL 7, +as well as Debian and OpenSUSE. -Plugins +If you do not have a preference, Ubuntu 16.04 is the most tested, and +will probably go the smoothest. + +Download DevStack +----------------- + +:: + + git clone https://git.openstack.org/openstack-dev/devstack + +The ``devstack`` repo contains a script that installs OpenStack and +templates for configuration files + +Create a local.conf +------------------- + +Create a ``local.conf`` file with 4 passwords preset + +:: + + [[local|localrc]] + ADMIN_PASSWORD=secret + DATABASE_PASSWORD=$ADMIN_PASSWORD + RABBIT_PASSWORD=$ADMIN_PASSWORD + SERVICE_PASSWORD=$ADMIN_PASSWORD + +This is the minimum required config to get started with DevStack. + +Add Stack User +-------------- + +Devstack should be run as a non-root user with sudo enabled +(standard logins to cloud images such as "ubuntu" or "cloud-user" +are usually fine). + +You can quickly create a separate `stack` user to run DevStack with + +:: + + devstack/tools/create-stack-user.sh; su stack + +Start the install +----------------- + +:: + + cd devstack; ./stack.sh + +This will take a 15 - 20 minutes, largely depending on the speed of +your internet connection. Many git trees and packages will be +installed during this process. + +Profit! ------- -:doc:`Extending DevStack with new features ` +You now have a working DevStack! Congrats! -FAQ ---- +Your devstack will have installed ``keystone``, ``glance``, ``nova``, +``cinder``, ``neutron``, and ``horizon``. Floating IPs will be +available, guests have access to the external world. -:doc:`The DevStack FAQ ` +You can access horizon to experience the web interface to +OpenStack, and manage vms, networks, volumes, and images from +there. -Contributing ------------- +You can ``source openrc`` in your shell, and then use the +``openstack`` command line tool to manage your devstack. -:doc:`Pitching in to make DevStack a better place ` +You can ``cd /opt/stack/tempest`` and run tempest tests that have +been configured to work with your devstack. +Going further +------------- + +Learn more about our :doc:`configuration system ` to +customize devstack for your needs. + +Read :doc:`guides ` for specific setups people have (note: +guides are point in time contributions, and may not always be kept +up to date to the latest devstack). + +Enable :doc:`devstack plugins ` to support additional +services, features, and configuration not present in base devstack. + +Get :doc:`the big picture ` of what we are trying to do +with devstack, and help us by :doc:`contributing to the project +`. diff --git a/doc/source/site-map.rst b/doc/source/site-map.rst new file mode 100644 index 0000000000..480d6aaf5e --- /dev/null +++ b/doc/source/site-map.rst @@ -0,0 +1,21 @@ +:orphan: + +.. the TOC on the front page actually makes the document a lot more + confusing. This lets us bury a toc which we can link in when + appropriate. + +========== + Site Map +========== + +.. toctree:: + :glob: + :maxdepth: 3 + + overview + configuration + plugins + plugin-registry + faq + hacking + guides