xCAT/xcat-core
2
0
Fork 0
mirror of https://github.com/xcat2/xcat-core.git synced 2025-06-12 17:30:19 +00:00
Code Issues Releases Wiki Activity

Add documentation in RTD for how to use an xCAT docker image (#6222)

Browse Source 
* Add docs for xcat container 2.14.6

* Modify depending on comments

* remove outdated documents

* Modify depending on comments

* update for comments

* update depending on comments

* update depending on mark's comment

* update depending on ertao's comment

* modify depending on Mark's comments

* modify depending on xiaopeng's comment
This commit is contained in:
Weihua Hu
2019-04-23 13:15:58 +08:00
committed by Bin Xu
parent 7e3310bfef
commit bcd01d19ba
8 changed files with 105 additions and 785 deletions
Download Patch File Download Diff File Expand all files Collapse all files

171
docs/source/advanced/docker/docker_registry.rst
View File

@ -1,171 +0,0 @@
Docker Registry in xCAT
=======================
Docker Registry is a stateless, highly scalable server side application that stores and lets you distribute Docker images.
This document describes how to set up a local private docker registry on Ubuntu 15.04 on x86_64.
.. note:: Ensure that docker registry is not already set up on this docker host.
Setting Up Docker Host
----------------------
Install Docker version 1.6.0 or newer.
Setting Up Docker Registry Manually
-----------------------------------
Docker registry needed to be set up on xCAT's MN.
This section describes two methods of setting up docker registry manually.
First, create some folders where files for this tutorial will live. ::
mkdir /docker-registry && cd $_
mkdir certs
Copy xCAT server certificate and key to certs folder. ::
cp /etc/xcat/cert/server-cert.pem certs/domain.crt
cp /etc/xcat/cert/server-key.pem certs/domain.key
Method 1: Start Docker Registry Directly
````````````````````````````````````````
Create Configuration File
'''''''''''''''''''''''''
Define configuration file ``docker-registry`` under ``/docker-registry/`` folder as below. ::
#!/bin/bash
docker_command=$1
if [ $docker_command = "start" ]; then
docker_ps_result=$(docker ps -a | grep "registry")
if [ -z $docker_ps_result ]; then
docker run -d -p 5000:5000 --restart=always --name registry \
-v `pwd`/data:/data \
-e REGISTRY_STORAGE_FILESYSTEM_ROOTDIRECTORY=/data \
-v `pwd`/certs:/certs \
-e REGISTRY_HTTP_TLS_CERTIFICATE=/certs/domain.crt \
-e REGISTRY_HTTP_TLS_KEY=/certs/domain.key \
registry:2
else
docker start registry
fi
elif [ $docker_command = "stop" ]; then
docker stop registry
else
echo "The parameter is wrong."
fi
Starting Docker Registry as a Service
'''''''''''''''''''''''''''''''''''''
Create ``docker-registry.service`` file in ``/etc/systemd/system/``, add the following contents to it. ::
[Unit]
Description=Docker Registry
[Service]
Type=oneshot
RemainAfterExit=yes
WorkingDirectory=/docker-registry
ExecStart=/bin/bash docker-registry start
ExecStop=/bin/bash docker-registry stop
[Install]
WantedBy=default.target
Start registry service: ::
service docker-registry start
Method 2: Managing Docker Registry with Compose
```````````````````````````````````````````````
Docker Compose it is a tool for defining and running Docker applications. It could help setting up registry.
Install Docker Compose
''''''''''''''''''''''
Compose can also be run inside a container, from a small bash script wrapper. To install compose as a container run: ::
curl -L https://github.com/docker/compose/releases/download/1.5.2/docker-compose-`uname -s`-`uname -m` > /usr/local/bin/docker-compose
chmod +x /usr/local/bin/docker-compose
Create Configuration File
'''''''''''''''''''''''''
Define configuration file ``docker-compose.yml`` under ``/docker-registry/`` folder as below. ::
registry:
restart: always
image: registry:2
ports:
- 5000:5000
environment:
REGISTRY_STORAGE_FILESYSTEM_ROOTDIRECTORY: /data
REGISTRY_HTTP_TLS_CERTIFICATE: /certs/domain.crt
REGISTRY_HTTP_TLS_KEY: /certs/domain.key
volumes:
- ./data:/data
- ./certs:/certs
The environment section sets environment variables in the Docker registry container. The Docker registry app knows to check this environment variable when it starts up and to start saving its data to the ``/data`` folder as a result.
Starting Docker Registry as a Service
'''''''''''''''''''''''''''''''''''''
Create ``docker-registry.service`` file in ``/etc/systemd/system/``, add the following contents to it. ::
[Uint]
Description=Docker Registry
[Service]
Type=simple
Restart=on-failure
RestartSec=30s
WorkingDirectory=/docker-registry
ExecStart=/usr/local/bin/docker-compose up
[Install]
WantedBy=default.target
Start registry service: ::
service docker-registry start
Accessing Docker Registry from other docker host
------------------------------------------------
Copy ca.crt file from xCAT MN to a client machine. Client machine must be a docker host. ::
scp username@xCAT_MN_ip:/etc/xcat/cert/ca.pem /etc/docker/certs.d/domainname:5000/ca.crt
List Available Images in Registry
`````````````````````````````````````
::
curl -k https://domainname:5000/v2/_catalog
Pull Images from Registry
`````````````````````````
Just use the "tag" image name, which includes the domain name, port, and image name. ::
docker pull domainname:5000/imagename
Push Images to Registry
```````````````````````
Before the image can be pushed to the registry, it must be tagged with the location of the private registry. ::
docker tag imagename domainname:5000/imagename
Now we can push that image to our registry. ::
docker push domainname:5000/imagename
**note:** If there is a problem with the CA certificate, edit the file ``/etc/default/docker`` so that there is a line that reads: ``DOCKER_OPTS="--insecure-registry domianname:5000"`` . Then restart Docker daemon ``service docker restart`` .

97
docs/source/advanced/docker/dockerized_xcat/dockerized_xcat.rst
View File

@ -1,97 +0,0 @@
Dockerized xCAT
================
Overview
--------
`Docker <https://www.docker.com/>`_ is a popular containment environment making it easier to create, deploy, and run applications/services. With Docker, applications/services are shipped as **Docker images** and run in **Docker containers**. **Docker containers** include the application/services and all of its running environment, which have isolated namespace and network stack but share the kernel on the host operating system. The server on which **Docker containers** run is called **Docker host**. **Docker image** can only run on **Docker host** with the same architecture.
.. image:: ./imgs/xcatindocker4.jpg
:height: 500 px
:width: 600 px
:scale: 50 %
:alt: alternate text
:align: right
**Compose** is a native tool shipped by Docker to define and run applications in Docker containers. You use a Compose file to configure your applications/services. Then, using a single command, you create and start all the services from your configuration.
By pulling xCAT Docker image and running xCAT Docker image in a container, you get a well-configured xCAT Management Node to start cluster management work, without worrying about the xCAT installation and configuration on different OS and various hardware platforms.
xCAT Docker images
------------------
xCAT ships 2 Docker images for Docker host with different architecture:
* "xcat/xcat-ubuntu-x86_64": run on x86_64 Docker host
* "xcat/xcat-ubuntu-ppc64le": run on ppc64le Docker host
Each of the xCAT Docker images above has 3 tags corresponding to different xCAT release inside Docker image:
* "latest" : the latest xCAT release
* "2.11" : xCAT 2.11 release
* "dev" : the latest xCAT development snapshot build
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 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):
* "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. 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
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. 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".
.. toctree::
:maxdepth: 2
setup_docker_host.rst
run_xcat_in_docker_compose.rst
run_xcat_in_docker_native.rst
Work with xCAT
--------------
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.
Currently, since xCAT can only generate the diskless osimages of Linux distributions with the same OS version and architecture with xCAT MN. If you need to provision diskless osimages besides ubuntu x86_64 with xCAT running in the Docker, you can use ``imgexport`` and ``imgimport`` to import the diskless osimages generated before.
If you start up the xCAT Docker container by following the steps described in sections above strictly, without specifying "--dns=IP_ADDRESS...", "--dns-search=DOMAIN...", or "--dns-opt=OPTION..." options, Docker uses the /etc/resolv.conf of the host machine (where the docker daemon runs). Any DNS problem inside container, make sure the DNS server on the Docker host works well.
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 uses "Data Volume" to save persistent 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.
* "/install": save the osimage resources under "/install" directory
* "/var/log/xcat/": save xCAT logs
* "/.dbbackup": save and restore xCAT DB tables. You can save the xCAT DB tables with ``dumpxCATdb -p /.dbbackup/`` inside container and xCAT will restore the tables on the container start up.

