Preparing your hosts

Before you install OKD, you must prepare the node hosts. They must meet the following requirements.

Setting PATH

The PATH for the root user on each host must contain the following directories:

  • /bin

  • /sbin

  • /usr/bin

  • /usr/sbin

These directories set by default in a new RHEL 7.x installation.

Ensuring host access

The OKD installer requires a user that has access to all hosts. If you want to run the installer as a non-root user, first configure passwordless sudo rights each host:

  1. Generate an SSH key on the host you run the installation playbook on:

    1. # ssh-keygen

    Do not use a password.

  2. Distribute the key to the other cluster hosts. You can use a bash loop:

    1. # for host in master.example.com \ (1)
    2.     node1.example.com \  (1)
    3.     node2.example.com; \ (1)
    4.     do ssh-copy-id -i ~/.ssh/id_rsa.pub $host; \
    5.     done
    1Provide the host name for each cluster host.

  3. Confirm that you can access each host that is listed in the loop through SSH.

Setting proxy overrides

If the /etc/environment file on your nodes contains either an http_proxy or https_proxy value, you must also set a no_proxy value in that file to allow open communication between OKD components.

The no_proxy parameter in /etc/environment file is not the same value as the global proxy values that you set in your inventory file. The global proxy values configure specific OKD services with your proxy settings. See Configuring Global Proxy Options for details.

If the /etc/environment file contains proxy values, define the following values in the no_proxy parameter of that file on each node:

  • Master and node host names or their domain suffix.

  • Other internal host names or their domain suffix.

  • Etcd IP addresses. You must provide IP addresses and not host names because etcd access is controlled by IP address.

  • Kubernetes IP address, by default 172.30.0.1. Must be the value set in the openshift_portal_net parameter in your inventory file.

  • Kubernetes internal domain suffix, cluster.local.

  • Kubernetes internal domain suffix, .svc.

Because no_proxy does not support CIDR, you can use domain suffixes.

If you use either an http_proxy or https_proxy value, your no_proxy parameter value resembles the following example:

  1. no_proxy=.internal.example.com,10.0.0.1,10.0.0.2,10.0.0.3,.cluster.local,.svc,localhost,127.0.0.1,172.30.0.1

Installing base packages

If your hosts use RHEL 7.5 and you want to accept OKD’s default docker configuration (using OverlayFS storage and all default logging options), do not manually install these packages. These packages are installed when you run the prerequisites.yml playbook during installation.

If your hosts use RHEL 7.4 or if they use RHEL 7.5 and you want to customize the docker configuration, install these packages.

For RHEL 7 systems:

  1. Install the following base packages:

    1. # yum install wget git net-tools bind-utils yum-utils iptables-services bridge-utils bash-completion kexec-tools sos psacct

  2. Update the system to the latest packages:

    1. # yum update
    2. # reboot

  3. Install packages that are required for your installation method:

    • If you plan to use the containerized installer, install the following package:

      1. # yum install atomic

    • If you plan to use the RPM-based installer:

      1. Install Ansible. To use EPEL as a package source for Ansible:

        1. Install the EPEL repository:

          1. # yum -y install \
          2.     https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm

        2. Disable the EPEL repository globally so that it is not accidentally used during later steps of the installation:

          1. # sed -i -e "s/^enabled=1/enabled=0/" /etc/yum.repos.d/epel.repo

        3. Install the packages for Ansible:

          1. # yum -y --enablerepo=epel install ansible pyOpenSSL
  1.     2.  Clone the **openshift/openshift-ansible** repository from GitHub, which provides the required playbooks and configuration files:
  3.         ```
  4.         # cd ~
  5.         # git clone https://github.com/openshift/openshift-ansible
  6.         # cd openshift-ansible
  7.         # git checkout release-3.11
  8.         ```
  10.         <table><tbody><tr><td><i title="Note"></i></td><td><div><p>Be sure to use the release branch of the <strong>openshift-ansible</strong> repository that corresponds to your OKD version. Use the <strong>master</strong> branch to install the version of OKD in development.</p></div></td></tr></tbody></table>

