ReleaseNotes/Folsom

= OpenStack 2012.2 (Folsom) Release Notes =

Key New Features

 * Unique-as-possible data placement within the cluster
 * DB prealloc toggle allows Swift to take advantage of the speed/space constraints of solid-state drives vs. spinning drives
 * The swift3 middleware (AWS S3 compatibility support) has been moved to a separate, externally hosted, project
 * Swift now supports versioned object writes
 * Deep statsd integration for monitoring a Swift cluster
 * Swift CLI and client lib moved to the python-swiftclient project
 * The Keystone middleware for Swift integration was moved from Keystone into Swift
 * Swift now has a new custom on-disk format for the rings that is hundreds of times faster in newer versions of Python
 * Swift no longer uses pickle in memcache values

The full changelog for Swift can be found in Swift's CHANGELOG

The full list of Folsom features can be found here.

Known Issues
None yet.

Upgrade Notes
As always, a production Swift cluster can be upgraded live, with no downtime for clients. The normal upgrade path is:


 * 1) Stop the background processes
 * 2) Upgrade the packages
 * 3) Reload the processes (eg `swift-init object reload`)
 * 4) Start the background processes

A normal upgrade process will upgrade one storage server in one zone (a "canary node") to check if any unforseen issue arise. After than node is upgraded, upgrade the other storage nodes in that zone. Next, upgrade each of the remaining zones in turn. Finally, upgrade each of your proxy servers (one at time).

The items below are things that have changed in Swift since the OpenStack Essex release and should be understood by deployers before upgrading:


 * DB Preallocation needs to be set to True for existing clusters using traditional hard drives (commit)
 * swift3 middleware is now hosted externally to the swift project
 * A new dependency on `python-swiftclient` (where the CLI and client library have moved). This project is the second deliverable of Swift in the OpenStack umbrella.
 * Upgraded clusters cannot use old rings (see post)
 * Migration path for memcache values (commit)

Key New Features
The entire list of features completed during the Folsom Release is available here. Highlights are included below.


 * Race conditions were reduced and state handling was dramatically improved: task-management
 * Messages to compute and scheduler are versioned. This helps prevent failures with attempting to use different workers together: versioned-rpc-apis
 * Nova-api can now run more than one process: multi-process-api-service
 * Support for LVM backed instances (instead of qcow2) was added to the libvirt driver: lvm-disk-images
 * Support for live-migration, block-migration and boot-from-volume were added to xenapi: xenapi-live-migration xenapi-live-block-migration xenapi-boot-from-volume
 * The libvirt_cpu_mode flag allows the CPU model of virtual machines to be customized by cloud administrators. See LibvirtXMLCPUModel for details.
 * General Host Aggregates were implemented, allowing metadata to be set dynamically for hosts and pased to the scheduler general-host-aggregates
 * Config Drive v2, which allows guests to retrieve metadata without dhcp and nova-metadata: config-drive-v2
 * Hyper V support was added: hyper-v-revival
 * Trusted computing pools: trusted-computing-pools
 * Nova Volume service has been extracted to Cinder: volume-decoupling
 * Lots of improvements were made to the scheduler, Including filters for image architecture and scheduling based on capabilities from aggregates. See doc.
 * XML support and testing was improved. We now have automatic testing for most of the api samples on http://api.openstack.org, and more samples and testing will be included over the next couple of months.

Known Issues

 * Security Groups do not mix well with floating ips. Users should use fixed ips in security group rules. More information here
 * Floating IPs are not automatically moved during a migrate or live-migrate. This was carried over from essex and was never addressed. Details and workaround in: bug 966529 and bug 1053344
 * The default value for the libvirt_cpu_mode option is "host-model" but apparently this results in an error like "unsupported configuration: CPU specification not supported by hypervisor" if you run Nova inside a VM; libvirt_cpu_mode="none" should be used for such deployments http://wiki.openstack.org/LibvirtXMLCPUModel
 * When using LVM as backend storage on Ubuntu 12.04 snapshot delete's can hang system on dd process. Track the fix here: bug 1023755
 * DHCP can fail with newer kernels. There is a workaround included in the bug report here: bug 1029430
 * Xenapi cannot boot raw images properly. Make sure to use vhd images for xenapi: bug 1055413
 * The xenapi driver does not properly handle vm_mode=xen images. The xenapi code doesn't report capabilities properly, so the scheduler doesn't find the host. For now, do not set vm_mode=xen in image properties: bug 1055431
 * The ZeroMQ RPC driver added during Folsom is still considered experimental and may see incompatible changes during the Grizzly cycle.

