644 lines
21 KiB
ReStructuredText
644 lines
21 KiB
ReStructuredText
|
||
=====================================================
|
||
Documentation re-org and user documentation framework
|
||
=====================================================
|
||
|
||
This specification proposes changes to the structure of the StarlingX
|
||
documentation to make it easier for new contributors and users to find
|
||
the information they need. We are also proposing a number of new
|
||
documents to cover gaps in the current documentation set. This spec
|
||
defines the proposed new structure of the stx.docs repo and includes
|
||
links to the Storyboard entries for the new documents proposed. The
|
||
new documents needed have been prioritized by the Docs team to allow for
|
||
the implementation to occur over time.
|
||
|
||
Story board entries for the numerous SB entries proposed here will
|
||
be created once the document is close to approval.
|
||
|
||
Problem description
|
||
===================
|
||
|
||
The StarlingX documentation structure can be improved to provide more
|
||
information for new users and contributors, as well as providing additional
|
||
reference information for more experienced users. It can also be
|
||
improved to make it easier for users and contributors to navigate the
|
||
document hierarchy so they can find what they need.
|
||
|
||
Use Cases
|
||
=========
|
||
|
||
1. As a new user, I would like to learn the basics about StarlingX
|
||
so I can plan and complete an evaluation of the software.
|
||
2. As a user, I would like to learn how to deploy, install and run
|
||
StarlingX, so I can successfully deploy Starlingx for my Edge Cloud
|
||
applications.
|
||
3. As a user administering a StarlingX edge cloud deployment, I would like
|
||
to learn how to use all of the features of StarlingX and have all of
|
||
the API and CLI interfaces documented, so I can manage my
|
||
StarlingX Edge Cloud.
|
||
4. As a new contributor, I would like to learn about how to contribute
|
||
to the StarlingX project, so that my contributions are accepted.
|
||
5. As a new contributor, I would like to learn about the process
|
||
for accessing the StarlingX source code and building it from source, so
|
||
I can make changes and test them.
|
||
6. As a contributor, I would like to learn about the architecture of
|
||
StarlingX and the project’s development process, so I can contribute to
|
||
the project more effectively.
|
||
|
||
Proposed Change
|
||
===============
|
||
|
||
This section describes the changes to be made to the documentation. The
|
||
changes are broken down into multiple stories each of which has a
|
||
priority as proposed by the Docs team.
|
||
|
||
New landing page
|
||
----------------
|
||
|
||
We propose to change the StarlingX documentation hierarchy on
|
||
docs.starlingx.io from this:
|
||
|
||
- Installation Guide
|
||
- Developer Guide
|
||
- Project Specifications
|
||
- REST API Reference
|
||
- Release Notes
|
||
- Contribute
|
||
|
||
To this:
|
||
|
||
- Introduction to StarlingX
|
||
- Deployment Guides
|
||
- Installation Guides
|
||
- Operation Guides
|
||
- Contributor Guides
|
||
- Releases and Release Notes
|
||
- Developer Resources
|
||
|
||
Each of the new sections in the document hierarchy is described below.
|
||
Note that we are separating Deployment from Installation. We define
|
||
Deployment as all the steps needed starting from empty racks in the
|
||
data center to a running StarlingX instance. Installation is defined
|
||
as installing the software and is a subset of Deployment. Both sets
|
||
of documents will leverage content from the existing StarlingX documentation.
|
||
|
||
SB entry: 2005000
|
||
Priority: VH - release gating
|
||
|
||
Introduction to StarlingX
|
||
-------------------------
|
||
|
||
This new page in the document tree is a landing page is intended
|
||
to be a Quick Start for people who are new to StarlingX. It contains
|
||
links to the following documents:
|
||
|
||
- StarlingX Project Introduction
|
||
- StarlingX for Kubernetes Users
|
||
- StarlingX for OpenStack Users
|
||
- StarlingX in a Box
|
||
- StarlingX Software Evaluation Guide
|
||
- Roadmap to StarlingX Documentation
|
||
|
||
SB entry: 2005001
|
||
Priority: VH - Release gating
|
||
|
||
The following documents are included in this section of the documentation.
|
||
|
||
**StarlingX Project Introduction (NEW)**
|
||
This document should start with a project overview with
|
||
respect to objectives,
|
||
capabilities, basic approaches. Introduce the concept of base
|
||
Kubernetes Cluster + optional OpenStack Cloud Application. Introduce
|
||
the various use cases for StarlingX and the available deployment
|
||
options. The document should include a link to the Release page,
|
||
noting that pre-built and tested images are available.
|
||
SB entry: 2005002
|
||
Priority: VH - release gating
|
||
|
||
**StarlingX for Kubernetes Users (NEW)**
|
||
This document should describe the Kubernetes solution installed
|
||
and supported by StarlingX; e.g. what Kubernetes services are
|
||
included, what networking options, what container runtime
|
||
options, what storage solutions and the local registry. It should
|
||
highlight the advantages of the way that StarlingX configures and
|
||
uses Kubernetes as opposed to standard Kubernetes.
|
||
SB entry: TBD
|
||
Priority: H
|
||
|
||
**StarlingX for OpenStack Users (NEW)**
|
||
This document shall describe the OpenStack solution installed and
|
||
supported by StarlingX; e.g. what OpenStack Services are supported,
|
||
what Neutron backends are supported and what storage backends are
|
||
supported. This document shall highlight the advantages of the way
|
||
that StarlingX configures and uses OpenStack as opposed to standard
|
||
OpenStack.
|
||
SB entry: TBD
|
||
Priority: H
|
||
|
||
**StarlingX in a Box (NEW)**
|
||
This doc will describe how to boot and run
|
||
“StarlingX in a Box” (SIAB). Once we actually create
|
||
it (SB 2004811). The document should take users through
|
||
the process of bringing OpenStack services
|
||
up and show them some basic commands
|
||
such as create VM, load image into VM, start/stop VM and other
|
||
similar commands. It should cover how to bring up StarlingX
|
||
Kubernetes, the basic K8S commands e.g. create a container, create
|
||
a service, launching a container application with a helm chart.
|
||
The challenge will be to not over document things documented elsewhere
|
||
or familiar to experienced OpenStack or K8S users, while
|
||
guiding less experienced users to performing real world tasks
|
||
in StarlingX. The team creating StarlingX in a Box may decide
|
||
to create an image with both the OpenStack and Kubernetes services
|
||
already up and running, in which case we don't need to document
|
||
the bring-up process here.
|
||
SB entry: 2005003
|
||
Priority: VH - release gating
|
||
|
||
**StarlingX Software Evaluation Guide (NEW)**
|
||
This is a new document that describes the key features of StarlingX
|
||
that we expect Edge Cloud users to be interested in, and how to
|
||
set up and operate a StarlingX system to showcase them. Without
|
||
over-documenting features already covered elsewhere - the goal of
|
||
this document is to be an appetizer and not the main course.
|
||
It should also describe
|
||
basic evaluation use cases and how to implement them in
|
||
StarlingX. The Document can start by directing evaluators to
|
||
the "StarlingX in a Box" document and then build off of that
|
||
to showcase more advanced features. It should call out the
|
||
open source functional and
|
||
performance test suites (once they exist) and how to run them.
|
||
The document’s main goal is to show users who are "kicking the tires"
|
||
of StarlingX how to use the key
|
||
differentiating features of StarlingX and guide them to a
|
||
very positive evaluation.
|
||
SB entry: TBD
|
||
Priority: M
|
||
|
||
**Roadmap to the StarlingX Documentation (New)**
|
||
This new document provides the reader with a brief overview of
|
||
the entire documentation set. It could be based on use cases
|
||
listed above e.g. “if you are a dev looking to contribute, you
|
||
should read X, Y and Z. If you are an operator planning a
|
||
deployment read A & B.". The contents of this spec itself
|
||
may be a good starting place for this document.
|
||
SB entry: TBD
|
||
Priority: H
|
||
|
||
Deployment Guides
|
||
------------------
|
||
|
||
This is a new landing page in the document hierarchy. The deployment
|
||
options can be defined on the landing page and/or in the Deployment Options
|
||
page - a brief version on the landign page with full details in the Options
|
||
page is suggested. The landing page contains
|
||
links to the following documents:
|
||
|
||
- StarlingX Deployment Planning
|
||
- StarlingX Deployment Options
|
||
- All-in-one Simplex Deployment Guide
|
||
- All-in-one Duplex Deployment Guide
|
||
- All-in-one Duplex with up to 4 Computes Deployment Guide
|
||
- Standard with Controller Storage Deployment Guide
|
||
- Standard with Dedicated Storage Deployment Guide
|
||
- Standard with Ironic Deployment Guide
|
||
- Multi-Region Deployment Guide
|
||
- Distributed Cloud Deployment Guide
|
||
|
||
SB entry: 2005004
|
||
Priority: VH - release gating
|
||
|
||
The following documents are included in this section of the documentation.
|
||
|
||
**StarlingX Deployment Planning (New)**
|
||
This is a new document for how to plan a deployment of StarlingX.
|
||
Needs to include references to the Deployment Options (or maybe
|
||
just include it). Discuss why, how and when the various deployment
|
||
options should be used. More focused on how to define what
|
||
hardware to buy and how to cable it up. The existing HW
|
||
requirements documents would go here.
|
||
SB entry: 2005005
|
||
Priority: VH - release gating
|
||
|
||
**StarlingX Deployment Options (New)**
|
||
This is a new document that describes at a high level the different
|
||
deployment options for StarlingX. This could be part of the
|
||
Deployment Planning document at the author's discretion.
|
||
SB entry: 2005006
|
||
Priority: VH - release gating
|
||
|
||
All of the Deployment Guides below should include Deployment
|
||
Diagrams showing the logical topology and networking of each
|
||
deployment option, e.g. showing the various node types, the various
|
||
network types, the typical gateway routers, etc... This has been
|
||
explicitly requested on our mailing list.
|
||
|
||
**All-in-one Simplex Deployment Guide (New)**
|
||
This is a new document that describes how to deploy StarlingX in
|
||
the All-in-one Simplex configuration.
|
||
SB entry: 2005007
|
||
Priority: VH - release gating
|
||
|
||
**All-in-one Duplex Deployment Guide (New)**
|
||
This is a new document that describes how to deploy StarlingX in
|
||
the All-in-one Duplex configuration.
|
||
SB entry: 2005008
|
||
Priority: VH - release gating
|
||
|
||
**All-in-one Duplex with up to 4 Computes Deployment Guide (New)**
|
||
This is a new document that describes how to deploy StarlingX in
|
||
the Duplex with Compute nodes configuration. Optionally, at the
|
||
discretion of the author of the All-in-one Duplex Deployment Guide, this
|
||
could be just an additional section of that document.
|
||
SB entry: 2005009
|
||
Priority: VH - release gating
|
||
|
||
**Standard with Controller Storage Deployment Guide (New)**
|
||
This is a new document that describes how to deploy StarlingX in
|
||
the Small Standard (no storage) configuration.
|
||
SB entry: 2005010
|
||
Priority: VH - release gating
|
||
|
||
**Standard with Dedicated Storage Deployment Guide (New)**
|
||
This is a new document that describes how to deploy StarlingX in
|
||
the Standard (with storage nodes) configuration.
|
||
SB entry: 2005011
|
||
Priority: VH - release gating
|
||
|
||
**Standard with Ironic Deployment Guide (New)**
|
||
This is a new document that describes how to deploy StarlingX in
|
||
the Standard configuration with OpenStack Ironic to allow use of
|
||
bare metal Compute nodes. This is basically just the existing
|
||
how-to doc on Ironic, updated to deploy it in a Container. At the
|
||
author's discretion, a separate Installation Guide for Ironic could
|
||
also be written.
|
||
SB entry: TBD
|
||
Priority: M
|
||
|
||
**Multi-Region Deployment Guide (New)**
|
||
This is a new document that describes how to deploy StarlingX in
|
||
the Multi-Region configuration.
|
||
SB entry: 2005012
|
||
Priority: VH - release gating
|
||
|
||
**Distributed Cloud Deployment Guide (New)**
|
||
This is a new document that describes how to deploy StarlingX in
|
||
the Distributed Cloud configuration.
|
||
SB entry: 2005013
|
||
Priority: VH - release gating
|
||
|
||
Installation Guides
|
||
-------------------
|
||
|
||
This is a new landing page in the document hierarchy. It contains
|
||
links to the following documents:
|
||
|
||
- All-in-one Simplex Installation Guide
|
||
- All-in-one Duplex Installation Guide
|
||
- All-in-one Duplex with Computes Installation Guide
|
||
- Standard with Controller Storage Installation Guide
|
||
- Standard with Dedicated Storage Installation Guide
|
||
- Multi-Region Installation Guide
|
||
- Distributed Cloud Installation Guide
|
||
- Additional OpenStack Services Installation Guide
|
||
|
||
SB entry: 2005174
|
||
Priority: VH - release gating
|
||
|
||
The following documents are included in this section of the documentation.
|
||
|
||
**All-in-one Simplex Installation Guide (New)**
|
||
This is a new document that describes how to install StarlingX in
|
||
the All-in-one Simplex configuration.
|
||
SB entry: 2005175
|
||
Priority: VH - release gating
|
||
|
||
**All-in-one Duplex Installation Guide (New)**
|
||
This is a new document that describes how to install StarlingX in
|
||
the All-in-one Duplex configuration.
|
||
SB entry: 2005176
|
||
Priority: VH - release gating
|
||
|
||
**All-in-one Duplex with Computes Installation Guide (New)**
|
||
This is a new document that describes how to install StarlingX
|
||
in the Duplex with Compute nodes configuration.
|
||
SB entry: 2005177
|
||
Priority: VH - release gating
|
||
|
||
**Standard with Controller Storage Installation Guide (New)**
|
||
This is a new document that describes how to install StarlingX
|
||
in the Small Standard (no storage) configuration.
|
||
SB entry: 2005178
|
||
Priority: VH - release gating
|
||
|
||
**Standard with Dedicated Storage Installation Guide (New)**
|
||
This is a new document that describes how to install StarlingX
|
||
in the Standard (with storage nodes) configuration.
|
||
SB entry: 2005179
|
||
Priority: VH - release gating
|
||
|
||
**Multi-Region Installation Guide (New)**
|
||
This is a new document that describes how to install StarlingX
|
||
in the Multi-Region configuration.
|
||
SB entry: 2005180
|
||
Priority: VH - release gating
|
||
|
||
**Distributed Cloud Installation Guide (New)**
|
||
This is a new document that describes how to install StarlingX
|
||
in the Distributed Cloud configuration.
|
||
SB entry: 2005181
|
||
Priority: VH - release gating
|
||
|
||
**Additional OpenStack Services Installation Guide (New)**
|
||
This is a new document that describes how to install and configure
|
||
additional OpenStack services (beyond those supported by StarlingX)
|
||
in a StarlingX deployment. Example services include Octavia,
|
||
Trove and Sahara, all of which have been mentioned in the
|
||
community as of interest.
|
||
SB entry: TBD
|
||
Priority: L
|
||
|
||
Operation Guides
|
||
----------------
|
||
|
||
This is a new landing page in the document hierarchy. It is intended to
|
||
serve as the home page for “how to” documents and user/operator focused
|
||
documentation. The page should contain links to the following documents:
|
||
|
||
- StarlingX API Reference
|
||
- StarlingX CLI Reference
|
||
- StarlingX Data Network Configuration
|
||
- StarlingX CEPH Storage Configuration
|
||
- StarlingX SDN Networking
|
||
- StarlingX Kubernetes Cluster Guide
|
||
- StarlingX SWIFT Configuration and Management
|
||
- StarlingX Fault Management
|
||
- StarlingX Patching Guide
|
||
- StarlingX Upgrade Guide
|
||
|
||
SB entry: 2005182
|
||
Priority: VH - release gating
|
||
|
||
**StarlingX API Reference**
|
||
This is the existing API Reference documentation.
|
||
|
||
**StarlingX CLI Reference (New)**
|
||
This is a new document the defines all of the CLI commands
|
||
accepted by the StarlingX unique services (the Flock).
|
||
SB entry: TBD
|
||
Priority: M
|
||
|
||
**StarlingX Data Network Configuration (New)**
|
||
This is a new document for how to configure the data networks. At
|
||
the author's discretion this can be covered in the deployment guides.
|
||
SB entry: TBD
|
||
Priority: M
|
||
|
||
**StarlingX CEPH Storage Configuration (New)**
|
||
This is a new document for how to configure CEPH. At the author's
|
||
discretion this could also be a part of the deployment guides.
|
||
SB entry: TBD
|
||
Priority: M
|
||
|
||
**StarlingX SDN Networking (New)**
|
||
This is a new document for how to configure SDN networking.
|
||
SB entry: TBD
|
||
Priority: L
|
||
|
||
**StarlingX Kubernetes Cluster Guide (New)**
|
||
This is a new document for how to operate the Kubernetes
|
||
within StarlingX. It should cover a description of how we use
|
||
the Armada component, how helm charts are managed within StarlingX,
|
||
how overrides for helm charts are configured/saved/edited.
|
||
SB entry: TBD
|
||
Priority: M
|
||
|
||
**StarlingX SWIFT Configuration and Management (New)**
|
||
This is a new document describing how to configure and use
|
||
SWIFT within StarlingX.
|
||
SB Entry: TBD
|
||
Priority: M
|
||
|
||
**StarlingX Fault Management (New)**
|
||
This is a new document describing the fault management
|
||
capabilities of StarlingX and how to use them, how to find and
|
||
read logs, etc… It should call out and provide a link to the SNMP MIB.
|
||
SB entry: TBD
|
||
Priority: M (H?)
|
||
|
||
|
||
**StarlingX Patching Guide (New)**
|
||
This is a new document describing the software patching
|
||
capabilities of StarlingX and how to use them.
|
||
SB entry: TBD
|
||
Priority: L
|
||
|
||
**StarlingX Upgrade Guide (New)**
|
||
This is a new document describing the software upgrade
|
||
capabilities of StarlingX and how to use them.
|
||
SB entry: TBD
|
||
Priority: L
|
||
|
||
Contributor Guides
|
||
------------------
|
||
|
||
This is a new landing page in the document hierarchy. It is intended
|
||
to serve as the home page for “how to” documents and user/operator
|
||
focused documentation. The page should contain links to the
|
||
following documents:
|
||
- StarlingX Contributor Guide
|
||
- StarlingX Development Process
|
||
- StarlingX Build Guide
|
||
- StarlingX API Contributor Guide
|
||
- StarlingX Release Notes Contributor Guide
|
||
- StarlingX Documentation Contributor Guide
|
||
|
||
SB entry: 2005183
|
||
Priority: VH - release gating
|
||
|
||
**StarlingX Contributor Guide (New)**
|
||
This is a new document providing a high level overview of how
|
||
to contribute to StarlingX. It should describe the
|
||
communication channels that are used by the project team, the
|
||
way we have divided up the project into sub-projects, our
|
||
wiki page, our weekly community and sub-project meetings, and
|
||
other similar topics. It should point to the build and
|
||
installation documents and describe our expectations for
|
||
pre-commit testing needed before changes can be accepted. It
|
||
should point to the project's formal Governance documents
|
||
and describe the roles of the TSC members and Core Reviewers
|
||
in reviewing and approving code changes.
|
||
SB entry: TBD
|
||
Priority: H
|
||
|
||
**StarlingX Development Process (New)**
|
||
This is a new document that can leverage existing content from
|
||
the wiki. The document should cover the basic tools used
|
||
(git / gerrit / etc…), the feature development and spec
|
||
approval process, the bug resolution process, our release
|
||
planning process and other similar topics.
|
||
|
||
Initially this document can be a link to the current
|
||
wiki pages that describe
|
||
the development process. Over time, we can consider moving the wiki
|
||
content into the git managed formal documentation.
|
||
SB entry: TBD
|
||
Priority: H
|
||
SB entry to fix the wiki content: 2005173
|
||
Priority: H
|
||
|
||
**StarlingX Build Guide**
|
||
This is the existing Build documentation, updated as needed to
|
||
fit within the new hierarchy and for the Containers changes. It should
|
||
include a description of the build artifacts hosted by the third party and
|
||
how to use the build to leverage them.
|
||
SB entry: 2005184
|
||
Priority: VH - release gating
|
||
|
||
**StarlingX API Contributor Guide**
|
||
This is the existing API Contributor Guide
|
||
|
||
**StarlingX Release Notes Contributor Guide**
|
||
This is the existing Release Notes Contributor Guide
|
||
|
||
**StarlingX Documentation Contributor Guide**
|
||
This is the existing Documentation Contributor Guide
|
||
|
||
Releases and Release Notes
|
||
--------------------------
|
||
|
||
This should be a landing page with links to the publicly
|
||
available pre-built images and the Release
|
||
notes for all releases. Releases that are no longer supported should
|
||
be included (for historical reasons) but should be marked as “obsolete”
|
||
or “unsupported”.
|
||
SB entry: 2995185
|
||
Priority: VH - release gating
|
||
|
||
Developer Resources
|
||
-------------------
|
||
|
||
This is a new landing page within the documentation and will contain
|
||
links to the following documents:
|
||
|
||
- How to Navigate the StarlingX Source Code
|
||
- StarlingX Architecture Documents
|
||
- StarlingX Specifications
|
||
|
||
SB entry: 2005186
|
||
Priority: VH - release gating
|
||
|
||
**How to Navigate the StarlingX Source Code (New)**
|
||
This is a new document describing the structure, layout and high
|
||
level architecture of the StarlingX git repos and source code.
|
||
SB entry: TBD
|
||
Priority: H
|
||
|
||
**StarlingX Architecture Documents (New)**
|
||
This is a landing page for architecture documents, which do not
|
||
yet exist.
|
||
SB entry: TBD
|
||
Priority: L
|
||
|
||
**StarlingX Specifications**
|
||
This is a link to the existing StarlingX Specifications page.
|
||
|
||
Alternatives
|
||
============
|
||
|
||
There are many ways to organize the StarlingX document repository. The
|
||
proposal here is the result of multiple discussions, drafts and reviews
|
||
within the Docs team.
|
||
|
||
Data model impact
|
||
=================
|
||
|
||
None
|
||
|
||
REST API impact
|
||
===============
|
||
|
||
None
|
||
|
||
Security impact
|
||
===============
|
||
|
||
None
|
||
Other end user impact
|
||
=====================
|
||
|
||
End users should find it significantly easier to deploy and manage StarlingX
|
||
Edge Clouds. New contributors should find it significantly easier to
|
||
make contributions to the project.
|
||
|
||
Performance Impact
|
||
==================
|
||
|
||
None
|
||
|
||
Other deployer impact
|
||
=====================
|
||
|
||
None
|
||
|
||
Developer impact
|
||
================
|
||
|
||
None
|
||
|
||
Upgrade impact
|
||
==============
|
||
|
||
None
|
||
|
||
Implementation
|
||
===============
|
||
|
||
This work will be implemented as a set of related Storyboard entries, as
|
||
called out in the Proposed Change. Each Story has a priority defined
|
||
for it so the work can be managed over time.
|
||
|
||
Assignee(s)
|
||
===========
|
||
|
||
Members of the Docs team will provide guidance and support. Responsibility
|
||
for the Documentation will need to be distributed across the StarlingX
|
||
sub-projects, to allow the work to be done by those most familar with the
|
||
software and to ensure the effort is scalable and manageable.
|
||
|
||
Primary assignee:
|
||
=================
|
||
|
||
Several will be needed.
|
||
|
||
Other contributors:
|
||
===================
|
||
|
||
Many will be needed.
|
||
|
||
Repos Impacted
|
||
==============
|
||
|
||
Stx.docs and likely the Flock services repos
|
||
|
||
Work Items
|
||
==========
|
||
|
||
See the SB entries called out in the Proposed Change
|
||
|
||
Dependencies
|
||
============
|
||
|
||
None significant
|
||
|
||
Testing
|
||
=======
|
||
|
||
Testing will be needed to ensure that the documents written accurately
|
||
describe the software.
|
||
|
||
Documentation Impact
|
||
====================
|
||
|
||
Lots :)
|