linux-metrics-exporter/README.adoc

= Linux Metrics Exporter for OpenShift Nodes =

== Components ==

. Container Image for SAR
. Container Image for PSACCT
. Container Image for Exporter

== Deployment ==

TBD

== Images ==

This set of images requires a valid entitlement for RHEL (and consequently
either a RHEL system to build on or a RHEL system to create an entitlement
secret from).

NOTE: The entitled system architecture needs to match the container host!

IMPORTANT: You do not have to build the images, they are already provided by the `is-readymade.yml` resource.

=== SAR ===

Sar image is based on `ubi-minimal` and includes just the `sysstat` package.

It expects a volume to be attached at `/var/log/sa`.

Entrypoint takes care of initialising the volume and rotating any old `sar` files out of the way.

It *requires* to be executed under `root` UID (can be rootless, but may affect your data).

It also *requires* access to host's network namespace if you want to measure network statistics.

=== PSACCT ===

Sar image is based on `ubi-minimal` and includes just the `psacct` package.

It expects a volume to be attached at `/var/account`.

Entrypoint takes care of initialising the volume and rotating any old `pacct` files out of the way.

In addition to *requiring* execution under a *real* `root` UID (i.e. *NOT* a rootless container), it also *requires* the `CAP_SYS_PACCT` capability (`--cap-add=SYS_PACCT`) and access to host's PID namespace (`--pid=host`).

=== Exporter ===

TBD

=== Building with Podman ===

If building the images using `podman` on an entitled host, no extra steps need
to be performed as host entitlements will automatically be imported into the
build container.

******
NOTE: When building for an architecture without the `ubi-minimal` image or on a
      host that can not be entitled (f.e. Fedora CoreOS), you can choose a
      different base image by using the `--from` option in `podman build`:
[subs=+quotes]
-------------------------------
$ *podman build --from=registry.fedoraproject.org/fedora-minimal:36 -f ./images/Containerfile-sysstat -t collector-sysstat:latest*
-------------------------------
******

=== Building in OpenShift ===

If building the images in OpenShift Container Platform, you must make sure an
entitlement secret and corresponding RHSM certificate secret are mounted inside
the build pod in order for packages to be found and installed.

The process is as follows.

.Verify access to host entitlement data.
[subs=+quotes]
-------------------------------
$ **ls -l /etc/pki/entitlement/*.pem /etc/rhsm/ca/*.pem**
-rw-r--r--. 1 root root   3272 Oct 31 06:09 /etc/pki/entitlement/_6028779042203586857_-key.pem
-rw-r--r--. 1 root root 149007 Oct 31 06:09 /etc/pki/entitlement/_6028779042203586857_.pem
-rw-r--r--. 1 root root   2305 Sep  2  2021 /etc/rhsm/ca/redhat-entitlement-authority.pem
-rw-r--r--. 1 root root   7411 Sep  2  2021 /etc/rhsm/ca/redhat-uep.pem
-------------------------------

.Create corresponding secrets.
[subs=+quotes]
-------------------------------
$ *oc create secret generic etc-pki-entitlement \*
    *--from-file=/etc/pki/entitlement/_6028779042203586857_-key.pem \*
    *--from-file=/etc/pki/entitlement/_6028779042203586857_.pem*
secret/etc-pki-entitlement created

$ *oc create secret generic rhsm-ca \*
    *--from-file=/etc/rhsm/ca/redhat-entitlement-authority.pem \*
    *--from-file=/etc/rhsm/ca/redhat-uep.pem*
secret/rhsm-ca created
-------------------------------

.Make sure the BuildConfig mounts those secrets.
[subs=+quotes]
-------------------------------
apiVersion: build.openshift.io/v1
kind: BuildConfig
...
  strategy:
    type: Docker
    dockerStrategy:
      dockerfilePath: Containerfile-psacct
      from:
        kind: ImageStreamTag
        name: ubi-minimal:latest
      **volumes:
        - source:
            type: Secret
            secret:
              secretName: etc-pki-entitlement
          name: etc-pki-entitlement
          mounts:
            - destinationPath: /etc/pki/entitlement
        - source:
            type: Secret
            secret:
              secretName: rhsm-ca
          name: rhsm-ca
          mounts:
            - destinationPath: /etc/rhsm/ca**
-------------------------------

`Containerfile` instructions are written such that they should work without
modification regardless of whether the build is running in `podman` on an
entitled host or inside a correctly configured OpenShift builder pod.

NOTE: Key thing in `Containerfile` steps is to remove `/etc/rhsm-host` at some
      point unless `/etc/pki/entitlement-host` contains something (such as for
      example, valid entitlemets). Both are symlinks to `/run/secrets`.