From 10b9f46dca8bc7dab16f6831795d5a0f2ca97dcc Mon Sep 17 00:00:00 2001 From: daz Date: Fri, 17 Jun 2016 17:00:03 +1000 Subject: [PATCH] [ops-guide] Remove duplicated content 1. Remove upstream section since this is documented in https://wiki.openstack.org/wiki/ 2. Remove DevStack installation instructions since it is documented in https://devstack.org Change-Id: I9ba8e6147bf783c8de5460c02870677b35f4c41e Implements: blueprint improve-ops-guide --- doc/ops-guide/source/operations.rst | 1 - .../source/ops_customize_development.rst | 136 +------- doc/ops-guide/source/ops_upstream.rst | 322 ------------------ doc/ops-guide/source/preface.rst | 5 - 4 files changed, 1 insertion(+), 463 deletions(-) delete mode 100644 doc/ops-guide/source/ops_upstream.rst diff --git a/doc/ops-guide/source/operations.rst b/doc/ops-guide/source/operations.rst index 4372eba326..db2450e802 100644 --- a/doc/ops-guide/source/operations.rst +++ b/doc/ops-guide/source/operations.rst @@ -36,6 +36,5 @@ problem. ops_logging_monitoring.rst ops_backup_recovery.rst ops_customize.rst - ops_upstream.rst ops_advanced_configuration.rst ops_upgrades.rst diff --git a/doc/ops-guide/source/ops_customize_development.rst b/doc/ops-guide/source/ops_customize_development.rst index 47a4aeb38b..6cd3106038 100644 --- a/doc/ops-guide/source/ops_customize_development.rst +++ b/doc/ops-guide/source/ops_customize_development.rst @@ -7,139 +7,5 @@ essentially a collection of shell scripts and configuration files that builds an OpenStack development environment for you. You use it to create such an environment for developing a new feature. -You can find all of the documentation at the +For more information on installing DevStack, see the `DevStack `_ website. - -**To run DevStack on an instance in your OpenStack cloud:** - -#. Boot an instance from the dashboard or the nova command-line interface - (CLI) with the following parameters: - - - Name: devstack - - - Image: Ubuntu 14.04 LTS - - - Memory Size: 4 GB RAM - - - Disk Size: minimum 5 GB - - If you are using the ``nova`` client, specify :option:`--flavor 3` for the - :command:`nova boot` command to get adequate memory and disk sizes. - -#. Log in and set up DevStack. Here's an example of the commands you can - use to set up DevStack on a virtual machine: - - #. Log in to the instance: - - .. code-block:: console - - $ ssh username@my.instance.ip.address - - #. Update the virtual machine's operating system: - - .. code-block:: console - - # apt-get update - - #. Install git: - - .. code-block:: console - - # apt-get install git - - #. Clone the ``devstack`` repository: - - .. code-block:: console - - $ git clone https://git.openstack.org/openstack-dev/devstack - - #. Change to the ``devstack`` repository: - - .. code-block:: console - - $ cd devstack - -#. (Optional) If you've logged in to your instance as the root user, you - must create a "stack" user; otherwise you'll run into permission issues. - If you've logged in as a user other than root, you can skip these steps: - - #. Run the DevStack script to create the stack user: - - .. code-block:: console - - # tools/create-stack-user.sh - - #. Give ownership of the ``devstack`` directory to the stack user: - - .. code-block:: console - - # chown -R stack:stack /root/devstack - - #. Set some permissions you can use to view the DevStack screen later: - - .. code-block:: console - - # chmod o+rwx /dev/pts/0 - - #. Switch to the stack user: - - .. code-block:: console - - $ su stack - -#. Edit the ``local.conf`` configuration file that controls what DevStack - will deploy. Copy the example ``local.conf`` file at the end of this - section (:ref:`local.conf`): - - .. code-block:: console - - $ vim local.conf - -#. Run the stack script that will install OpenStack: - - .. code-block:: console - - $ ./stack.sh - -#. When the stack script is done, you can open the screen session it - started to view all of the running OpenStack services: - - .. code-block:: console - - $ screen -r stack - -#. Press ``Ctrl+A`` followed by 0 to go to the first ``screen`` window. - -.. note:: - - - The ``stack.sh`` script takes a while to run. Perhaps you can - take this opportunity to `join the OpenStack - Foundation `__. - - - ``Screen`` is a useful program for viewing many related services - at once. For more information, see the `GNU screen quick - reference `__. - -Now that you have an OpenStack development environment, you're free to -hack around without worrying about damaging your production deployment. -:ref:`local.conf` provides a working environment for running -Identity service, Compute service, Block Storage service, Image service, -Dashboard, and Object Storage service as the starting point. - -.. _local.conf: - -local.conf -~~~~~~~~~~ - -.. code-block:: bash - - [[local|localrc]] - FLOATING_RANGE=192.168.1.224/27 - FIXED_RANGE=10.11.12.0/24 - FIXED_NETWORK_SIZE=256 - FLAT_INTERFACE=eth0 - ADMIN_PASSWORD=supersecret - DATABASE_PASSWORD=iheartdatabases - RABBIT_PASSWORD=flopsymopsy - SERVICE_PASSWORD=iheartksl - SERVICE_TOKEN=xyzpdqlazydog diff --git a/doc/ops-guide/source/ops_upstream.rst b/doc/ops-guide/source/ops_upstream.rst deleted file mode 100644 index 618335c091..0000000000 --- a/doc/ops-guide/source/ops_upstream.rst +++ /dev/null @@ -1,322 +0,0 @@ -================== -Upstream OpenStack -================== - -OpenStack is founded on a thriving community that is a source of help -and welcomes your contributions. This chapter details some of the ways -you can interact with the others involved. - -Getting Help -~~~~~~~~~~~~ - -There are several avenues available for seeking assistance. The quickest -way is to help the community help you. Search the Q&A sites, mailing -list archives, and bug lists for issues similar to yours. If you can't -find anything, follow the directions for reporting bugs or use one of -the channels for support, which are listed below. - -Your first port of call should be the official OpenStack documentation, -found on http://docs.openstack.org. You can get questions answered on -http://ask.openstack.org. - -`Mailing lists `_ are -also a great place to get help. The wiki page has more information about -the various lists. As an operator, the main lists you should be aware of -are: - -`General list `_ - *openstack@lists.openstack.org*. - The scope of this list is the current state of OpenStack. - This is a high-traffic mailing list, with multiple emails per day. - -`Operators list `_ - *openstack-operators@lists.openstack.org*. - This list is intended for discussion among existing OpenStack cloud - operators, such as yourself. Currently, - this list is relatively low traffic, on the order of one email a day. - -`Development list `_ - *openstack-dev@lists.openstack.org*. - The scope of this list is the future state of OpenStack. - This is a very high-traffic mailing list, with many, many emails per day. - -We recommend that you subscribe to the general list and the operator -list, although you must set up filters to manage the volume for the -general list. You'll also find links to the mailing list archives on the -mailing list wiki page, where you can search through the discussions. - -`Multiple IRC channels `_ are -available for general questions and developer discussions. The general -discussion channel is #openstack on *irc.freenode.net*. - -Reporting Bugs -~~~~~~~~~~~~~~ - -As an operator, you are in a very good position to report unexpected -behavior with your cloud. Since OpenStack is flexible, you may be the -only individual to report a particular issue. Every issue is important -to fix, so it is essential to learn how to easily submit a bug -report. - -All OpenStack projects use `Launchpad `_ -for bug tracking. You'll need to create an account on Launchpad before you -can submit a bug report. - -Once you have a Launchpad account, reporting a bug is as simple as -identifying the project or projects that are causing the issue. -Sometimes this is more difficult than expected, but those working on the -bug triage are happy to help relocate issues if they are not in the -right place initially: - -- Report a bug in - `nova `_. - -- Report a bug in - `python-novaclient `_. - -- Report a bug in - `swift `_. - -- Report a bug in - `python-swiftclient `_. - -- Report a bug in - `glance `_. - -- Report a bug in - `python-glanceclient `_. - -- Report a bug in - `keystone `_. - -- Report a bug in - `python-keystoneclient `_. - -- Report a bug in - `neutron `_. - -- Report a bug in - `python-neutronclient `_. - -- Report a bug in - `cinder `_. - -- Report a bug in - `python-cinderclient `_. - -- Report a bug in - `manila `_. - -- Report a bug in - `python-manilaclient `_. - -- Report a bug in - `python-openstackclient `_. - -- Report a bug in - `horizon `_. - -- Report a bug with the - `documentation `_. - -- Report a bug with the `API - documentation `_. - -To write a good bug report, the following process is essential. First, -search for the bug to make sure there is no bug already filed for the -same issue. If you find one, be sure to click on "This bug affects X -people. Does this bug affect you?" If you can't find the issue, then -enter the details of your report. It should at least include: - -- The release, or milestone, or commit ID corresponding to the software - that you are running - -- The operating system and version where you've identified the bug - -- Steps to reproduce the bug, including what went wrong - -- Description of the expected results instead of what you saw - -- Portions of your log files so that you include only relevant excerpts - -When you do this, the bug is created with: - -- Status: *New* - -In the bug comments, you can contribute instructions on how to fix a -given bug, and set it to *Triaged*. Or you can directly fix it: assign -the bug to yourself, set it to *In progress*, branch the code, implement -the fix, and propose your change for merging. But let's not get ahead of -ourselves; there are bug triaging tasks as well. - -Confirming and Prioritizing ---------------------------- - -This stage is about checking that a bug is real and assessing its -impact. Some of these steps require bug supervisor rights (usually -limited to core teams). If the bug lacks information to properly -reproduce or assess the importance of the bug, the bug is set to: - -- Status: *Incomplete* - -Once you have reproduced the issue (or are 100 percent confident that -this is indeed a valid bug) and have permissions to do so, set: - -- Status: *Confirmed* - -Core developers also prioritize the bug, based on its impact: - -- Importance: - -The bug impacts are categorized as follows: - -#. *Critical* if the bug prevents a key feature from working properly - (regression) for all users (or without a simple workaround) or - results in data loss - -#. *High* if the bug prevents a key feature from working properly for - some users (or with a workaround) - -#. *Medium* if the bug prevents a secondary feature from working - properly - -#. *Low* if the bug is mostly cosmetic - -#. *Wishlist* if the bug is not really a bug but rather a welcome change - in behavior - -If the bug contains the solution, or a patch, set the bug status to -*Triaged*. - -Bug Fixing ----------- - -At this stage, a developer works on a fix. During that time, to avoid -duplicating the work, the developer should set: - -- Status: *In Progress* - -- Assignee: - -When the fix is ready, the developer proposes a change and gets the -change reviewed. - -After the Change Is Accepted ----------------------------- - -After the change is reviewed, accepted, and lands in master, it -automatically moves to: - -- Status: *Fix Committed* - -When the fix makes it into a milestone or release branch, it -automatically moves to: - -- Milestone: Milestone the bug was fixed in - -- Status: \ *Fix Released* - -Join the OpenStack Community -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Since you've made it this far in the book, you should consider becoming -an official individual member of the community and `join the OpenStack -Foundation `_. The OpenStack -Foundation is an independent body providing shared resources to help -achieve the OpenStack mission by protecting, empowering, and promoting -OpenStack software and the community around it, including users, -developers, and the entire ecosystem. We all share the responsibility to -make this community the best it can possibly be, and signing up to be a -member is the first step to participating. Like the software, individual -membership within the OpenStack Foundation is free and accessible to -anyone. - -How to Contribute to the Documentation -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -OpenStack documentation efforts encompass operator and administrator -docs, API docs, and user docs. - -The genesis of this book was an in-person event, but now that the book -is in your hands, we want you to contribute to it. OpenStack -documentation follows the coding principles of iterative work, with bug -logging, investigating, and fixing. - -Just like the code, http://docs.openstack.org is updated constantly -using the Gerrit review system, with source stored in git.openstack.org -in the `openstack-manuals -repository `_ -and the `api-site -repository `_. - -To review the documentation before it's published, go to the OpenStack -Gerrit server at \ http://review.openstack.org and search for -`project:openstack/openstack-manuals `_ -or -`project:openstack/api-site `_. - -See the `How To Contribute page on the -wiki `_ for more -information on the steps you need to take to submit your first -documentation review or change. - -Security Information -~~~~~~~~~~~~~~~~~~~~ - -As a community, we take security very seriously and follow a specific -process for reporting potential issues. We vigilantly pursue fixes and -regularly eliminate exposures. You can report security issues you -discover through this specific process. The OpenStack Vulnerability -Management Team is a very small group of experts in vulnerability -management drawn from the OpenStack community. The team's job is -facilitating the reporting of vulnerabilities, coordinating security -fixes and handling progressive disclosure of the vulnerability -information. Specifically, the team is responsible for the following -functions: - -Vulnerability management - All vulnerabilities discovered by community members (or users) can - be reported to the team. - -Vulnerability tracking - The team will curate a set of vulnerability related issues in the - issue tracker. Some of these issues are private to the team and the - affected product leads, but once remediation is in place, all - vulnerabilities are public. - -Responsible disclosure - As part of our commitment to work with the security community, the - team ensures that proper credit is given to security researchers who - responsibly report issues in OpenStack. - -We provide two ways to report issues to the OpenStack Vulnerability -Management Team, depending on how sensitive the issue is: - -- Open a bug in Launchpad and mark it as a "security bug." This makes - the bug private and accessible to only the Vulnerability Management - Team. - -- If the issue is extremely sensitive, send an encrypted email to one - of the team's members. Find their GPG keys at `OpenStack - Security `_. - -You can find the full list of security-oriented teams you can join at -`Security Teams `_. The -vulnerability management process is fully documented at `Vulnerability -Management `_. - -Finding Additional Information -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -In addition to this book, there are many other sources of information -about OpenStack. The `OpenStack website `_ -is a good starting point, with -`OpenStack Docs `_ and `OpenStack API -Docs `_ providing technical -documentation about OpenStack. -The `OpenStack wiki `_ -contains a lot of general information that cuts across the OpenStack -projects, including a list of -`recommended tools `_. -Finally, there are a number of blogs aggregated at -`Planet OpenStack `_. diff --git a/doc/ops-guide/source/preface.rst b/doc/ops-guide/source/preface.rst index fb4a445010..18a9aa0202 100644 --- a/doc/ops-guide/source/preface.rst +++ b/doc/ops-guide/source/preface.rst @@ -266,11 +266,6 @@ OpenStack clouds. this chapter describes how to use DevStack to write custom middleware or a custom scheduler to rebalance your resources. -:doc:`ops_upstream` - Because OpenStack is so, well, open, this chapter is dedicated to - helping you navigate the community and find out where you can help - and where you can get help. - :doc:`ops_advanced_configuration` Much of OpenStack is driver-oriented, so you can plug in different solutions to the base set of services. This chapter describes some