Skip to content

Commit 07b03f3

Browse files
hairmarehairmare
authored
feat: modernise repo structure and add Zabbix 6.4 templates (#103)
* New directory structure that closer matches application groups in zabbix * Support multiple Zabbix major versions 👉 existing templates are in `3.0/` subdirs each * Add 6.4 templates 👉 mostly in `Templates/Applications` and `Stacks` and as preparation for future 7.0 LTS support * Replace nodejs based tooling with an Ansible playbook for downloading templates and generating documentation * Add mkdocs support * Rewrite main README.md 👉 existing contents are mostly in CONTRIBUTING.md now * CI/CD with GitHub Actions for semantic releasing and mkdocs publishing
1 parent 5d2dfb7 commit 07b03f3

File tree

315 files changed

+22354
-1587
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

315 files changed

+22354
-1587
lines changed

Diff for: ‎.gitattributes

+5
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
catalog-info.yaml linguist-generated=true
2+
**/README.md linguist-generated=true
3+
**/DIFF.md linguist-generated=true
4+
**/gen_ref_pages.py linguist-generated=true
5+
**/mkdocs.yaml linguist-generated=true

Diff for: ‎.github/dependabot.yml

+6
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
version: 2
2+
updates:
3+
- package-ecosystem: "github-actions"
4+
directory: "/"
5+
schedule:
6+
interval: "daily"

Diff for: ‎.github/workflows/release.yaml

+11
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
name: Release
2+
3+
on:
4+
push:
5+
tags:
6+
- 'v*.*.*'
7+
pull_request:
8+
9+
jobs:
10+
release-container:
11+
uses: radiorabe/actions/.github/workflows/[email protected]

Diff for: ‎.github/workflows/semantic-release.yaml

+13
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
name: Run semantic-release
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
- release/*
8+
9+
jobs:
10+
semantic-release:
11+
uses: radiorabe/actions/.github/workflows/[email protected]
12+
secrets:
13+
RABE_ITREAKTION_GITHUB_TOKEN: ${{ secrets.RABE_ITREAKTION_GITHUB_TOKEN }}

Diff for: ‎.github/workflows/test.yaml

+23
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
name: Test
2+
3+
on:
4+
pull_request:
5+
6+
jobs:
7+
test:
8+
runs-on: ubuntu-latest
9+
steps:
10+
- uses: actions/checkout@v4
11+
with:
12+
fetch-depth: 0
13+
14+
- name: Setup Python
15+
uses: actions/setup-python@v5
16+
with:
17+
python-version: '3.x'
18+
19+
- run: pip install ansible
20+
21+
- run: ansible-playbook hack/plays/manage.yml
22+
23+
- run: git diff --exit-code

Diff for: ‎.gitignore

+2-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
11
/rabe.lst
22
**/selinux/tmp
33
**/selinux/*.pp
4-
node_modules/
4+
site/
5+
venv/

Diff for: ‎.jshintrc

-1
This file was deleted.

Diff for: ‎CONTRIBUTING.md

+161
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,161 @@
1+
# Contributing to the RaBe Zabbix Templates
2+
3+
Hi and thanks for wanting to contribute to the RaBe Zabbix templates.
4+
5+
* Please [create an issue](https://github.com/radiorabe/rabe-zabbix/issues) if you found a bug
6+
* [Start a discussion](https://github.com/radiorabe/rabe-zabbix/discussions) if you need general help
7+
* Or check out the conventions and documentation in this file to add templates
8+
9+
Keep in mind that this repository is the source of truth for our Zabbix installation, hence we tend to be cautious when merging changes as to now have them impact our Zabbix installation.
10+
11+
## Conventions
12+
13+
🚧 Refactor underway! These conventions were written with Zabbix 3.0 in mind. 🚧
14+
15+
### Template conventions
16+
17+
* Use active mode for zabbix agent items by default
18+
* Use an update interval of 300 seconds (5 minutes) by default
19+
* Create at least one unique application per app, ipmi and snmp template
20+
* Use macros whenever possible and feasible, prefix them with a unique per template prefix
21+
22+
### App specific conventions
23+
24+
* Apps may contain configuration snippets in a `userparameters/` subdir.
25+
* SELinux policy modules for an app are in the `selinux/` subdir. They are prefixed with "rabezbx" to help differentiate them from system policy.
26+
27+
### IPMI specific conventions
28+
29+
* Name server or motherboard templates according to `IPMI <VENDOR>
30+
<PRODUCT-NAME>`, for example `Template IPMI Supermicro SSG-6048R-E1CR24N`
31+
* Try to build up a server or motherboard template from existing (or newly
32+
created) standalone sensor templates (which can be reused for the same sensor
33+
and reading type).
34+
* Standalone sensor templates which contain sensor-specific discrete IPMI
35+
sensors (event/reading type code 6Fh)
36+
* Template naming according to `IPMI <SENSOR-NAME> Sensors`, for example
37+
`IPMI Power Supply Sensors`
38+
* Item key naming according to
39+
`ipmi.discrete-sensor[<SENSOR-TYPE>,<SENSOR-NAME>]`, for example
40+
`ipmi.discrete-sensor[power-supply,{#IPMI_SENSOR_NAME}]`
41+
* Create triggers according to the sensor's specific event/reading type code
42+
and offsets (see [Table 42-3, Sensor Type
43+
Codes](http://www.intel.com/content/dam/www/public/us/en/documents/product-briefs/second-gen-interface-spec-v2.pdf))
44+
with the help of the Zabbix [band()
45+
function](https://www.zabbix.com/documentation/3.0/manual/appendix/triggers/functions)
46+
* Standalone sensor templates which contain generic discrete IPMI sensors
47+
(event/reading type code 02h - 0Ch)
48+
* Template naming according to `IPMI <SENSOR-NAME> Generic Sensors`, for
49+
example `IPMI Module Board Generic Sensors`
50+
* Item key naming according to
51+
`ipmi.discrete-generic-sensor[<SENSOR-TYPE>,<SENSOR-NAME>]`, for example
52+
`ipmi.discrete-generic-sensor[module-board,{#IPMI_SENSOR_NAME}]`
53+
* Create triggers according to the sensor's generic event/reading type code
54+
and offsets (see [Table 42-2, Generic Event/Reading Type
55+
Codes](http://www.intel.com/content/dam/www/public/us/en/documents/product-briefs/second-gen-interface-spec-v2.pdf))
56+
with the help of the Zabbix [band()
57+
function](https://www.zabbix.com/documentation/3.0/manual/appendix/triggers/functions)
58+
* Use the provided `ipmi-sensor-discovery.sh` external check script for
59+
low-level auto-discovery of multiple sensors.
60+
* FreeIPMI's [interpret sensor
61+
configuration](http://git.savannah.gnu.org/cgit/freeipmi.git/tree/etc/freeipmi_interpret_sensor.conf)
62+
might be helpful for mapping sensor states to Zabbix trigger severities.
63+
* There should be no more need for threshold based sensor templates
64+
(event/reading type code 01h), as they are already handled by the `IPMI
65+
Threshold Sensors` template.
66+
67+
### SNMP specific conventions
68+
69+
* Name SNMP templates according to `Template SNMPv<SNMP-VERSION> <NAME>`, for example
70+
`Template SNMPv2 Bridge`
71+
* Try to reflect the MIBs name within `<NAME>` whenever feasible
72+
* Use the textual form of MIB OIDs within your SNMP items.
73+
As an example, use `BRIDGE-MIB::dot1dBaseNumPorts.0` instead of
74+
`.1.3.6.1.2.1.17.1.2.0`
75+
* Include instructions on how to obtain and install the required MIBs for your
76+
template.
77+
* Name items according to `rabe.snmp.<NAME>.<OID-NAME>` to avoid clashes with
78+
other templates.
79+
Example: `rabe.snmp.bridge.dot1dBaseNumPorts`
80+
* Name low-level discovery rule keys with `rabe.snmp.<NAME>.<OBJECT>.discovery`
81+
Example: `rabe.snmp-bridge.ports.discovery`
82+
* Create value mappings according to the OID's syntax definition from the MIB.
83+
84+
## Developing
85+
86+
The "RaBe Zabbix Templator" is based on Ansible and it's code is stored in the
87+
`hack/` directory.
88+
The playbook supports the version of Zabbix currently used at RaBe as we use
89+
it to download templates for integration in this repository. The all-in-one
90+
`manage.py` playbook takes care of everything, without an API key for the
91+
RaBe servers it soley regenerates README files and documentation.
92+
93+
### Regenerating READMEs
94+
95+
```bash
96+
ansible-playbook hack/plays/manage.yml
97+
```
98+
99+
### Fetching Templates using ansible
100+
101+
```bash
102+
ansible-playbook hack/plays/manage.yml -e ansible_zabbix_auth_key=<AUTH_KEY>
103+
```
104+
105+
If you just want to fetch a single template:
106+
107+
```bash
108+
ansible-playbook hack/plays/manage.yml -e ansible_zabbix_auth_key=<AUTH_KEY> -e 'rabe_zabbix_templates=[{"template_name":"CHANGEME"}]'
109+
```
110+
111+
### Adding new templates
112+
113+
After downloading a template for the first time, you need to configure it's vendor in the new YAML file.
114+
115+
Add the following in `<Template_Group>/<Name>/<Version>/<Name>.yaml` right after the `description` key.
116+
117+
```yaml
118+
vendor:
119+
name: RaBe
120+
version: '6.4'
121+
```
122+
123+
Switch branch and look at the generated README.md before you commit it:
124+
125+
```bash
126+
git branch -c feat/<Template_Group>/add-<Name>-for-<Version>
127+
git add <Template_Group>/<Name>/<Version>/
128+
git commit -m 'feat: Add <Name> template'
129+
```
130+
131+
## Release Management
132+
133+
The CI/CD setup uses semantic commit messages following the [conventional commits standard](https://www.conventionalcommits.org/en/v1.0.0/).
134+
The workflow is based on the [RaBe shared actions](https://radiorabe.github.io/actions/)
135+
and uses [go-semantic-commit](https://go-semantic-release.xyz/)
136+
to create new releases.
137+
138+
The commit message should be structured as follows:
139+
140+
```console
141+
<type>[optional scope]: <description>
142+
143+
[optional body]
144+
145+
[optional footer(s)]
146+
```
147+
148+
The commit contains the following structural elements, to communicate intent to the consumers of your library:
149+
150+
1. **fix:** a commit of the type `fix` patches gets released with a PATCH version bump
151+
1. **feat:** a commit of the type `feat` gets released as a MINOR version bump
152+
1. **BREAKING CHANGE:** a commit that has a footer `BREAKING CHANGE:` gets released as a MAJOR version bump
153+
1. types other than `fix:` and `feat:` are allowed and don't trigger a release
154+
155+
If a commit does not contain a conventional commit style message you can fix
156+
it during the squash and merge operation on the PR.
157+
158+
## Build Process
159+
160+
The CI/CD setup uses [mkdocs](https://www.mkdocs.org/) to publish documentation to [GitHub Pages](https://pages.github.com/).
161+
The workflow is based on the [RaBe shared actions](https://radiorabe.github.io/actions/).

0 commit comments

Comments
 (0)