Although directly making changes to OKD nodes is discouraged, there are times when it is necessary to implement a required low-level security, networking, or performance feature. Direct changes to OKD nodes can be done by:

  • Creating MachineConfigs that are included in manifest files to start up a cluster during openshift-install.

  • Creating MachineConfigs that are passed to running OKD nodes via the Machine Config Operator.

The following sections describe features that you might want to configure on your nodes in this way.

Adding day-1 kernel arguments

Although it is often preferable to modify kernel arguments as a day-2 activity, you might want to add kernel arguments to all master or worker nodes during initial cluster installation. Here are some reasons you might want to add kernel arguments during cluster installation so they take effect before the systems first boot up:

  • You want to disable a feature, such as SELinux, so it has no impact on the systems when they first come up.

  • You need to do some low-level network configuration before the systems start.

To add kernel arguments to master or worker nodes, you can create a MachineConfig object and inject that object into the set of manifest files used by Ignition during cluster setup.

For a listing of arguments you can pass to a RHEL 8 kernel at boot time, see Kernel.org kernel parameters. It is best to only add kernel arguments with this procedure if they are needed to complete the initial OKD installation.

Procedure
  1. Generate the Kubernetes manifests for the cluster:

    $ ./openshift-install create manifests --dir=<installation_directory>
  2. Decide if you want to add kernel arguments to worker or master nodes.

  3. In the openshift directory, create a file (for example, 99-openshift-machineconfig-master-kargs.yaml) to define a MachineConfig object to add the kernel settings. This example adds a loglevel=7 kernel argument to master nodes:

    $ cat << EOF > 99-openshift-machineconfig-master-kargs.yaml
    apiVersion: machineconfiguration.openshift.io/v1
    kind: MachineConfig
    metadata:
      labels:
        machineconfiguration.openshift.io/role: master
      name: 99-openshift-machineconfig-master-kargs
    spec:
      kernelArguments:
        - 'loglevel=7'
    EOF

    You can change master to worker to add kernel arguments to worker nodes instead. Create a separate YAML file to add to both master and worker nodes.

You can now continue on to create the cluster.

Adding kernel modules to nodes

For most common hardware, the Linux kernel includes the device driver modules needed to use that hardware when the computer starts up. For some hardware, however, modules are not available in Linux. Therefore, you must find a way to provide those modules to each host computer. This procedure describes how to do that for nodes in an OKD cluster.

When a kernel module is first deployed by following these instructions, the module is made available for the current kernel. If a new kernel is installed, the kmods-via-containers software will rebuild and deploy the module so a compatible version of that module is available with the new kernel.

The way that this feature is able to keep the module up to date on each node is by:

  • Adding a systemd service to each node that starts at boot time to detect if a new kernel has been installed and

  • If a new kernel is detected, the service rebuilds the module and installs it to the kernel

For information on the software needed for this procedure, see the kmods-via-containers github site.

A few important issues to keep in mind:

  • This procedure is Technology Preview.

  • Software tools and examples are not yet available in official RPM form and can only be obtained for now from unofficial github.com sites noted in the procedure.

  • Third-party kernel modules you might add through these procedures are not supported by Red Hat.

  • In this procedure, the software needed to build your kernel modules is deployed in a RHEL 8 container. Keep in mind that modules are rebuilt automatically on each node when that node gets a new kernel. For that reason, each node needs access to a yum repository that contains the kernel and related packages needed to rebuild the module. That content is best provided with a valid RHEL subscription.

Building and testing the kernel module container

Before deploying kernel modules to your OKD cluster, you can test the process on a separate RHEL system. Gather the kernel module’s source code, the KVC framework, and the kmod-via-containers software. Then build and test the module. To do that on a RHEL 8 system, do the following:

