Add README.md
This commit is contained in:
parent
3a8ad2a1e2
commit
5219f32d79
187
README.md
Normal file
187
README.md
Normal file
@ -0,0 +1,187 @@
|
|||||||
|
# rsyslog GitOps
|
||||||
|
|
||||||
|
Manage rsyslog configuration on Linux servers using Git as the single source of truth.
|
||||||
|
If it's not in Git, it doesn't belong on the server.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## How it works in one sentence
|
||||||
|
|
||||||
|
Every change goes through Git. The pipeline makes sure the server always matches what's in Git — and if someone changes the server directly, the system detects it automatically.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## The three pipelines
|
||||||
|
|
||||||
|
### 1. Pull Request — "Is this config safe?"
|
||||||
|
|
||||||
|
Triggered when you open or update a pull request.
|
||||||
|
Does **not** touch the live server beyond a basic reachability check.
|
||||||
|
Does **not** compare the PR content to the server (they're expected to differ before merge).
|
||||||
|
|
||||||
|
```
|
||||||
|
Open PR
|
||||||
|
│
|
||||||
|
├─► syntax-check Check the YAML/Ansible syntax is valid
|
||||||
|
│
|
||||||
|
└─► validate Connect to the server and verify rsyslog is running
|
||||||
|
and the current config is loadable
|
||||||
|
```
|
||||||
|
|
||||||
|
**Pass** = safe to review and merge.
|
||||||
|
**Fail** = syntax error or server is unreachable / config is broken.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 2. Push to master — "Deploy and verify"
|
||||||
|
|
||||||
|
Triggered when a PR is merged into master.
|
||||||
|
|
||||||
|
```
|
||||||
|
Merge to master
|
||||||
|
│
|
||||||
|
├─► syntax-check Same lint check as PR
|
||||||
|
│
|
||||||
|
├─► validate Same server check as PR
|
||||||
|
│
|
||||||
|
├─► deploy Copy the new config files from Git to the server
|
||||||
|
│ and restart rsyslog
|
||||||
|
│
|
||||||
|
└─► update-sync-metric Run a diff between Git and the live server
|
||||||
|
│
|
||||||
|
├─ Matches? → push metric 1 (SYNCED)
|
||||||
|
└─ Differs? → push metric 0 (OUT_OF_SYNC)
|
||||||
|
```
|
||||||
|
|
||||||
|
**Pass** = new config is live and the server matches Git.
|
||||||
|
The sync result is always sent to Prometheus regardless of outcome.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 3. Cron — "Is the server still synced?"
|
||||||
|
|
||||||
|
Runs automatically every 2 minutes, **even with no new push**.
|
||||||
|
This is the ArgoCD-style continuous check.
|
||||||
|
It only reads — never deploys anything.
|
||||||
|
|
||||||
|
```
|
||||||
|
Every 2 minutes (cron)
|
||||||
|
│
|
||||||
|
└─► gitops_sync_check SSH to the server, compare every managed config
|
||||||
|
file against the latest Git commit
|
||||||
|
│
|
||||||
|
├─ Matches? → push metric 1 (SYNCED)
|
||||||
|
└─ Differs? → push metric 0 (OUT_OF_SYNC)
|
||||||
|
```
|
||||||
|
|
||||||
|
**Why this matters:** if someone edits `/etc/rsyslog.conf` directly on the server
|
||||||
|
(bypassing Git), the next cron run catches it within 2 minutes and marks OUT_OF_SYNC.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Full flow diagram
|
||||||
|
|
||||||
|
```
|
||||||
|
Developer Woodpecker CI Linux Server Prometheus
|
||||||
|
│ │ │ │
|
||||||
|
│── open PR ───────────────►│ │ │
|
||||||
|
│ │── syntax-check │ │
|
||||||
|
│ │── validate ─────────────►│ │
|
||||||
|
│◄── PR ok / failed ────────│ │ │
|
||||||
|
│ │ │ │
|
||||||
|
│── merge to master ───────►│ │ │
|
||||||
|
│ │── syntax-check │ │
|
||||||
|
│ │── validate ─────────────►│ │
|
||||||
|
│ │── deploy ───────────────►│ write config │
|
||||||
|
│ │ │ restart rsyslog │
|
||||||
|
│ │── drift-check ──────────►│ compare files │
|
||||||
|
│ │ │◄────────────────────│
|
||||||
|
│ │── metric (1 or 0) ───────────────────────────►│
|
||||||
|
│ │ │ │
|
||||||
|
│ │ [every 2 min, no push] │ │
|
||||||
|
│ │── drift-check ──────────►│ compare files │
|
||||||
|
│ │── metric (1 or 0) ───────────────────────────►│
|
||||||
|
│ │ │ │
|
||||||
|
|
||||||
|
|
||||||
|
Someone edits the server directly (bad):
|
||||||
|
|
||||||
|
rogue admin Woodpecker CI Linux Server Prometheus
|
||||||
|
│ │ │ │
|
||||||
|
│── ssh rsyslog-lab │ │ │
|
||||||
|
│── vim /etc/rsyslog.conf ──────────────────────────► │ file changed │
|
||||||
|
│ │ │ │
|
||||||
|
│ [2 min later, cron runs] │ │
|
||||||
|
│ │── drift-check ──────────►│ diff detected │
|
||||||
|
│ │── metric 0 (OUT_OF_SYNC)────────────────────►│
|
||||||
|
│ │ │ alert fires
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## What is the sync metric?
|
||||||
|
|
||||||
|
```
|
||||||
|
gitops_sync_status{repo="rsyslog", server="rsyslog-lab"}
|
||||||
|
```
|
||||||
|
|
||||||
|
| Value | Meaning |
|
||||||
|
|-------|---------|
|
||||||
|
| `1` | Server config matches Git (SYNCED) |
|
||||||
|
| `0` | Server config differs from Git (OUT_OF_SYNC) |
|
||||||
|
|
||||||
|
Alert on `gitops_sync_status == 0` in Grafana/Alertmanager.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## What drift-check actually compares
|
||||||
|
|
||||||
|
The drift-check playbook compares files **from the Woodpecker CI container** (always the latest Git commit) against the live server. It checks:
|
||||||
|
|
||||||
|
1. `/etc/rsyslog.conf` — must match `files/rsyslog.conf` in Git
|
||||||
|
2. `/etc/rsyslog.d/30-lab.conf` — must match `files/rsyslog.d/30-lab.conf` in Git
|
||||||
|
3. Any file managed by Git must not be missing from the server
|
||||||
|
|
||||||
|
Files on the server that are **not** in Git (e.g. `50-default.conf`, `20-ufw.conf`) are ignored — they are owned by the OS and are not our concern.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Repository structure
|
||||||
|
|
||||||
|
```
|
||||||
|
.woodpecker.yml CI pipeline definition
|
||||||
|
ansible/
|
||||||
|
inventory/
|
||||||
|
hosts.yml Server list
|
||||||
|
group_vars/all.yml Variables (paths, user, etc.)
|
||||||
|
playbooks/
|
||||||
|
validate.yml Check rsyslog is running and config loads
|
||||||
|
apply.yml Deploy config files from Git to server
|
||||||
|
drift-check.yml Compare Git files to live server (read-only)
|
||||||
|
files/
|
||||||
|
rsyslog.conf Main rsyslog config (source of truth)
|
||||||
|
rsyslog.d/
|
||||||
|
30-lab.conf Drop-in config for lab logging
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Woodpecker cron setup
|
||||||
|
|
||||||
|
Go to **Repository Settings → Crons → Add cron**:
|
||||||
|
|
||||||
|
| Field | Value |
|
||||||
|
|----------|---------------------|
|
||||||
|
| Name | `gitops_sync_check` |
|
||||||
|
| Branch | `master` |
|
||||||
|
| Schedule | `*/2 * * * *` |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Required secrets
|
||||||
|
|
||||||
|
Go to **Repository Settings → Secrets**:
|
||||||
|
|
||||||
|
| Name | Description |
|
||||||
|
|-------------------|------------------------------------|
|
||||||
|
| `SSH_PRIVATE_KEY` | Private key to SSH into the server |
|
||||||
Loading…
x
Reference in New Issue
Block a user