Difference between revisions of "Blueprint-os-user-docs"
(→Summary) |
|||
Line 5: | Line 5: | ||
== Summary == | == Summary == | ||
− | This blueprint describes a plan to create documentation for OpenStack users. What is an OpenStack user? An OpenStack user | + | This blueprint describes a plan to create documentation for OpenStack users. What is an OpenStack user? An OpenStack user performs tasks on an existing cloud. An OpenStack user might be someone who wants to list available resources, such as images and servers, and create and manage resources. Or an OpenStack user might be a budding OpenStack developer: Someone who wants to build web applications that run on a cloud. |
This documentation will provide a conceptual overview of the OpenStack cloud, and it will enable users to authenticate, boot a server, list resources, such as instances, networks, volumes, and so on, delete resources, access a console for an instance, and configure VNC, among other tasks. | This documentation will provide a conceptual overview of the OpenStack cloud, and it will enable users to authenticate, boot a server, list resources, such as instances, networks, volumes, and so on, delete resources, access a console for an instance, and configure VNC, among other tasks. | ||
Line 16: | Line 16: | ||
! Document !! Purpose | ! Document !! Purpose | ||
|- | |- | ||
− | | OpenStack User Guide || Introduces users to cloud concepts, common tasks, and ways of interacting with the cloud. <br /> | + | | OpenStack User Guide || Introduces end users to cloud concepts, common tasks, and ways of interacting with the cloud. <br /> |
Through tutorials, shows users how to perform tasks in an OpenStack cloud through: | Through tutorials, shows users how to perform tasks in an OpenStack cloud through: | ||
Line 25: | Line 25: | ||
* Rackspace open SDKs? | * Rackspace open SDKs? | ||
* Other? | * Other? | ||
+ | |||
+ | In an appendix (or appendices), provides reference information that enables users to perform tasks through OpenStack command-line client commands. | ||
|- | |- | ||
− | | OpenStack | + | | OpenStack Admin User Guide || Introduces admin users to administrative tasks, and ways of interacting with the cloud. <br /> |
+ | |||
+ | Through tutorials, shows admin users how to perform administrative tasks in an OpenStack cloud through: | ||
+ | |||
+ | * the Horizon dashboard | ||
+ | * the OpenStack command-line clients | ||
+ | * cURL commands with embedded OpenStack API calls | ||
+ | * Rackspace open SDKs? | ||
+ | * Other? | ||
|} | |} | ||
Revision as of 13:34, 11 June 2013
- Launchpad Entry: [1]
- Created: Diane Fleming
- Contributors:
Contents
- 1 Summary
- 2 Blueprint - OpenStack User Guide
- 3 Blueprint - OpenStack Command Reference (TBD)
Summary
This blueprint describes a plan to create documentation for OpenStack users. What is an OpenStack user? An OpenStack user performs tasks on an existing cloud. An OpenStack user might be someone who wants to list available resources, such as images and servers, and create and manage resources. Or an OpenStack user might be a budding OpenStack developer: Someone who wants to build web applications that run on a cloud.
This documentation will provide a conceptual overview of the OpenStack cloud, and it will enable users to authenticate, boot a server, list resources, such as instances, networks, volumes, and so on, delete resources, access a console for an instance, and configure VNC, among other tasks.
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 through cURL commands or in the Rackspace-provided open SDKs.
The planned documentation includes:
Document | Purpose |
---|---|
OpenStack User Guide | Introduces end 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:
In an appendix (or appendices), provides reference information that enables users to perform tasks through OpenStack command-line client commands. |
OpenStack Admin User Guide | Introduces admin users to administrative tasks, and ways of interacting with the cloud. Through tutorials, shows admin users how to perform administrative tasks in an OpenStack cloud through:
|
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.
- Include Cloud application architecture diagram.
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. Architecture diagram with few sentences of explanation. 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/. Also, http://docs.openstack.org/cli/quick-start/content/nova_client.html
- 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/ - What storage can you attach to instances? Can I attach an ISO as if I'm mounting a CD/DVD? Backend Storage Devices, Users and Tenants (Projects), Volumes Snapshots and Backups.
- Networking - http://www.openstack.org/software/openstack-networking/
SECTION 2: 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. Base off of: http://docs.rackspace.com/servers/api/v2/cn-gettingstarted/content/novaclient.html
cURL Commands with Embedded API Calls
Base off of: http://docs.rackspace.com/servers/api/v2/cn-gettingstarted/content/curl.html
OpenStack APIs
Talk about ways to use the APIs – cURL? SDKs? Language bindings?
SECTION 3: Common User Tasks
- Boot, list, and delete servers
- List and delete images - point to new book about OpenStack Images for info about creating images
- Load-balance xx
- Create an isolated network
- Access a console for an instance
- Configure VNC
- Create, attach, and detach a volume
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
Provide tutorials for various use cases. Use different methods in each tutorial so user gets an idea of what’s possible.
CHAPTER 2: Tutorials
TUTORIAL 1: Authenticate
Method: cURL commands with embedded API
TUTORIAL 2: Run Your Wordpress Blog on Your Cloud
Method: nova client
- Install the nova client
- Set up a user
- Get images for your application servers
- Spin up server instances
- Install Wordpress and its dependencies.
Source from: http://docs.openstack.org/grizzly/openstack-compute/admin/content/running-elastic-web-app-cloud.html Provide pointers to installation information in Command Reference, and other books with more information
TUTORIAL 3: Store Large Photos or Videos in Your Cloud
Method: swift client and Cyberduck application
- Install swift client
- Set up secure access to OpenStack Object Storage
- Install and configuration Cyberduck to connect to OpenStack Object Storage
- Copy files to the cloud
TUTORIAL 4: Create and Attach a Volume to Your Instance
Method: cinder and nova clients Use case? http://docs.openstack.org/grizzly/openstack-block-storage/admin/content/block_storage_overview.html#managing-volumes
TUTORIAL 5: Create an Isolated Network
Method: nova and quantum clients Use case? http://docs.openstack.org/grizzly/openstack-network/admin/content/basic_operations.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