Quickstart Insights Development¶
Table of Contents
Insights-core is the framework upon which Red Hat Insights rules are built and delivered. The basic purpose is to apply “rules” to a set of files collected from a system at a given point in time.
Insights-core rule “plugins” are written in Python. The rules follow a “MapReduce” approach, dividing the logic between “mapping” and “reducing” methods. This is a convenient approach where a rule’s logic takes place in two steps. First, there is a “gathering of facts” (the map phase) followed by logic being applied to the facts (the reduce phase).
Prerequisites¶
All Plugin code is written in Python and all Insights libraries and framework code necessary for development and execution are stored in Git repositories. Before you begin make sure you have the following installed:
- Python 3 (recommended Python 3.6)
- Git
- Python Virtualenv
- Python PIP
Further requirements can be found in the README.rst file associated with the insights-core project.
Hint
You might also need to install gcc
to be able to build some python modules,
unzip
to be able to run pytest on the insights-core
repo,
and pandoc
to build Insights Core documentation.
Insights Development Setup¶
Insights Core Development¶
Clone the project:
[userone@hostone project_dir]$ git clone git@github.com:RedHatInsights/insights-core.git
Or, alternatively, using HTTPS:
[userone@hostone project_dir]$ git clone https://github.com/RedHatInsights/insights-core.git
Initialize a virtualenv (depending on your python installation you may need to specify a specific version of python using the -p option and the name or path of the python you want to use. For example -p python3 or -p /usr/bin/python3.6):
[userone@hostone project_dir]$ cd insights-core
[userone@hostone project_dir/insights-core]$ virtualenv -p python3.6 .
Verify that you have the desired version of python by enabling the virtualenv:
[userone@hostone project_dir/insights-core]$ source bin/activate
(insights-core)[userone@hostone project_dir/insights-core]$ python --version
You can also ensure that your virtualenv is set by checking which python is being used:
(insights-core)[userone@hostone project_dir/insights-core]$ which python
project_dir/insights-core/bin/python
Depending upon your environment, your prompt may also indicate you are using a virtualenv. In the example above it is indicated by (insights-core).
Next install the insights-core project and its dependencies into your virtualenv:
(insights-core)[userone@hostone project_dir/insights-core]$ bin/pip install -e .[develop]
Now check to make sure your environment is setup correctly by invoking the insights-run command. You should see the help information for insights-run:
(insights-core)[userone@hostone project_dir/insights-core]$ insights-run --help
When you are finished working on this project you can deactivate your virtualenv using the deactivate command.
Tip
If you don’t plan on digging into the Insights Core code you can skip cloning the insights-core
repo and follow these steps:
- Create a virtualenv in your
myrules
directory. - Activate and check your virtualenv as specified above
- Install
insights-core
using the command pip install insights-core - Check insights installation with insights-run --help
If you use this method make sure you periodically update insights core in your virtualenv with the command pip install --upgrade insights-core.
Insights Client Development¶
Clone the project:
[userone@hostone project_dir]$ git clone git@github.com:RedHatInsights/insights-core.git
Initialize a virtualenv with the --system-site-packages
flag:
[userone@hostone project_dir/insights-core]$ python3.6 -m venv --sytem-site-packages .
Next install the insights-core project and its dependencies into your virtualenv:
(insights-core)[userone@hostone project_dir/insights-core]$ bin/pip install -e .[client-develop]
Rule Development Setup¶
In order to develop rules to run in Red Hat Insights you’ll need Insights Core (http://github.com/RedHatInsights/insights-core) as well as your own rules code. The commands below assume the following sample project directory structure containing the insights-core project repo and your directory and files for rule development:
project_dir
├── insights-core
└── myrules
├── hostname_rel.py
└── bash_version.py
Rule Development¶
From your project root directory create a directory for your rules:
(insights-core)[userone@hostone project_dir/insights-core]$ cd ..
(insights-core)[userone@hostone project_dir]$ mkdir myrules
(insights-core)[userone@hostone project_dir]$ cd myrules
(insights-core)[userone@hostone project_dir/myrules]$
Create an empty file named __init__.py
that will enable your rules directory
as a python package. This makes the myrules
directory a python package allowing
you to use insights-run to run multiple components in the package.
If you create subdirectories create an empty
__init__.py
in each subdir that contains any components you want to run.
(insights-core)[userone@hostone project_dir/myrules]$ touch __init__.py
Create a sample rule called hostname_rel.py
in the myrules
directory:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 | #!/usr/bin/env python from insights.core.plugins import make_fail, make_pass, rule from insights.parsers.hostname import Hostname from insights.parsers.redhat_release import RedhatRelease ERROR_KEY_1 = "RELEASE_IS_RHEL" ERROR_KEY_2 = "RELEASE_IS_NOT_RECOGNIZED" ERROR_KEY_3 = "RELEASE_CANNOT_BE_DETERMINED" CONTENT = { ERROR_KEY_1: "This release is RHEL\nHostname: {{ hostname }}\nRelease: {{ release }}", ERROR_KEY_2: "This release is not RHEL\nHostname: {{ hostname }}\nRelease: {{ release }}", ERROR_KEY_3: "This release is not RHEL\nHostname: {{ hostname }}\nRelease: not present" } @rule(Hostname, [RedhatRelease]) def report(hostname, release): if release and release.is_rhel: return make_pass(ERROR_KEY_1, hostname=hostname.fqdn, release=release.version) elif release: return make_fail(ERROR_KEY_2, hostname=hostname.fqdn, release=release.raw) else: return make_fail(ERROR_KEY_3, hostname=hostname.fqdn) if __name__ == "__main__": from insights import run run(report, print_summary=True) |
Hint
You can download the code for hostname_rel.py
Now you can use Insights to evaluate your rule by running your rule script:
(insights-core)[userone@hostone project_dir/myrules]$ python hostname_rel.py
Depending upon the system you are using you will see several lines of output ending with your rule results that should look something like this:
---------
Progress:
---------
F
--------------
Rules Executed
--------------
[FAIL] __main__.report
---------------
This release is not RHEL
Hostname: hostone
Release: Fedora release 29 (Twenty Nine)
----------------------
Rule Execution Summary
----------------------
Missing Deps: 0
Passed : 0
Fingerprint : 0
Failed : 1
Metadata : 0
Metadata Key: 0
Exceptions : 0
Depending on your system you may also be able to make this file executable (chmod +x hostname_rel.py) and run like this: ./hostname_rel.py.
Now create a second rule named bash_version.py`
and include the following code
1 2 3 4 5 6 7 8 9 10 11 12 | from insights.core.plugins import make_pass, rule from insights.parsers.installed_rpms import InstalledRpms KEY = "BASH_VERSION" CONTENT = "Bash RPM Version: {{ bash_version }}" @rule(InstalledRpms) def report(rpms): bash_ver = rpms.get_max('bash') return make_pass(KEY, bash_version=bash_ver) |
Hint
You can download the code for bash_version.py
You’ll notice that this file does not include the #!/usr/bin/env python and the run(report…) lines. You can still run this rule easily from the command line using insights-run. Here’s how you can run each rule individually with insights-run:
(insights-core)[userone@hostone project_dir/myrules]$ insights-run -p bash_version
(insights-core)[userone@hostone project_dir/myrules]$ insights-run -p hostname_rel
Finally you can run multiple rules at once. First you can specify a comma separate list of all rules as the argument to -p:
(insights-core)[userone@hostone project_dir/myrules]$ insights-run -p bash_version,hostname_rel
The second way to do this is by taking advantage of the fact that all of your rules are in one package
(remember the empty __init__.py
file we created in the myrules
dir to make it a python package).
Just provide the name of the package to run all rules in the package:
(insights-core)[userone@hostone project_dir/myrules]$ cd ..
(insights-core)[userone@hostone project_dir]$ insights-run -p myrules
You can run one module in the package using either dot notation, myrules.bash_version
, or simply
using bash tab completion to specify the path name myrules/bash_version.py
:
(insights-core)[userone@hostone project_dir]$ insights-run -p myrules.bash_version
(insights-core)[userone@hostone project_dir]$ insights-run -p myrules/bash_version.py
Tip
If you don’t see the results you expect when using insights-run, try adding the -t flag to show python exception tracebacks and look for exceptions in your rule code. You can expect to see some exceptions from parsers if the data is not accessible due to permissions or is missing from your system or the data source.
Evaluating Archive Files and Directories¶
By default Insights will collect information from your computer for evaluation of your rules. You can also evaluate a sosreport or insights archive or directory by specifying it as the last argument on the command line:
(insights-core)[userone@hostone project_dir/myrules]$ insights-run -p bash_version sosreport.tar.xz
(insights-core)[userone@hostone project_dir/myrules]$ insights-run -p bash_version sosreport_dir
For a more detailed description of how to develop your own rules see the Rule tutorial section in the Insights Core Tutorials.
Insights Core Contributor Setup¶
If you wish to contribute to the insights-core project you’ll need to create a fork in GitHub. See Fork a repo on Github for help on forking a repo. After you have created your fork continue with these steps to setup your development environment.
Clone your fork:
[userone@hostone project_dir]$ git clone git@github.com:your-user/insights-core.git
Reference the original project as “upstream”:
[userone@hostone project_dir]$ cd insights-core [userone@hostone project_dir/insights-core]$ git remote add upstream git@github.com:RedHatInsights/insights-core.git
At this point, you would synchronize your fork with the upstream project using the following commands:
[userone@hostone project_dir/insights-core]$ git pull upstream master
[userone@hostone project_dir/insights-core]$ git push origin master
You should synchronize your fork with the upstream project regularly to ensure you have the most recent Insights Core code.
For more details steps on contributing to Insights Core see CONTRIBUTING.md.