Blueprint-os-user-docs

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

Summary

This blueprint describes a plan to create documentation for OpenStack users. This documentation will provide a conceptual overview of the OpenStack cloud, and it will enable users to complete tasks in an OpenStack cloud. The tasks include authentication, booting a server, creating an image, listing instances, networks, volumes, and so on, deleting resources, accessing a console for an instance, and configuring VNC.

This documentation will provide a clear roadmap for users to interact with OpenStack clouds by using the dashboard and client commands and then progress to using the APIs directly.

The planned documentation includes:

Document	Purpose
OpenStack User Guide	Introduces users to cloud concepts, common tasks, and ways of interacting with the cloud. Through tutorials, 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.

These documents will be partially sourced from existing documentation, and will reduce redundancy and increase usability, clarity, and consistency.

This blueprint is related to Blueprint Restructure Documentation.

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

One-to-two paragraph description of the OpenStack cloud. Descriptions of the OpenStack projects. State the goals of the book - concepts, set-up, and tutorials.

SECTION 1: 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/

SECTION 2: Common User Tasks

• Boot, list, and delete servers
• Configure VNC
• Attach and detach volumes
• Create, list, and delete images
• Load-balance xx
• 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

SECTION 3: How to Interact with an OpenStack Cloud

Describe ways you can interact with a cloud:

• Horizon Dashboard - http://www.openstack.org/software/openstack-dashboard/
• OpenStack Command-line Clients - provide x-ref to OpenStack Command Reference.
• OpenStack APIs
• Talk about ways to use the APIs – cURL? SDKs? Language bindings?

SECTION 4: How to Use the Tutorials in this Guide

Base off of: http://docs.rackspace.com/servers/api/v2/cn-gettingstarted/content/ch_how_examples_work.html

SECTION 5: How the OpenStack Command-line Clients Work

Base off of: http://docs.rackspace.com/servers/api/v2/cn-gettingstarted/content/novaclient.html

SECTION 6: How cURL Commands Work

Base off of: http://docs.rackspace.com/servers/api/v2/cn-gettingstarted/content/curl.html

CHAPTER 2: 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 (TBD)

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