Spec for container snapshot

This spec proposed to providing snapshot feature for containers.

Implements: blueprint container-snapshot

Change-Id: I768046ba4d9e2f211af8397f59eea8a4a2b4471f

specs/containter-snapshot.rst

@@ -0,0 +1,129 @@
+..
+   This work is licensed under a Creative Commons Attribution 3.0 Unported
+ License.
+
+ http://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.