openshift/openshift-docs
1
0
Fork 0
mirror of https://github.com/openshift/openshift-docs.git synced 2026-02-05 21:46:22 +01:00
Code Issues Releases Activity
Files
a5b436bbfb85015700a967931ab22ea2a96e6e96
openshift-docs/modules/installing-docker.adoc
Kathryn Alexander b160717450 replacing ' in anchor ids
2019-03-19 08:21:41 -04:00

455 lines
16 KiB
Plaintext
Raw Blame History

// Module included in the following assemblies:
//
// * installing-byoh/installing-existing-hosts.adoc
[id="installing-docker-{context}"]
= Installing Docker
[IMPORTANT]
====
Docker probably won't be supported anywhere on 4.0, but we might need to replace
this content with equivalent CRI-O information. This is not a well-formed module
because I expect to delete it.
====
At this point, install Docker on all master and node hosts. This
allows you to configure your Docker storage
options before you install {product-title}.
[NOTE]
====
The cluster installation process automatically modifies
the *_/etc/sysconfig/docker_* file.
====
. Install Docker 1.13:
+
----
# yum install docker-1.13.1
----
. Verify that version 1.13 was installed:
+
----
# rpm -V docker-1.13.1
# docker version
----
[id="configuring-docker-storage-{context}"]
== Configuring Docker Storage
Containers and the images they are created from are stored in Docker's storage
back end. This storage is ephemeral and separate from any persistent
storage allocated to meet the needs of your applications. With _Ephemeral
storage_, container-saved data is lost when the container is removed. With
_persistent storage_, container-saved data remains if the container is removed.
You must configure storage for all master and node hosts because by default each
system runs a container daemon. For containerized installations, you need
storage on masters. Also, by default, the web console and etcd, which require
storage, run in containers on masters. Containers run on nodes, so storage is
always required on them.
The size of storage depends on workload, number of containers, the
size of the containers being run, and the containers' storage requirements.
The default storage back end for Docker on RHEL 7 is a thin pool on loopback
devices, which is not supported for production use and only appropriate for
proof of concept environments. For production environments, you must create a
thin pool logical volume and re-configure Docker to use that volume.
Docker stores images and containers in a graph driver, which is a pluggable storage technology, such as `DeviceMapper`,
`OverlayFS`, and `Btrfs`. Each has advantages and disadvantages. For example, OverlayFS is faster than DeviceMapper
at starting and stopping containers but is not Portable Operating System Interface for Unix (POSIX) compliant
because of the architectural limitations of a union file system. See the
link:https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/?version=7[Red Hat Enterprise Linux] release notes
for information on using OverlayFS with your version of RHEL.
.Configuring OverlayFS
OverlayFS is a type of union file system. It allows you to overlay one file system on top of another.
Changes are recorded in the upper file system, while the lower file system remains unmodified.
For information about enabling the OverlayFS storage driver for the Docker service, see the
link:https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux_atomic_host/7/html-single/managing_containers/#using_the_overlay_graph_driver[Red Hat Enterprise Linux Atomic Host documentation].
.Configuring thin pool storage
You can use the `docker-storage-setup` script included with Docker to create a
thin pool device and configure Docker's storage driver. You can do this after
you install Docker and must do it before you create images or containers. The
script reads configuration options from the
*_/etc/sysconfig/docker-storage-setup_* file and supports three options for
creating the logical volume:
- Use an additional block device.
- Use an existing, specified volume group.
- Use the remaining free space from the volume group where your root
file system is located.
Using an additional block device is the most robust option, but it requires adding another
block device to your host before you configure Docker storage. The other options
both require leaving free space available when you provision your host. Using
the remaining free space in the root file system volume group
is known to cause issues with some applications, for example Red Hat Mobile
Application Platform (RHMAP).
. Create the `docker-pool` volume using one of the following three options:
** To use an additional block device:
.. *_/etc/sysconfig/docker-storage-setup_*, set `DEVS` to the path of the block
device to use. Set `VG` to the volume group name to create, such as
`docker-vg`. For example:
+
----
# cat <<EOF > /etc/sysconfig/docker-storage-setup
DEVS=/dev/vdc
VG=docker-vg
EOF
----
.. Run `docker-storage-setup` and review the output to ensure the
`docker-pool` volume was created:
+
----
# docker-storage-setup [5/1868]
0
Checking that no-one is using this disk right now ...
OK
Disk /dev/vdc: 31207 cylinders, 16 heads, 63 sectors/track
sfdisk: /dev/vdc: unrecognized partition table type
Old situation:
sfdisk: No partitions found
New situation:
Units: sectors of 512 bytes, counting from 0
Device Boot Start End #sectors Id System
/dev/vdc1 2048 31457279 31455232 8e Linux LVM
/dev/vdc2 0 - 0 0 Empty
/dev/vdc3 0 - 0 0 Empty
/dev/vdc4 0 - 0 0 Empty
Warning: partition 1 does not start at a cylinder boundary
Warning: partition 1 does not end at a cylinder boundary
Warning: no primary partition is marked bootable (active)
This does not matter for LILO, but the DOS MBR will not boot this disk.
Successfully wrote the new partition table
Re-reading the partition table ...
If you created or changed a DOS partition, /dev/foo7, say, then use dd(1)
to zero the first 512 bytes: dd if=/dev/zero of=/dev/foo7 bs=512 count=1
(See fdisk(8).)
Physical volume "/dev/vdc1" successfully created
Volume group "docker-vg" successfully created
Rounding up size to full physical extent 16.00 MiB
Logical volume "docker-poolmeta" created.
Logical volume "docker-pool" created.
WARNING: Converting logical volume docker-vg/docker-pool and docker-vg/docker-poolmeta to pool's data and metadata volumes.
THIS WILL DESTROY CONTENT OF LOGICAL VOLUME (filesystem etc.)
Converted docker-vg/docker-pool to thin pool.
Logical volume "docker-pool" changed.
----
** To use an existing, specified volume group:
.. In *_/etc/sysconfig/docker-storage-setup_*, set `VG` to the volume
group. For example:
+
----
# cat <<EOF > /etc/sysconfig/docker-storage-setup
VG=docker-vg
EOF
----
.. Then run `docker-storage-setup` and review the output to ensure the
`docker-pool` volume was created:
+
----
# docker-storage-setup
Rounding up size to full physical extent 16.00 MiB
Logical volume "docker-poolmeta" created.
Logical volume "docker-pool" created.
WARNING: Converting logical volume docker-vg/docker-pool and docker-vg/docker-poolmeta to pool's data and metadata volumes.
THIS WILL DESTROY CONTENT OF LOGICAL VOLUME (filesystem etc.)
Converted docker-vg/docker-pool to thin pool.
Logical volume "docker-pool" changed.
----
** To use the remaining free space from the volume group where your root file
system is located:
.. Verify that the volume group where your root file system resides has the required
free space, then run `docker-storage-setup` and review the output to ensure the
`docker-pool` volume was created:
+
----
# docker-storage-setup
Rounding up size to full physical extent 32.00 MiB
Logical volume "docker-poolmeta" created.
Logical volume "docker-pool" created.
WARNING: Converting logical volume rhel/docker-pool and rhel/docker-poolmeta to pool's data and metadata volumes.
THIS WILL DESTROY CONTENT OF LOGICAL VOLUME (filesystem etc.)
Converted rhel/docker-pool to thin pool.
Logical volume "docker-pool" changed.
----
. Verify your configuration. Confirm that the *_/etc/sysconfig/docker-storage_*
file has `dm.thinpooldev` and `docker-pool` logical volume values:
+
----
# cat /etc/sysconfig/docker-storage
DOCKER_STORAGE_OPTIONS="--storage-driver devicemapper --storage-opt dm.fs=xfs --storage-opt dm.thinpooldev=/dev/mapper/rhel-docker--pool --storage-opt dm.use_deferred_removal=true --storage-opt dm.use_deferred_deletion=true "
# lvs
LV VG Attr LSize Pool Origin Data% Meta% Move Log Cpy%Sync Convert
docker-pool rhel twi-a-t--- 9.29g 0.00 0.12
----
+
[IMPORTANT]
====
Before using Docker or {product-title}, verify that the `docker-pool` logical volume
is large enough to meet your needs. Make the `docker-pool` volume 60% of
the available volume group; it will grow to fill the volume group through LVM
monitoring.
====
. Start or restart Docker.
** If Docker has never run on the host, enable and start the
service, then verify that it is running:
+
----
# systemctl enable docker
# systemctl start docker
# systemctl is-active docker
----
** If Docker is already running:
.. Re-initialize Docker:
+
[WARNING]
====
This will destroy any containers or images currently on the host.
====
+
----
# systemctl stop docker
# rm -rf /var/lib/docker/*
# systemctl restart docker
----
.. Delete any content in the *_/var/lib/docker/_* folder.
.Reconfiguring Docker storage
If you need to reconfigure Docker storage after you create the
`docker-pool`:
. Remove the `docker-pool` logical volume.
. If you use a dedicated volume group, remove the volume group and
any associated physical volumes
. Run `docker-storage-setup` again.
See
link:https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/7/html/Logical_Volume_Manager_masters/index.html[Logical Volume Manager Administration]
for more detailed information about LVM management.
.Enabling image signature support
{product-title} is capable of cryptographically verifying that images are from
trusted sources. The
Container Security Guide
provides a high-level description of how image signing works.
You can configure image signature verification using the `atomic` command line
interface (CLI), version 1.12.5 or greater.
ifdef::openshift-enterprise[]
[NOTE]
====
For more on the `atomic` CLI, see the
link:https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux_atomic_host/7/html/cli_reference/prerequisites[Atomic CLI documentation].
====
endif::[]
The following files and directories comprise the trust configuration of a host:
- *_/etc/containers/registries.d/*_*
- *_/etc/containers/policy.json_*
You can manage trust configuration directly on each node or manage the files on
a separate host distribute them to the appropriate nodes using
Ansible, for example. See the
link:https://access.redhat.com/articles/2750891#automating-cluster-configuration[Container
Image Signing Integration Guide] for an example of automating file distribution
with Ansible.
. Install the `atomic` package if it is not installed on the host system:
+
----
$ yum install atomic
----
. View the current trust configuration:
+
----
$ atomic trust show
* (default) accept
----
+
The default configuration is to whitelist all registries, which means that no
signature verification is configured.
. Customize your trust configuration. In the following example, you whitelist
one registry or namespace, blacklist (reject) untrusted registries, and require signature
verification on a vendor registry:
+
----
$ atomic trust add --type insecureAcceptAnything 172.30.1.1:5000
$ atomic trust add --sigstoretype atomic \
--pubkeys pub@example.com \
172.30.1.1:5000/production
$ atomic trust add --sigstoretype atomic \
--pubkeys /etc/pki/example.com.pub \
172.30.1.1:5000/production
$ atomic trust add --sigstoretype web \
--sigstore https://access.redhat.com/webassets/docker/content/sigstore \
--pubkeys /etc/pki/rpm-gpg/RPM-GPG-KEY-redhat-release \
registry.redhat.io
# atomic trust show
* (default) accept
172.30.1.1:5000 accept
172.30.1.1:5000/production signed security@example.com
registry.redhat.io signed security@redhat.com,security@redhat.com
----
. You can further harden nodes by adding a global `reject` default trust:
+
----
$ atomic trust default reject
$ atomic trust show
* (default) reject
172.30.1.1:5000 accept
172.30.1.1:5000/production signed security@example.com
registry.redhat.io signed security@redhat.com,security@redhat.com
----
. Optionally, review the `atomic` man page `man atomic-trust` for more configuration
options.
.Managing container logs
To prevent a container's log file, the
*_/var/log/containers/<hash>/<hash>-json.log_* file on the node where the
container is running, from increasing to a problematic size, you can
configure Docker's `json-file` logging driver to restrict the size and number
of log files.
[options="header"]
|===
|Option |Purpose
|`--log-opt max-size`
|Sets the size at which a new log file is created.
|`--log-opt max-file`
|Sets the maximum number of log files to be kept per host.
|===
. To configure the log file, edit the *_/etc/sysconfig/docker_* file. For
example, to set the maximum file size to 1 MB and always keep the last three
log files, set the following options:
+
----
OPTIONS='--insecure-registry=172.30.0.0/16 --selinux-enabled --log-opt max-size=1M --log-opt max-file=3'
----
+
See Docker's documentation for additional information on how to
link:https://docs.docker.com/engine/admin/logging/overview/#/options[configure logging drivers].
. Restart the Docker service:
+
----
# systemctl restart docker
----
.Viewing available container logs
You can view the container logs in the *_/var/lib/docker/containers/<hash>/_*
directory on the node where the container is running. For example:
----
# ls -lh /var/lib/docker/containers/f088349cceac173305d3e2c2e4790051799efe363842fdab5732f51f5b001fd8/
total 2.6M
-rw-r--r--. 1 root root 5.6K Nov 24 00:12 config.json
-rw-r--r--. 1 root root 649K Nov 24 00:15 f088349cceac173305d3e2c2e4790051799efe363842fdab5732f51f5b001fd8-json.log
-rw-r--r--. 1 root root 977K Nov 24 00:15 f088349cceac173305d3e2c2e4790051799efe363842fdab5732f51f5b001fd8-json.log.1
-rw-r--r--. 1 root root 977K Nov 24 00:15 f088349cceac173305d3e2c2e4790051799efe363842fdab5732f51f5b001fd8-json.log.2
-rw-r--r--. 1 root root 1.3K Nov 24 00:12 hostconfig.json
drwx------. 2 root root 6 Nov 24 00:12 secrets
----
.Blocking local volume usage
When a volume is provisioned using the `VOLUME` instruction in a *_Dockerfile_*
or using the `docker run -v <volumename>` command, a host's storage space is
used. Using this storage can lead to an unexpected out of space issue and can
bring down the host.
In {product-title}, users trying to run their own images risk filling the entire
storage space on a node host. One solution to this issue is to prevent users
from running images with volumes. This way, the only storage a user has access
to can be limited, and the cluster administrator can assign storage quota.
Using 1docker-novolume-plugin` solves this issue by disallowing starting a
container with local volumes defined. In particular, the plug-in blocks `docker run`
commands that contain:
- The `--volumes-from` option
- Images that have `VOLUME`(s) defined
- References to existing volumes that were provisioned with the `docker volume`
command
The plug-in does not block references to bind mounts.
To enable `docker-novolume-plugin`, perform the following steps on each node
host:
. Install the `docker-novolume-plugin` package:
+
----
$ yum install docker-novolume-plugin
----
. Enable and start the `docker-novolume-plugin` service:
+
----
$ systemctl enable docker-novolume-plugin
$ systemctl start docker-novolume-plugin
----
. Edit the *_/etc/sysconfig/docker_* file and append the following to the
`OPTIONS` list:
+
----
--authorization-plugin=docker-novolume-plugin
----
. Restart the `docker` service:
+
----
$ systemctl restart docker
----
After you enable this plug-in, containers with local volumes defined fail to
start and show the following error message:
----
runContainer: API error (500): authorization denied by plugin
docker-novolume-plugin: volumes are not allowed
----
View Git Blame Copy Permalink