Difference between revisions of "Blueprint-os-user-docs"

Revision as of 19:46, 16 May 2013

• Launchpad Entry: [1]
• Created: Diane Fleming
• Contributors:

Summary

This blueprint describes a plan to create the following documentation for OpenStack users:

• OpenStack User Guide
• OpenStack Command Reference
  
  

These documents will provide a clear roadmap for users to interact with OpenStack clouds.

Additionally, these documents will reduce redundancy and increase usability, clarity, and consistency in the existing documentation.

This blueprint is related to [- Restructure Documentation]

OpenStack User Guide

Introduces users to cloud concepts and common tasks. Shows users how to perform tasks in an OpenStack cloud through:

• The Horizon dashboard
• The OpenStack command-line clients
• Directly through the OpenStack APIs
  
  

OpenStack Command Reference

Provides reference information that enables users to perform tasks through OpenStack command-line client commands.

User Tasks

User tasks include:

• Authenticate
• Boot a server
• Create an image
• Create and attach a volume to a server
• Create an isolated network and attach it to a server
• List instances, networks, volumes, images, flavors, and other resources
• Delete resources
• Access a console for an instances
• Configure VNC

Blueprint - OpenStack User Guide

Audience: Users of OpenStack clouds who perform tasks through the Horizon dashboard or the OpenStack command-line clients. Also, developers who create applications on top of OpenStack by using the OpenStack APIs.
Roadmap: Users ramp up on cloud computing by using the Horizon dashboard and the OpenStack command-line clients. Then, they use the OpenStack APIs to create scalable applications.
Product info: Havana, 2013.1

Include common glossary? Yes

Purpose:

• Explain OpenStack cloud concepts and describe how to use an OpenStack cloud.
• Include command-line tools and credentials, how to use Horizon dashboard, and how to create images.
• Exclude Cloud application architecture.
  
  

Source material:

• OpenStack API Quick Start
• Python Developer Documentation
• Language Bindings Documentation
• OpenStack Clients Guide
• OpenStack Administration Guides
• OpenStack API Specifications
• Programming OpenStack Compute API with Shell and Python

CHAPTER 1: Overview

CHAPTER 2: OpenStack Cloud Concepts

Describe the main concepts that a user needs to understand to use the cloud. Authentication/Identity service http://www.openstack.org/software/openstack-shared-services/ Images, Image service What’s an image? What’s a snapshot? http://www.openstack.org/software/openstack-shared-services/ Servers What is a virtual machine? A hypervisor? A server personality? What does it mean to boot a server? http://www.openstack.org/software/openstack-compute/

Security groups http://www.openstack.org/software/openstack-compute/ Floating IP addresses Console log Object and block storage http://www.openstack.org/software/openstack-storage/ Networking http://www.openstack.org/software/openstack-networking/ Dashboard, command-line clients, APIs, extensions How to Interact with an OpenStack Cloud Describe ways you can interact with a cloud: OpenStack Command-line Clients OpenStack APIs Talk about ways to use the APIs – cURL? SDKs? Language bindings? Horizon Dashboard http://www.openstack.org/software/openstack-dashboard/

Listing Deleting/Terminating Instance Console access About console log Configuring VNC How do I attach a volume?

(Details on doing these actions in user guide)  

Attach/Detach volumes How do I save a running instance to an image? Snapshots

CHAPTER 3: Common User Tasks

Boot, list, and delete servers Configure VNC Attach and detach volumes Create, list, and delete images Load-balance xx

CHAPTER 4: Tutorials

Provide tutorials for various use cases. Use different methods in each tutorial so user gets an idea of what’s possible.

TUTORIAL 1: Authenticate

Method: cURL commands with embedded API

TUTORIAL 2: Run Your Elastic Web Application on Your Cloud

Method: nova client Set up a user, get images for your application servers, spin up server instances, install Wordpress and its dependencies. http://docs.openstack.org/grizzly/openstack-compute/admin/content/running-elastic-web-app-cloud.html

TUTORIAL 3: Store Large Photos or Videos in Your Cloud

Method: swift client and Cyberduck application Set up secure access to OpenStack Object Storage, configure Cyberduck to connect to OpenStack Object Storage, and copy files to the cloud. http://docs.openstack.org/grizzly/openstack-object-storage/admin/content/storing-large-photos-or-videos-on-the-cloud.html

Blueprint - OpenStack Command Reference

Purpose

• Describe command-line clients and their subcommands and required and optional parameters.
• Write scripts to auto-generate command and command parameters from the code.
• Use conditional tags to generate two versions of this book: One with admin commands, and one without.
• Exclude concepts (these go in the OpenStack User Guide) or installation instructions (these go in the OpenStack Installation Guide).
  
  

Source material

• OpenStack Clients Guide