Red Hat SummitChapter 6. Using the Docker Service
When you initialize the Container Development Kit virtual machine (using the vagrant up command), various services are automatically pre-configured and running — depending on the Vagrantfile you used to provision the Container Development Kit box. The Docker service is running in all cases, and you can use it immediately after the virtual machine is launched. While it is possible to use and interact with the Docker service using GUI tools (for example, the integrated Docker support provided by the Eclipse IDE), this section introduces a number of basic docker commands to get you started using the Docker service from the command line.
Command-line usage of the Docker service provided by the Container Development Kit box is possible both from within the virtual machine and from the host machine — see section Using the vagrant-service-manager Plugin for instructions on how to set up your host machine to interact with the Docker service running inside the Container Development Kit virtual machine.
See the Get Started with Docker Formatted Container Images chapter of the Red Hat Enterprise Linux Atomic Host 7 Getting Started with Containers guide for a more thorough introduction into the Docker service.
6.1. Preparing Host System for Using Docker from the Command Line
To use the docker command on your host system to interact with the Docker service running inside the Container Development Kit virtual machine, you need to install the docker executable.
If you intend to use Docker (and the docker command) only from within the Container Development Kit virtual machine, no preparation is required — the docker command is installed in the Container Development Kit box by default.
6.1.1. Installing the docker Executable
Use the install-cli command of the vagrant-service-manager plugin to install the docker binary on your host system.
For example:
~]$ vagrant service-manager install-cli docker # Binary now available at /home/joe/.vagrant.d/data/service-manager/bin/docker/1.10.3/docker # run binary as: # docker <command> export PATH=/home/joe/.vagrant.d/data/service-manager/bin/docker/1.10.3:$PATH # run following command to configure your shell: # eval "$(VAGRANT_NO_COLOR=1 vagrant service-manager install-cli docker | tr -d '\r')"
To use the install-cli command when behind a proxy, the Container Development Environment needs to be configured to operate behind a proxy using the vagrant-service-manager plugin. See section Using vagrant-service-manager to Set Proxy Environment Variables in the Red Hat Container Development Kit 2.3 Installation Guide.
6.1.1.1. Installing a Custom Version of the docker Binary
By default, the install-cli command installs the docker binary from the upstream Docker project in version 1.10.3. To install a different version, use the --cli-version option.
For example:
~]$ vagrant service-manager install-cli docker --cli-version 1.12.3 # Binary now available at /home/joe/.vagrant.d/data/service-manager/bin/docker/1.12.3/docker # run binary as: # docker <command> export PATH=/home/joe/.vagrant.d/data/service-manager/bin/docker/1.12.3:$PATH # run following command to configure your shell: # eval "$(VAGRANT_NO_COLOR=1 vagrant service-manager install-cli docker --cli-version 1.12.3 | tr -d '\r')"
6.1.1.2. Installing the docker Binary to a Custom Location
By default, the install-cli command installs the docker binary from the upstream Docker project to the following directory: /home/joe/.vagrant.d/data/service-manager/bin/docker/1.10.3/. To install the executable to a different location, use the --path option. Note that you need to specify an existing directory and the name of the binary.
For example:
~]$ vagrant service-manager install-cli docker --cli-version 1.12.3 --path ~/bin/docker # Binary now available at /home/joe/bin/docker # run binary as: # docker <command> export PATH=/home/joe/bin:$PATH # run following command to configure your shell: # eval "$(VAGRANT_NO_COLOR=1 vagrant service-manager install-cli docker --path /home/joe/bin/docker --cli-version 1.12.3 | tr -d '\r')"
6.2. Learning about the Docker Environment
The docker command offers several sub-commands that let you acquire information about the Docker service, the environment it runs in, and available resources. You can also query the service for images and containers it manages and for images that are available to you from the pre-configured registries. By default, the Docker service in Container Development Kit can download and use images from both the Docker Hub (docker.io) and the Red Hat Atomic Registry (registry.access.redhat.com).
Use the following commands to obtain information about the Docker service and the working environment.
6.2.1. Verifying the Version of the Docker Service
Run the docker version command to see the version of both the Docker Client and Docker Server:
~]$ docker version
Client:
Version: 1.10.3
API version: 1.22
Package version: docker-1.10.3-46.el7.14.x86_64
Go version: go1.4.2
Git commit: 78ee77d/1.10.3
Built:
OS/Arch: linux/amd64
Server:
Version: 1.10.3
API version: 1.22
Package version: docker-1.10.3-46.el7.14.x86_64
Go version: go1.4.2
Git commit: 78ee77d/1.10.3
Built:
OS/Arch: linux/amd646.2.2. Displaying Information about the System and Resources
Run the docker info command to see information about the host system (which, in this case, is the virtualized Red Hat Enterprise Linux instance managed by Vagrant), utilization of virtualization resources, basic networking information, and the numbers of managed containerrs and images:
~]$ docker info
Containers: 14
Images: 32
Server Version: 1.9.1
Storage Driver: devicemapper
Pool Name: VolGroup00-docker--pool
Pool Blocksize: 524.3 kB
Base Device Size: 107.4 GB
Backing Filesystem: xfs
Data file:
Metadata file:
Data Space Used: 2.172 GB
Data Space Total: 13.6 GB
Data Space Available: 11.43 GB
Metadata Space Used: 1.016 MB
Metadata Space Total: 46.14 MB
Metadata Space Available: 45.12 MB
Udev Sync Supported: true
Deferred Removal Enabled: true
Deferred Deletion Enabled: true
Deferred Deleted Device Count: 0
Library Version: 1.02.107-RHEL7 (2015-12-01)
Execution Driver: native-0.2
Logging Driver: json-file
Kernel Version: 3.10.0-514.el7.x86_64
Operating System: Red Hat Enterprise Linux Server 7.3 (Maipo)
CPUs: 2
Total Memory: 2.781 GiB
Name: rhel-cdk
ID: PZ3X:6J7V:OF4L:KZRY:XXDT:QXCU:UHGQ:XMWE:EMM5:4POR:CG6D:YF4S6.3. Learning about Containers and Images
Use the following commands to obtain information about images and containers on your system.
6.3.1. Listing Managed Images
Run the docker images command to display a list of images available in the local registry.
~]$ docker images
REPOSITORY TAG IMAGE ID CREATED VIRTUAL SIZE
docker.io/prom/haproxy-exporter latest 2b168f203700 11 days ago 23.64 MB
registry.access.redhat.com/openshift3/ose-pod v3.1.1.6 2b96d2bcbc46 2 weeks ago 428 MB
registry.access.redhat.com/openshift3/ose-sti-builder v3.1.1.6 983aa720a8e7 3 weeks ago 441.9 MB
registry.access.redhat.com/openshift3/ose-deployer v3.1.1.6 d772a87d1aac 3 weeks ago 441.9 MB
registry.access.redhat.com/openshift3/ose v3.1.1.6 88178069a37f 3 weeks ago 441.9 MB
registry.access.redhat.com/openshift3/ose-haproxy-router v3.1.1.6 5e18f7fbcc6c 3 weeks ago 456.8 MB
registry.access.redhat.com/openshift3/ose-docker-registry v3.1.1.6 3c272743b20a 3 weeks ago 478.5 MB6.3.2. Listing Managed Containers
Run the docker ps command to display a list of running containers. Add the --all or -a parameter to list all available containers (not just the running ones). As you can see from the example output below, there are several running containers in Container Development Kit immediately after launch. These containers provide some of the services offered by Container Development Kit and as such should not be stopped or removed. The example below shows containers with the OpenShift service
Use the --format parameter to specify what information you want displayed about the individual containers (see the docker-ps(1) manual page for a list of available placeholders). For example:
~]$ docker ps --format "table {{.ID}}\t{{.Image}}\t{{.Command}}\t{{.Status}}"
CONTAINER ID IMAGE COMMAND STATUS
ce4817df7620 prom/haproxy-exporter:latest "/bin/go-run -haproxy" Up 55 minutes
e38b37b6e13a openshift3/ose-docker-registry:v3.1.1.6 "/bin/sh -c 'DOCKER_R" Up 56 minutes
8abd50d2311f openshift3/ose-pod:v3.1.1.6 "/pod" Up 56 minutes
6821a60044a8 openshift3/ose-haproxy-router:v3.1.1.6 "/usr/bin/openshift-r" Up 56 minutes
5312e060116d openshift3/ose-pod:v3.1.1.6 "/pod" Up 56 minutes
8c94cc0c049b registry.access.redhat.com/openshift3/ose:v3.1.1.6 "/usr/bin/openshift s" Up 59 minutes6.3.3. Displaying Information about Container Resource Usage
Run the docker stats <container> command to display a live output showing resource-usage statistics for a specific running container. For example:
~]$ docker stats openshift
CONTAINER CPU % MEM USAGE / LIMIT MEM % NET I/O BLOCK I/O
openshift 0.00% 110.4 MB / 2.986 GB 3.70% 0 B / 0 B 77.24 MB / 3.708 MB6.3.4. Displaying Detailed Information about Container or Image Configuration
Run the docker inspect <container> command to show low-level information about a container or an image in JSON format. Use the --type parameter to specify whether you want to display information about a container (the default) or an image in case you have containers and images of the same name.
Use the --format parameter to specify what part of the output you want displayed (see the docker-inspect(1) manual page for examples of the output). For example, define the following format to list network ports exposed by the container:
~]$ docker inspect --format='{{.Config.ExposedPorts}}' openshift
map[8443/tcp:{} 53/tcp:{}]6.4. Getting New Docker-Formatted Container Images
Existing images for creating containers can be either downloaded (pulled) from one of the two pre-configured repositories (the Docker Hub (docker.io) and the Red Hat Atomic Registry (registry.access.redhat.com)) or imported from a local file.
6.4.1. Searching Registries for Images
Run the docker search <search-term> command to search the pre-configured registries for images. For example, to search for images containing the string rhscl in the name or namespace, use the following command:
~]$ docker search rhscl
INDEX NAME DESCRIPTION STARS OFFICIAL AUTOMAT
docker.io docker.io/rhscl/mongodb-26-centos7 A Centos7 based MongoDB v2.6 image for use... 0
redhat.com registry.access.redhat.com/rhscl/devtoolset-4-toolchain-rhel7 Developer toolset toolchain 0
redhat.com registry.access.redhat.com/rhscl/httpd-24-rhel7 Apache HTTP 2.4 Server 0
redhat.com registry.access.redhat.com/rhscl/mariadb-100-rhel7 MariaDB 10.0 SQL database server 0
redhat.com registry.access.redhat.com/rhscl/mongodb-26-rhel7 MongoDB 2.6 NoSQL database server 0
redhat.com registry.access.redhat.com/rhscl/mysql-56-rhel7 MySQL 5.6 SQL database server 0
redhat.com registry.access.redhat.com/rhscl/nginx-16-rhel7 Nginx 1.6 server and a reverse proxy server 0
[...]6.4.2. Downloading Images from a Registry
Run the docker pull <image> command to download (pull) the specified image to your system for local use. Note that while it is possible to provide just the name of the image, it is better practice to also specify the registry you want to pull from and the namespace in which the particular image is published. The naming convention follows this order: [registry/][namespace/]name.
For example, to pull the image with the toolchain components of the Red Hat Developer Toolset from the Red Hat Atomic Registry, use the following command:
~]$ docker pull registry.access.redhat.com/rhscl/devtoolset-4-toolchain-rhel7 Using default tag: latest 68f6775524af: Download complete 6c3a84d798dc: Download complete Status: Downloaded newer image for registry.access.redhat.com/rhscl/devtoolset-4-toolchain-rhel7:latest ~]$ docker images registry.access.redhat.com/rhscl/devtoolset-4-toolchain-rhel7 REPOSITORY TAG IMAGE ID CREATED VIRTUAL SIZE registry.access.redhat.com/rhscl/devtoolset-4-toolchain-rhel7 latest 68f6775524af 7 weeks ago 365.5 MB
6.4.3. Loading an Image from a File
Run the docker load < file.tar command to load an image from a local file file.tar. By default, the docker pull command loads image data from the standard input. To load an image from a file, use the --input or -i parameter. For example to load the Red Hat Developer Toolset toolchain image that was previously saved to a tar file using the docker save command, use the following command:
~]$ docker load -i devtoolset.tar6.5. Using Containers
Use the following commands to launch, stop, or remove containers or to run applications from within containers.
6.5.1. Launching a New Container and Running a Command
Run the docker run <image> <command> command to launch a new container from an image and run the specified command. Use the --name parameter to specify a name for the container to prevent the Docker service from assigning a random name to the container. For example, to run the uname -a command (and display its output) in a container created from the Red Hat Developer Toolset toolchain image, use the following command:
~]$ docker run --name devtoolset registry.access.redhat.com/rhscl/devtoolset-4-toolchain-rhel7 uname -a Linux 22b819dec3f1 3.10.0-327.el7.x86_64 #1 SMP Thu Oct 29 17:29:29 EDT 2015 x86_64 x86_64 x86_64 GNU/Linux ~]$ docker ps -a --format "table {{.ID}}\t{{.Names}}\t{{.Command}}\t{{.Status}}" CONTAINER ID NAMES COMMAND STATUS 22b819dec3f1 devtoolset "uname -a" Exited (0) 2 seconds ago [...]
6.5.2. Stopping a Container
Run the docker stop <container> command to stop one or more containers. This action tries to gracefully shut down the applications running in the container by sending them the SIGTERM signal (followed by the SIGKILL signal if SIGTERM does not work). For example, to stop the container created in the previous example, use the following command:
~]$ docker stop devtoolset devtoolset ~]$ docker ps | grep devtoolset
6.5.3. Starting an Existing Container
Use the docker start -i <container> command to run the container stopped in the previous example (the --interactive or -i parameter ensures that the container’s standard output is attached to your current shell — in other words, it ensures that the output of the command executed in the container is displayed):
~]$ docker start -i devtoolset
Linux 22b819dec3f1 3.10.0-327.el7.x86_64 #1 SMP Thu Oct 29 17:29:29 EDT 2015 x86_64 x86_64 x86_64 GNU/Linux6.5.4. Launching a New Container and Switching to the Container’s Shell
Run the docker run -ti <image> bash command to launch a new container from an image and switch to an interactive shell within the container. The --interactive or -i parameter along with the --tty or -t parameter are used to allocate a pseudo-TTY within which the Bash shell is run. For example:
~]$ docker run -it registry.access.redhat.com/rhscl/devtoolset-4-toolchain-rhel7 bash bash-4.2$ uname -a Linux 5e224c8c3878 3.10.0-327.el7.x86_64 #1 SMP Thu Oct 29 17:29:29 EDT 2015 x86_64 x86_64 x86_64 GNU/Linux bash-4.2$ exit exit ~]$ docker ps -a --format "table {{.ID}}\t{{.Names}}\t{{.Command}}\t{{.Status}}" CONTAINER ID NAMES COMMAND STATUS 5e224c8c3878 devtoolset "uname -a" Exited (0) 2 seconds ago [...]
6.5.5. Removing a Container
Run the docker rm <container> command to remove one or more containers, thus freeing the host’s resources. For example, to remove the container created in the previous example, use the following command:
~]$ docker rm devtoolset devtoolset ~]$ docker ps -a | grep devtoolset
6.6. Additional Resources
-
See the
COMMANDSsection of thedocker(1)manual page for a complete list of availabledockercommands and detailed descriptions of their function. - See the Getting Started with Containers guide for detailed information about the use and management of containers on the Red Hat Enterprise Linux and Red Hat Atomic platforms.