For RHEL Atomic Host 7 systems:

  1. Ensure the host is up to date by upgrading to the latest Atomic tree if one is available:

    1. # atomic host upgrade

  2. After the upgrade is completed and prepared for the next boot, reboot the host:

    1. # reboot

Installing Docker

At this point, install Docker on all master and node hosts. This allows you to configure your Docker storage options before you install OKD.

The cluster installation process automatically modifies the /etc/sysconfig/docker file.

For RHEL 7 systems:

  1. Install Docker 1.13:

    1. # yum install docker-1.13.1

  2. Verify that version 1.13 was installed:

    1. # rpm -V docker-1.13.1
    2. # docker version

For RHEL Atomic Host 7 systems:

No action is required. Docker is installed, configured, and running by default.

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.

If your hosts use RHEL 7.5 and you want to accept OKD’s default docker configuration (using OverlayFS storage and all default logging options), do not manually install these packages. These packages are installed when you run the prerequisites.yml playbook during installation.

If your hosts use RHEL 7.4 or if they use RHEL 7.5 and you want to customize the docker configuration, install these packages.

For RHEL 7 systems:

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 Red Hat Enterprise Linux release notes for information on using OverlayFS with your version of RHEL.

For more information about the benefits and limitations of DeviceMapper and OverlayFS, see Choosing a Graph Driver.

For RHEL Atomic Host 7 systems:

The default storage back end for Docker on RHEL Atomic Host is a thin pool logical volume, which is supported for production environments. You must ensure that enough space is allocated for this volume per the Docker storage requirements mentioned in System Requirements.

If you do not have enough space allocated, see Managing Storage with Docker Formatted Containers for details about using docker-storage-setup and basic instructions on storage management in RHEL Atomic Host.

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.

Comparing the Overlay Versus Overlay2 Graph Drivers has more information about the overlay and overlay2 drivers.

