Skip to content

Commit 0e62157

Browse files
ralphmralphm
authored
Merge pull request #18 from pid1/full-rewrite-v2
Modernization rewrite V2
2 parents c75f632 + def83dd commit 0e62157

164 files changed

Lines changed: 625 additions & 1904 deletions

File tree

Some content is hidden

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

‎.ansible-lint‎

Lines changed: 0 additions & 6 deletions
This file was deleted.

‎.github/workflows/linting.yml‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
name: Linting
2+
3+
on:
4+
push:
5+
pull_request:
6+
7+
8+
jobs:
9+
build:
10+
name: Ansible Lint # Naming the build is important to use it as a status check
11+
runs-on: ubuntu-latest
12+
steps:
13+
- uses: actions/checkout@v6
14+
- name: Run ansible-lint
15+
uses: ansible/ansible-lint@main
16+
with:
17+
args: "--exclude tests/test.yml --skip-list=role-name"

‎.github/workflows/linux-ci.yml‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
name: Integration Test
2+
3+
on:
4+
push:
5+
pull_request:
6+
7+
jobs:
8+
9+
# Test installation on apt-based distributions (Debian and Ubuntu)
10+
apt-test:
11+
name: "Test (${{ matrix.image }})"
12+
runs-on: ubuntu-latest
13+
strategy:
14+
fail-fast: false
15+
matrix:
16+
image:
17+
- debian:bullseye
18+
- debian:bookworm
19+
- ubuntu:22.04
20+
- ubuntu:24.04
21+
container:
22+
image: ${{ matrix.image }}
23+
steps:
24+
- name: Install dependencies
25+
run: |
26+
apt-get -y update; apt-get -y upgrade; apt-get -y install ansible
27+
- name: Checkout code
28+
uses: actions/checkout@v6
29+
- name: Test installation
30+
run: |
31+
ansible-playbook tests/test.yml
32+
33+
# Test installation on openSUSE (Leap and Tumbleweed)
34+
opensuse-test:
35+
name: "Test (${{ matrix.image }})"
36+
runs-on: ubuntu-latest
37+
strategy:
38+
fail-fast: false
39+
matrix:
40+
include:
41+
- image: opensuse/leap:15.6
42+
community_general_version: ""
43+
- image: opensuse/leap:16.0
44+
community_general_version: ""
45+
- image: opensuse/tumbleweed
46+
community_general_version: ""
47+
container:
48+
image: ${{ matrix.image }}
49+
steps:
50+
- name: Install dependencies
51+
run: |
52+
zypper -n refresh; zypper -n update; zypper -n install ansible tar gzip
53+
ansible-galaxy collection install community.general${{ matrix.community_general_version }}
54+
- name: Checkout code
55+
uses: actions/checkout@v6
56+
- name: Test installation
57+
run: |
58+
ansible-playbook tests/test.yml

‎.gitignore‎

Lines changed: 2 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,2 @@
1-
hosts
2-
ansible.cfg
3-
test.yml
4-
.vscode
5-
.swp
1+
# FastForward runtime artifacts
2+
.fastforward/

‎AGENTS.md‎