Procedure
  1. Register a RHEL 8 system:

    # subscription-manager register
  2. Attach a subscription to the RHEL 8 system:

    # subscription-manager attach --auto
  3. Install software that is requried to build the software and container:

    # yum install podman make git -y
  4. Clone the kmod-via-containers repository:

    1. Create a folder for the repository:

      $ mkdir kmods; cd kmods
    2. Clone the repository:

      $ git clone https://github.com/kmods-via-containers/kmods-via-containers
  5. Install a KVC framework instance on your RHEL 8 build host to test the module. This adds a kmods-via-container systemd service and loads it:

    1. Change to the kmod-via-containers directory:

      $ cd kmods-via-containers/
    2. Install the KVC framework instance:

      $ sudo make install
    3. Reload the systemd manager configuration:

      $ sudo systemctl daemon-reload
  6. Get the kernel module source code. The source code might be used to build a third-party module that you do not have control over, but is supplied by others. You will need content similar to the content shown in the kvc-simple-kmod example that can be cloned to your system as follows:

    $ cd .. ; git clone https://github.com/kmods-via-containers/kvc-simple-kmod
  7. Edit the configuration file, simple-kmod.conf file, in this example, and change the name of the Dockerfile to Dockerfile.rhel:

    1. Change to the kvc-simple-kmod directory:

      $ cd kvc-simple-kmod
    2. Rename the Dockerfile:

      $ cat simple-kmod.conf
      Example Dockerfile
      KMOD_CONTAINER_BUILD_CONTEXT="https://github.com/kmods-via-containers/kvc-simple-kmod.git"
      KMOD_CONTAINER_BUILD_FILE=Dockerfile.rhel
      KMOD_SOFTWARE_VERSION=dd1a7d4
      KMOD_NAMES="simple-kmod simple-procfs-kmod"
  8. Create an instance of kmods-via-containers@.service for your kernel module, simple-kmod in this example:

    $ sudo make install
  9. Enable the kmods-via-containers@.service instance:

    $ sudo kmods-via-containers build simple-kmod $(uname -r)
  10. Enable and start the systemd service:

    1. Enable the service:

      $ sudo systemctl enable kmods-via-containers@simple-kmod.service
    2. Start the service:

      $ sudo systemctl start kmods-via-containers@simple-kmod.service
    3. Review the service status:

      $ sudo systemctl status kmods-via-containers@simple-kmod.service
      Example output
      ● kmods-via-containers@simple-kmod.service - Kmods Via Containers - simple-kmod
         Loaded: loaded (/etc/systemd/system/kmods-via-containers@.service;
                enabled; vendor preset: disabled)
         Active: active (exited) since Sun 2020-01-12 23:49:49 EST; 5s ago...
  11. To confirm that the kernel modules are loaded, use the lsmod command to list the modules:

    $ lsmod | grep simple_
    Example output
    simple_procfs_kmod     16384  0
    simple_kmod            16384  0
  12. Optional. Use other methods to check that the simple-kmod example is working:

    • Look for a "Hello world" message in the kernel ring buffer with dmesg:

      $ dmesg | grep 'Hello world'
      Example output
      [ 6420.761332] Hello world from simple_kmod.
    • Check the value of simple-procfs-kmod in /proc:

      $ sudo cat /proc/simple-procfs-kmod
      Example output
      simple-procfs-kmod number = 0
    • Run the spkut command to get more information from the module:

      $ sudo spkut 44
      Example output
      KVC: wrapper simple-kmod for 4.18.0-147.3.1.el8_1.x86_64
      Running userspace wrapper using the kernel module container...
      + podman run -i --rm --privileged
         simple-kmod-dd1a7d4:4.18.0-147.3.1.el8_1.x86_64 spkut 44
      simple-procfs-kmod number = 0
      simple-procfs-kmod number = 44

Going forward, when the system boots this service will check if a new kernel is running. If there is a new kernel, the service builds a new version of the kernel module and then loads it. If the module is already built, it will just load it.

Provisioning a kernel module to OKD

Depending on whether or not you must have the kernel module in place when OKD cluster first boots, you can set up the kernel modules to be deployed in one of two ways:

  • Provision kernel modules at cluster install time (day-1): You can create the content as a MachineConfig and provide it to openshift-install by including it with a set of manifest files.

  • Provision kernel modules via Machine Config Operator (day-2): If you can wait until the cluster is up and running to add your kernel module, you can deploy the kernel module software via the Machine Config Operator (MCO).

In either case, each node needs to be able to get the kernel packages and related software packages at the time that a new kernel is detected. There are a few ways you can set up each node to be able to obtain that content.

  • Provide RHEL entitlements to each node.

  • Get RHEL entitlements from an existing RHEL host, from the /etc/pki/entitlement directory and copy them to the same location as the other files you provide when you build your Ignition config.

  • Inside the Dockerfile, add pointers to a yum repository containing the kernel and other packages. This must include new kernel packages as they are needed to match newly installed kernels.

Provision kernel modules via a MachineConfig

By packaging kernel module software with a MachineConfig you can deliver that software to worker or master nodes at installation time or via the Machine Config Operator.

First create a base Ignition config that you would like to use. At installation time, the Ignition config will contain the ssh public key to add to the authorized_keys file for the core user on the cluster. To add the MachineConfig later via the MCO instead, the ssh public key is not required. For both type, the example simple-kmod service creates a systemd unit file, which requires a kmods-via-containers@simple-kmod.service.

