Magnum User Guide for Cloud Operator

Registered by Ton Ngo on 2015-11-12

There has been frequent requests for a Magnum User Guide that is more in-depth than the current Quick Start Guide.
From the discussion at the contributor meetup in Tokyo, a user guide skeleton will be set up for contributors to add content over time.

The following sections are suggested for the User Guide (not in any particular order):

- High level overview of Magnum - Magnum Rationale (compelling features, mention of how we use heat)

- TLS (Native Client Configuration guide), one per bay

- Native client configuration should be setup automatically by magnum client?

- Networking

- Kubernetes

- Swarm

- Python Client

- Horizon Interface (with screenshots)

- Buyer's guide for choosing COE by example use case
( example: http://www.openstack.org/software/project-navigator)

- HA Guide

- Scaling How-to (Including Autoscaling)

- Storage Overview (this will grow as we add storage features)

- Image Management

- Clean up of bay resources, i.e. heat stack-delete

Blueprint information

Status:
Complete
Approver:
Adrian Otto
Priority:
Essential
Drafter:
Ton Ngo
Direction:
Approved
Assignee:
Ton Ngo
Definition:
Approved
Series goal:
Accepted for newton
Implementation:
Implemented
Milestone target:
None
Started by
Ton Ngo on 2016-01-05
Completed by
Adrian Otto on 2016-10-04

Related branches

Sprints

Whiteboard

The following sections have existing write-up in separate documents, so the relevant parts from these documents can be pulled and expanded for the user guide.

-Transport Layer Security: doc/source/dev/dev-tls.rst, spec/tls-support-magnum.rst
-Mesos: doc/source/dev/dev-mesos.rst
-Networking: spec/container-networking-model.rst

The quick start guide also has tid-bits that can be used as the starting point for some sections.
The following sections need full new write-up:

-Python Client
-Horizon Interface
-Choosing COE
-Native clients
-Kubernetes
-Swarm
-High Availability
-Scaling
-Storage
-Image Management
-Bay driver

--
strigazi 2016 - 08 - 09
We might want to break the user guide to ops guide and end-user guide.

ops guide could contain:
- this option which is related to performance and security [1]
(The performance gain is not confirmed though)
- add LBaaS
- add swift for docker registry
- HA with barbican or X509keypair

The above three options are essentially part of an extended or advanced install guide

[1] https://github.com/openstack/magnum/blob/master/doc/source/userguide.rst#performance-tuning-for-periodic-task

---

tango 2016/08/12
I think the operator would use the install guide, so it probably makes sense to add an "Advanced" section to the install guide to cover performance tuning and optional components for additional functionality. As we gain more experience with the scalability study, we can add best practices there also.
Users normally would not have access to the environment to perform these tasks.

--

Gerrit topic: https://review.openstack.org/#q,topic:bp/user-guide,n,z

Addressed by: https://review.openstack.org/263599
    Skeleton for User Guide

Addressed by: https://review.openstack.org/272339
    Networking user guide

Gerrit topic: https://review.openstack.org/#q,topic:bp/magnum-user-guide,n,z

Addressed by: https://review.openstack.org/289744
    Add Image Management section in User Guide

Addressed by: https://review.openstack.org/317592
    Add Storage section in user guide

Addressed by: https://review.openstack.org/317764
    Update Image section in user guide

Gerrit topic: https://review.openstack.org/#q,topic:317745,n,z

Addressed by: https://review.openstack.org/317745
    Added "Choosing a COE" to user guide

Addressed by: https://review.openstack.org/320532
    [WIP] Add Bay Drivers section in user guide

Addressed by: https://review.openstack.org/326158
    Add Kubernetes section to User Guide

Addressed by: https://review.openstack.org/329212
    Add Swarm section to User Guide

Addressed by: https://review.openstack.org/333012
    Add Baymodel section to User Guide

Addressed by: https://review.openstack.org/340670
    Add Bay section to User Guide

Addressed by: https://review.openstack.org/344046
    Add Mesos section to User Guide

Addressed by: https://review.openstack.org/347077
    Add TLS section to User Guide

Addressed by: https://review.openstack.org/355660
    Update to User Guide

Gerrit topic: https://review.openstack.org/#q,topic:labels_doc,n,z

Addressed by: https://review.openstack.org/318458
    Add Mesos labels and summary for labels

Addressed by: https://review.openstack.org/365085
    Add Scaling section to User Guide

Addressed by: https://review.openstack.org/372029
    Add Horizon and Native Clients to user guide

(?)

Work Items

Work items:
Initial Outline: DONE
Baymodel: DONE
Bay: DONE
Python Client : TODO
Horizon Interface (merge existing README): INPROGRESS
Choosing COE: DONE
Native clients: TODO
Kubernetes: DONE
Swarm: DONE
Mesos: DONE
Transport Layer Security (merge existing doc): DONE
Networking: DONE
High Availability: TODO
Storage: DONE
Image Management: DONE
Bay Driver: DONE
Scaling: INPROGRESS
Scalability & Tuning: TODO

This blueprint contains Public information 
Everyone can see this information.