Jump to: navigation, search

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

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