The systemd unit is a workaround for an upstream bug and makes sure that the kmods-via-containers@simple-kmod.service gets started on boot:

  1. Register a RHEL 8 system:

    # subscription-manager register
  2. Attach a subscription to the RHEL 8 system:

    # subscription-manager attach --auto
  3. Install software needed to build the software:

    # yum install podman make git -y
  4. Create an Ignition config file that creates a systemd unit file:

    1. Create a directory to host the Ignition config file:

      $ mkdir kmods; cd kmods
    2. Create the Ignition config file that creates a systemd unit file:

      $ cat <<EOF > ./baseconfig.ign
      {
        "ignition": { "version": "3.1.0" },
        "passwd": {
          "users": [
            {
              "name": "core",
              "groups": ["sudo"],
              "sshAuthorizedKeys": [
                "ssh-rsa AAAA"
              ]
            }
          ]
        },
        "systemd": {
          "units": [{
            "name": "require-kvc-simple-kmod.service",
            "enabled": true,
            "contents": "[Unit]\nRequires=kmods-via-containers@simple-kmod.service\n[Service]\nType=oneshot\nExecStart=/usr/bin/true\n\n[Install]\nWantedBy=multi-user.target"
          }]
        }
      }
      EOF

      You must add your public SSH key to the baseconfig.ign file to use the file during openshift-install. The public SSH key is not needed if you create the MachineConfig via the MCO.

  5. Create a base MCO YAML snippet that uses the following configuration:

    $ cat <<EOF > mc-base.yaml
    apiVersion: machineconfiguration.openshift.io/v1
    kind: MachineConfig
    metadata:
      labels:
        machineconfiguration.openshift.io/role: worker
      name: 10-kvc-simple-kmod
    spec:
      config:
    EOF

    The mc-base.yaml is set to deploy the kernel module on worker nodes. To deploy on master nodes, change the role from worker to master. To do both, you could repeat the whole procedure using different file names for the two types of deployments.

  6. Get the kmods-via-containers software:

    1. Clone the kmods-via-containers repository:

      $ git clone https://github.com/kmods-via-containers/kmods-via-containers
    2. Clone the kvc-simple-kmod repository:

      $ git clone https://github.com/kmods-via-containers/kvc-simple-kmod
  7. Get your module software. In this example, kvc-simple-kmod is used:

  8. Create a fakeroot directory and populate it with files that you want to deliver via Ignition, using the repositories cloned earlier:

    1. Create the directory:

      $ FAKEROOT=$(mktemp -d)
    2. Change to the kmod-via-containers directory:

      $ cd kmods-via-containers
    3. Install the KVC framework instance:

      $ make install DESTDIR=${FAKEROOT}/usr/local CONFDIR=${FAKEROOT}/etc/
    4. Change to the kvc-simple-kmod directory:

      $ cd ../kvc-simple-kmod
    5. Create the instance:

      $ make install DESTDIR=${FAKEROOT}/usr/local CONFDIR=${FAKEROOT}/etc/
  9. Get a tool called filetranspiler and dependent software:

    $ cd .. ; sudo yum install -y python3
    git clone https://github.com/ashcrow/filetranspiler.git
  10. Generate a final MachineConfig YAML (mc.yaml) and have it include the base Ignition config, base MachineConfig, and the fakeroot directory with files you would like to deliver:

    $ ./filetranspiler/filetranspile -i ./baseconfig.ign \
         -f ${FAKEROOT} --format=yaml --dereference-symlinks \
         | sed 's/^/     /' | (cat mc-base.yaml -) > 99-simple-kmod.yaml
  11. If the cluster is not up yet, generate manifest files and add this file to the openshift directory. If the cluster is already running, apply the file as follows:

    $ oc create -f 99-simple-kmod.yaml

    Your nodes will start the kmods-via-containers@simple-kmod.service service and the kernel modules will be loaded.

  12. To confirm that the kernel modules are loaded, you can log in to a node (using oc debug node/<openshift-node>, then chroot /host). To list the modules, use the lsmod command:

    $ lsmod | grep simple_
    Example output
    simple_procfs_kmod     16384  0
    simple_kmod            16384  0

Encrypting disks during installation

During OKD installation, you can enable disk encryption on all master and worker nodes. This feature:

  • Is available for installer-provisioned infrastructure and user provisioned infrastructure deployments

  • Is supported on Red Hat Enterprise Linux CoreOS (RHCOS) systems only

  • Sets up disk encryption during the manifest installation phase so all data written to disk, from first boot forward, is encrypted

  • Encrypts data on the root filesystem only (/dev/mapper/coreos-luks-root on /)

  • Requires no user intervention for providing passphrases

  • Uses AES-256-CBC encryption

  • Should be enabled for your cluster to support FIPS.

