linux-metrics-exporter/README.adoc

= Linux Metrics Exporter for OpenShift Nodes =

== Components ==

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

== How It All Works ==

Very simple: two sidecar containers, `collector-sysstat` and
`collector-psacct`, produce data on a shared ephemeral volume, and the third
container, `metrics-exporter`, consumes the data and exposes it on the
`/metrics` endpoint where Prometheus can pick them up.

The specific thing about how the entire composition works is that care has been
taken, especially with `psacct`, that accounting files are regularly moved out
of the way in order to keep the disk space utilisation as low as possible.

== 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).

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

=== SAR ===

The _system activity reporting_ 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 `saXX` files and rotating any old files out of the way.

It *requires* to be executed under `root` UID (can be rootless, but that may affect your data depending on host and container configuration).

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

=== PSACCT ===

The _process accounting_ 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 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.

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

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