For information about enabling the OverlayFS storage driver for the Docker service, see the 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).

  1. Create the docker-pool volume using one of the following three options:

    • To use an additional block device:

      1. In /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:

        1. # cat <<EOF > /etc/sysconfig/docker-storage-setup
        2. DEVS=/dev/vdc
        3. VG=docker-vg
        4. EOF

      2. Run docker-storage-setup and review the output to ensure the docker-pool volume was created:

        1. # docker-storage-setup                                                                                                                                                                                                                                [5/1868]
        2. 0
        3. Checking that no-one is using this disk right now ...
        4. OK
        6. Disk /dev/vdc: 31207 cylinders, 16 heads, 63 sectors/track
        7. sfdisk:  /dev/vdc: unrecognized partition table type
        9. Old situation:
        10. sfdisk: No partitions found
        12. New situation:
        13. Units: sectors of 512 bytes, counting from 0
        15.    Device Boot    Start       End   #sectors  Id  System
        16. /dev/vdc1          2048  31457279   31455232  8e  Linux LVM
        17. /dev/vdc2             0         -          0   0  Empty
        18. /dev/vdc3             0         -          0   0  Empty
        19. /dev/vdc4             0         -          0   0  Empty
        20. Warning: partition 1 does not start at a cylinder boundary
        21. Warning: partition 1 does not end at a cylinder boundary
        22. Warning: no primary partition is marked bootable (active)
        23. This does not matter for LILO, but the DOS MBR will not boot this disk.
        24. Successfully wrote the new partition table
        26. Re-reading the partition table ...
        28. If you created or changed a DOS partition, /dev/foo7, say, then use dd(1)
        29. to zero the first 512 bytes:  dd if=/dev/zero of=/dev/foo7 bs=512 count=1
        30. (See fdisk(8).)
        31.   Physical volume "/dev/vdc1" successfully created
        32.   Volume group "docker-vg" successfully created
        33.   Rounding up size to full physical extent 16.00 MiB
        34.   Logical volume "docker-poolmeta" created.
        35.   Logical volume "docker-pool" created.
        36.   WARNING: Converting logical volume docker-vg/docker-pool and docker-vg/docker-poolmeta to pool's data and metadata volumes.
        37.   THIS WILL DESTROY CONTENT OF LOGICAL VOLUME (filesystem etc.)
        38.   Converted docker-vg/docker-pool to thin pool.
        39.   Logical volume "docker-pool" changed.
  1. -   To use an existing, specified volume group:
  3.     1.  In ***/etc/sysconfig/docker-storage-setup***, set **VG** to the volume group. For example:
  5.         ```
  6.         # cat <<EOF > /etc/sysconfig/docker-storage-setup
  7.         VG=docker-vg
  8.         EOF
  9.         ```
  11.     2.  Then run **docker-storage-setup** and review the output to ensure the **docker-pool** volume was created:
  13.         ```
  14.         # docker-storage-setup
  15.           Rounding up size to full physical extent 16.00 MiB
  16.           Logical volume "docker-poolmeta" created.
  17.           Logical volume "docker-pool" created.
  18.           WARNING: Converting logical volume docker-vg/docker-pool and docker-vg/docker-poolmeta to pool's data and metadata volumes.
  19.           THIS WILL DESTROY CONTENT OF LOGICAL VOLUME (filesystem etc.)
  20.           Converted docker-vg/docker-pool to thin pool.
  21.           Logical volume "docker-pool" changed.
  22.         ```
  25. -   To use the remaining free space from the volume group where your root file system is located:
  27.     1.  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:
  29.         ```
  30.         # docker-storage-setup
  31.           Rounding up size to full physical extent 32.00 MiB
  32.           Logical volume "docker-poolmeta" created.
  33.           Logical volume "docker-pool" created.
  34.           WARNING: Converting logical volume rhel/docker-pool and rhel/docker-poolmeta to pool's data and metadata volumes.
  35.           THIS WILL DESTROY CONTENT OF LOGICAL VOLUME (filesystem etc.)
  36.           Converted rhel/docker-pool to thin pool.
  37.           Logical volume "docker-pool" changed.
  38.         ```

  1. Verify your configuration. Confirm that the /etc/sysconfig/docker-storage file has dm.thinpooldev and docker-pool logical volume values:

    1. # cat /etc/sysconfig/docker-storage
    2. 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 "
    4. # lvs
    5.   LV          VG   Attr       LSize  Pool Origin Data%  Meta%  Move Log Cpy%Sync Convert
    6.   docker-pool rhel twi-a-t---  9.29g             0.00   0.12

    Before using Docker or OKD, 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.

  2. Start or restart Docker.

    • If Docker has never run on the host, enable and start the service, then verify that it is running:

      1. # systemctl enable docker
      2. # systemctl start docker
      3. # systemctl is-active docker

    • If Docker is already running:

      1. Re-initialize Docker:

        This will destroy any containers or images currently on the host.

        1. # systemctl stop docker
        2. # rm -rf /var/lib/docker/*
        3. # systemctl restart docker

      2. 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:

  1. Remove the docker-pool logical volume.

  2. If you use a dedicated volume group, remove the volume group and any associated physical volumes

  3. Run docker-storage-setup again.

See Logical Volume Manager Administration for more detailed information about LVM management.

Enabling image signature support

