Uploading rules to RHOBS is normally done through obsctl-reloader
.
The obsctl-reloader-rules-checker
tool is a command line tool checking that the PrometheusRule
objects fed to obsctl-reloader
can safely be consumed.
You can retrieve this tool binary from GitHub release section.
The binary is delivered for all major platforms (Linux, Windows, Mac OS) and for all major architectures.
The obsctl-reloader-rules-checker
tool relies on the following command line tools:
promtool
: this tool is at the heart ofobsctl-reloader-rules-checker
.
It is used to check that input files really storePrometheusRule
objects; the tool is also used to run the rules unittests.yamllint
: this tool is a linter (so a nice to have) used both on the rules and the unittests.
It only need to be present if you plan on using the-y
flag ofobsctl-reloader-rules-checker
.pint
: this tool is an other linter which is aimed a tacklingPrometheusRule
objects.
Again installing it is optional as its use is conditioned by the-p
flag.
You have to make sure that those tool are present on your computer when using the obsctl-reloader-rules-checker
tool binary.
Take a look at the following files to know the versions of those tools to use:
- For
promtool
&pint
:hack/install-go-tools.sh
- For
yamllint
:hack/install-yamllint-tool.sh
A docker image wrapping the tool is delivered on quay:
quay.io/rhobs/obsctl-reloader-rules-checker:latest
This is actually the preferred way of using the tool as the image contains the promtool
, pint
and yamllint
dependencies.
The only prerequisite before using the docker image is to have a container engine (docker
, podman
) installed on your computer.
This image can also be used on GitHub and GitLab continuous integrations to assess the correctness of your pull requests and merge requests on rules repositories. More on that later.
The obsctl-reloader-rules-checker
file at the root of the repository is a wrapper of the tool binary.
It accepts the exact same arguments than the tool binary and make sure that:
- The wrapped tool binary is built
promtool
,pint
andyamllint
are installed
This allows using the tool out of the box without understanding how to build or locally work on it (see local development). However this script is not standalone and you have to clone the repository to use it.
This tool is used to assess the validity of rule files.
Imagine you have a repository containing rules definitions structured as follows:
my-tenant-rhobs-rules-clone/
├── .git/
├── .yamllint
├── Makefile
├── rules/
│ ├── rule1.yaml
│ ├── rule2.yaml
│ └── rule3.yaml
├── tests/
│ ├── test1.yaml
│ └── test2.yaml
└── template.yaml
In this example the repository contains the rules for the tenant named my-tenant
.
As this tenant may differ a bit between prod and staging, we are gonna call the tool in such a way that it will generate a template; the template gather all the rules and allows to define the exact tenant through the TENANT
parameter when instantiated.
Let's assume that you are at the root of the clone; you will have to call the tool as follows on Linux/Mac:
- When using the tool binary:
obsctl-reloader-rules-checker -t my-tenant -d rules -g template.yaml -T tests -y
- When using the tool docker image:
(replace
docker run -v "$(pwd):/work" -t quay.io/rhobs/obsctl-reloader-rules-checker:latest -t my-tenant -d rules -g template.yaml -T tests -y
docker
container engine bypodman
if needed)
Remark that the flags are the same whether you are using the tool binary or the tool docker image; indeed, as a reminder, the tool docker image is just a wrapper of the tool binary with all the prerequisites needed by it.
Now lets explain the flags used in above example:
- The
-t
flag is used to specify the rules tenant.
The tenant is a string used by RHOBS to partition / shard data.
As previously said, we are not yet sure of the tenant on which the rules will be uploaded and that's why we are generating a template.
The value passed here is just used as a default value for the templateTENANT
parameter. - The
-d
flag locates the directory in which the rules are located. - The
-g
flag tells to generate a template and gives the path to the file to generate. - The
-T
flag gives the path to the unittests directory. - The
-y
flag tells to runyamllint
on all the rule files and on all the unittests.
Remark that the.yamllint
at the root of the clone repository is telling how those YAML files should be formatted. This file is optional when using the docker image; indeed the tool docker image is bundling a defaultyamllint
config file defined there.
Use the -h
or --help
flag of the tool to know more about the possible usages.
As previously explained, the purpose of this tool is to check the validity of the given rule files.
Once again, the -h
/ --help
flag is pretty explicit about those checks. Here is a brief list of those checks:
- Check that all rule files store
PrometheusRule
objects. - Check that objects have all a different name.
- Check that the
spec
part of those objects are valid againstpromtool check rules
. - Check that the objects names and
tenant
label are properly set. - Run all the unittests with
promtool test rules
. - Run
yamllint
on the rule files and the unittests. - Run
pint
on thespec
part of thePrometheusRule
objects.
Prerequisites:
- You have to checkout the code.
- The following tools must be present on your computer:
make
go
(version 1.20 or later)
To build the binary you just have to run:
make build
The binary will be delivered in the bin
folder. promtool
& pint
are also built and installed when running that command.
Prerequisites:
- You have to checkout the code.
- The following tools must be present on your computer:
make
- a container engine: either
docker
orpodman
To build the binary you just have to run:
make docker-build
The docker image will be tagged as follows is your local registry:
obsctl-reloader-rules-checker:latest
Local development is not just about building the code. It is also about making sure that your changes will pass all the checks performed by the continuous integration (CI) jobs.
Prerequisites:
- You have to checkout the code.
- The following tools must be present on your computer:
make
go
(version 1.20 or later)- a container engine: either
docker
orpodman
yamllint
(eventually runmake yamllint-tool
to install the tool)golangci-lint
As you can see you have to install some linters on top of "building the code" prerequisites.
Rapidly checking that your change is okay. Just run:
make
Checking that your change will really pass the CI. Just run:
make pr-checks
The difference between the 2 commands are that:
make
builds the tool binary whilemake pr-checks
build the tool docker image.
Building the code outside a docker image is faster asgo
can benefit some caching when building locally.make
will format the code and updatego.mod
andgo.sum
files if needed; you will need to commit those files alongside with your change.
make pr-checks
also updates those files but fails if the differs from what is committed.
Cleaning the repository clone. Just run:
make clean
This will remove the bin
folder in which the tool binary has been delivered but also the .bingo
folder which was used to build promtool
& pint
.
You have to perform the following checks prior sending your code in a PR:
- Run
make pr-checks
: this will build the code and make sure it passes all linters.
More details on that in the previous section. - Make sure your commit messages follow the Conventional Commits specification as this will be checked by the CI.
You can check that locally by installing a hook on your repository clone; see below.
Installing a hook to check commit messages:
- Install
pre-commit
tool if not already done.
This is platform specific, refer to the tool documentation for instructions. - Run the following command:
pre-commit install --hook-type commit-msg
The hook is only installed on your repository clone. You my want to remove it when performing some advanced operations, see below instructions.
Uninstalling the hook checking commit messages:
- Run the following command:
pre-commit uninstall --hook-type commit-msg
- Or just:
rm .git/hooks/commit-msg
Just tag your local clone and push the tag without going through a pull request:
git tag 1.0.0
git push [email protected]:rhobs/obsctl-reloader-rules-checker.git main --tags
This operation is reserved to repository maintainers. Also:
- Replace
1.0.0
by your version. - Make sure you pulled the latests changes (i.e. commits) from the central repository