From 79162f7c36846eac1acd4742f2c789bca824d310e3cca03983c95493f10462ac Mon Sep 17 00:00:00 2001 From: Ludwig Nussel Date: Sat, 16 Aug 2014 13:38:01 +0000 Subject: [PATCH] Accepting request 244864 from Virtualization Automatic submission by obs-autosubmit OBS-URL: https://build.opensuse.org/request/show/244864 OBS-URL: https://build.opensuse.org/package/show/openSUSE:Factory/docker?expand=0&rev=3 --- README_SUSE.md | 209 +++++++++++++++++++++++++++++++++++++++++++++ docker.changes | 21 +++++ docker.service | 1 - docker.spec | 8 +- sysctl-docker.conf | 2 - 5 files changed, 233 insertions(+), 8 deletions(-) create mode 100644 README_SUSE.md delete mode 100644 sysctl-docker.conf diff --git a/README_SUSE.md b/README_SUSE.md new file mode 100644 index 0000000..237cfe8 --- /dev/null +++ b/README_SUSE.md @@ -0,0 +1,209 @@ +# Abstract + +Docker is a lightweight "virtualization" method to run multiple virtual units +(containers, akin to “chroot”) simultaneously on a single control host. +Containers are isolated with Kernel Control Groups (cgroups) and Kernel Namespaces. + +Docker provides an operating system-level virtualization where the Kernel +controls the isolated containers. With other full virtualization solutions +like Xen, KVM, or libvirt the processor simulates a complete hardware +environment and controls its virtual machines. + +# Terminology + +## chroot + +A change root (chroot, or change root jail) is a section in the file system +which is isolated from the rest of the file system. For this purpose, the chroot +command is used to change the root of the file system. A program which is +executed in such a “chroot jail” cannot access files outside the designated +directory tree. + +## cgroups + +Kernel Control Groups (commonly referred to as just “cgroups”) are a Kernel +feature that allows aggregating or partitioning tasks (processes) and all their +children into hierarchical organized groups to isolate resources. + +## Image + +A "virtual machine" on the host server that can run any Linux system, for +example openSUSE, SUSE Linux Enterprise Desktop, or SUSE Linux Enterprise Server. + +A Docker image is made by a series of layers built one over the other. Each layer +corresponds to a permanent change committed from a container to the image. + +For more details checkout [Docker's official documentation](http://docs.docker.com/terms/image/). + +## Image Name + +A name that refers to an image. The name is used by the docker commands. + +## Container + +A running Docker Image. + +## Container ID + +A ID that refers to a container. The ID is used by the docker commands. + +## TAG + +A string associated to a Image. It commonly used to identify a specific version +of a Image (like tags in version control systems). It is also possible to refer +the same Image with different TAGs. + +## Kernel Namespaces + +A Kernel feature to isolate some resources like network, users, and others for +a group of processes. + +## Docker Host Server + +The system that runs the Docker daemon, provides the images, and the management +control capabilities through cgroups. + + +# Overview + +Docker is a platform that allows developers and sysadmins to manage the complete +lifecycle of images. + +Docker makes incredibly easy to build, ship and run images containing +applications. + +Benefits of Docker: + + * Isolating applications and operating systems through containers. + * Providing nearly native performance as Docker manages allocation of resources + in real-time. + * Controlling network interfaces and applying resources inside containers through cgroups. + * Versioning of images. + * Building images based on existing ones. + * Sharining/storing on [public](http://docs.docker.com/docker-hub/) or + [private](http://docs.docker.com/userguide/dockerrepos/#private-repositories) + repositories. + +Limitations of Docker: + + * All Docker containers are running inside the host system's Kernel and not with + a different Kernel. + * Only allows Linux "guest" operating systems. + * Docker is not a full virtualization stack like Xen, KVM, or libvirt. + * Security depends on the host system. Refer to the [official documentation](http://docs.docker.com/articles/security/) + for more details. + +## Container drivers + +Docker has different backend drivers to handle the containers. The recommended +on is [libcontainer](https://github.com/docker/libcontainer), which is also the +default choice. This driver provides direct access with cgroups. + +The Docker packages ships also a LXC driver which handles containers using the +LXC tools. + +At the time of writing, upstream is working on a `libvirt-lxc` driver. + +## Storage drivers + +Docker images are made by series of stacked layers. The recommended driver is +DeviceMapper one, which is also the default choice. + +The Docker packages ships also an experimental BTRFS driver. To use this driver +Docker daemon must run on a BTRFS partition already prepared by the host system. + +To use the experimental BTRFS driver the Docker daemon must be started with this +command: + +``` +docker -d -s btrfs +``` + + +# Setting up a Docker host + +Prepare the host: + + 1. Install the `docker` package. + 2. Automatically start the Docker daemon at boot: + `sudo systemctl enable docker` + 3. Start the Docker daemon: + `sudo systemctl start docker` + +The Docker daemon listens on a local socket which is accessible only by the `root` +user and by the members of the `docker` group. + +The `docker` group is automatically created at package installation time. To +allow a certain user to connect to the local Docker daemon use the following +command: + +``` +sudo /usr/sbin/usermod -aG docker +``` + +The user will be able to communicate with the local Docker daemon upon his next +login. + +## Networking + +If you want your containers to be able to access the external network you must +enable the `net.ipv4.ip_forward` rule. +This can be done using YaST by browsing to the +`Network Devices -> Network Settings -> Routing` menu and ensuring that the +`Enable IPv4 Forwarding` box is checked. + +This option cannot be changed when networking is handled by the Network Manager. +In such cases the `/etc/sysconfig/SuSEfirewall2` file needs to be edited by +hand to ensure the `FW_ROUTE` flag is set to `yes` like so: + +``` + FW_ROUTE="yes" +``` + + +# Basic Docker operations + +Images can be pulled from [Docker's central index](http://index.docker.io) using +the following command: + +``` +docker pull +``` + +Containers can be started using the `docker run` command. + +Please refer to the [official documentation](http://docs.docker.com/) +for more details. + + +# Building Docker containers using KIWI + +Starting from version 5.06.8 KIWI can be used to build Docker images. +Please refer to KIWI's [official documentation](https://doc.opensuse.org/projects/kiwi/doc/#chap.lxc). +The official `kiwi-doc` package contains examples of Docker images. + +## Docker build system versus KIWI + +Docker has an [internal build system](http://docs.docker.com/reference/builder/) +which makes incredibly easy to create new images based on existing ones. + +Some users might be confused about what to use. The right approach is to build +the [base images](http://docs.docker.com/terms/image/#base-image-def) using KIWI +and then use them as foundation blocks inside of your Docker's build system. + +That two advantages: + + 1. Be able to use docker specific directives (like `ENTRYPOINT`, `EXPOSE`, ...). + 2. Be able to reuse already existing layers. + +Sharing the common layers between different images makes possible to: + + * Use less disk space on the Docker hosts. + * Make the deployments faster: only the requested layers are sent over the + network (it is like upgrading installed packages using delta rpms). + * Take full advantage of caching while building Docker images: this will result + in faster executions of `docker build` command. + +To recap: KIWI is not to be intended as a replacement for Docker's build system. +It rather complements with it. + diff --git a/docker.changes b/docker.changes index bb3030f..8a3b055 100644 --- a/docker.changes +++ b/docker.changes @@ -1,3 +1,24 @@ +------------------------------------------------------------------- +Fri Aug 8 15:31:41 UTC 2014 - fcastelli@suse.com + +- Final changes to README_SUSE.md + +------------------------------------------------------------------- +Fri Aug 8 10:28:48 UTC 2014 - fcastelli@suse.com + +- Added other small fixes to README_SUSE.md + +------------------------------------------------------------------- +Thu Aug 7 14:06:30 UTC 2014 - fcastelli@suse.com + +- Small improvements to README_SUSE.md + +------------------------------------------------------------------- +Thu Aug 7 13:29:30 UTC 2014 - fcastelli@suse.com + +- Removed useless sysctl rule. +- Added README_SUSE.md + ------------------------------------------------------------------- Fri Jul 25 06:17:04 UTC 2014 - fcastelli@suse.com diff --git a/docker.service b/docker.service index 9177f8e..a75974f 100644 --- a/docker.service +++ b/docker.service @@ -7,7 +7,6 @@ After=multi-user.target Type=simple EnvironmentFile=/etc/sysconfig/docker ExecStart=/usr/bin/docker -d $DOCKER_OPTS -ExecStartPre=/usr/sbin/sysctl -p /etc/sysctl.d/200-docker.conf [Install] WantedBy=multi-user.target diff --git a/docker.spec b/docker.spec index ff9345b..1568353 100644 --- a/docker.spec +++ b/docker.spec @@ -27,11 +27,11 @@ Group: System/Management Url: http://www.docker.io Source: %{name}-%{version}.tar.bz2 Source1: docker.service -Source2: sysctl-docker.conf Source3: 80-docker.rules Source4: sysconfig.docker Source5: docker.socket Source6: docker-rpmlintrc +Source7: README_SUSE.md Patch0: 0002-Stripped-dockerinit-binary.patch BuildRequires: bash-completion BuildRequires: device-mapper-devel >= 1.2.68 @@ -91,6 +91,7 @@ Zsh command line completion support for %{name}. %prep %setup -q -n docker %patch0 -p1 +cp %{SOURCE7} . %build %{go_disable_brp_strip_static_archive} @@ -121,8 +122,6 @@ install -D -m0644 contrib/completion/zsh/_docker "%{buildroot}/etc/zsh_completio install -D -m 0644 %SOURCE1 %{buildroot}%{_unitdir}/%{name}.service install -D -m 0644 %SOURCE5 %{buildroot}%{_unitdir}/%{name}.socket -install -D -m 0644 %SOURCE2 %{buildroot}%{_sysconfdir}/sysctl.d/200-%{name}.conf - # # udev rules that prevents dolphin to show all docker devices and slows down # upstream report https://bugs.kde.org/show_bug.cgi?id=329930 @@ -150,9 +149,8 @@ groupadd -r docker 2>/dev/null || : %files %defattr(-,root,root) -%doc README.md LICENSE +%doc README.md LICENSE README_SUSE.md %{_bindir}/docker -%config %{_sysconfdir}/sysctl.d/200-docker.conf %{_prefix}/lib/docker/ %{_prefix}/lib/docker/dockerinit %{_unitdir}/%{name}.service diff --git a/sysctl-docker.conf b/sysctl-docker.conf deleted file mode 100644 index 4e3553b..0000000 --- a/sysctl-docker.conf +++ /dev/null @@ -1,2 +0,0 @@ -# Enable IPv4 forward, required to have working network within the containers -net.ipv4.ip_forward = 1