Upgrade Notes
image_cache_manager_interval = 0 Related Bug
 * WARNING: If you are backing your instances with shared storage, make sure to disable image cache BEFORE upgrading to Folsom:


 * NOVA-VOLUMES IS DEPRECATED Please migrate to cinder as soon as possible. Cinder migration is documented at MigrateToCinder. Nova-volumes will no longer exist in grizzly.
 * The libvirt.xml.template and cpuinfo.xml.template files have been removed. See LibvirtXMLConfigAPIs
 * The way that nova-volumes (and cinder) interacts with tgtd has changed significantly in Folsom. You need to ensure that the config files now written to /var/lib/nova/volumes are loaded via tgtd's targets.conf file. See this ML post for details.
 * The way rootwrap is configured has changed significantly in Folsom. See Packager/Rootwrap for details.
 * The connection_type flag has been deprecated (and will be removed for the Grizzly release) in favor of compute_driver, so  should be replaced with   and   should be replaced with.
 * Due to an old difference in the way that the different drivers allocated disks from instance_types/flavors, the migration would create different default flavors depending on connection_type. Since connection_type is deprecated, if you use the new compute_driver above, a new install will always get the "xenapi-style" flavors, which means all the space allocated to the root disk and an empty ephemeral disk. If you wish the flavors to be "libvirt-style" (10 GB root disk and other space in the ephemeral), you can leave connection_type=libvirt in your config file or change them manually after db sync.
 * Some dependency requirements have been upgraded.
 * eventlet must now be >= 0.9.17
 * lxml must now be >= 2.3 and <= 2.3.5
 * python-quantumclient >= 2.0 is required (new)
 * python-glanceclient >= 0.5.0 and < 2 is required (new)
 * sqlalchemy must now be >= 0.7.8 (not shown in pip-requires)

Key New Features

 * Completely new v2 API
 * Completely new client - python-glanceclient
 * Client SSL certificate validation on glance-api
 * Tenant-specific storage in Swift
 * Image replication using glance-replicator

The full list of Folsom features can be found here.

Known Issues

 * v2 API requires sql configuration on glance-api nodes

Upgrade Notes

 * auth_token middleware configuration moved from paste configuration to server confguration
 * Set enable_v2_api to 'false' to disable new v2 API or copy sql configuration from glance-registry.conf to glance-api.conf
 * Update local keystone code before starting Folsom glance services

Networking (Quantum)
With Quantum being a core project for the Folsom release, we worked closely with the Quantum team to bring networking support back into Horizon. This appears in two primary places: the Networks panel in both the Project and Admin dashboards, and the Network tab in the Launch Instance workflow. Expect further improvements in these areas as Quantum continues to mature and more users adopt this model of virtual network management.

Workflows
By far the biggest UI/UX change in the Folsom release is the introduction of programmatic workflows. These components allow developers to create concise interactions that combine discrete tasks spanning multiple services and resources in a user-friendly way and with minimal boilerplate code. Within a workflow, related objects can also be dynamically created so users don't lose their place when they realize the item they wanted isn't currently available. Look for examples of these workflows in Launch Instance, Associate Floating IP, and Create/Edit Project.

Resource Browser
Another cool new component is an interface designed for browsing resources which are nested under a parent resource. The object store (Swift) is a prime example of this. Now there is a consistent top-level navigation for containers on the left-hand pane of the browser while the right-hand pane lets you explore within those containers and sub-folders.

User Experience Improvements

 * Timezone support is now enabled. You can select your preferred timezone in the User Settings panel.

Community

 * Third-party developers who wish to build on Horizon can get started much faster using the new dashboard and panel templates. See the docs on creating a dashboard and creating a panel for more information.
 * A thorough set of documentation for developers on how to go about internationalizing, localizing and translating OpenStack projects is now available.

Under The Hood

 * The python-swiftclient library and python-cinderclient libraries are now used under the hood instead of cloudfiles and python-novaclient respectively.
 * Internationalization of client-side JavaScript is now possible in addition to server-side Python code.
 * Keystone authentication is now handled by a proper pluggable Django authentication backend, offering significantly better and more reliable security for Horizon.

Other Improvements and Fixes
Some of the general areas of improvement include:


 * Images can now be added to Glance by providing a URL for Glance to download the image data from.
 * Quotas are now displayed dynamically throughout the Project dashboard.
 * API endpoints are now displayed on the OpenStack RC File panel so they can be organically discovered by an end-user.
 * DataTables now support a summation row at the bottom of the table.
 * Better cross-browser support (Safari and IE particularly).
 * Fewer API calls to OpenStack endpoints (improves performance).
 * Better validation of what actions are permitted when.
 * Improved error handling and error messages.

Floating IPs and Quantum
Due to the very late addition of floating IP support in Quantum, Nova's integration there is lacking, so floating IP-related API calls to Nova will fail when your OpenStack deployment uses Quantum for networking. This means that Horizon actions such as 'allocate' and 'associate' floating IPs will not work either since they rely on the underlying APIs.

Pagination
A number of the 'index' pages don't fully work with API pagination yet, causing them to only display the first chunk of results returned by the API. This number is often 1000 (as in the case of novaclient results), but does vary somewhat.

Deleting large numbers of resources simultaneously
Using the 'select all' checkbox to delete large numbers of resources via the API can cause network timeouts (depending on configuration). This is due to the APIs not supporting bulk-deletion natively, and consequently Horizon has to send requests to delete each resource individually behind the scenes.