OKD 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.

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 Container Image Signing Integration Guide for an example of automating file distribution with Ansible.

  1. Install the atomic package if it is not installed on the host system:

    1. $ yum install atomic

  2. View the current trust configuration:

    1. $ atomic trust show
    2. * (default)                         accept

    The default configuration is to whitelist all registries, which means that no signature verification is configured.

  3. 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:

    1. $ atomic trust add --type insecureAcceptAnything 172.30.1.1:5000
    3. $ atomic trust add --sigstoretype atomic \
    4.   --pubkeys pub@example.com \
    5.   172.30.1.1:5000/production
    7. $ atomic trust add --sigstoretype atomic \
    8.   --pubkeys /etc/pki/example.com.pub \
    9.   172.30.1.1:5000/production
    11. $ atomic trust add --sigstoretype web \
    12.   --sigstore https://access.redhat.com/webassets/docker/content/sigstore \
    13.   --pubkeys /etc/pki/rpm-gpg/RPM-GPG-KEY-redhat-release \
    14.   registry.redhat.io
    16. # atomic trust show
    17. * (default)                         accept
    18. 172.30.1.1:5000                     accept
    19. 172.30.1.1:5000/production          signed security@example.com
    20. registry.redhat.io                  signed security@redhat.com,security@redhat.com

  4. You can further harden nodes by adding a global reject default trust:

    1. $ atomic trust default reject
    3. $ atomic trust show
    4. * (default)                         reject
    5. 172.30.1.1:5000                     accept
    6. 172.30.1.1:5000/production          signed security@example.com
    7. registry.redhat.io                  signed security@redhat.com,security@redhat.com

  5. 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/lib/docker/containers//-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.

OptionPurpose

—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.

  1. 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, append max-size=1M and max-file=3 to the OPTIONS= line, ensuring that the values maintain the single quotation mark formatting:

    1. 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 configure logging drivers.

  2. Restart the Docker service:

    1. # systemctl restart docker

Viewing available container logs

You can view the container logs in the /var/lib/docker/containers// directory on the node where the container is running. For example:

  1. # ls -lh /var/lib/docker/containers/f088349cceac173305d3e2c2e4790051799efe363842fdab5732f51f5b001fd8/
  2. total 2.6M
  3. -rw-r--r--. 1 root root 5.6K Nov 24 00:12 config.json
  4. -rw-r--r--. 1 root root 649K Nov 24 00:15 f088349cceac173305d3e2c2e4790051799efe363842fdab5732f51f5b001fd8-json.log
  5. -rw-r--r--. 1 root root 977K Nov 24 00:15 f088349cceac173305d3e2c2e4790051799efe363842fdab5732f51f5b001fd8-json.log.1
  6. -rw-r--r--. 1 root root 977K Nov 24 00:15 f088349cceac173305d3e2c2e4790051799efe363842fdab5732f51f5b001fd8-json.log.2
  7. -rw-r--r--. 1 root root 1.3K Nov 24 00:12 hostconfig.json
  8. 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 OKD, 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 docker-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:

  1. Install the docker-novolume-plugin package:

    1. $ yum install docker-novolume-plugin

  2. Enable and start the docker-novolume-plugin service:

    1. $ systemctl enable docker-novolume-plugin
    2. $ systemctl start docker-novolume-plugin

  3. Edit the /etc/sysconfig/docker file and append the following to the OPTIONS list:

    1. --authorization-plugin=docker-novolume-plugin

  4. Restart the docker service:

    1. $ systemctl restart docker

After you enable this plug-in, containers with local volumes defined fail to start and show the following error message:

  1. runContainer: API error (500): authorization denied by plugin
  2. docker-novolume-plugin: volumes are not allowed

GlusterFS Software Requirements

To access GlusterFS volumes, the mount.glusterfs command must be available on all schedulable nodes. For RPM-based systems, the glusterfs-fuse package must be installed:

  1. # yum install glusterfs-fuse

If glusterfs-fuse is already installed on the nodes, ensure that the latest version is installed:

  1. # yum update glusterfs-fuse

Next steps

If you came here from Getting Started for Administrators, you can now continue there by choosing an installation method. Alternatively, you can install OKD using the standard cluster installation process by proceeding to configure your inventory file.