specs for support-volume-binds

Change-Id: Ie610573205112008ed83f4562000545fff9f2418
Implements: blueprint support-volume-binds

specs/local-volume-integration.rst

@@ -0,0 +1,130 @@
+..
+   This work is licensed under a Creative Commons Attribution 3.0 Unported
+ License.
+
+ https://creativecommons.org/licenses/by/3.0/legalcode
+
+============================
+Local Volume Integration
+============================
+Related Launchpad Blueprint:
+
+https://blueprints.launchpad.net/zun/+spec/support-volume-binds
+
+Zun has introduced an option for users to bind-mount Cinder volumes
+to containers.
+However, users can't bind-mount file or directory in local file system
+into the container. This function is like the option '-v' of docker run/create:
+$ docker run -v /host/path:/container/path <image>
+The above command will bind-mount the directory with path '/host/path'
+into path '/container/path' inside the container.
+
+Problem description
+===================
+Some special application containers need use the files/directories
+in localhost for initializing process or getting a large amount of data.
+So zun should implement the option, and this option should work well with
+the cinder volume together.
+
+Proposed change
+===============
+This spec proposes the following changes.
+
+1. It's unsafe to mount the host directory into the container, so only admin can
+   bind-mount file or directory in local file system into the container.
+
+2. We leverage the --mount option for cinder volume bindmount. It is better to
+   reuse this option for bind-mounting local file system.
+   For example:
+   $ zun run --mount type=<local|cinder>,source=...,destination=... <image>
+
+3. Zun introduces a config (called 'allowed_mount_path.conf').
+   Operators can tune this config to restrict the path for bind-mounting.
+
+4. The administrator would be aware that a special container should be scheduled
+   on which nodes. Users may combine --mount and --label options to create a container.
+
+Workflow
+=============
+The typical workflow to create a container with a Local volume will be as
+following:
+
+1. A user calls Zun APIs to create a container with a local volume::
+
+    $ zun run --mount type=local,source=/proc,destination=/proc \
+      --label <key=value> centos
+
+2. After receiving this request, Zun will check if the mount info has local volumes.
+   Then it will check the user has administrator permissions operation.
+
+3. Zun will create an item for local volume, and store in the volume_mapping table.
+
+4. Zun will choose a node by the option --label, and check the local volume whether in
+   the volume lists in forbidden_volume.conf.
+
+5. Zun will calls Docker API to create a container and use the option "-v".
+
+    $ docker run -d -v /proc:/proc centos
+
+Security impact
+---------------
+1. Only admin can bind-mount file or directory in local file system into the container.
+
+2. Zun introduces a config (called 'allowed_mount_path.conf') to check the files/directories
+   can be bind-mounted. When the config is unsetted or empty, zun will raise Exception
+   when using the bind-mounted option.
+
+
+Notifications impact
+--------------------
+None
+
+
+Other end user impact
+---------------------
+None
+
+
+Performance Impact
+------------------
+None
+
+Other deployer impact
+---------------------
+Deployers need to deploy a Cinder.
+
+
+Developer impact
+----------------
+None
+
+
+Implementation
+==============
+
+
+Assignee(s)
+-----------
+Primary assignee:
+Feng Shengqin
+
+Other contributors:
+
+
+Dependencies
+============
+
+
+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.
+
+References
+==========
+[1] https://docker-py.readthedocs.io/en/stable/containers.html#container-objects.
+