[virt-tools-list] [virt-bootstrap] [PATCH v6 24/26] Update doc strings
Cedric Bosdonnat
cbosdonnat at suse.com
Sat Aug 19 13:39:41 UTC 2017
On Thu, 2017-08-17 at 10:40 +0100, Radostin Stoyanov wrote:
> These documentation can be seen using:
>
> pydoc virtBootstrap
> ---
> src/virtBootstrap/__init__.py | 207 +++++++++++++++++++++++++++++++---
> src/virtBootstrap/sources/__init__.py | 34 +++---
> src/virtBootstrap/utils.py | 9 +-
> 3 files changed, 208 insertions(+), 42 deletions(-)
>
> diff --git a/src/virtBootstrap/__init__.py b/src/virtBootstrap/__init__.py
> index d5c7651..483bfab 100644
> --- a/src/virtBootstrap/__init__.py
> +++ b/src/virtBootstrap/__init__.py
> @@ -1,26 +1,199 @@
> # -*- coding: utf-8 -*-
> -"""
> -virt-bootstrap - Is a tool providing an easy way to setup the root file system
> - for libvirt-based containers.
> +# Authors:
> +# Radostin Stoyanov <rstoyanov1 at gmail.com>
>
> - Authors:
> - Radostin Stoyanov <rstoyanov1 at gmail.com>
> +# Copyright (c) 2017 Radostin Stoyanov
>
> - Copyright (c) 2017 Radostin Stoyanov
> +# This program is free software: you can redistribute it and/or modify
> +# it under the terms of the GNU General Public License as published by
> +# the Free Software Foundation, either version 3 of the License, or
> +# (at your option) any later version.
>
> - This program is free software: you can redistribute it and/or modify
> - it under the terms of the GNU General Public License as published by
> - the Free Software Foundation, either version 3 of the License, or
> - (at your option) any later version.
> +# This program is distributed in the hope that it will be useful,
> +# but WITHOUT ANY WARRANTY; without even the implied warranty of
> +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
> +# GNU General Public License for more details.
>
> - This program is distributed in the hope that it will be useful,
> - but WITHOUT ANY WARRANTY; without even the implied warranty of
> - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
> - GNU General Public License for more details.
> +# You should have received a copy of the GNU General Public License
> +# along with this program. If not, see <http://www.gnu.org/licenses/>.
>
> - You should have received a copy of the GNU General Public License
> - along with this program. If not, see <http://www.gnu.org/licenses/>.
> -"""
> +r"""
> +The virtBootstrap module provides an easy way to setup the root file system for
> +Libvirt-LXC containers.
> +
> +This module exports the method bootstrap() which takes the following arguments:
> +
> +
> + uri
> + This parameter takes a string of source URI.
> +
> + Supported URI formats:
> + --------------------------------------
> + - File (tarball)
> + /path/to/local/rootfs.tar.xz
> + file://path/to/local/rootfs.tar.xz
> +
> + - Docker registry (skopeo)
> + docker://ubuntu:latest
> + docker://docker.io/fedora
> + docker://privateregistry:5000/image
> +
> + - virt-builder
> + virt-builder://fedora-25
> + virt-builder://ubuntu-16.04
> + --------------------------------------
> + * If Docker registry is not specified "docker.io" is used.
> +
> +
> + dest
> + This parameter takes a string which represents absolute or real path of
> + destination directory where the root file system will be extract or
> + qcow2 images will be stored.
> +
> +
> + fmt (optional)
> + This parameter takes a string which represents the output format for
> + the root file system. Possible values are:
> + - dir (default)
> + - qcow2
> +
> +
> + username (optional)
> + This parameter takes a string which represents the username used to
> + access Docker source registry. See also "password" and "not_secure".
> +
> + If this parameter is specified and the "password" is ommited password
> + prompt will be issued.
> +
> + *See https://docs.docker.com/registry/deploying/#restricting-access
> +
> +
> + password (optional)
> + This parameter takes a string which represents the password used to
> + access Docker source registry.
> +
> + *See https://docs.docker.com/registry/deploying/#restricting-access
> +
> +
> + root_password (optional)
> + This parameter takes a string which represents root password.
> + This string is hashed and inserted into /etc/shadow file of the
> + extracted root file system.
> + If the output format is "qcow2" the modification of /etc/shadow are
> + applied in additional qcow2 disk image with backing file set to the
> + last layer.
> +
> + *The /etc/shadow file must already exist in the rootfs of the container
> + image and have "root" user entry.
> +
> +
> + uid_map (optional)
> + This parameter takes a list of lists which represents the translation
> + map for UID. See also "gid_map".
> +
> + Format:
> + [[<start>, <target>, <count>]]
> + Example:
> + [[0, 1000, 10], [500, 1500, 10]]
> + This will map the UID: 0-9 to 1000-1009 and 500-509 to 1500-1509
> +
> + *When the output format is "dir" (fmt="dir") this option is available
> + only for privileged users.
> +
> +
> + gid_map (optional)
> + This parameter is used to map group ownership of files in the
> + extracted rootfs. It works in a similar way as "uid_map".
> +
> +
> + not_secure (optional)
> + This parameter takes a boolean which indicates whether HTTPS errors
> + will be ignored. Default value is False.
> +
> + *See "--src-tls-verify" from "skopeo copy".
> + https://www.mankier.com/1/skopeo#skopeo_copy
> +
> +
> + no_cache (optional)
> + This parameter takes a boolean which indicates whether the downloaded
> + Docker images will be discarded after the root file system was
> + extracted.
> +
> + By default downloaded images are stored in:
> + /var/cache/virt-bootstrap/docker_images/
> + for non-root users:
> + ~/.cache/share/virt-bootstrap/docker_images/
> +
> +
> + progress_cb (optional)
> + This parameter takes a function which is called every time when the
> + progress information is updated. Only one parameter passed to the
> + called function - a dictionary with keys 'status' and 'value'.
> +
> + Examples:
> + {'status': 'Checking cached layers', 'value': 0}
> + {'status': 'Downloading layer (1/1)', 'value': 12.82051282051282}
> +
> +
> +Usage Examples
> +
> + import virtBootstrap
> +
> + # Bootstrap latest Ubuntu container image from docker.io
> + virtBootstrap.bootstrap(uri='docker://ubuntu', dest='/tmp/foo')
> +
> + # Bootstrap Fedora 25 container image from docker.io
> + virtBootstrap.bootstrap(
> + uri='docker://registry.fedoraproject.org/fedora:25',
> + dest='/tmp/bar'
> + )
> +
> + # Set password for root
> + virtBootstrap.bootstrap(
> + uri='docker://fedora',
> + dest='/tmp/foo',
> + root_password='secret'
> + )
> +
> + # Convert Ubuntu container image to qcow2 disk image using backing chains
> + virtBootstrap.bootstrap(
> + uri='docker://ubuntu',
> + dest='/tmp/foo',
> + fmt='qcow2'
> + )
> +
> + # Bootstrap root file system from image stored in private registry
> + virtBootstrap.bootstrap(
> + uri='docker://localhost:5000/opensuse',
> + dest='/tmp/foo',
> + username='testuser',
> + password='testpassoword',
> + not_secure=True
> + )
> +
> + # Apply UID/GID mapping (root privileges required).
> + virtBootstrap.bootstrap(
> + uri='docker://ubuntu',
> + dest='/tmp/foo',
> + uid_map=[[0,1000,10]],
> + gid_map=[[0,1000,10]]
> + )
> +
> + # Use progress callback to print the current progress to stdout
> + def show(prog): print(prog)
> +
> + virtBootstrap.bootstrap(
> + uri='docker://ubuntu',
> + dest='/tmp/foo',
> + progress_cb=show
> + )
> +
> +Note:
> + You don't necessarily need to be root when using virt-bootstrap with
> + "qcow2" output format, however, for "dir" format there are some drawbacks:
> + 1. Mapping UID/GID is not supported for unprivileged users.
> + 2. All extracted files will be owned by the current unprivileged user.
> + """
>
> from virtBootstrap.virt_bootstrap import bootstrap
> from virtBootstrap.virt_bootstrap import __version__
> diff --git a/src/virtBootstrap/sources/__init__.py b/src/virtBootstrap/sources/__init__.py
> index d858466..e65b8bc 100644
> --- a/src/virtBootstrap/sources/__init__.py
> +++ b/src/virtBootstrap/sources/__init__.py
> @@ -1,26 +1,26 @@
> # -*- coding: utf-8 -*-
> -"""
> -sources - Class definitions which process container image or
> - tarball to extract the root file system in destination
> - directory or qcow2 image.
> +# Authors:
> +# Radostin Stoyanov <rstoyanov1 at gmail.com>
>
> - Authors:
> - Radostin Stoyanov <rstoyanov1 at gmail.com>
> +# Copyright (c) 2017 Radostin Stoyanov
>
> - Copyright (c) 2017 Radostin Stoyanov
> +# This program is free software: you can redistribute it and/or modify
> +# it under the terms of the GNU General Public License as published by
> +# the Free Software Foundation, either version 3 of the License, or
> +# (at your option) any later version.
>
> - This program is free software: you can redistribute it and/or modify
> - it under the terms of the GNU General Public License as published by
> - the Free Software Foundation, either version 3 of the License, or
> - (at your option) any later version.
> +# This program is distributed in the hope that it will be useful,
> +# but WITHOUT ANY WARRANTY; without even the implied warranty of
> +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
> +# GNU General Public License for more details.
>
> - This program is distributed in the hope that it will be useful,
> - but WITHOUT ANY WARRANTY; without even the implied warranty of
> - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
> - GNU General Public License for more details.
> +# You should have received a copy of the GNU General Public License
> +# along with this program. If not, see <http://www.gnu.org/licenses/>.
>
> - You should have received a copy of the GNU General Public License
> - along with this program. If not, see <http://www.gnu.org/licenses/>.
> +"""
> +Class definitions which process container images and extract the root
> +file system to destination directory or convert them to qcow2 disk images with
> +backing chains.
> """
>
> from virtBootstrap.sources.file_source import FileSource
> diff --git a/src/virtBootstrap/utils.py b/src/virtBootstrap/utils.py
> index 508dd04..f670919 100644
> --- a/src/virtBootstrap/utils.py
> +++ b/src/virtBootstrap/utils.py
> @@ -332,7 +332,7 @@ def untar_layers(layers_list, dest_dir, progress):
>
> def get_mime_type(path):
> """
> - Get the mime type of a file.
> + Get the mime type of a file.
> """
> proc = subprocess.Popen(
> ["/usr/bin/file", "--mime-type", path],
> @@ -386,10 +386,6 @@ def is_new_layer_message(line):
> """
> Return T/F whether a line in skopeo's progress is indicating
> start the process of new image layer.
> -
> - Reference:
> - - https://github.com/containers/image/blob/master/copy/copy.go#L464
> - - https://github.com/containers/image/blob/master/copy/copy.go#L459
> """
> return line.startswith('Copying blob') or line.startswith('Skipping fetch')
>
> @@ -398,9 +394,6 @@ def is_layer_config_message(line):
> """
> Return T/F indicating whether the message from skopeo copies the manifest
> file.
> -
> - Reference:
> - - https://github.com/containers/image/blob/master/copy/copy.go#L414
> """
> return line.startswith('Copying config')
>
ACK
--
Cedric
More information about the virt-tools-list
mailing list