There are two different supported encryption modes:

  • TPM v2: This is the preferred mode. TPM v2 stores passphrases in a secure cryptoprocessor. To implement TPM v2 disk encryption, create an Ignition config file as described below.

  • Tang: To use Tang to encrypt your cluster, you need to use a Tang server. Clevis implements decryption on the client side. Tang encryption mode is only supported for bare metal installs.

Follow one of the two procedures to enable disk encryption for the nodes in your cluster.

Enabling TPM v2 disk encryption

Use this procedure to enable TPM v2 mode disk encryption during OKD deployment.

Procedure
  1. Check to see if TPM v2 encryption needs to be enabled in the BIOS on each node. This is required on most Dell systems. Check the manual for your computer.

  2. Generate the Kubernetes manifests for the cluster:

    $ ./openshift-install create manifests --dir=<installation_directory>
  3. In the openshift directory, create master or worker files to encrypt disks for those nodes.

    • To create a worker file, run the following command:

      $ cat << EOF > ./99-openshift-worker-tpmv2-encryption.yaml
      apiVersion: machineconfiguration.openshift.io/v1
      kind: MachineConfig
      metadata:
        name: worker-tpm
        labels:
          machineconfiguration.openshift.io/role: worker
      spec:
        config:
          ignition:
            version: 3.1.0
          storage:
            files:
            - contents:
                source: data:text/plain;base64,e30K
              mode: 420
              overwrite: true
              path: /etc/clevis.json
      EOF
    • To create a master file, run the following command:

      $ cat << EOF > ./99-openshift-master-tpmv2-encryption.yaml
      apiVersion: machineconfiguration.openshift.io/v1
      kind: MachineConfig
      metadata:
        name: master-tpm
        labels:
          machineconfiguration.openshift.io/role: master
      spec:
        config:
          ignition:
            version: 3.1.0
          storage:
            files:
            - contents:
                source: data:text/plain;base64,e30K
              mode: 420
              overwrite: true
              path: /etc/clevis.json
      EOF
  4. Make a backup copy of the YAML file. You should do this because the file will be deleted when you create the cluster.

  5. Continue with the remainder of the OKD deployment.

Enabling Tang disk encryption

Use this procedure to enable Tang mode disk encryption during OKD deployment.

Procedure
  1. Access a Red Hat Enterprise Linux server from which you can configure the encryption settings and run openshift-install to install a cluster and oc to work with it.

  2. Set up or access an existing Tang server. See Network-bound disk encryption for instructions. See Securing Automated Decryption New Cryptography and Techniques for a presentation on Tang.

  3. Add kernel arguments to configure networking when you do the Fedora CoreOS (FCOS) installations for your cluster. For example, to configure DHCP networking, identify ip=dhcp, or set static networking when you add parameters to the kernel command line. For both DHCP and static networking, you also must provide the rd.neednet=1 kernel argument.

Skipping this step causes the second boot to fail.

  1. Install the clevis package, if it is not already installed:

