RuBAN 6 overview
- Former user (Deleted)
(what you absolutely need to know about it as a fellow troubleshooter)
Introduction
Unlike RuBAN 5, where we (usually) ran all the databases, third party components and Davra-made components on a single machine with a large number of moving parts, RuBAN 6 is dockerized.
"Docker containers wrap up a piece of software in a complete filesystem that contains everything it needs to run: code, runtime, system tools, system libraries – anything you can install on a server. This guarantees that it will always run the same, regardless of the environment it is running in." – Docker website.
The end result of a release build is a docker image, which contains all the previously separate RuBAN (micro)services. In other words, RuBAN-in-docker is the new RuBAN.
Docker primer
Docker concepts
Docker is a paravirtualization solution. It does not emulate hardware at all. The easiest way to describe docker is that it's a tool which can provide a pretty isolated environment for a process group.
A "docker image" is similar to a disk image: it contains files and folders in a certain way. It is immutable, which means that an image can not be changed after it has been built. Any changes made in a container's file system which is not a volume is lost upon terminating the container
A "docker container" is an isolated process group running at least one command in the environment established by the docker image.
A "docker volume" is a special folder mounted using a bind mount. This allows to expose a host folder to the container, which means that any changes made to this folder will remain even in case of container shutdown
Docker commands cheat-sheet
(Please note that in place of an <image_id> you could use the <image_name> if it's available. Similarly, you could use <container_id> in place of <container_name>)
| Command | What it does |
|---|---|
docker images | lists all the images available |
docker ps | lists currently running containers |
docker run <image_id> | starts a new container |
docker inspect <container_name> | lists information about a container, like IP Address and mounted volumes |
docker kill <container_name> | kills the container |
docker exec -it <container_name> bash | starts an interactive bash session inside the container (if the container is running) (you may want to execute "export TERM=vt100" as your first command if you are going to troubleshoot inside the container) |
docker rmi -f <image_id> | remove the image |
How to recover from catastrophic failures of docker?
Only use it as a last resort, when docker does not behave as it should.
Use these three simple commands:
service docker stop rm -rf /var/lib/docker service docker start
Please note that this will shut down all currently running containers and wipe out all stored images.
New features walkthrough
The new installer
The new installer only contains 6 files, which install the prerequisites (Docker, MongoDB and Cassandra) and then loads the image to the local images store of Docker.
It uses the package manager to accomplish these. It also opens up the database ports to the (by default the docker0) network using CentOS 7's firewall-cmd.
The installation also writes the unified configuration file to /var/Davra/RuBAN/config.sh with config values which were true at installation time.
How does the docker image gets built?
It's pretty similar to RuBAN 5's installation sequence. In fact, most of the installation files are identical, with two important changes: a. the iptables firewall rules are not executed and b. the services are not started immediately after installed.
The reasons for these are the following:
a. iptables are not installed on CentOS 7 by default. They are accessible via an optional legacy interface. Also in order to use them from a docker container, the container needs to run using elevated privileges, which are a security risk. Docker containers by default run within their own virtual subnet, and as such firewall rules are not strictly necessary (as this virtual subnet is host-only by default)
b. Docker distinguishes between installation time (image creation time) and run time. The docker container used to build the image does not support all the same features as run time, and it is killed after the image is built. There is no point starting the services at this time.
How can I start RuBAN?
The installer will start RuBAN 6 for you with the following (non-exhaustive) list of parameters:
docker run -d --restart=unless-stopped --link mongo:mongo --name ruban -v /var/Davra:/var/Davra $latest_ruban_image
The options are:
| Parameter | What it does |
|---|---|
-d | detach from the current terminal and run in the background |
--restart=unless-stopped | unless explicitly stopped or killed, restart the container with the same settings upon CentOS restart |
-p 58000:58000 | expose the container's 58000 port on the host's 58000 port. |
-v /var/Davra:/var/Davra | expose the /var/Davra directory on the host as the /var/Davra directory in the container |
--name ruban | name the container as "ruban" |
--link mongo:mongo | link the container named "mongo" to this container, so it will be accessible to the internal docker network via the domain name "mongo" |
Inside the docker container, the file at /opt/Davra/RuBAN/run.sh is executed, which performs the post-installation step if necessary and then starts all the services in order.
If it ever needs to be killed, refer to the installer with the proper way of starting it up again. You might need to use docker commit to change the environmental parameters of a running docker container (for more info, see the official documentation)
Dockerized Davra services
Some Davra services/applications are now dockerized.
| Name | Comments |
|---|---|
| /wiki/spaces/CN/pages/61734939 | Comes as a standard security feature on all RuBAN installations. Superseded the "ruban" container for host-exposed port 58000 |
Third-party services are now dockerized
MongoDB, Cassandra and PostgreSQL are the third-party databases we depend on. Instead of installing them from packages, we are using the official Docker images of these.
The docker images are automatically retrieved upon running docker run, similarly to docker's own hello world image, invoked by "docker run hello-world"
The third party databases are then linked to the ruban docker container using docker run --link x:x mechanism, which will expose the named container (eg cassandra) as a domain name only to the ruban container, regardless of what IP they've got.
Unified state
If you run RuBAN using the recommended way, all the state of a RuBAN instance (excluding the databases, of course) should be in /var/Davra on the host. This includes custom panels, node red flows and the logs for all services. This is an easy way to backup the state of RuBAN, or you can tar it up for further analysis to be performed by a developer somewhere else.
Unified configuration
The biggest change is that all the services are getting their configuration from environmental variables, which are present in the Dockerfile. To change them, you will need to use docker commit to change the environmental parameters of a running docker container (for more info, see the official documentation)
The node-based microservices get these values via command-line parameters in their startup script.
The RuBAN core and baseline services use a yaml file. This yaml file is generated by the script update-ruban-yaml-configs.sh at start time. (The plural is because there are actually 3 yaml files with identical content).
KairosDB uses a property file which is updated by update-kairosdb-config.sh at start time.