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

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

  • Creating machine configs that are passed to running OpenShift Container Platform nodes via the Machine Config Operator.

  • Creating an Ignition config that is passed to coreos-installer when installing bare-metal nodes.

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

Creating machine configs with Butane

Machine configs are used to configure control plane and worker machines by instructing machines how to create users and file systems, set up the network, install systemd units, and more.

Because modifying machine configs can be difficult, you can use Butane configs to create machine configs for you, thereby making node configuration much easier.

About Butane

Butane is a command-line utility that OpenShift Container Platform uses to provide convenient, short-hand syntax for writing machine configs, as well as for performing additional validation of machine configs. The format of the Butane config file that Butane accepts is defined in the OpenShift Butane config spec.

Installing Butane

You can install the Butane tool (butane) to create OpenShift Container Platform machine configs from a command-line interface. You can install butane on Linux, Windows, or macOS by downloading the corresponding binary file.

Butane releases are backwards-compatible with older releases and with the Fedora CoreOS Config Transpiler (FCCT).

  1. Navigate to the Butane image download page at https://mirror.openshift.com/pub/openshift-v4/clients/butane/.

  2. Get the butane binary:

    1. For the newest version of Butane, save the latest butane image to your current directory:

      $ curl https://mirror.openshift.com/pub/openshift-v4/clients/butane/latest/butane --output butane
    2. Optional: For a specific type of architecture you are installing Butane on, such as aarch64 or ppc64le, indicate the appropriate URL. For example:

      $ curl https://mirror.openshift.com/pub/openshift-v4/clients/butane/latest/butane-aarch64 --output butane
  3. Make the downloaded binary file executable:

    $ chmod +x butane
  4. Move the butane binary file to a directory on your PATH.

    To check your PATH, open a terminal and execute the following command:

    $ echo $PATH
Verification steps
  • You can now use the Butane tool by running the butane command:

    $ butane <butane_file>

Creating a MachineConfig object by using Butane

You can use Butane to produce a MachineConfig object so that you can configure worker or control plane nodes at installation time or via the Machine Config Operator.

  • You have installed the butane utility.

  1. Create a Butane config file. The following example creates a file named 99-worker-custom.bu that configures the system console to show kernel debug messages and specifies custom settings for the chrony time service:

    variant: openshift
    version: 4.11.0
      name: 99-worker-custom
        machineconfiguration.openshift.io/role: worker
        - loglevel=7
        - path: /etc/chrony.conf
          mode: 0644
          overwrite: true
            inline: |
              pool 0.rhel.pool.ntp.org iburst
              driftfile /var/lib/chrony/drift
              makestep 1.0 3
              logdir /var/log/chrony

    The 99-worker-custom.bu file is set to create a machine config for worker nodes. To deploy on control plane 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.

  2. Create a MachineConfig object by giving Butane the file that you created in the previous step:

    $ butane 99-worker-custom.bu -o ./99-worker-custom.yaml

    A MachineConfig object YAML file is created for you to finish configuring your machines.

  3. Save the Butane config in case you need to update the MachineConfig object in the future.

  4. If the cluster is not running yet, generate manifest files and add the MachineConfig object YAML file to the openshift directory. If the cluster is already running, apply the file as follows:

    $ oc create -f 99-worker-custom.yaml

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.

Disabling SELinux on RHCOS is not supported.

  • 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 OpenShift Container Platform installation.

  1. Change to the directory that contains the installation program and 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 control plane 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 control plane nodes:

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

    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 OpenShift Container Platform 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 OpenShift Container Platform 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:

  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 required 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_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:

    $ sudo systemctl enable kmods-via-containers@simple-kmod.service --now
    1. 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 ri