diff --git a/docs/source/advanced/docker/dockerized_xcat/dockerized_xcat.rst b/docs/source/advanced/docker/dockerized_xcat/dockerized_xcat.rst index 78024022c..833845869 100644 --- a/docs/source/advanced/docker/dockerized_xcat/dockerized_xcat.rst +++ b/docs/source/advanced/docker/dockerized_xcat/dockerized_xcat.rst @@ -32,30 +32,32 @@ xCAT shippes 2 Docker images for Docker host with different architecture: Each of the xCAT Docker images above has 3 tags corresponding to different xCAT release inside Docker image: * "latest" : the latest xCAT release -* the specified xCAT release: "2.11" is supported -* "dev": the latest xCAT development snapshot build +* "2.11" : xCAT 2.11 release +* "dev" : the latest xCAT development snapshot build -A Docker image with the specified tag should be denoted in format "[docker image name]:[tag]", for example, "xcat/xcat-ubuntu-x86_64:2.11". The tag is "latest" by default if not specified. +A Docker image with specified tag should be denoted in format "[docker image name]:[tag]", for example, "xcat/xcat-ubuntu-x86_64:2.11". If not specified, default tag is "latest". Run xCAT in Docker ------------------ -Each container with xCAT Docker image running inside is a xCAT management node, the container connect to the compute nodes and hardware control points in the cluster via "bridge" network on the Docker host. Generally, a xCAT container should connect to 2 types of networks: +Each container with xCAT Docker image running inside is a xCAT management node, the container connects to the compute nodes and hardware control points in the cluster via "bridge" network on the Docker host. Generally, a xCAT container should connect to 2 types of networks( the 2 types of networks might be one network in some cluster): -* "provnet": provision network connecting to compute nodes, i.e, a bridge "provbr" attached to the network interface facing the compute nodes on Docker host -* "hwmgtnet": hardware management network connecting to the hardware control points, i.e, a bridge "hwmgtbr" attached to the network interface facing the hardware control points +* "mgtnet": Management network, the network used by the Management Node to install operating systems and manage the nodes. The Management Node and in-band Network Interface Card (NIC) of the nodes are connected to this network. A bridge "mgtbr" will be created and attached to the network interface facing the compute nodes on Docker host +* "svcnet": Service network, the network used by the Management Node to control the nodes using out-of-band management using the Service Processor. A bridge "svcbr" will be created and attached to the network interface facing the hardware control points -You are required to determine and specify some necessary information, so that xCAT is well configured and running when the container is started. These information includes: +You are required to determine and specify some necessary information, so that xCAT is well configured and running when the container is started. This includes: * Docker container: xCAT Docker image with specified xCAT release; the data volumes with directories on Docker host including xCAT DB tables, the osimage resources and xCAT logs, which can be used to save and restore the data of xCAT service * network information: the network configuration of the xCAT container * cluster information: the domain of the cluster -These information can be specified in 2 ways to run xCAT container: -* in options and arguments of docker commands such as "docker network create" or "docker run" +The information can be specified in 2 ways to run xCAT container: + +* in options and arguments of docker commands such as ``docker network create`` or ``docker run`` * in the "docker-compose.yml", which contains all the configuration to start xCAT containers with Compose. This is the recommended way to start xCAT container. -The 2 ways are described step-by-step in the following sections of this documentation. + +The 2 ways are described step-by-step in the following sections of this documentation. We recommend you start xCAT container with Compose. When xCAT Docker container is started, you can access it with ``sudo docker attach``, however, we recommend you to access it via "ssh". @@ -65,14 +67,15 @@ When xCAT Docker container is started, you can access it with ``sudo docker atta :maxdepth: 2 setup_docker_host.rst - run_xcat_in_docker_native.rst run_xcat_in_docker_compose.rst + run_xcat_in_docker_native.rst + Work with xCAT -------------- -Once xCAT Docker container is run, you can use xCAT with the shell inside the container. Since the ssh service has also been enabled on the Docker container startup, you can also connect to the container via ssh, the default password for the user "root" is "cluster". +Once xCAT Docker container is running, you can use xCAT with the shell inside the container. Since the ssh service has been enabled on the Docker container startup, you can connect to the container via ssh. The default root password is "cluster". Once you attach or ssh to the container, you will find that xCAT is running and configured, you can play with xCAT and manage your cluster now. @@ -83,7 +86,7 @@ If you start up the xCAT Docker container by following the steps described in se Save and Restore xCAT data ---------------------------- -According to the policy of Docker, Docker image should only be the service deployment unit, it is not recommended to save data in Docker image. Docker use "Data Volume" to save persisent data inside container, which can be simply taken as a shared directory between Docker host and Docker container. +According to the policy of Docker, Docker image should only be the service deployment unit, it is not recommended to save data in Docker image. Docker uses "Data Volume" to save persisent data inside container, which can be simply taken as a shared directory between Docker host and Docker container. For dockerized xCAT, there are 3 volumes recommended to save and restore xCAT user data. diff --git a/docs/source/advanced/docker/dockerized_xcat/run_xcat_in_docker_compose.rst b/docs/source/advanced/docker/dockerized_xcat/run_xcat_in_docker_compose.rst index 182f90370..f534edd5d 100644 --- a/docs/source/advanced/docker/dockerized_xcat/run_xcat_in_docker_compose.rst +++ b/docs/source/advanced/docker/dockerized_xcat/run_xcat_in_docker_compose.rst @@ -1,5 +1,5 @@ -Run xCAT in Docker with Compose -=============================== +Run xCAT in Docker with Compose (Recommended) +============================================= An example configuration in the documentation @@ -25,7 +25,7 @@ Compose v1.7.0 or above should be installed on Docker host: :: Customize docker-compose file ----------------------------- -xCAT shippes a docker-compose template `docker-compose.yml `_, which is a self-description file including all the configurations to run xCAT in container. You can make up your compose file based on it if you are familiar with `Compose file `_ , otherwise, you can simply customize it with the following steps: +xCAT ships a docker-compose template `docker-compose.yml `_, which is a self-description file including all the configurations to run xCAT in container. You can make up your compose file based on it if you are familiar with `Compose file `_ , otherwise, you can simply customize it with the following steps: :: image: [xCAT docker image name]:[tag] @@ -33,46 +33,46 @@ xCAT shippes a docker-compose template `docker-compose.yml `_ . The commands should be run successively in one line to avoid breaking the network connection of the network interface of Docker host. +This command starts up the Docker container and attaches the network interface "eno1" of Docker host to the bridge network "mgtbr". It is a little complex due to a Compose bug `#1003 `_ . The commands should be run successively in one line to avoid breaking the network connection of the network interface of Docker host. To remove the container, you can run :: @@ -114,5 +114,5 @@ Known Issues "Couldn't connect to Docker daemon at http+unix://var/run/docker.sock - is it running? If it's at a non-standard location, specify the URL with the DOCKER_HOST environment variable." -please do not worry and just ignore it, the container has already been running. It is a Docker bug `#1214 `_ +You can ignore it, the container has already been running. It is a Docker bug `#1214 `_ diff --git a/docs/source/advanced/docker/dockerized_xcat/setup_docker_host.rst b/docs/source/advanced/docker/dockerized_xcat/setup_docker_host.rst index 3109fa843..d01367fe7 100644 --- a/docs/source/advanced/docker/dockerized_xcat/setup_docker_host.rst +++ b/docs/source/advanced/docker/dockerized_xcat/setup_docker_host.rst @@ -1,8 +1,8 @@ -setup Docker host +Setup Docker host ================= -Install Dockerc Engine ----------------------- +Install Docker Engine +--------------------- The Docker host to run xCAT Docker image should be a baremental or virtual server with Docker v1.10 or above installed. For the details on system requirements and Docker installation, please refer to `Docker Installation Docs `_.