Upgrade Notes
The Folsom Horizon release should be fully-compatible with both Folsom and Essex versions of the rest of the OpenStack core projects (Nova, Swift, etc.). While some features work significantly better with an all-Folsom stack due to bugfixes, etc. in underlying services, there should not be any limitations on what will or will not function. (Note: Quantum was not a core OpenStack project in Essex, and thus this statement does not apply to network management.)

In terms of APIs provided for extending Horizon, there are a handful of backwards-incompatible changes that were made:


 * The can_haz and can_haz_list template filters have been renamed to has_permissions and has_permissions_on_list respectively.
 * The dashboard-specific base.html templates (e.g. nova/base.html, syspanel/base.html, etc.) have been removed in favor of a single base.html template.
 * In conjunction with the previous item, the dashboard-specific template blocks (e.g. nova_main, syspanel_main, etc.) have been removed in favor of a single main template block.

Overall, though, great effort has been made to maintain compatibility for third-party developers who may have built on Horizon so far.

Key New Features

 * PKI Support for authentication
 * Integration into openstack-common libraries
 * Swift AUTH middleware allowing overrides of authentication
 * Consolidation of CLI option names to global OpenStack standard (use hyphens)

The full list of Folsom features can be found here.

Known Issues

 * V2 API exposes token within the URL
 * If a tenant is deleted in Keystone, there is no orchestration to verify that resources associated with that tenant are disabled and/or removed in other projects (glance, nova, swift, etc)
 * The Keystone CLI lacks a means of reporting the tenants that a user is associated with
 * auth_token middleware requires installation of almost all of keystone, is not in its own package
 * LDAP backend is lacking TLS/LDAPS support
 * No active directory specific LDAP backend
 * V2 API is not backed by RBAC

Upgrade Notes
None yet.

Key Features

 * First "core" release of OpenStack Quantum
 * v2 tenant-facing API to control L2 networking and IP address management
 * pluggable network back-ends technologies, including Open vSwitch, Cisco, Linux Bridge, Nicira NVP, Ryu, and NEC.
 * support for overlapping IP addresses on different L2 networks.
 * new and improved CLI
 * DHCP service with support for overlapping IPs.
 * support for OpenStack notifications and API quotas.
 * extension support for "provider networks" that map to physical VLANs or flat networks.
 * extension support for basic L3 forwarding, SNAT, and floating IPs. Support for multiple routers.
 * Keystone-integrated API policy framework to allow support different API-modes: tenant network control or admin-only network control.

The full list of Folsom features can be found here.

Known Issues

 * Nova security groups and metadata server are not compatible with overlapping IPs.

Key Features

 * First core release of OpenStack Cinder
 * Block Storage service
 * Cinder is an extraction of nova-volume
 * Updated third party drivers
 * New drivers from NetApp (iSCSI and NFS) and IBM
 * Upgraded features in Ceph RDB
 * Generic NFS driver to present NFS as block storage
 * Improved boot from volume (ability to specify image at volume creation)
 * Ability to create image from volume
 * Introduction of Persistent iSCSI targets via tgtadm. Note that you must add '$state_path/volumes/*' to your tgtd conf file, either via includes file in tgt/conf.d or directly in tgt/targets.conf.
 * DB migration tool added to cinder-manage
 * Fully compatible with Nova-Volume with the exception of XenSM
 * Features and bug fixes have been synced between Folsom Nova-Vol and Cinder
 * Full volume info now returned in create response
 * Size argument is now optional in create_snapshot (defaults to volume size)

The full list of Folsom features can be found here.

Migrate From Nova-Volumes to Cinder
The process for migrating from Nova-Volumes to Cinder are as follows:


 * Cinder migration is documented at MigrateToCinder

Known Issues

 * Moving from Nova-Volume to Cinder is only supported Folsom-->Folsom
 * After an upgrade from essex to folsom, attempting to attach volumes that existed pre-upgrade to instances does not work. Track the fix here: bug 1065702
 * When using LVM as backend storage on Ubuntu 12.04 snapshot delete's can hang. Track the fix here: bug 1023755.
 * Current unit tests are incompatible with 32 bit machines
 * XenSM support needs updated

= Known packaged distributions =

Ubuntu 12.04 / Ubuntu 12.10
All core OpenStack Folsom components are officially supported and available in the Main Quantal Ubuntu archive and the Ubuntu Cloud Archive:


 * Nova
 * Glance
 * Swift
 * Horizon
 * Keystone
 * Quantum
 * Cinder

Folsom can be deployed using MAAS and Juju.

To read about how to use Folsom on Ubuntu 12.04, please see the following blog post.

Fedora 17 / Fedora 18 / EPEL 6
All core OpenStack Folsom components are available in the Main Fedora 18 repository.

Please see the Fedora OpenStack packages overview, where you can drill down to get details of versions available etc.

You can also install on Fedora 17 using this side repository

EPEL 6 will be updated to Folsom shortly after release