Jump to: navigation, search

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

 
(14 intermediate revisions by the same user not shown)
Line 1: Line 1:
* '''Launchpad Entry''':  [https://blueprints.launchpad.net/openstack-manuals/+spec/blueprint-os-admin-docs/ Design for OpenStack Administration Guide]
+
* '''Launchpad Entry''':  [https://blueprints.launchpad.net/openstack-manuals/+spec/blueprint-os-admin-docs/ Design for OpenStack Cloud Administration Guide]
 
* '''Created''': Nicholas Chase
 
* '''Created''': Nicholas Chase
 
* '''Updated''': Nermina Miller  
 
* '''Updated''': Nermina Miller  
* '''Contributors''':  
+
* '''Advisor''': Anne Gentle
  
 
== Summary ==
 
== Summary ==
  
This blueprint describes a plan to create documentation for OpenStack administrators and operators. These are tasks that go beyond the everyday actions an OpenStack user would take, but don't get into the depths of the OpenStack Operations Manual.  
+
This blueprint describes a plan to create documentation for OpenStack cloud administrators. These are tasks that go beyond the everyday actions an OpenStack user would take, but don't get into the depths of the OpenStack Operations Manual.  
  
This documentation organizes the existing administration documentation into conceptional categories rather than chronological activities.  It is meant to be comprehensive, but to be built out of content that has been drawn from other manuals.  The reason for this is that while this guide is meant to be comprehensive, users should still be able to create documentation in smaller chunks to avoid being overwhelmed.  (This process is covered by a separate blueprint.)<br />
+
This blueprint takes the information left over after the extraction of install and config reference from component guides and establishes a new guide that will contain links and references to other guides and serve as a standalone system maintenance guide.<br />
  
 
This blueprint is related to [[Blueprint-restructure-documentation|Blueprint Restructure Documentation]].
 
This blueprint is related to [[Blueprint-restructure-documentation|Blueprint Restructure Documentation]].
  
== Blueprint - OpenStack Administration Guide ==
+
== Blueprint&mdash;OpenStack Cloud Administration Guide ==
'''Audience''': Administrators and operators of OpenStack clouds who maintain OpenStack clusters.<br />
+
 
 +
'''Audience''': Administrators and operators who maintain OpenStack clouds<br />
  
 
'''Product info:''' Havana, 2013.1<br />
 
'''Product info:''' Havana, 2013.1<br />
  
 
'''Include common glossary?''' Yes <br />
 
'''Include common glossary?''' Yes <br />
 +
  
 
'''Purpose''':
 
'''Purpose''':
  
* Explain OpenStack cloud concepts and describe how to use an OpenStack cloud.  
+
* Provide information about managing and troubleshooting various parts of a cloud system
* Include Cloud application architecture diagram.
+
* Consolidate the material left over from appropriation to config, install, and user guides
* TBD<br /><br />
+
* Consolidate the formatting and style
 +
* Match up the chapter titles to the order of OpenStack components in the Getting Started... chapter
 +
* Link to appropriate parts in other guides for additional information
 +
* Update the material against Havana (last task)
 +
 
  
 
'''Source  material''':
 
'''Source  material''':
  
* [https://www.suse.com/documentation/suse_cloud10/book_cloud_user/?page=/documentation/suse_cloud10/book_cloud_user/data/book_cloud_user.html Suse End User Guide]
+
* OpenStack Compute Administration Guide
* [http://training.rackspace.com/certification/rackspace-certified-technician-for-openstack/1/ Rackspace-sponsored OpenStack training]
+
* OpenStack Networking Administration Guide
* [http://www.openstack.org/software/start/ OpenStack API Quick Start]
+
* OpenStack Object Storage Administration Guide
* [http://docs.openstack.org/developer/openstack-projects.html Python Developer Documentation]
+
* OpenStack Block Storage Service Administration Guide
* [http://docs.openstack.org/developer/language-bindings.html Language Bindings Documentation]
 
* [http://docs.openstack.org/cli/quick-start/content/index.html OpenStack Clients Guide]
 
* [http://docs.openstack.org/run/ OpenStack Administration Guides]
 
* [http://docs.openstack.org/api/api-specs.html OpenStack API Specifications]
 
* [http://docs.openstack.org/api/openstack-compute/programmer/content/ 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: <br />
 
 
 
===== 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?
 
 
 
 
 
=== CHAPTER 2: Architecture ===
 
A more in-depth discussion of how all of the pieces and projects fit together.
 
 
 
=== CHAPTER 3: Compute ===
 
 
 
==== SECTION 1: Introduction ====
 
===== Images =====
 
===== Instances =====
 
 
 
==== SECTION 2: Installation  ====
 
 
 
This section includes both basic and automated installation.  It will likely pull heavily from the installation guide.
 
 
 
==== SECTION 3: Configuration ====
 
 
 
This section discusses nova.conf. but any actual configuration parameters will be sourced from the configuration guide.
 
 
 
==== SECTION 4: Identity, Image, and Instance Management ====
 
 
 
==== SECTION 5: Scheduling ====
 
 
 
==== SECTION 6: System Administration ====
 
 
 
==== SECTION 7: Interfaces ====
 
 
 
==== SECTION 8: Security ====
 
 
 
==== SECTION 9: Troubleshooting ====
 
 
 
==== SECTION 10: Community Support ====
 
 
 
==== SECTION 11: Tutorials ====
 
 
 
=== CHAPTER 3. OpenStack Networking ===
 
 
 
 
 
 
 
==== SECTION 1: Introduction ====
 
 
 
This section gives an overview of the architecture and touches on what things look like under the hood, including giving a "teaser" of advanced features.
 
 
 
==== SECTION 2: Installation ====
 
 
 
==== SECTION 3: Configuration for OpenStack Identity and Compute ====
 
 
 
This section includes both basic and advanced configuration and core configuration options.
 
 
 
==== SECTION 4 Deployment and Usage Cases ====
 
 
 
This section includes both basic and advanced use cases, such as high availability, demos and plugin pagination and sorting support.
 
 
 
==== SECTION 5 Authentication and Authorization ====
 
 
 
=== CHAPTER 4 OpenStack Storage ===
 
 
 
This chapter is a combination of the Object and Block storage books, and might be better broken out into two chapters, if we can find a way to include the introduction just once.  Perhaps we need to create parts.  The only thing stopping me is that the other parts would have just one chapter each, which is just wrong.
 
 
 
==== SECTION 1 Introduction ====
 
 
 
This section includes the storage concepts table.
 
 
 
==== SECTION 2 Object Storage ====
 
 
 
'''Source  material'''
 
 
 
* [http://docs.openstack.org/grizzly/openstack-object-storage/admin/content/index.html Object Storage Administration Guide]
 
 
 
===== Introduction =====
 
===== Installation =====
 
===== System Administration =====
 
===== Monitoring =====
 
===== Troubleshooting =====
 
===== Community Support =====
 
===== Tutorials =====
 
 
 
==== SECTION 3 Block Storage ====
 
 
 
'''Source  material'''
 
 
 
* [http://docs.openstack.org/grizzly/openstack-block-storage/admin/content/index.html Block Storage Service Administration Guide]
 
 
 
===== Introduction (link to OpenStack Compute in the text) =====
 
====== Volumes ======
 
* Managing
 
* Drivers
 
===== Installation =====
 
===== Administration =====
 
===== System Monitoring =====
 
===== Troubleshooting =====
 
===== Community Support =====
 
===== Tutorials =====
 
  
=== CHAPTER 5. Summary ===
+
== Proposed contents ==
  
=== CHAPTER 6. Glossary ===
+
# Getting Started with OpenStack [move up from Compute]
 +
## OpenStack architecture
 +
## OpenStack services
 +
## Feedback
 +
# Compute
 +
## Introduction to Compute [revise the order so it fits the upcoming sequence]
 +
### Hypervisors
 +
### Users and Tenants (Projects)
 +
### Images and Instances
 +
### System Architecture
 +
### Block Storage and OpenStack Compute
 +
## Identity Management
 +
### Identity Service Concepts
 +
### Memcached and System Time
 +
### User CRUD
 +
### Monitoring
 +
### Certificates for PKI
 +
### Run the Identity Service
 +
### Troubleshoot the Identity Service
 +
## Image Management
 +
### Adding images with glance image-create
 +
### Getting virtual machine images
 +
### Booting a test image
 +
### Tearing down (deleting) Instances
 +
### Pausing and Suspending Instances
 +
### Select a specific host to boot instances on [move to booting]
 +
### Creating images from running instances with KVM and Xen
 +
### Replicating images across multiple data centers
 +
## Instance Management
 +
### Interfaces to managing instances
 +
### Instance building blocks
 +
### Customizing Flavors
 +
### Creating instances
 +
### Control where instances run
 +
### Instance specific data
 +
### Managing instance networking
 +
### Manage Volumes
 +
### Access running instances
 +
### Manage running instances
 +
## Hypervisors
 +
### Hypervisor Configuration Basics
 +
### KVM
 +
### Xen, XenAPI, XenServer, and XCP
 +
### LXC (Linux containers)
 +
### VMware vSphere
 +
### PowerVM
 +
### Hyper-V Virtualization Platform
 +
### Bare Metal Driver
 +
## Networking with nova-network
 +
### Networking Options
 +
### DHCP server: dnsmasq
 +
### Metadata service
 +
### Enabling Ping and SSH on VMs
 +
### Removing a Network from a Project
 +
### Using multiple interfaces for your instances (multinic)
 +
### Existing High Availability Options for Networking
 +
### Troubleshooting Networking
 +
## (Block Storage) Volumes [install info needs to be moved]
 +
### Scheduling
 +
### Filter Scheduler
 +
### Filters
 +
### Weights
 +
### Chance Scheduler
 +
### Host aggregates
 +
## Cells [all config, needs to be moved]
 +
## System Administration
 +
### Understanding the Compute Service Architecture [move up]
 +
### Managing Compute Users
 +
### Managing the Cloud
 +
### Show usage statistics for hosts and instances
 +
### Managing logs
 +
### Reference Information for Securing with Root Wrappers
 +
### Using Migration
 +
### Recovering from a failed compute node
 +
### Recovering from a UID/GID mismatch
 +
### Nova Disaster Recovery Process
 +
## OpenStack Interfaces [make a separate chapter]
 +
### The OpenStack dashboard
 +
### Using VNC Console
 +
## Security Hardening
 +
### Trusted Compute Pools
 +
## OpenStack Compute Automated Installations [move to install doc?]
 +
## OpenStack Compute Tutorials
 +
### Running Your First Elastic Web Application on the Cloud
 +
## Support [move to the end]
 +
### Community Support
 +
## Troubleshooting OpenStack Compute
 +
### Log files for OpenStack Compute
 +
### Common Errors and Fixes for OpenStack Compute
 +
### Manually reset the state of an instance
 +
### Problems with Injection
 +
# OpenStack Networking
 +
## Using OpenStack Networking
 +
### Core OpenStack Networking API features
 +
### Using OpenStack Compute with OpenStack Networking
 +
## Under the Hood [Proposing a new title: Networking scenarios]
 +
### Open vSwitch
 +
### Linux bridge
 +
## Advanced Features through API Extensions
 +
### Provider Networks
 +
### L3 Routing and NAT
 +
### Security Groups
 +
### Load-Balancer-as-a-Service
 +
### Plugin Specific Extensions
 +
## Authentication and Authorization
 +
## Advanced Operational Features [remove Quota info and merge with other Advanced Features]
 +
### Logging Settings
 +
### Notifications
 +
## High Availability
 +
## Limitations
 +
## Demos Setup [Poll for placement]
 +
### Single Flat Network
 +
### Provider Router with Private Networks
 +
### Per-tenant Routers with Private Networks
 +
### Scalable and Highly Available DHCP Agents
 +
## Plugin pagination and sorting support
 +
# Object Storage
 +
## Introduction to OpenStack Object Storage
 +
### Accounts and Account Servers
 +
### Authentication and Access Permissions
 +
### Containers and Objects
 +
### Operations
 +
### Language-Specific API Bindings
 +
## System Administration for OpenStack Object Storage
 +
### Understanding How Object Storage Works
 +
### Object Layout on Storage
 +
### Preparing the Ring
 +
### Considerations and Tuning
 +
### Replication
 +
### Managing Large Objects (Greater than 5 GB)
 +
### Throttling Resources by Setting Rate Limits
 +
### Additional Features
 +
### Bulk Delete
 +
### Managing OpenStack Object Storage with CLI Swift
 +
## OpenStack Object Storage Tutorials
 +
### Storing Large Photos or Videos on the Cloud
 +
## OpenStack Object Storage Monitoring
 +
### Swift Recon
 +
### Swift-Informant
 +
### Statsdlog
 +
### Swift StatsD Logging
 +
## Support [generic, can be moved to the end]
 +
## Troubleshooting OpenStack Object Storage
 +
### Handling Drive Failure
 +
### Handling Server Failure
 +
### Detecting Failed Drives
 +
### Emergency Recovery of Ring Builder Files
 +
# Block Storage
 +
## Introduction to the OpenStack Block Storage Service
 +
## Managing Volumes
 +
### Troubleshoot your cinder installation
 +
### Adding Block Storage Nodes
 +
### Boot From Volume
 +
# Support
 +
# A list of other docs with links
 +
# Glossary (if and when possible)
 +
# Index (if and when possible)
  
This is the common glossary
 
  
=== CHAPTER 7. Index ===
+
'''Next  steps''':
  
I think this would be pretty useful, but probably difficult to maintain.
+
* Now that we have narrowed down the purpose of this guide to cloud system administrations, ask SMEs whether any other content should be moved to other guides
 +
* Match up the structure of each chapter, moving the content around and updating the headings as appropriate
 +
* Clean up the content for style and grammar
 +
* Update the material for Havana

Latest revision as of 15:31, 30 August 2013

Summary

This blueprint describes a plan to create documentation for OpenStack cloud administrators. These are tasks that go beyond the everyday actions an OpenStack user would take, but don't get into the depths of the OpenStack Operations Manual.

This blueprint takes the information left over after the extraction of install and config reference from component guides and establishes a new guide that will contain links and references to other guides and serve as a standalone system maintenance guide.

This blueprint is related to Blueprint Restructure Documentation.

Blueprint—OpenStack Cloud Administration Guide

Audience: Administrators and operators who maintain OpenStack clouds

Product info: Havana, 2013.1

Include common glossary? Yes


Purpose:

  • Provide information about managing and troubleshooting various parts of a cloud system
  • Consolidate the material left over from appropriation to config, install, and user guides
  • Consolidate the formatting and style
  • Match up the chapter titles to the order of OpenStack components in the Getting Started... chapter
  • Link to appropriate parts in other guides for additional information
  • Update the material against Havana (last task)


Source material:

  • OpenStack Compute Administration Guide
  • OpenStack Networking Administration Guide
  • OpenStack Object Storage Administration Guide
  • OpenStack Block Storage Service Administration Guide

Proposed contents

  1. Getting Started with OpenStack [move up from Compute]
    1. OpenStack architecture
    2. OpenStack services
    3. Feedback
  2. Compute
    1. Introduction to Compute [revise the order so it fits the upcoming sequence]
      1. Hypervisors
      2. Users and Tenants (Projects)
      3. Images and Instances
      4. System Architecture
      5. Block Storage and OpenStack Compute
    2. Identity Management
      1. Identity Service Concepts
      2. Memcached and System Time
      3. User CRUD
      4. Monitoring
      5. Certificates for PKI
      6. Run the Identity Service
      7. Troubleshoot the Identity Service
    3. Image Management
      1. Adding images with glance image-create
      2. Getting virtual machine images
      3. Booting a test image
      4. Tearing down (deleting) Instances
      5. Pausing and Suspending Instances
      6. Select a specific host to boot instances on [move to booting]
      7. Creating images from running instances with KVM and Xen
      8. Replicating images across multiple data centers
    4. Instance Management
      1. Interfaces to managing instances
      2. Instance building blocks
      3. Customizing Flavors
      4. Creating instances
      5. Control where instances run
      6. Instance specific data
      7. Managing instance networking
      8. Manage Volumes
      9. Access running instances
      10. Manage running instances
    5. Hypervisors
      1. Hypervisor Configuration Basics
      2. KVM
      3. Xen, XenAPI, XenServer, and XCP
      4. LXC (Linux containers)
      5. VMware vSphere
      6. PowerVM
      7. Hyper-V Virtualization Platform
      8. Bare Metal Driver
    6. Networking with nova-network
      1. Networking Options
      2. DHCP server: dnsmasq
      3. Metadata service
      4. Enabling Ping and SSH on VMs
      5. Removing a Network from a Project
      6. Using multiple interfaces for your instances (multinic)
      7. Existing High Availability Options for Networking
      8. Troubleshooting Networking
    7. (Block Storage) Volumes [install info needs to be moved]
      1. Scheduling
      2. Filter Scheduler
      3. Filters
      4. Weights
      5. Chance Scheduler
      6. Host aggregates
    8. Cells [all config, needs to be moved]
    9. System Administration
      1. Understanding the Compute Service Architecture [move up]
      2. Managing Compute Users
      3. Managing the Cloud
      4. Show usage statistics for hosts and instances
      5. Managing logs
      6. Reference Information for Securing with Root Wrappers
      7. Using Migration
      8. Recovering from a failed compute node
      9. Recovering from a UID/GID mismatch
      10. Nova Disaster Recovery Process
    10. OpenStack Interfaces [make a separate chapter]
      1. The OpenStack dashboard
      2. Using VNC Console
    11. Security Hardening
      1. Trusted Compute Pools
    12. OpenStack Compute Automated Installations [move to install doc?]
    13. OpenStack Compute Tutorials
      1. Running Your First Elastic Web Application on the Cloud
    14. Support [move to the end]
      1. Community Support
    15. Troubleshooting OpenStack Compute
      1. Log files for OpenStack Compute
      2. Common Errors and Fixes for OpenStack Compute
      3. Manually reset the state of an instance
      4. Problems with Injection
  3. OpenStack Networking
    1. Using OpenStack Networking
      1. Core OpenStack Networking API features
      2. Using OpenStack Compute with OpenStack Networking
    2. Under the Hood [Proposing a new title: Networking scenarios]
      1. Open vSwitch
      2. Linux bridge
    3. Advanced Features through API Extensions
      1. Provider Networks
      2. L3 Routing and NAT
      3. Security Groups
      4. Load-Balancer-as-a-Service
      5. Plugin Specific Extensions
    4. Authentication and Authorization
    5. Advanced Operational Features [remove Quota info and merge with other Advanced Features]
      1. Logging Settings
      2. Notifications
    6. High Availability
    7. Limitations
    8. Demos Setup [Poll for placement]
      1. Single Flat Network
      2. Provider Router with Private Networks
      3. Per-tenant Routers with Private Networks
      4. Scalable and Highly Available DHCP Agents
    9. Plugin pagination and sorting support
  4. Object Storage
    1. Introduction to OpenStack Object Storage
      1. Accounts and Account Servers
      2. Authentication and Access Permissions
      3. Containers and Objects
      4. Operations
      5. Language-Specific API Bindings
    2. System Administration for OpenStack Object Storage
      1. Understanding How Object Storage Works
      2. Object Layout on Storage
      3. Preparing the Ring
      4. Considerations and Tuning
      5. Replication
      6. Managing Large Objects (Greater than 5 GB)
      7. Throttling Resources by Setting Rate Limits
      8. Additional Features
      9. Bulk Delete
      10. Managing OpenStack Object Storage with CLI Swift
    3. OpenStack Object Storage Tutorials
      1. Storing Large Photos or Videos on the Cloud
    4. OpenStack Object Storage Monitoring
      1. Swift Recon
      2. Swift-Informant
      3. Statsdlog
      4. Swift StatsD Logging
    5. Support [generic, can be moved to the end]
    6. Troubleshooting OpenStack Object Storage
      1. Handling Drive Failure
      2. Handling Server Failure
      3. Detecting Failed Drives
      4. Emergency Recovery of Ring Builder Files
  5. Block Storage
    1. Introduction to the OpenStack Block Storage Service
    2. Managing Volumes
      1. Troubleshoot your cinder installation
      2. Adding Block Storage Nodes
      3. Boot From Volume
  6. Support
  7. A list of other docs with links
  8. Glossary (if and when possible)
  9. Index (if and when possible)


Next steps:

  • Now that we have narrowed down the purpose of this guide to cloud system administrations, ask SMEs whether any other content should be moved to other guides
  • Match up the structure of each chapter, moving the content around and updating the headings as appropriate
  • Clean up the content for style and grammar
  • Update the material for Havana