$ sudo yum install clevis -y
  1. Generate a thumbprint from the Tang server.

    1. In the following command, replace the value of url with the Tang server URL:

      $ echo nifty random wordwords \
           | clevis-encrypt-tang \
             '{"url":"https://tang.example.org"}'
      Example output
      The advertisement contains the following signing keys:
      
      PLjNyRdGw03zlRoGjQYMahSZGu9
    2. When the Do you wish to trust these keys? [ynYN] prompt displays, type Y, and the thumbprint is displayed:

      Example output
      eyJhbmc3SlRyMXpPenc3ajhEQ01tZVJiTi1oM...
  2. Create a Base64 encoded file, replacing the URL of the Tang server (url) and thumbprint (thp) you just generated:

    $ (cat <<EOM
    {
     "url": "https://tang.example.com",
     "thp": "PLjNyRdGw03zlRoGjQYMahSZGu9"
    }
    EOM
    ) | base64 -w0
    Example output
    ewogInVybCI6ICJodHRwczovL3RhbmcuZXhhbXBsZS5jb20iLAogInRocCI6ICJaUk1leTFjR3cwN3psVExHYlhuUWFoUzBHdTAiCn0K
  3. In the openshift directory, create master or worker files to encrypt disks for those nodes.

    • For worker nodes, use the following command:

      $ cat << EOF > ./99-openshift-worker-tang-encryption.yaml
      apiVersion: machineconfiguration.openshift.io/v1
      kind: MachineConfig
      metadata:
        name: worker-tang
        labels:
          machineconfiguration.openshift.io/role: worker
      spec:
        config:
          ignition:
            version: 3.1.0
          storage:
            files:
            - contents:
                source: data:text/plain;base64,e30K
                source: data:text/plain;base64,ewogInVybCI6ICJodHRwczovL3RhbmcuZXhhbXBsZS5jb20iLAogInRocCI6ICJaUk1leTFjR3cwN3psVExHYlhuUWFoUzBHdTAiCn0K
              mode: 420
              overwrite: true
              path: /etc/clevis.json
      EOF
    • For master nodes, use the following command:

      $ cat << EOF > ./99-openshift-master-tang-encryption.yaml
      apiVersion: machineconfiguration.openshift.io/v1
      kind: MachineConfig
      metadata:
        name: master-tang
        labels:
          machineconfiguration.openshift.io/role: master
      spec:
        config:
          ignition:
            version: 3.1.0
          storage:
            files:
            - contents:
                source: data:text/plain;base64,e30K
                source: data:text/plain;base64,ewogInVybCI6ICJodHRwczovL3RhbmcuZXhhbXBsZS5jb20iLAogInRocCI6ICJaUk1leTFjR3cwN3psVExHYlhuUWFoUzBHdTAiCn0K
              mode: 420
              overwrite: true
              path: /etc/clevis.json
      EOF
  4. Add the rd.neednet=1 kernel argument, as shown in the following example:

      apiVersion: machineconfiguration.openshift.io/v1
      kind: MachineConfig
      metadata:
        name: <node_type>-tang (1)
      spec:
        config:
          ignition:
            version: 3.1.0
        kernelArguments:
          - rd.neednet=1 (2)
    1 Use the name you defined in the previous examples based on the type of node you are configuring, for example: name: worker-tang.
    2 Required.
  5. Continue with the remainder of the OKD deployment.

Configuring chrony time service

You can set the time server and related settings used by the chrony time service (chronyd) by modifying the contents of the chrony.conf file and passing those contents to your nodes as a MachineConfig.

Procedure
  1. Create the contents of the chrony.conf file and encode it as base64. For example:

    $ cat << EOF | base64
        pool 0.rhel.pool.ntp.org iburst (1)
        driftfile /var/lib/chrony/drift
        makestep 1.0 3
        rtcsync
        logdir /var/log/chrony
        EOF
    1 Specify any valid, reachable time source. Alternately, you can specify any of the following NTP servers: 1.rhel.pool.ntp.org, 2.rhel.pool.ntp.org, or 3.rhel.pool.ntp.org.
    Example output
    ICAgIHNlcnZlciBjbG9jay5yZWRoYXQuY29tIGlidXJzdAogICAgZHJpZnRmaWxlIC92YXIvbGli
    L2Nocm9ueS9kcmlmdAogICAgbWFrZXN0ZXAgMS4wIDMKICAgIHJ0Y3N5bmMKICAgIGxvZ2RpciAv
    dmFyL2xvZy9jaHJvbnkK
  2. Create the MachineConfig file, replacing the base64 string with the one you just created yourself. This example adds the file to master nodes. You can change it to worker or make an additional MachineConfig for the worker role:

    $ cat << EOF > ./masters-chrony-configuration.yaml
    apiVersion: machineconfiguration.openshift.io/v1
    kind: MachineConfig
    metadata:
      labels:
        machineconfiguration.openshift.io/role: master
      name: masters-chrony-configuration
    spec:
      config:
        ignition:
          config: {}
          security:
            tls: {}
          timeouts: {}
          version: 3.1.0
        networkd: {}
        passwd: {}
        storage:
          files:
          - contents:
              source: data:text/plain;charset=utf-8;base64,ICAgIHNlcnZlciBjbG9jay5yZWRoYXQuY29tIGlidXJzdAogICAgZHJpZnRmaWxlIC92YXIvbGliL2Nocm9ueS9kcmlmdAogICAgbWFrZXN0ZXAgMS4wIDMKICAgIHJ0Y3N5bmMKICAgIGxvZ2RpciAvdmFyL2xvZy9jaHJvbnkK
            mode: 420
            overwrite: true
            path: /etc/chrony.conf
      osImageURL: ""
    EOF
  3. Make a backup copy of the configuration file.

  4. Apply the configuration in one of two ways:

    • If the cluster is not up yet, generate manifest files, add this file to the openshift directory, and then continue to create the cluster.

    • If the cluster is already running, apply the file as follows:

       $ oc apply -f ./masters-chrony-configuration.yaml