Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add equivalent of bind-recursive option to the Mount type class #3242

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Add equivalent of bind-recursive option to the Mount type class #3242

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 23 additions & 5 deletions docker/types/services.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -235,6 +235,9 @@ class Mount(dict):
``default```, ``consistent``, ``cached``, ``delegated``.
propagation (string): A propagation mode with the value ``[r]private``,
``[r]shared``, or ``[r]slave``. Only valid for the ``bind`` type.
recursive (string): Bind mount recursive mode, one of ``enabled``,
``disabled``, ``writable``, or ``readonly``. Only valid for the
``bind`` type.
no_copy (bool): False if the volume should be populated with the data
from the target. Default: ``False``. Only valid for the ``volume``
type.
Expand All @@ -247,9 +250,9 @@ class Mount(dict):
"""

def __init__(self, target, source, type='volume', read_only=False,
consistency=None, propagation=None, no_copy=False,
labels=None, driver_config=None, tmpfs_size=None,
tmpfs_mode=None):
consistency=None, propagation=None, recursive=None,
no_copy=False, labels=None, driver_config=None,
tmpfs_size=None, tmpfs_mode=None):
self['Target'] = target
self['Source'] = source
if type not in ('bind', 'volume', 'tmpfs', 'npipe'):
Expand All @@ -267,6 +270,21 @@ def __init__(self, target, source, type='volume', read_only=False,
self['BindOptions'] = {
'Propagation': propagation
}
if recursive is not None:
bind_options = self.setdefault('BindOptions', {})
if recursive == "enabled":
pass # noop - default
elif recursive == "disabled":
bind_options['NonRecursive'] = True
elif recursive == "writable":
bind_options['ReadOnlyNonRecursive'] = True
elif recursive == "readonly":
bind_options['ReadOnlyForceRecursive'] = True
else:
raise errors.InvalidArgument(
'Invalid recursive bind option, must be one of '
'"enabled", "disabled", "writable", or "readonly".'
)
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks good.

The CLI also does some validation, not sure if we should do those too? 🤔
https://github.com/docker/cli/blob/v25.0.5/opts/mount.go#L183-L196

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure - some other options are also validated loosely here or not at all, so I'm sticking with that, only added this InvalidArgument error for unknown options since we need to enumerate the possible values to map them to mount config options anyway.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

(disclaimer: I'm a maintainer for the docker CLI, but I'm not very good at Python, or very familiar with existing code in this repository for that matter).

In general (in docker/cli), we try to keep client-side validation "light" where possible, so that we can defer to the API as source of truth (also accounting for situations where only the daemon can fully validate, as well as preventing the CLI from disallowing options that may be supported at some point in future).

That said, for some cases we do some validation on the client side, either where we are sure (or "very confident") certain validation would never change, or for situations where performing the API request (when invalid) would be much more "heavyweight" than a local check, and where a client-side validation can provide a better experience to the user (e.g. producing a more specific error message).

All of the above out of the way, it would be good to verify the behavior when using one of those invalid combinations; the API should validate those, but it'd be good to check if it does, and if so, if the error-message is useful enough to the user to resolve the problem.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Cool, thanks for the insights, @thaJeztah. For me the only concern is this:

we are sure (or "very confident") certain validation would never change

I think it's the case for the referred checks done in CLI for the bind options, and the check in Python will have minimal overhead, so I'm fine with adding it here. Let's see what others have to say.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Just to emphasize; If the API already responds with a reasonable error, then I'm (personally) perfectly fine with keeping it light.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, I mean trade-offs: Validate more means more maintenance. But I'd rather prefer checks in this library than on users side 😅. I guess in our use case it doesn't matter all that much as we won't have this options user controlled, but just use sensible value/combinations. But I agree, it mostly depends on if/how errors are raised if invalid combinations hit the API directly.

On the other hand, since we don't have such validation so far, probably better to skip them too for consistency. 🤷‍♂️

if any([labels, driver_config, no_copy, tmpfs_size, tmpfs_mode]):
raise errors.InvalidArgument(
'Incompatible options have been provided for the bind '
Expand All @@ -282,7 +300,7 @@ def __init__(self, target, source, type='volume', read_only=False,
volume_opts['DriverConfig'] = driver_config
if volume_opts:
self['VolumeOptions'] = volume_opts
if any([propagation, tmpfs_size, tmpfs_mode]):
if any([propagation, recursive, tmpfs_size, tmpfs_mode]):
raise errors.InvalidArgument(
'Incompatible options have been provided for the volume '
'type mount.'
Expand All @@ -299,7 +317,7 @@ def __init__(self, target, source, type='volume', read_only=False,
tmpfs_opts['SizeBytes'] = parse_bytes(tmpfs_size)
if tmpfs_opts:
self['TmpfsOptions'] = tmpfs_opts
if any([propagation, labels, driver_config, no_copy]):
if any([propagation, recursive, labels, driver_config, no_copy]):
raise errors.InvalidArgument(
'Incompatible options have been provided for the tmpfs '
'type mount.'
Expand Down
69 changes: 68 additions & 1 deletion tests/integration/api_container_test.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -598,6 +598,60 @@ def test_create_with_mounts_ro(self):
inspect_data = self.client.inspect_container(container)
self.check_container_data(inspect_data, False)

@requires_api_version('1.41')
def test_create_with_mounts_recursive_disabled(self):
mount = docker.types.Mount(
type="bind", source=self.mount_origin, target=self.mount_dest,
read_only=True, recursive="disabled"
)
host_config = self.client.create_host_config(mounts=[mount])
container = self.run_container(
TEST_IMG, ['ls', self.mount_dest],
host_config=host_config
)
assert container
logs = self.client.logs(container).decode('utf-8')
assert self.filename in logs
inspect_data = self.client.inspect_container(container)
self.check_container_data(inspect_data, False,
bind_options_field="NonRecursive")

@requires_api_version('1.44')
def test_create_with_mounts_recursive_writable(self):
mount = docker.types.Mount(
type="bind", source=self.mount_origin, target=self.mount_dest,
read_only=True, recursive="writable"
)
host_config = self.client.create_host_config(mounts=[mount])
container = self.run_container(
TEST_IMG, ['ls', self.mount_dest],
host_config=host_config
)
assert container
logs = self.client.logs(container).decode('utf-8')
assert self.filename in logs
inspect_data = self.client.inspect_container(container)
self.check_container_data(inspect_data, False,
bind_options_field="ReadOnlyNonRecursive")

@requires_api_version('1.44')
def test_create_with_mounts_recursive_ro(self):
mount = docker.types.Mount(
type="bind", source=self.mount_origin, target=self.mount_dest,
read_only=True, recursive="readonly"
)
host_config = self.client.create_host_config(mounts=[mount])
container = self.run_container(
TEST_IMG, ['ls', self.mount_dest],
host_config=host_config
)
assert container
logs = self.client.logs(container).decode('utf-8')
assert self.filename in logs
inspect_data = self.client.inspect_container(container)
self.check_container_data(inspect_data, False,
bind_options_field="ReadOnlyForceRecursive")

@requires_api_version('1.30')
def test_create_with_volume_mount(self):
mount = docker.types.Mount(
Expand All @@ -620,7 +674,8 @@ def test_create_with_volume_mount(self):
assert mount['Source'] == mount_data['Name']
assert mount_data['RW'] is True

def check_container_data(self, inspect_data, rw, propagation='rprivate'):
def check_container_data(self, inspect_data, rw, propagation='rprivate',
bind_options_field=None):
assert 'Mounts' in inspect_data
filtered = list(filter(
lambda x: x['Destination'] == self.mount_dest,
Expand All @@ -631,6 +686,18 @@ def check_container_data(self, inspect_data, rw, propagation='rprivate'):
assert mount_data['Source'] == self.mount_origin
assert mount_data['RW'] == rw
assert mount_data['Propagation'] == propagation
if bind_options_field:
assert 'Mounts' in inspect_data['HostConfig']
mounts = [
x for x in inspect_data['HostConfig']['Mounts']
if x['Target'] == self.mount_dest
]
assert len(mounts) == 1
mount = mounts[0]
assert 'BindOptions' in mount
bind_options = mount['BindOptions']
assert bind_options_field in bind_options
assert bind_options[bind_options_field] is True

def run_with_volume(self, ro, *args, **kwargs):
return self.run_container(
Expand Down
Loading