156
docs/source/advanced/docker/dockerized_xcat/run_xcat_in_docker_compose.rst
View File

@ -1,156 +0,0 @@
Run xCAT in Docker with Compose (Recommended)
=============================================
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 ::
The name of the docker container running xCAT: xcatmn
The hostname of container xcatmn: xcatmn
The dns domain of the cluster: clusters.com
The management network object: mgtnet
The network bridge of management network on Docker host: mgtbr
The management network interface on the Docker host facing the compute nodes: eno1
The IP address of eno1 on Docker host: 10.5.107.1/8
The IP address of xCAT container in management network: 10.5.107.101
The service network object: svcnet
The network bridge of service network on Docker host: svcbr
The service network interface on the Docker host facing the hardware control points: eno2
The IP address of eno2 on Docker host: 192.168.0.1/8
The IP address of xCAT container in service network: 192.168.0.101
Install Compose on Docker host
------------------------------
Compose v1.7.0 or above should be installed on Docker host: ::
curl -L https://github.com/docker/compose/releases/download/1.7.0-rc1/docker-compose-`uname -s`-`uname -m` > /usr/local/bin/docker-compose
chmod +x /usr/local/bin/docker-compose
Customize docker-compose file
-----------------------------
xCAT ships a docker-compose template `docker-compose.yml <https://github.com/immarvin/xcat-docker/blob/master/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 <https://docs.docker.com/compose/compose-file/>`_ , otherwise, you can simply customize it with the following steps:
1. Specify the xCAT Docker image
::
image: [xCAT Docker image name]:[tag]
specify the name and tag of xCAT Docker image, for example "xcat/xcat-ubuntu-x86_64:2.11"
2. Specify the cluster domain name
::
extra_hosts:
- "xcatmn.[cluster domain name] xcatmn:[Container's IP address in management network]"
specify the cluster domain name,i.e, "site.domain" on xCAT Management Node, for example "clusters.com", and the IP address of xCAT Docker container in the management network, such as "10.5.107.101"
3. Specify the IP address of xCAT container in service network and management network
::
networks:
svcnet:
ipv4_address : [Container's IP address in service network]
mgtnet:
ipv4_address : [Container's IP address in management network]
specify the IP address of Docker container in service network and management network. If the "svcnet" is the same as "mgtnet", the 2 "svcnet" lines should be commented out.
4. Specify the Docker network objects for management network and service network
::
networks:
#management network, attached to the network interface on Docker host
#facing the nodes to provision
mgtnet:
driver: "bridge"
driver_opts:
com.docker.network.bridge.name: "mgtbr"
ipam:
config:
- subnet: [subnet of mgtbr in CIDR]
gateway:[IP address of mgtbr]
#service network, attached to the network interface on
#Docker host facing the bmc network
svcnet:
driver: "bridge"
driver_opts:
com.docker.network.bridge.name: "svcbr"
ipam:
config:
- subnet: [subnet of svcbr in CIDR]
gateway: [IP address of svcbr]
specify the network configuration of bridge networks "mgtnet" and "svcnet", the network configuration of the bridge networks should be same as the network interfaces attached to the bridges. The "mgtnet" and "svcnet" might the same network in some cluster, in this case, you can ignore the lines for "svcnet".
5. Specify the Data Volumes for xCAT Docker container
::
volumes:
#the "/install" volume is used to keep user data in xCAT,
#such as osimage resources
#the user data can be accessible if specified
- [The directory on Docker host mounted to "/install" inside container]:/install
#the "/.dbbackup" volume is used to backup and restore xCAT DB tables
#Dockerized xCAT will restore xCAT DB tables if specified
#"dumpxCATdb -p /.dbbackup" should be run manually to save xCAT DB inside container
- [The directory on Docker host mounted to save xCAT DB inside container]:/.dbbackup
#the "/.logs" value is used to keep xCAT logs
#the xCAT logs will be kept if specified
- [The directory on Docker host to save xCAT logs inside container]:/var/log/xcat/
specify the volumes of the xCAT container used to save and restore xCAT data
Start xCAT Docker container with Compose
----------------------------------------
After the "docker-compose.yml" is ready, the xCAT Docker container can be started with [1]_ ::
docker-compose -f "docker-compose.yml" up -d; \
ifconfig eno1 0.0.0.0; \
brctl addif mgtbr eno1; \
ip link set mgtbr up; \
docker-compose logs -f
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 <https://github.com/docker/libnetwork/issues/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 ::
docker-compose -f "docker-compose.yml" down; \
ifdown eno1; \
ifup eno1
To update the xCAT Docker image, you can run ::
docker-compose -f "docker-compose.yml" pull
Known Issues
------------
.. [1]
When you start up xCAT Docker container, you might see an error message at the end of the output like ::
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.
You can ignore it, the container has already been running. It is a Docker bug `#1214 <https://github.com/docker/compose/issues/1214>`_

104
docs/source/advanced/docker/dockerized_xcat/run_xcat_in_docker_host.rst Normal file
View File

@ -0,0 +1,104 @@
Quick Start to Use xCAT Docker Image
====================================
A new Docker image will be published for each new release of xCAT. Use ``docker search xcat2`` to list all Docker images xCAT has released. xCAT Docker image offical organization is ``xcat``, repository is ``xcat2``. ::
[dockerhost]# sudo docker search xcat2
NAME DESCRIPTION STARS OFFICIAL AUTOMATED
xcat/xcat2 ... ... ... ...
The xCAT Docker images are tagged to match the xCAT releases, If you want to deploy the xCAT 2.14.6 version, pull down the ``xcat/xcat2:2.14.6`` image. xCAT Docker image also has a ``latest`` tag to point to the latest release. Currently xCAT Docker images are based on CentOS.
.. Attention::
To do discovery for POWER9 bare metal server, please refer to :doc:`xCAT Genesis Base </references/coral/known_issues/genesis_base>`
Prerequisite for Docker Host
----------------------------
* To run xCAT under Docker, the services ``SELinux`` and ``AppArmor`` on Docker host must be disabled.
SELinux can be disabled with: ::
echo 0 > /selinux/enforce
sed -i 's/^SELINUX=.*$/SELINUX=disabled/' /etc/selinux/config
AppArmor can be disabled with: ::
/etc/init.d/apparmor teardown
* To run xCAT under Docker the ports described in :doc:`document </advanced/ports/xcat_ports>` should be available.
For Linux user, use the following command to verify ports are not used ::
netstat -nlp |grep -E ":(3001|3002|68|53|873|80|69|12429|12430|67) "
Pull the xCAT Docker Image from DockerHub
-----------------------------------------
To pull the latest xCAT Docker image, run ::
[dockerhost]# sudo docker pull xCAT/xCAT2:latest
Run xCAT in Docker Container
----------------------------
Run the xCAT Docker container with the Docker image ``xCAT/xCAT2:latest`` ::
[dockerhost]# sudo docker run -d \
--name xcatmn \
--network=host \
--hostname xcatmn \
--privileged \
-v /sys/fs/cgroup:/sys/fs/cgroup:ro \
-v /xcatdata:/xcatdata \
-v /var/log/xcat:/var/log/xcat \
-v /customer_data:/customer_data \
xcat/xcat2:latest
The descriptions:
:name:
Assign a name to the container, this name can be used to manipulate the container on docker host.
:--network=host:
Use the host network driver for a container, that container network stack is not isolated from the docker host.
:hostname:
Specify the hostname of container, which is available inside the container.
:--privileged=true:
Give extended privileges to this container.
:-v /sys/fs/cgroup\:/sys/fs/cgroup\:ro:
Is **mandatory** configuration to enable systemd in container.
:-v /xcatdata\:/xcatdata:
xCAT container will create ``/xcatdata`` volume to store configuration and OS distro data. I.e. xCAT important directories ``/install``, ``/tftpboot`` and ``/etc`` will be saved under ``/xcatdata``. If user does not explicitly mount this directory to docker host, this directory will be mounted under ``/var/lib/docker/volumes/``.
:-v /var/log/xcat\:/var/log/xcat:
All xCAT running logs are saved under ``/var/log/xcat``. Use this setting to export them to Docker host.
:-v /customer_data\:/customer_data:
**Is optional**. Use this setting to transfer user data between Docker host and container.
Run xCAT Command in Docker Container
------------------------------------
To enter xCAT Docker container ::
[dockerhost]# sudo docker exec -it xcatmn bash
[xcatmn]#
Also can enter xCAT Docker container through ``ssh`` ::
[anynode]# ssh <docker_container_ip> -p 2200
Now container ``xcatmn`` will work as a normal xCAT management node, can run xCAT commands directly.
For example ::
[xcatmn]# lsxcatd -a

77
docs/source/advanced/docker/dockerized_xcat/run_xcat_in_docker_native.rst
View File

@ -1,77 +0,0 @@
Run xCAT in Docker with Docker native commands
==============================================
Pull the xCAT Docker image from DockerHub
-----------------------------------------
Now xCAT ships xCAT Docker images(x86_64 and ppc64le) on the `DockerHub <https://hub.docker.com/u/xcat/>`_:
To pull the latest xCAT Docker image for x86_64, run ::
sudo docker pull xcat/xcat-ubuntu-x86_64
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 3a3631463e83 2 days ago 643 MB
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 name of the docker container running xCAT: xcatmn
The hostname of container xcatmn: xcatmn
The management network object: mgtnet
The network bridge of management network on Docker host: mgtbr
The management network interface on the Docker host facing the compute nodes: eno1
The IP address of eno1 on Docker host: 10.5.107.1/8
The IP address of xCAT container in management network: 10.5.107.101
The dns domain of the cluster: clusters.com
Create a customized Docker network on the Docker host
-----------------------------------------------------
**Docker Networks** provide complete isolation for containers, which gives you control over the networks your containers run on. To run xCAT in Docker, you should create a customized bridge network according to the cluster network plan, instead of using the default bridge network created on Docker installation.
As an example, we create a customized bridge network "mgtbr" which is attached to the network interface "eno1" facing the compute nodes and inherits the network configuration of "eno1". Since the commands to create the network will break the network connection on "eno1", you'd better run the commands in one line instead of running them seperatly ::
sudo docker network create --driver=bridge --gateway=10.5.107.1 --subnet=10.5.107.0/8 -o "com.docker.network.bridge.name"="mgtbr" mgtnet; \
ifconfig eno1 0.0.0.0; \
brctl addif mgtbr eno1; \
ip link set mgtbr up
* ``--driver=bridge`` specify the network driver to be "bridge"
* ``--gateway=10.5.107.1`` specify the network gateway to be the IP address of "eno1" on Docker host. which will also be the IP address of network bridge "mgtbr"
* ``--subnet=10.5.107.0/8`` speify the subnet in CIDR format to be the subnet of "eno1"
* ``com.docker.network.bridge.name"="mgtbr"`` specify the bridge name of management network
* ``ifconfig eno1 0.0.0.0`` delete the IP address of "eno1"
* ``brctl addif mgtbr eno1`` attach the bridge "br0" to network interface "eno1"
* ``ip link set mgtbr up`` change the state of "br0" to UP
When the network is created, you can list it with ``sudo docker network ls`` and get the information of it with ``sudo docker inspect mgtnet``.
Run xCAT in Docker container
----------------------------
Now run the xCAT Docker container with the Docker image "xcat/xcat-ubuntu-x86_64" and connect it to the newly created customized Docker network "mgtnet" ::
sudo docker run -it --privileged=true --hostname=xcatmn --name=xcatmn --add-host="xcatmn.clusers.com xcatmn:10.5.107.101" --volume /docker/xcatdata/:/install --net=mgtnet --ip=10.5.107.101 xcat/xcat-ubuntu-x86_64
* use ``--privileged=true`` to give extended privileges to this 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="xcatmn.clusers.com xcatmn:10.5.107.101"`` to write the ``/etc/hosts`` entries of Docker container inside container. Since xCAT use the FQDN(Fully Qualified Domain Name) to determine the cluster domain on startup, make sure the format to be "<FQDN> <hostname>: <IP Address>", otherwise, you need to set the cluster domain with ``chdef -t site -o clustersite domain="clusters.com"`` inside the container manually
* use ``--volume /docker/xcatdata/:/install`` to mount a pre-created "/docker/xcatdata" directory on Docker host to "/install" directory inside container as a data volume. This is optional, it is mandatory if you want to backup and restore xCAT data.
* use ``--net=mgtnet`` to connect the container to the Docker network "mgtnet"
* use ``--ip=10.5.107.101`` to specify the IP address of the xCAT Docker container

25
docs/source/advanced/docker/dockerized_xcat/setup_docker_host.rst
View File

@ -1,25 +0,0 @@
Setup Docker host
=================
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, refer to `Docker Installation Docs <https://docs.docker.com/engine/installation/>`_.
.. note:: Docker images can only run on Docker hosts with the same architecture. Since xCAT only ships x86_64 and ppc64le Docker images, running xCAT in Docker requires x86_64 or ppc64 Docker Hosts.
Shutdown the SELinux/Apparmor on Docker host
--------------------------------------------
If the SELinux or Apparmor on Docker host is enabled, the services/applications inside Docker Container might be confined. To run xCAT in Docker container, SELinux and Apparmor on the Docker host must be disabled.
SELinux can be disabled with: ::
echo 0 > /selinux/enforce
sed -i 's/^SELINUX=.*$/SELINUX=disabled/' /etc/selinux/config
AppArmor can be disabled with: ::
/etc/init.d/apparmor teardown

4
docs/source/advanced/docker/index.rst
View File

@ -4,6 +4,4 @@ Docker
.. toctree::
:maxdepth: 2
dockerized_xcat/dockerized_xcat.rst
lifecycle_management.rst
docker_registry.rst
dockerized_xcat/run_xcat_in_docker_host.rst

256
docs/source/advanced/docker/lifecycle_management.rst
View File

@ -1,256 +0,0 @@
Docker life-cycle management in xCAT
====================================
The Docker linux container technology is currently very popular. xCAT can help managing Docker containers. xCAT, as a system management tool has the natural advantage for supporting multiple operating systems, multiple architectures and large scale clusters.
This document describes how to use xCAT for docker management, from Docker Host setup to docker container operations.
.. note:: This document was verified with:
* Docker Version 1.10, 1.11
* Docker API version 1.22
Docker Host has been verified on the following OS/ARCH combinations:
* Ubuntu 14.04.3,x86_64
* Ubuntu 15.10,x86_64
* Ubuntu 16.04,x86_64
* Ubuntu 16.04,ppc64el
Setting up Docker Host
----------------------
The **Docker Host** is the bare metal server or virtual machine where Docker containers can run. It will be called *dockerhost* in the following sections.
The *dockerhost* at a minimum must provide the following:
* An Operating System for running docker daemon
* The certification related files to be used by Docker service for trusted connection.
Preparing osimage for docker host
`````````````````````````````````
The osimage represents the image of the Operating System which will be deployed on the dockerhost.
Copy files out from DVDs/ISOs and generate
""""""""""""""""""""""""""""""""""""""""""
**[ubuntu x86_64]** ::
copycds ubuntu-xxx-server-amd64.iso
**[ubuntu16.04 ppc64el]** ::
copycds ubuntu-16.04-server-ppc64el.iso
Create pkglist and otherpkglist of osimage for dockerhost
"""""""""""""""""""""""""""""""""""""""""""""""""""""""""
The pkglist file should contain the following: ::
# cat /install/custom/ubuntu/ubuntu.pkglist
openssh-server
ntp
gawk
nfs-common
snmpd
bridge-utils
The otherpkglist file should contain the following:
**[ubuntu x86_64]** ::
# cat /install/custom/ubuntu/ubuntu_docker.pkglist
docker-engine
**[ubuntu16.04 ppc64el]**
At the time of this writing (February 2016), docker package is not available for **ppc64el** architecture from docker.org. You can follow instructions below on how to manually download and install it.
* Download docker engine for ppc64el:
::
wget http://launchpadlibrarian.net/251622081/docker.io_1.10.3-0ubuntu4_ppc64el.deb -O /install/docker_ppc64el/docker.io_1.10.3-0ubuntu4_ppc64el.deb
* Configure **otherpkgdir** like this:
::
otherpkgdir=/install/docker_ppc64el
* The **otherpkglist** file should be:
::
# cat /install/custom/ubuntu/ubuntu_docker.pkglist
docker.io
Create the osimage for dockerhost
"""""""""""""""""""""""""""""""""
The osimage for dockerhost will be like this:
**[ubuntu x86_64]** ::
# lsdef -t osimage ub14.04.03-x86_64-dockerhost
Object name: ub14.04.03-x86_64-dockerhost
imagetype=linux
osarch=x86_64
osname=Linux
osvers=ubuntu14.04.3
otherpkgdir=https://apt.dockerproject.org/repo ubuntu-trusty main,http://cz.archive.ubuntu.com/ubuntu trusty main
otherpkglist=/install/custom/ubuntu/ubuntu_docker.pkglist
pkgdir=/install/ubuntu14.04.3/x86_64
pkglist=/install/custom/ubuntu/ubuntu.pkglist
profile=compute
provmethod=install
template=/opt/xcat/share/xcat/install/ubuntu/compute.tmpl
**[ubuntu16.04 ppc64el]** ::
# lsdef -t osimage ub16.04-ppc64el-dockerhost
Object name: ub16.04-ppc64el-dockerhost
imagetype=linux
osarch=ppc64el
osname=Linux
osvers=ubuntu16.04
otherpkgdir=/install/docker_ppc64el
otherpkglist=/install/custom/ubuntu/ubuntu_docker.pkglist
pkgdir=/install/ubuntu16.04/ppc64el
pkglist=/install/custom/ubuntu/ubuntu.pkglist
profile=compute
provmethod=install
template=/opt/xcat/share/xcat/install/ubuntu/compute.tmpl
Preparing setup trust connection for docker service and create docker network object
````````````````````````````````````````````````````````````````````````````````````
Currently, a customer defined network object is needed when create a docker container with static IP address, it can be done with the command: ::
chdef host01 -p postbootscripts="setupdockerhost <netobj_name>=<subnet>/<netmask>@<gateway>[:nicname]"
* netobj_name: the network object to be created, it will be used in *dockernics* when creating docker container
* subnet/netmask@gateway: the network which the IP address of docker container running on the docker host must be located in. If *nicname* is specified, the *subnet/netmask* must be the subnet of the nic *nicname* located in. And *gateway* shall be the IP address of the nic *nicname*.
* nicname: the physical nic name which will be attached to the network object
For example, a network object *mynet0* with subnet *10.0.0.0/16* and gateway *10.0.101.1* on nic *eth0* can be created with the command: ::
chdef host01 -p postbootscripts="setupdockerhost mynet0=10.0.0.0/16@10.0.101.1:eth0"
Start OS provisioning for dockerhost
````````````````````````````````````
Reference :ref:`Initialize the Compute for Deployment<deploy_os>` for how to finish an OS deployment.
Docker instance management
--------------------------
After the dockerhost is ready, a docker instance can be managed through xCAT commands. In xCAT, a docker instance is represented by a node whose definition can be like this: ::
# lsdef host01c01
Object name: host01c01
dockerhost=host01:2375
dockernics=mynet0
groups=docker,all
ip=10.0.120.1
mac=02:42:0a:00:78:01
mgt=docker
postbootscripts=otherpkgs
postscripts=syslog,remoteshell,syncfiles
The command :doc:`mkdef </guides/admin-guides/references/man1/mkdef.1>` or :doc:`chdef </guides/admin-guides/references/man1/chdef.1>` can be used to create a new docker instance node or change the node attributes. Specify any available unused ip address for *ip* attribute. *mac* attribute is optional and if left unset, will be filled in by *mkdocker* command.
After docker instance node is defined, use command `makehosts host01c01` to add node *host01c01* and its IP address *10.0.120.1* into /etc/hosts.
Create docker instance
``````````````````````
::
mkdocker <node> [image=<image_name> [command=<command>] [dockerflag=<docker_flags>]]
* node - The node object which represents the docker instance
* image - The image name that the docker instance will use
* command - The command that the docker will run
* dockerflag - A JSON string which will be used as parameters to create a docker. Reference `docker API v1.22 <https://docs.docker.com/engine/reference/api/docker_remote_api_v1.22/>`_ for more information about which parameters can be specified for "dockerflag".
To create the docker instance *host01c01* with image *ubuntu* and command */bin/bash*, use: ::
mkdocker host01c01 image=ubuntu command=/bin/bash dockerflag="{\"AttachStdin\":true,\"AttachStdout\":true,\"AttachStderr\":true,\"OpenStdin\":true}"
Remove docker instance
``````````````````````
::
rmdocker <node>
The command **rmdocker host01c01** can be used to remove the docker instance *host01c01*.
List docker information
```````````````````````
::
lsdocker <dockerhost|node> [-l|--logs]
To list all the running docker instances on the dockerhost *host01*, use **lsdocker host01**.
To list the info of docker instance *host01c01*, use **lsdocker host01c01**.
To get log info of docker instance *host01c01*, use **lsdocker host01c01 --logs**.
Start docker instance
`````````````````````
::
rpower <node> start
Stop docker instance
````````````````````
::
rpower <node> stop
Restart docker instance
```````````````````````
::
rpower <node> restart
Pause all processes within a docker instance
````````````````````````````````````````````
::
rpower <node> pause
Unpause all processes within a docker instance
``````````````````````````````````````````````
::
rpower <node> unpause
Check docker instance status
````````````````````````````
::
rpower <node> state
Troubleshooting
--------------------------
If things go wrong:
* After dockerhost node boots, check contents of **/var/log/xcat/xcat.log** file on the dockerhost for errors.
* Verify **nicname** specified in **Preparing setup trust connection for docker service and create docker network object** section exists on the docker host. Depending on the version of Ubuntu OS and host architecture, it could be **eth0**, or **em1**, or **eno1**, or **enp0s1**. Verify by running on the dockerhost
::
ip addr show dev <nicname>
* Run **ps -ef | grep docker** to verify docker engine is running with configured options. It should look something like
::
root 3703 1 0 Apr15 ? 00:12:28 /usr/bin/docker daemon -H unix:///var/run/docker.sock -H tcp://host01:2375 --tls --tlscacert=/root/.docker/ca-cert.pem --tlscert=/root/.docker/dockerhost-cert.pem --tlskey=/root/.docker/dockerhost-cert.pem --tlsverify=true --raw-logs
If the output is missing some options, verify that file **/lib/systemd/system/docker.service** contains the following lines
::
EnvironmentFile=-/etc/default/docker
ExecStart=/usr/bin/docker daemon $DOCKER_OPTS -H fd://