544 lines
21 KiB
XML
544 lines
21 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
|
<chapter version="5.0" xml:id="upstream_openstack"
|
|
xmlns="http://docbook.org/ns/docbook"
|
|
xmlns:xlink="http://www.w3.org/1999/xlink"
|
|
xmlns:xi="http://www.w3.org/2001/XInclude"
|
|
xmlns:ns5="http://www.w3.org/1999/xhtml"
|
|
xmlns:ns4="http://www.w3.org/2000/svg"
|
|
xmlns:ns3="http://www.w3.org/1998/Math/MathML"
|
|
xmlns:ns="http://docbook.org/ns/docbook">
|
|
<?dbhtml stop-chunking?>
|
|
|
|
<title>Upstream OpenStack</title>
|
|
|
|
<para>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.</para>
|
|
|
|
<section xml:id="get_help">
|
|
<title>Getting Help</title>
|
|
|
|
<para>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.<indexterm
|
|
class="singular">
|
|
<primary>mailing lists</primary>
|
|
</indexterm><indexterm class="singular">
|
|
<primary>OpenStack</primary>
|
|
|
|
<secondary>documentation</secondary>
|
|
</indexterm><indexterm class="singular">
|
|
<primary>help, resources for</primary>
|
|
</indexterm><indexterm class="singular">
|
|
<primary>troubleshooting</primary>
|
|
|
|
<secondary>getting help</secondary>
|
|
</indexterm><indexterm class="singular">
|
|
<primary>OpenStack community</primary>
|
|
|
|
<secondary>getting help from</secondary>
|
|
</indexterm></para>
|
|
|
|
<para>Your first port of call should be the official OpenStack
|
|
documentation, found on <link
|
|
xlink:href="http://docs.openstack.org"></link>. You can get questions
|
|
answered on <link xlink:href="http://ask.openstack.org"></link>.</para>
|
|
|
|
<para><link xlink:href="https://wiki.openstack.org/wiki/Mailing_Lists">Mailing lists</link> 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:</para>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><link xlink:href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack">General
|
|
list</link></term>
|
|
|
|
<listitem>
|
|
<para><emphasis>openstack@lists.openstack.org</emphasis>. The scope
|
|
of this list is the current state of OpenStack. This is a very
|
|
high-traffic mailing list, with many, many emails per day.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><link xlink:href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-operators">Operators
|
|
list</link></term>
|
|
|
|
<listitem>
|
|
<para><emphasis>openstack-operators@lists.openstack.org.</emphasis>
|
|
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.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><link xlink:href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev">Development
|
|
list</link></term>
|
|
|
|
<listitem>
|
|
<para><emphasis>openstack-dev@lists.openstack.org</emphasis>. The
|
|
scope of this list is the future state of OpenStack. This is a
|
|
high-traffic mailing list, with multiple emails per day.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
|
|
<para>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.</para>
|
|
|
|
<para><link xlink:href="https://wiki.openstack.org/wiki/IRC">Multiple IRC
|
|
channels</link> are available for general questions and developer
|
|
discussions. The general discussion channel is #openstack on
|
|
<emphasis>irc.freenode.net</emphasis>.</para>
|
|
</section>
|
|
|
|
<section xml:id="report_bugs">
|
|
<title>Reporting Bugs</title>
|
|
|
|
<para>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.<indexterm
|
|
class="singular">
|
|
<primary>maintenance/debugging</primary>
|
|
|
|
<secondary>reporting bugs</secondary>
|
|
</indexterm><indexterm class="singular">
|
|
<primary>bugs, reporting</primary>
|
|
</indexterm><indexterm class="singular">
|
|
<primary>OpenStack community</primary>
|
|
|
|
<secondary>reporting bugs</secondary>
|
|
</indexterm></para>
|
|
|
|
<para>All OpenStack projects use <link
|
|
xlink:href="https://launchpad.net/">Launchpad</link> for bug
|
|
tracking. You'll need to create an account on Launchpad before you can
|
|
submit a bug report.</para>
|
|
|
|
<para>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:</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>Report a bug in <link
|
|
xlink:href="https://bugs.launchpad.net/nova/+filebug/+login">nova</link>.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Report a bug in <link
|
|
xlink:href="https://bugs.launchpad.net/python-novaclient/+filebug/+login">python-novaclient</link>.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Report a bug in <link
|
|
xlink:href="https://bugs.launchpad.net/swift/+filebug/+login">swift</link>.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Report a bug in <link
|
|
xlink:href="https://bugs.launchpad.net/python-swiftclient/+filebug/+login">python-swiftclient</link>.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Report a bug in <link
|
|
xlink:href="https://bugs.launchpad.net/glance/+filebug/+login">glance</link>.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Report a bug in <link
|
|
xlink:href="https://bugs.launchpad.net/python-glanceclient/+filebug/+login">python-glanceclient</link>.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Report a bug in <link
|
|
xlink:href="https://bugs.launchpad.net/keystone/+filebug/+login">keystone</link>.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Report a bug in <link
|
|
xlink:href="https://bugs.launchpad.net/python-keystoneclient/+filebug/+login">python-keystoneclient</link>.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Report a bug in <link
|
|
xlink:href="https://bugs.launchpad.net/neutron/+filebug/+login">neutron</link>.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Report a bug in <link
|
|
xlink:href="https://bugs.launchpad.net/python-neutronclient/+filebug/+login">python-neutronclient</link>.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Report a bug in <link
|
|
xlink:href="https://bugs.launchpad.net/cinder/+filebug/+login">cinder</link>.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Report a bug in <link
|
|
xlink:href="https://bugs.launchpad.net/python-cinderclient/+filebug/+login">python-cinderclient</link>.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Report a bug in <link
|
|
xlink:href="https://bugs.launchpad.net/manila/+filebug/+login">manila</link>.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Report a bug in <link
|
|
xlink:href="https://bugs.launchpad.net/python-manilaclient/+filebug/+login">python-manilaclient</link>.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Report a bug in <link
|
|
xlink:href="https://bugs.launchpad.net/python-openstackclient/+filebug/+login">python-openstackclient</link>.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Report a bug in <link
|
|
xlink:href="https://bugs.launchpad.net/horizon/+filebug/+login">horizon</link>.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Report a bug with the <link
|
|
xlink:href="https://bugs.launchpad.net/openstack-manuals/+filebug/+login">documentation</link>.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Report a bug with the <link
|
|
xlink:href="https://bugs.launchpad.net/openstack-api-site/+filebug/+login">API documentation</link>.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<para>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:</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>The release, or milestone, or commit ID corresponding to the
|
|
software that you are running</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>The operating system and version where you've identified the
|
|
bug</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Steps to reproduce the bug, including what went wrong</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Description of the expected results instead of what you
|
|
saw</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Portions of your log files so that you include only relevant
|
|
excerpts</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<para>When you do this, the bug is created with:</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>Status: <emphasis>New</emphasis></para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<para>In the bug comments, you can contribute instructions on how to fix a
|
|
given bug, and set it to <emphasis>Triaged</emphasis>. Or you can directly
|
|
fix it: assign the bug to yourself, set it to <emphasis>In
|
|
progress</emphasis>, 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.</para>
|
|
|
|
<section xml:id="confirm_priority">
|
|
<title>Confirming and Prioritizing</title>
|
|
|
|
<para>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:</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>Status: <emphasis>Incomplete</emphasis></para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<para>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:</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>Status: <emphasis>Confirmed</emphasis></para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<para>Core developers also prioritize the bug, based on its
|
|
impact:</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>Importance: <Bug impact></para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<para>The bug impacts are categorized as follows:</para>
|
|
|
|
<?hard-pagebreak ?>
|
|
|
|
<orderedlist>
|
|
<listitem>
|
|
<para><emphasis>Critical</emphasis> if the bug prevents a key
|
|
feature from working properly (regression) for all users (or without
|
|
a simple workaround) or results in data loss</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><emphasis>High</emphasis> if the bug prevents a key feature
|
|
from working properly for some users (or with a workaround)</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><emphasis>Medium</emphasis> if the bug prevents a secondary
|
|
feature from working properly</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><emphasis>Low</emphasis> if the bug is mostly cosmetic</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><emphasis>Wishlist</emphasis> if the bug is not really a bug
|
|
but rather a welcome change in behavior</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
|
|
<para>If the bug contains the solution, or a patch, set the bug status
|
|
to <emphasis>Triaged</emphasis>.</para>
|
|
</section>
|
|
|
|
<section xml:id="bug_fixing">
|
|
<title>Bug Fixing</title>
|
|
|
|
<para>At this stage, a developer works on a fix. During that time, to
|
|
avoid duplicating the work, the developer should set:</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>Status: <emphasis>In Progress</emphasis></para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Assignee: <yourself></para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<para>When the fix is ready, the developer proposes a change and gets
|
|
the change reviewed.</para>
|
|
</section>
|
|
|
|
<section xml:id="after_change_is_accepted">
|
|
<title>After the Change Is Accepted</title>
|
|
|
|
<para>After the change is reviewed, accepted, and lands in master, it
|
|
automatically moves to:</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>Status: <emphasis>Fix Committed</emphasis></para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<para>When the fix makes it into a milestone or release branch, it
|
|
automatically moves to:</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>Milestone: Milestone the bug was fixed in</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Status: <emphasis>Fix Released</emphasis></para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</section>
|
|
</section>
|
|
|
|
<section xml:id="openstack_community">
|
|
<title>Join the OpenStack Community</title>
|
|
|
|
<para>Since you've made it this far in the book, you should consider
|
|
becoming an official individual member of the community and <link
|
|
xlink:href="https://www.openstack.org/join/">join the OpenStack
|
|
Foundation</link>. 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.<indexterm class="singular">
|
|
<primary>OpenStack community</primary>
|
|
|
|
<secondary>joining</secondary>
|
|
</indexterm></para>
|
|
</section>
|
|
|
|
<section xml:id="contribute_to_docs">
|
|
<title>How to Contribute to the Documentation</title>
|
|
|
|
<para>OpenStack documentation efforts encompass operator and administrator
|
|
docs, API docs, and user docs.<indexterm class="singular">
|
|
<primary>OpenStack community</primary>
|
|
|
|
<secondary>contributing to</secondary>
|
|
</indexterm></para>
|
|
|
|
<para>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.</para>
|
|
|
|
<para>Just like the code, <link
|
|
xlink:href="http://docs.openstack.org"></link> is updated constantly using
|
|
the Gerrit review system, with source stored in git.openstack.org in the <link
|
|
xlink:href="https://git.openstack.org/cgit/openstack/openstack-manuals/">openstack-manuals repository</link>
|
|
and the <link xlink:href="https://git.openstack.org/cgit/openstack/api-site/">api-site
|
|
repository</link>.</para>
|
|
|
|
<para>To review the documentation before it's published, go to the
|
|
OpenStack Gerrit server at <link
|
|
xlink:href="http://review.openstack.org"></link> and search for <link
|
|
xlink:href="https://review.openstack.org/#/q/status:open+project:openstack/openstack-manuals,n,z">project:openstack/openstack-manuals</link>
|
|
or <link
|
|
xlink:href="https://review.openstack.org/#/q/status:open+project:openstack/api-site,n,z">project:openstack/api-site</link>.</para>
|
|
|
|
<para>See the <link xlink:href="https://wiki.openstack.org/wiki/How_To_Contribute">How To Contribute
|
|
page on the wiki</link> for more information on the steps you need to take
|
|
to submit your first documentation review or change.</para>
|
|
</section>
|
|
|
|
<section xml:id="security_info">
|
|
<title>Security Information</title>
|
|
|
|
<para>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:<indexterm class="singular">
|
|
<primary>vulnerability tracking/management</primary>
|
|
</indexterm><indexterm class="singular">
|
|
<primary>security issues</primary>
|
|
|
|
<secondary>reporting/fixing vulnerabilities</secondary>
|
|
</indexterm><indexterm class="singular">
|
|
<primary>OpenStack community</primary>
|
|
|
|
<secondary>security information</secondary>
|
|
</indexterm></para>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>Vulnerability management</term>
|
|
|
|
<listitem>
|
|
<para>All vulnerabilities discovered by community members (or users)
|
|
can be reported to the team.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>Vulnerability tracking</term>
|
|
|
|
<listitem>
|
|
<para>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.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>Responsible disclosure</term>
|
|
|
|
<listitem>
|
|
<para>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.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
|
|
<para>We provide two ways to report issues to the OpenStack Vulnerability
|
|
Management Team, depending on how sensitive the issue is:</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>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.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>If the issue is extremely sensitive, send an encrypted email to
|
|
one of the team's members. Find their GPG keys at <link
|
|
xlink:href="http://www.openstack.org/projects/openstack-security/">OpenStack
|
|
Security</link>.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<para>You can find the full list of security-oriented teams you can join
|
|
at <link xlink:href="https://wiki.openstack.org/wiki/SecurityTeams">Security Teams</link>. The
|
|
vulnerability management process is fully documented at <link
|
|
xlink:href="https://wiki.openstack.org/wiki/VulnerabilityManagement">Vulnerability
|
|
Management</link>.</para>
|
|
</section>
|
|
|
|
<section xml:id="additional_info">
|
|
<title>Finding Additional Information</title>
|
|
|
|
<para>In addition to this book, there are many other sources of
|
|
information about OpenStack. The <link
|
|
xlink:href="http://www.openstack.org/">OpenStack website</link> is a good
|
|
starting point, with <link
|
|
xlink:href="http://docs.openstack.org/">OpenStack
|
|
Docs</link> and <link
|
|
xlink:href="http://developer.openstack.org/">OpenStack API Docs</link> providing
|
|
technical documentation about OpenStack. The <link
|
|
xlink:href="https://wiki.openstack.org/wiki/Main_Page">OpenStack wiki</link> contains a lot
|
|
of general information that cuts across the OpenStack projects, including
|
|
a list of <link xlink:href="https://wiki.openstack.org/wiki/OperationsTools">recommended
|
|
tools</link>. Finally, there are a number of blogs aggregated
|
|
at <link xlink:href="http://planet.openstack.org/">Planet
|
|
OpenStack</link>.<indexterm class="singular">
|
|
<primary>OpenStack community</primary>
|
|
|
|
<secondary>additional information</secondary>
|
|
</indexterm></para>
|
|
</section>
|
|
</chapter>
|