..
   This work is licensed under a Creative Commons Attribution 3.0 Unported
 License.

 https://creativecommons.org/licenses/by/3.0/legalcode

==================
Container Snapshot
==================
Related Launchpad Blueprint:

https://blueprints.launchpad.net/zun/+spec/container-snapshot
Zun needs to snapshot a running container, and make it available to user.
Potentially, a user can restore the container from this snapshot image.

Problem description
===================
It is a common requirement from users of containers to save the changes of a
current running container to a new image. Zun currently does not support
taking a snapshot of a container.

Proposed change
===============
1. Introduce a new CLI command to enable a user to take a snapshot of a running
   container instance.
   zun commit <container-name> <image-name>
   # zun help commit
   usage: zun commit <container-name> <image-name>
          Create a new image by taking a snapshot of a running container.
   Positional arguments:
          <container-name>              Name or ID of container.
          <image-name>                  Name of snapshot.
2. Extend docker driver to enable “docker commit” command to create a
   new image.
3. The new image should be accessable from other hosts. There are two
   options to support this:
   a) upload the image to glance
   b) upload the image to docker hub
   Option a) will be implemented as default; future enhancement can be
   done to support option b).

Design Principles
=================
Similar user experience between VMs and containers. In particular,
the ways to snapshot a container should be similar as the VM equivalent.

Alternatives
============
1. Using linked volumes to persistent changes in a container.
2. Use docker cp to copy data from the container onto the host machine.

Data model impact
=================
None

REST API impact
===============
Creates an image from a container.

Specify the image name in the request body.

After making this request, a user typically must keep polling the status of the created image
from glance to determine whether the request succeeded.
If the operation succeeds, the created image has a status of active. User can also see the new
image in the image back end that OpenStack Image service manages.

Preconditions:
1. The container must exist.
2. User can only create a new image from the container when its status is Running, Stopped,
   and Paused.
3. The connection to the Image service is valid.


POST /containers/<ID>/commit:        commit a container
Example commit
{
    "image-name" : "foo-image"
}

Response:
If successful, this method does not return content in the response body. Normal response codes: 202
Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404)

Security impact
===============
None

Notifications impact
====================
None

Other end user impact
=====================
None

Performance Impact
==================
None

Other deployer impact
=====================
None

Developer impact
================
None

Implementation
==============
Assignee(s)
Primary assignee: Bin Zhou
Other contributors:
Work Items
1. Expend docker driver to enable “docker commit”.
2. Upload the generated image to glance.
3. Implement a new API endpoint for createImage.
4. Implement unit/integration test.

Dependencies
============
None

Testing
=======
Each patch will have unit tests, and Tempest functional tests covered.

Documentation Impact
====================
A set of documentation for this new feature will be required.