From 0372d0f81bd33d4a9032516554e6f4c1b88254db Mon Sep 17 00:00:00 2001 From: immarvin Date: Sat, 16 Jan 2016 23:38:34 -0500 Subject: [PATCH 1/6] add the doc for running xcat in docker container --- docs/source/advanced/docker/index.rst | 2 + .../advanced/docker/run_xcat_in_docker.rst | 168 ++++++++++++++++++ 2 files changed, 170 insertions(+) create mode 100644 docs/source/advanced/docker/run_xcat_in_docker.rst diff --git a/docs/source/advanced/docker/index.rst b/docs/source/advanced/docker/index.rst index 803bb1fee..c2e028d76 100644 --- a/docs/source/advanced/docker/index.rst +++ b/docs/source/advanced/docker/index.rst @@ -5,3 +5,5 @@ Placeholder for Docker related topics .. toctree:: :maxdepth: 2 + + run_xcat_in_docker.rst diff --git a/docs/source/advanced/docker/run_xcat_in_docker.rst b/docs/source/advanced/docker/run_xcat_in_docker.rst new file mode 100644 index 000000000..dd05eb377 --- /dev/null +++ b/docs/source/advanced/docker/run_xcat_in_docker.rst @@ -0,0 +1,168 @@ +Run xCAT in Docker Container +============================ + +`Docker `_ is a popular application containment environment. With Docker, applications/Services are shipped as **Docker images** and run in **Docker containers**. **Docker containers** include the application and all of its dependencies, but share the kernel with other containers. They run as an isolated process in userspace on the host operating system. The server on which **Docker containers** run are called **Docker host**. + +When running xCAT in Docker container, you do not have to worry about the xCAT installation and configuration on different OS and hardware platforms, just focus on the cluster management work with xCAT features. + + +Prerequisite: setup Docker host +-------------------------------- + +You can select a baremental or virtual server with the Operating Systems which docker supports as a docker host,then install Docker on it. Please refer to `Docker Docs `_ for the details of system requirements and Docker installation. + +**Note:** Running xCAT in Docker requires x86_64 or ppc64le Docker hosts, since a **Docker image** can only run on the **Docker host** with the same archtecture, and xCAT currently only ships x86_64 and ppc64le Docker images. + + +An example configuration in the documentation +--------------------------------------------- + +To demonstrate the steps to run xCAT in a Docker container, take a cluster with the following configuration as an example :: + + Docker host: dockerhost1 + The Docker host network interface facing the compute nodes: eth0 + The IP address of eth0: 10.5.106.1/24 + The customized docker bridge: br0 + The docker container name running xCAT: xcat2-11mn + The hostname of container xcat2-11mn: xcat2-11mn + The IP address of container xcat2-11mn: 10.5.106.101 + The name server of container xcat2-11mn: 10.5.106.1 + The dns domain of container xcat2-11mn: clusters.com + + +Create a customized bridge on the Docker host +--------------------------------------------- + +**Docker containers** connect to the Docker host network via a network bridge. To run xCAT in Docker, you should create a customized bridge according to the cluster network plan, instead of the default bridge "docker0". + +As an example, you create a bridge "br0" and attach the network interface "eth0" to it :: + + brctl addbr br0 + brctl setfd br0 0 + ip addr del dev eth0 10.5.106.1/24 + brctl addif br0 eth0 + ip link set br0 up + ip addr add dev br0 10.5.106.1/24 + + +Pull the xCAT Docker image from DockerHub: +------------------------------------------ + +Now xCAT ships xCAT 2.11 Docker images(x86_64 and ppc64le) on the `DockerHub `_: + +To pull the xCAT 2.11 Docker for x86_64, run :: + + [root@dockerhost1 ~]# sudo docker pull xcat/xcat-ubuntu-x86_64 + Using default tag: latest + latest: Pulling from xcat/xcat-ubuntu-x86_64 + 27fd83569599: Pull complete + 89706b056337: Pull complete + 3285add8133c: Pull complete + 1f5976d786ae: Downloading [=====================> ] 70.81 MB/163.8 MB + 1f5976d786ae: Pull complete + d0442ae1ac04: Pull complete + 9c0a9f718574: Pull complete + be5d9994870b: Pull complete + 9be4d0394b0d: Pull complete + 78dd691f50bf: Pull complete + Digest: sha256:a7b5cc6157b7fd6837752d43c298d1a031d371752c18b312c54fe5c45366cb12 + Status: Downloaded newer image for xcat/xcat-ubuntu-x86_64:latest + + +On success, you will see the pulled Docker image on Docker host :: + + [root@dockerhost1 ~]# sudo docker images + REPOSITORY TAG IMAGE ID CREATED VIRTUAL SIZE + xcat/xcat-ubuntu-x86_64 latest 78dd691f50bf 5 hours ago 630.6 MB + + +Create the Docker container +--------------------------- + +Now create the xCAT Docker container with the Docker image "xcat/xcat-ubuntu-x86_64" :: + + [root@dockerhost1 ~]# sudo docker create -it --privileged=true --dns=10.5.106.1 --dns-search=clusters.com --hostname=xcat2-11mn --name=xcat2-11mn --add-host=xcat2-11mn:10.5.106.101 --add-host c910f05c01bc06:10.5.106.1 --net=none xcat/xcat-ubuntu-x86_64:2.11 + +* use ``--privileged=true`` to give extended privileges to this container +* use ``--dns`` and ``--dns-search`` to specify the name server and dns domain for the container,which will be written to ``/etc/resolv.conf`` of the container +* use ``--hostname`` to specify the hostname of the container, which is available inside the container +* use ``--name`` to assign a name to the container +* use ``--add-host`` to write the ``/etc/hosts`` entries of Docker host and Docker container to ``/etc/hosts`` in the container +* use ``--net=none`` not to create networking for the container + + +Start the Docker container +-------------------------- + +Start the pre-created container "xcat2-11mn" with :: + + sudo docker start xcat2-11mn + + +Setup the network for the Docker container +------------------------------------------ + +Now you need to assign a static IP address for Docker container and attach it to the customized network bridge.Since Docker does not provide native support on this, `pipeworks `_ can be used to simplify the work. + +First, download the "pipework" :: + + git clone https://github.com/jpetazzo/pipework.git + +install "pipework" by copying the script "pipework" to "/usr/local/bin/pipework" :: + + cp ./pipework /usr/local/bin/pipework + +Assign a static IP address for Docker container and attach it to the customized network bridge with :: + + pipework @ + +As an example, run :: + + pipework br0 xcat2-11mn 10.5.106.101/24@10.5.106.1 + + +Attach to the Docker container +------------------------------ + +You can attach to the container :: + + sudo docker attach xcat2-11mn + +Besides the terminal opened by ``docker attach``, you can also enable the ssh inside the container and login the Docker container via "ssh". For ubuntu, you can enable the ssh by: + +* change the "PermitRootLogin" to "yes" in "/etc/ssh/sshd_config" +* set the password for "root" with ``passwd root`` +* restart the sshd service with ``service ssh restart`` + + +Play with xCAT +-------------- + +Once you attach or ssh to the container, you will find that xCAT is running and has already been well configured, you can play with xCAT and manage your cluster now. + +Due to the features of Docker container, there are some differences from the xCAT documentation: + +* The "/install/sources" in the container is a data volume from Docker host to prevent the growth of the Docker container size. You should specify "-p /install/sources//", for example :: + + copycds -p /install/sources/rhels7.2/x86_64/ RHEL-7.2-Server-x86_64-dvd.iso + + +Known Issues +------------ + +Since Docker is still in the maturing process, there are some issues which cause some problem for xCAT : + +* copycds might hang due to all the loop devices(/dev/loop1,/dev/loop2) in the Docker host are busy. You can run ``losetup -f`` to get the first available loop device, if it fails, you might need to add several loop devices with :: + + mknod /dev/loop3 -m0660 b 7 3 + mknod /dev/loop4 -m0660 b 7 4 + ... + mknod /dev/loop9 -m0660 b 7 9 + + + + + + + + From 12a5882947b6ae8320dd891824f3e0973b689ba0 Mon Sep 17 00:00:00 2001 From: immarvin Date: Mon, 18 Jan 2016 03:14:48 -0500 Subject: [PATCH 2/6] refine the doc --- docs/source/advanced/docker/run_xcat_in_docker.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/advanced/docker/run_xcat_in_docker.rst b/docs/source/advanced/docker/run_xcat_in_docker.rst index dd05eb377..c5828d115 100644 --- a/docs/source/advanced/docker/run_xcat_in_docker.rst +++ b/docs/source/advanced/docker/run_xcat_in_docker.rst @@ -86,7 +86,7 @@ Now create the xCAT Docker container with the Docker image "xcat/xcat-ubuntu-x86 * use ``--privileged=true`` to give extended privileges to this container * use ``--dns`` and ``--dns-search`` to specify the name server and dns domain for the container,which will be written to ``/etc/resolv.conf`` of the container * use ``--hostname`` to specify the hostname of the container, which is available inside the container -* use ``--name`` to assign a name to the container +* use ``--name`` to assign a name to the container, this name can be used to manipulate the container on Docker host * use ``--add-host`` to write the ``/etc/hosts`` entries of Docker host and Docker container to ``/etc/hosts`` in the container * use ``--net=none`` not to create networking for the container From 43e709ca8dbce3008ed8f2c91656255804afbb47 Mon Sep 17 00:00:00 2001 From: immarvin Date: Tue, 19 Jan 2016 04:53:48 -0500 Subject: [PATCH 3/6] refine the doc according to the comments --- .../advanced/docker/run_xcat_in_docker.rst | 40 +++++++++---------- 1 file changed, 20 insertions(+), 20 deletions(-) diff --git a/docs/source/advanced/docker/run_xcat_in_docker.rst b/docs/source/advanced/docker/run_xcat_in_docker.rst index c5828d115..cd711d0fe 100644 --- a/docs/source/advanced/docker/run_xcat_in_docker.rst +++ b/docs/source/advanced/docker/run_xcat_in_docker.rst @@ -1,7 +1,7 @@ Run xCAT in Docker Container ============================ -`Docker `_ is a popular application containment environment. With Docker, applications/Services are shipped as **Docker images** and run in **Docker containers**. **Docker containers** include the application and all of its dependencies, but share the kernel with other containers. They run as an isolated process in userspace on the host operating system. The server on which **Docker containers** run are called **Docker host**. +`Docker `_ is a popular application containment environment. With Docker, applications/Services are shipped as **Docker images** and run in **Docker containers**. **Docker containers** include the application and all of its dependencies, but share the kernel with other containers. They run as an isolated process in userspace on the host operating system. The server on which **Docker containers** run is called **Docker host**. When running xCAT in Docker container, you do not have to worry about the xCAT installation and configuration on different OS and hardware platforms, just focus on the cluster management work with xCAT features. @@ -9,9 +9,9 @@ When running xCAT in Docker container, you do not have to worry about the xCAT i Prerequisite: setup Docker host -------------------------------- -You can select a baremental or virtual server with the Operating Systems which docker supports as a docker host,then install Docker on it. Please refer to `Docker Docs `_ for the details of system requirements and Docker installation. +You can select a baremental or virtual server with the Operating Systems which docker supports as a docker host, then install Docker on it. Please refer to `Docker Docs `_ for the details on system requirements and Docker installation. -**Note:** Running xCAT in Docker requires x86_64 or ppc64le Docker hosts, since a **Docker image** can only run on the **Docker host** with the same archtecture, and xCAT currently only ships x86_64 and ppc64le Docker images. +**Note:** **Docker image** can only run on the **Docker host** with the same architecture. Since xCAT currently only ships x86_64 and ppc64le Docker images, running xCAT in Docker requires x86_64 or ppc64le **Docker hosts**. An example configuration in the documentation @@ -23,11 +23,11 @@ To demonstrate the steps to run xCAT in a Docker container, take a cluster with The Docker host network interface facing the compute nodes: eth0 The IP address of eth0: 10.5.106.1/24 The customized docker bridge: br0 - The docker container name running xCAT: xcat2-11mn - The hostname of container xcat2-11mn: xcat2-11mn - The IP address of container xcat2-11mn: 10.5.106.101 - The name server of container xcat2-11mn: 10.5.106.1 - The dns domain of container xcat2-11mn: clusters.com + The docker container name running xCAT: xcatmn + The hostname of container xcatmn: xcatmn + The IP address of container xcatmn: 10.5.106.101 + The name server of container xcatmn: 10.5.106.1 + The dns domain of container xcatmn: clusters.com Create a customized bridge on the Docker host @@ -35,7 +35,7 @@ Create a customized bridge on the Docker host **Docker containers** connect to the Docker host network via a network bridge. To run xCAT in Docker, you should create a customized bridge according to the cluster network plan, instead of the default bridge "docker0". -As an example, you create a bridge "br0" and attach the network interface "eth0" to it :: +As an example, create a bridge "br0" and attach the network interface "eth0" to it :: brctl addbr br0 brctl setfd br0 0 @@ -81,28 +81,28 @@ Create the Docker container Now create the xCAT Docker container with the Docker image "xcat/xcat-ubuntu-x86_64" :: - [root@dockerhost1 ~]# sudo docker create -it --privileged=true --dns=10.5.106.1 --dns-search=clusters.com --hostname=xcat2-11mn --name=xcat2-11mn --add-host=xcat2-11mn:10.5.106.101 --add-host c910f05c01bc06:10.5.106.1 --net=none xcat/xcat-ubuntu-x86_64:2.11 + [root@dockerhost1 ~]# sudo docker create -it --privileged=true --dns=10.5.106.1 --dns-search=clusters.com --hostname=xcatmn --name=xcatmn --add-host=xcatmn:10.5.106.101 --add-host c910f05c01bc06:10.5.106.1 --net=none xcat/xcat-ubuntu-x86_64:2.11 * use ``--privileged=true`` to give extended privileges to this container -* use ``--dns`` and ``--dns-search`` to specify the name server and dns domain for the container,which will be written to ``/etc/resolv.conf`` of the container +* use ``--dns`` and ``--dns-search`` to specify the name server and dns domain for the container, which will be written to ``/etc/resolv.conf`` of the container * use ``--hostname`` to specify the hostname of the container, which is available inside the container * use ``--name`` to assign a name to the container, this name can be used to manipulate the container on Docker host * use ``--add-host`` to write the ``/etc/hosts`` entries of Docker host and Docker container to ``/etc/hosts`` in the container -* use ``--net=none`` not to create networking for the container +* use ``--net=none`` to create no networking for the container Start the Docker container -------------------------- -Start the pre-created container "xcat2-11mn" with :: +Start the pre-created container "xcatmn" with :: - sudo docker start xcat2-11mn + sudo docker start xcatmn Setup the network for the Docker container ------------------------------------------ -Now you need to assign a static IP address for Docker container and attach it to the customized network bridge.Since Docker does not provide native support on this, `pipeworks `_ can be used to simplify the work. +Now you need to assign a static IP address for Docker container and attach it to the customized network bridge. Since Docker does not provide native support for this, `pipeworks `_ can be used to simplify the work. First, download the "pipework" :: @@ -118,7 +118,7 @@ Assign a static IP address for Docker container and attach it to the customized As an example, run :: - pipework br0 xcat2-11mn 10.5.106.101/24@10.5.106.1 + pipework br0 xcatmn 10.5.106.101/24@10.5.106.1 Attach to the Docker container @@ -126,9 +126,9 @@ Attach to the Docker container You can attach to the container :: - sudo docker attach xcat2-11mn + sudo docker attach xcatmn -Besides the terminal opened by ``docker attach``, you can also enable the ssh inside the container and login the Docker container via "ssh". For ubuntu, you can enable the ssh by: +Besides the terminal opened by ``docker attach``, you can also enable the ssh inside the container and login to the Docker container via "ssh". For Ubuntu, you can enable the ssh by: * change the "PermitRootLogin" to "yes" in "/etc/ssh/sshd_config" * set the password for "root" with ``passwd root`` @@ -150,9 +150,9 @@ Due to the features of Docker container, there are some differences from the xCA Known Issues ------------ -Since Docker is still in the maturing process, there are some issues which cause some problem for xCAT : +Since Docker is still in the maturing process, there are some issues with xCAT: -* copycds might hang due to all the loop devices(/dev/loop1,/dev/loop2) in the Docker host are busy. You can run ``losetup -f`` to get the first available loop device, if it fails, you might need to add several loop devices with :: +* copycds might hang when all the loop devices(/dev/loop1,/dev/loop2) in the Docker host are busy. You can run ``losetup -f`` to get the first available loop device, if it fails, you might need to add several loop devices with :: mknod /dev/loop3 -m0660 b 7 3 mknod /dev/loop4 -m0660 b 7 4 From dfc55add483b071e50d72bc17e7c16534a8f4302 Mon Sep 17 00:00:00 2001 From: immarvin Date: Wed, 20 Jan 2016 03:52:37 -0500 Subject: [PATCH 4/6] is no longer mandatory, correct the doc --- docs/source/advanced/docker/run_xcat_in_docker.rst | 6 ------ 1 file changed, 6 deletions(-) diff --git a/docs/source/advanced/docker/run_xcat_in_docker.rst b/docs/source/advanced/docker/run_xcat_in_docker.rst index cd711d0fe..42ef85cec 100644 --- a/docs/source/advanced/docker/run_xcat_in_docker.rst +++ b/docs/source/advanced/docker/run_xcat_in_docker.rst @@ -140,12 +140,6 @@ Play with xCAT Once you attach or ssh to the container, you will find that xCAT is running and has already been well configured, you can play with xCAT and manage your cluster now. -Due to the features of Docker container, there are some differences from the xCAT documentation: - -* The "/install/sources" in the container is a data volume from Docker host to prevent the growth of the Docker container size. You should specify "-p /install/sources//", for example :: - - copycds -p /install/sources/rhels7.2/x86_64/ RHEL-7.2-Server-x86_64-dvd.iso - Known Issues ------------ From 178ff17668195bcdaed26c9361b52ccfa828c7dd Mon Sep 17 00:00:00 2001 From: immarvin Date: Wed, 20 Jan 2016 07:46:34 -0500 Subject: [PATCH 5/6] modify the pipework usage --- docs/source/advanced/docker/run_xcat_in_docker.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/advanced/docker/run_xcat_in_docker.rst b/docs/source/advanced/docker/run_xcat_in_docker.rst index 42ef85cec..7536521bd 100644 --- a/docs/source/advanced/docker/run_xcat_in_docker.rst +++ b/docs/source/advanced/docker/run_xcat_in_docker.rst @@ -110,7 +110,7 @@ First, download the "pipework" :: install "pipework" by copying the script "pipework" to "/usr/local/bin/pipework" :: - cp ./pipework /usr/local/bin/pipework + cp pipework/pipework /usr/local/bin/pipework Assign a static IP address for Docker container and attach it to the customized network bridge with :: From f8369a2dd7d6ecea1c816a4a55e42c9c910dc8f5 Mon Sep 17 00:00:00 2001 From: immarvin Date: Thu, 21 Jan 2016 03:22:44 -0500 Subject: [PATCH 6/6] use the latest image instead of 2.11 --- docs/source/advanced/docker/run_xcat_in_docker.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/advanced/docker/run_xcat_in_docker.rst b/docs/source/advanced/docker/run_xcat_in_docker.rst index 7536521bd..a2592b8b1 100644 --- a/docs/source/advanced/docker/run_xcat_in_docker.rst +++ b/docs/source/advanced/docker/run_xcat_in_docker.rst @@ -81,7 +81,7 @@ Create the Docker container Now create the xCAT Docker container with the Docker image "xcat/xcat-ubuntu-x86_64" :: - [root@dockerhost1 ~]# sudo docker create -it --privileged=true --dns=10.5.106.1 --dns-search=clusters.com --hostname=xcatmn --name=xcatmn --add-host=xcatmn:10.5.106.101 --add-host c910f05c01bc06:10.5.106.1 --net=none xcat/xcat-ubuntu-x86_64:2.11 + [root@dockerhost1 ~]# sudo docker create -it --privileged=true --dns=10.5.106.1 --dns-search=clusters.com --hostname=xcatmn --name=xcatmn --add-host=xcatmn:10.5.106.101 --add-host c910f05c01bc06:10.5.106.1 --net=none xcat/xcat-ubuntu-x86_64 * use ``--privileged=true`` to give extended privileges to this container * use ``--dns`` and ``--dns-search`` to specify the name server and dns domain for the container, which will be written to ``/etc/resolv.conf`` of the container