diff --git a/docs/docker_run.rst b/docs/docker_run.rst index f17cd642..15c667a6 100644 --- a/docs/docker_run.rst +++ b/docs/docker_run.rst @@ -12,10 +12,10 @@ The ``docker_run`` task exposes a ``container_args`` parameter which can be used to pass arguments to the container entrypoint. -Volumes -------- +BindMountVolumes +---------------- -The volumes to be mounted into a container can be passed to the ``docker_run`` task +The volumes to be bind mounted into a container can be passed to the ``docker_run`` task in one of two ways. Using docker-py syntax @@ -36,23 +36,23 @@ which is passed directly to docker-py. For example } docker_run.delay('my/image', pull_image=True, volumes=volumes) -Using the Volume class -^^^^^^^^^^^^^^^^^^^^^^ +Using the BindMountVolume class +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Girder Worker provides a utility class :py:class:`girder_worker.docker.transforms.Volume` +Girder Worker provides a utility class :py:class:`girder_worker.docker.transforms.BindMountVolume` that can be used to define volumes that should be mounted into a container. These classes can also be used in conjunction with other parts of the girder_work docker infrastructure, for example providing a location where a file should be downloaded to. -See `Downloading files from Girder`_. When using the :py:class:`girder_worker.docker.transforms.Volume` +See `Downloading files from Girder`_. When using the :py:class:`girder_worker.docker.transforms.BindMountVolume` class a list of instances is provided as the value for the ``volumes`` parameter, Girder Worker will take care of ensuring that these volumes are mounted. In the example below we are creating -a :py:class:`girder_worker.docker.transforms.Volume` instance and passing it as a container argument to provide +a :py:class:`girder_worker.docker.transforms.BindMountVolume` instance and passing it as a container argument to provide the mounted location to the container. Girder Worker will take care of transforming the instance into the approriate path inside the container. .. code-block:: python - vol = Volume('/home/docker/data', '/mnt/docker/') + vol = BindMountVolume('/home/docker/data', '/mnt/docker/') docker_run.delay('my/image', pull_image=True, volumes=[vol], container_args=[vol]) Temporary Volume @@ -72,7 +72,7 @@ will simply received a path. .. code-block:: python - vol = Volume('/home/docker/data', '/mnt/docker/') + vol = BindMountVolume('/home/docker/data', '/mnt/docker/') docker_run.delay('my/image', pull_image=True, container_args=[TemporaryVolume.default]) Note that because we are using the default path, we don't have to add the instance to @@ -97,11 +97,11 @@ downloaded to into the docker container's entrypoint as an argument. If no ``volume`` parameter is specified then the file will be downloading to the task temporary volume. The file can also be downloaded to a specific -:py:class:`girder_worker.docker.transforms.Volume` by specifying a volume parameter, as follows: +:py:class:`girder_worker.docker.transforms.BindMountVolume` by specifying a volume parameter, as follows: .. code-block:: python - vol = Volume(host_path, container_path) + vol = BindMountVolume(host_path, container_path) docker_run.delay('my/image', pull_image=True, container_args=[GirderFileIdToVolume(file_id,volume=vol)]) diff --git a/girder_worker/docker/transforms/__init__.py b/girder_worker/docker/transforms/__init__.py index fc47065f..f8cd6467 100644 --- a/girder_worker/docker/transforms/__init__.py +++ b/girder_worker/docker/transforms/__init__.py @@ -70,9 +70,9 @@ def open(self): pass -class Volume(Transform): +class BindMountVolume(Transform): """ - A docker volume that will be attached to a docker container. + A volume that will be bind mounted to a docker container. """ def __init__(self, host_path, container_path, mode='rw'): """ @@ -114,7 +114,7 @@ def default(cls): return _DefaultTemporaryVolume() -class _TemporaryVolumeBase(Volume): +class _TemporaryVolumeBase(BindMountVolume): def __init__(self, *arg, **kwargs): super(_TemporaryVolumeBase, self).__init__(*arg, **kwargs) self._transformed = False diff --git a/tests/integration/integration_test_endpoints/server/docker.py b/tests/integration/integration_test_endpoints/server/docker.py index e21fc1be..b790a732 100644 --- a/tests/integration/integration_test_endpoints/server/docker.py +++ b/tests/integration/integration_test_endpoints/server/docker.py @@ -23,7 +23,7 @@ NamedInputPipe, Connect, VolumePath, - Volume, + BindMountVolume, ChunkedTransferEncodingStream, TemporaryVolume ) @@ -207,7 +207,7 @@ def test_docker_run_mount_idiomatic_volume(self, params): filename = 'read.txt' mount_dir = '/mnt/test' mount_path = os.path.join(mount_dir, filename) - volume = Volume(fixture_dir, mount_path, 'ro') + volume = BindMountVolume(fixture_dir, mount_path, 'ro') volumepath = VolumePath(filename, volume) result = docker_run.delay( diff --git a/tests/test_docker_transforms.py b/tests/test_docker_transforms.py index 977e85a4..0849f1f0 100644 --- a/tests/test_docker_transforms.py +++ b/tests/test_docker_transforms.py @@ -36,7 +36,7 @@ NamedPipeBase, TEMP_VOLUME_MOUNT_PREFIX, TemporaryVolume, - Volume, + BindMountVolume, VolumePath, _maybe_transform ) @@ -75,7 +75,7 @@ def patch_mkdir(): @pytest.fixture def bogus_volume(): - yield Volume(BOGUS_HOST_PATH, BOGUS_CONTAINER_PATH) + yield BindMountVolume(BOGUS_HOST_PATH, BOGUS_CONTAINER_PATH) @pytest.mark.parametrize('obj', [