Lines changed: 151 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,151 @@
1+
# AGENTS.md
2+
3+
Guidelines for AI agents working on this repository.
4+
5+
## Project Overview
6+
7+
This is an Ansible role (`netdata`) that deploys and configures the [Netdata](https://www.netdata.cloud/) monitoring agent on Linux systems. It supports Debian, Ubuntu, and openSUSE platforms.
8+
9+
## Repository Structure
10+
11+
This repository follows the standard Ansible role directory layout:
12+
13+
```
14+
netdata-ansible/
15+
defaults/main.yml # Default variable values for the role
16+
handlers/main.yml # Handlers (restart Netdata, reload claiming state)
17+
meta/main.yml # Role metadata for Ansible Galaxy
18+
tasks/
19+
main.yml # Top-level task dispatcher
20+
install-debian.yml # Debian/Ubuntu package installation
21+
install-opensuse.yml # openSUSE package installation
22+
configure-linux.yml # Configuration file management
23+
node_claim.yml # Netdata Cloud node claiming
24+
templates/
25+
claim.conf.j2 # Claiming configuration template
26+
go.d/plugin.conf.j2 # Go collector plugin configuration template
27+
tests/
28+
test.yml # CI integration test playbook
29+
netdata.conf.j2 # Test configuration template
30+
example.chart.j2 # Test chart template
31+
roles/netdata # Symlink to repository root (`../../`) so the test
32+
# playbook can reference the role by its name
33+
# (`role: netdata`) via Ansible's default
34+
# roles_path resolution.
35+
.github/
36+
workflows/
37+
linux-ci.yml # Integration tests (matrix strategy, 7 OS versions)
38+
linting.yml # Ansible Lint checks
39+
CODEOWNERS # Code ownership rules
40+
.gitignore # Git ignore rules (excludes .fastforward/)
41+
README.md # User-facing documentation
42+
AGENTS.md # This file
43+
```
44+
45+
## CI Workflows
46+
47+
Two GitHub Actions workflows run on every push and pull request:
48+
49+
### Integration Test (`linux-ci.yml`)
50+
51+
Uses GitHub Actions matrix strategy to run `ansible-playbook tests/test.yml` across seven container environments, organized into two jobs by package manager:
52+
53+
**`apt-test`** (Debian and Ubuntu, uses `apt-get`):
54+
55+
| Container Image |
56+
|----------------|
57+
| `debian:bullseye` |
58+
| `debian:bookworm` |
59+
| `ubuntu:22.04` |
60+
| `ubuntu:24.04` |
61+
62+
**`opensuse-test`** (openSUSE Leap and Tumbleweed, uses `zypper`):
63+
64+
| Container Image | `community.general` Version |
65+
|----------------|----------------------------|
66+
| `opensuse/leap:15.6` | latest |
67+
| `opensuse/leap:16.0` | latest |
68+
| `opensuse/tumbleweed` | latest |
69+
70+
Both jobs set `fail-fast: false` so all matrix entries run even if one fails. Each job installs Ansible inside the container, checks out the code, and runs the test playbook. The `opensuse-test` job additionally installs the `community.general` Ansible collection via `ansible-galaxy`, because the openSUSE Leap `ansible` package does not bundle it. This collection provides the `community.general.zypper` and `community.general.zypper_repository` modules that the role requires.
71+
72+
The `opensuse-test` matrix uses `include` entries with a `community_general_version` variable to control the installed collection version per image. All current entries install the latest version. When adding new openSUSE matrix entries, check the Python version in the container. If the Python version is below 3.7, pin `community.general` to 3.8.8 (the last release supporting Python 3.6 and Ansible 2.9).
73+
74+
### Linting (`linting.yml`)
75+
76+
Runs `ansible-lint` via the `ansible/ansible-lint@main` action. The lint configuration excludes `tests/test.yml` and skips the `role-name` rule.
77+
78+
### Actions Pinning Convention
79+
80+
All GitHub Actions checkout steps use `actions/checkout@v6` (Node.js 24). Keep this version current to avoid Node.js deprecation warnings.
81+
82+
## Key Files
83+
84+
### `meta/main.yml`
85+
86+
Ansible Galaxy role metadata. Valid top-level keys are `galaxy_info`, `dependencies`, and `allow_duplicates` only. Do NOT add a top-level `version` key; Ansible roles derive versions from Git tags, not from role metadata.
87+
88+
The `galaxy_info.platforms` list declares supported platforms for Ansible Galaxy. Platform names and version strings must match the ansible-lint `schema[meta]` rule. When a specific OS minor version is not in the Galaxy schema's allowed enum, use `versions: [all]` instead of explicit version numbers.
89+
90+
### `defaults/main.yml`
91+
92+
All role variables with their defaults. See `README.md` for a complete variable reference table.
93+
94+
### `tasks/main.yml`
95+
96+
Entry point for role execution. Dispatches to platform-specific install tasks based on `ansible_facts.distribution`, then runs configuration and claiming tasks when enabled.
97+
98+
### `tasks/install-debian.yml`
99+
100+
Handles Debian and Ubuntu package installation. Uses the modern `signed-by` keyring approach for GPG key management:
101+
102+
1. Installs `gnupg` (required for key dearmoring).
103+
2. Creates `/etc/apt/keyrings/` directory.
104+
3. Downloads the ASCII-armored GPG key to `/etc/apt/keyrings/netdata.asc`.
105+
4. Dearmors the key to binary format at `/etc/apt/keyrings/netdata.gpg`.
106+
5. References the binary keyring via `[signed-by=...]` in the apt source line.
107+
108+
Do NOT use `ansible.builtin.apt_key` in this file. It wraps the deprecated `apt-key` utility, which fails on Debian 12+ and Ubuntu 22.04+ with subkey validation errors.
109+
110+
### `tasks/install-opensuse.yml`
111+
112+
Handles openSUSE Leap and Tumbleweed package installation. Installs `libnetfilter_acct1` from the standard Leap 15.x repositories (skipped on Leap 16.0+ and Tumbleweed where the package is unavailable), imports the Netdata GPG key, adds the Netdata package repository, and installs the `netdata` package (plus optional chart support).
113+
114+
All zypper-related tasks use the `community.general` collection (`community.general.zypper` and `community.general.zypper_repository`). This collection must be available on the control node.
115+
116+
The repository URL uses a computed version path segment: the literal string `tumbleweed` for Tumbleweed, or the zypper `$releasever` variable for Leap. Do not hardcode version-specific repository URLs. The `libnetfilter_acct1` package is available from the standard Leap 15.x Main Repository and does not require an external repository. It is not available on Leap 16.0+ or Tumbleweed; the install task skips it on those systems via a version comparison condition.
117+
118+
## Conventions
119+
120+
### YAML Style
121+
122+
- Use `---` document start markers in Ansible YAML files.
123+
- Use fully qualified collection names for modules (e.g., `ansible.builtin.setup`, not `setup`).
124+
- Quote string values in variable definitions.
125+
126+
### Task Naming
127+
128+
- Every task must have a `name` field with a descriptive label.
129+
- Use the pattern: verb + object (e.g., "Install dependencies", "Configure Netdata").
130+
131+
### Testing
132+
133+
- The integration test playbook is `tests/test.yml`. It runs the role against `localhost` with `netdata_manage_config: true` and `netdata_manage_charts: true`.
134+
- The playbook references the role by name (`role: netdata`). The role is resolved via the `tests/roles/netdata` symlink that points at the repository root (`../../`). This is the standard Ansible Galaxy convention for testing a role from within its own repository. Do NOT change the playbook to use a relative path like `role: ../netdata-ansible`; that path is brittle because Ansible resolves role paths relative to the playbook file, and the parent directory name depends on how the repo was checked out (in CI it is `ansible`, not `netdata-ansible`).
135+
- CI tests validate that the role installs successfully. They do not validate Netdata runtime behavior (the containers do not run systemd).
136+
137+
### Variable Naming
138+
139+
- All role variables are prefixed with `netdata_`.
140+
- Boolean variables use `true`/`false`, not `yes`/`no`.
141+
142+
### Git Ignore Rules
143+
144+
- The `.gitignore` file excludes `.fastforward/` (the runtime artifact directory used by multi-session AI workflows).
145+
- Do NOT commit files under `.fastforward/`. If a file gets tracked before its `.gitignore` entry exists, remove it from the index with `git rm --cached <path>`. Do NOT use `git rm` without `--cached`; that deletes the file from disk.
146+
147+
### Commit Messages
148+
149+
- Follow conventional commit format: `type: description`.
150+
- Common types: `fix`, `feat`, `docs`, `ci`, `refactor`.
151+
- Keep the subject line concise (under 72 characters).

0 commit comments

Comments
 (0)