Compare commits

...

6 Commits

Author SHA1 Message Date
Prox
0eef866266 markdown improvement 2026-03-06 18:34:59 +02:00
Prox
aa4aa32655 updated dry-run job 2026-03-06 18:34:59 +02:00
Prox
9a29a9cc0c improved jobs 2026-03-06 18:34:59 +02:00
Prox
19bf70034c updated dry-run.yml and reconcile jobs 2026-03-06 18:34:59 +02:00
Prox
42c1eb6f73 added test setup key 2026-03-06 18:34:59 +02:00
Prox
a316e39cae added TEST_SCENARIOS 2026-03-06 18:29:39 +02:00
8 changed files with 447 additions and 223 deletions

50
.beads/.gitignore vendored
View File

@ -1,45 +1,30 @@
# Dolt database (managed by Dolt, not git)
dolt/
dolt-access.lock
# SQLite databases
*.db
*.db?*
*.db-journal
*.db-wal
*.db-shm
# Runtime files
# Daemon runtime files
daemon.lock
daemon.log
daemon.pid
bd.sock
bd.sock.startlock
sync-state.json
last-touched
# Local version tracking (prevents upgrade notification spam after git ops)
.local_version
# Legacy database files
db.sqlite
bd.db
# Worktree redirect file (contains relative path to main repo's .beads/)
# Must not be committed as paths would be wrong in other clones
redirect
# Sync state (local-only, per-machine)
# These files are machine-specific and should not be shared across clones
.sync.lock
.jsonl.lock
sync_base.jsonl
export-state/
# Ephemeral store (SQLite - wisps/molecules, intentionally not versioned)
ephemeral.sqlite3
ephemeral.sqlite3-journal
ephemeral.sqlite3-wal
ephemeral.sqlite3-shm
# Legacy files (from pre-Dolt versions)
*.db
*.db?*
*.db-journal
*.db-wal
*.db-shm
db.sqlite
bd.db
daemon.lock
daemon.log
daemon-*.log.gz
daemon.pid
# Merge artifacts (temporary files from 3-way merge)
beads.base.jsonl
beads.base.meta.json
beads.left.jsonl
@ -47,6 +32,11 @@ beads.left.meta.json
beads.right.jsonl
beads.right.meta.json
# Sync state (local-only, per-machine)
# These files are machine-specific and should not be shared across clones
.sync.lock
sync_base.jsonl
# NOTE: Do NOT add negation patterns (e.g., !issues.jsonl) here.
# They would override fork protection in .git/info/exclude, allowing
# contributors to accidentally commit upstream issue databases.

0
.beads/issues.jsonl Normal file
View File

View File

@ -1,7 +1,4 @@
{
"database": "dolt",
"jsonl_export": "issues.jsonl",
"backend": "dolt",
"dolt_mode": "server",
"dolt_database": "beads_netbird-gitops"
"jsonl_export": "issues.jsonl"
}

3
.gitattributes vendored Normal file
View File

@ -0,0 +1,3 @@
# Use bd merge for beads JSONL files
.beads/issues.jsonl merge=beads

View File

@ -6,101 +6,114 @@ on:
- "state/*.json"
jobs:
detect:
dry-run:
runs-on: ubuntu-latest
outputs:
envs: ${{ steps.changed.outputs.envs }}
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Detect changed environments
id: changed
run: |
FILES=$(git diff --name-only ${{ github.event.pull_request.base.sha }} ${{ github.sha }} -- 'state/*.json')
ENVS="[]"
for f in $FILES; do
ENV=$(basename "$f" .json)
ENVS=$(echo "$ENVS" | jq -c ". + [\"$ENV\"]")
done
echo "envs=$ENVS" >> "$GITHUB_OUTPUT"
echo "Changed environments: $ENVS"
dry-run:
needs: detect
runs-on: ubuntu-latest
if: needs.detect.outputs.envs != '[]'
strategy:
matrix:
env: ${{ fromJson(needs.detect.outputs.envs) }}
steps:
- uses: actions/checkout@v4
- name: Resolve environment secrets
id: env
run: |
ENV_UPPER=$(echo "${{ matrix.env }}" | tr '[:lower:]-' '[:upper:]_')
echo "token_key=${ENV_UPPER}_RECONCILER_TOKEN" >> "$GITHUB_OUTPUT"
echo "url_key=${ENV_UPPER}_RECONCILER_URL" >> "$GITHUB_OUTPUT"
- name: Run dry-run reconcile
id: plan
env:
RECONCILER_TOKEN: ${{ secrets[steps.env.outputs.token_key] }}
RECONCILER_URL: ${{ secrets[steps.env.outputs.url_key] }}
run: |
if [ -z "$RECONCILER_URL" ] || [ -z "$RECONCILER_TOKEN" ]; then
echo "No secrets configured for environment '${{ matrix.env }}' — skipping"
echo "response={}" >> "$GITHUB_OUTPUT"
exit 0
fi
RESPONSE=$(curl -sf \
-X POST \
-H "Authorization: Bearer ${RECONCILER_TOKEN}" \
-H "Content-Type: application/json" \
-d @state/${{ matrix.env }}.json \
"${RECONCILER_URL}/reconcile?dry_run=true")
echo "response<<EOF" >> "$GITHUB_OUTPUT"
echo "$RESPONSE" >> "$GITHUB_OUTPUT"
echo "EOF" >> "$GITHUB_OUTPUT"
- name: Format plan as markdown
id: format
if: steps.plan.outputs.response != '{}'
run: |
cat <<'SCRIPT' > format.py
import json, sys
data = json.loads(sys.stdin.read())
ops = data.get("operations", [])
summary = data.get("summary", {})
env = sys.argv[1]
lines = [f"## Reconciliation Plan: `{env}`\n"]
if not ops:
lines.append("No changes detected.\n")
else:
lines.append("| Operation | Name |")
lines.append("|-----------|------|")
for op in ops:
lines.append(f"| `{op['type']}` | {op['name']} |")
lines.append("")
s = summary
lines.append(f"**Summary:** {s.get('created',0)} create, {s.get('updated',0)} update, {s.get('deleted',0)} delete")
print("\n".join(lines))
SCRIPT
COMMENT=$(echo '${{ steps.plan.outputs.response }}' | python3 format.py "${{ matrix.env }}")
echo "comment<<EOF" >> "$GITHUB_OUTPUT"
echo "$COMMENT" >> "$GITHUB_OUTPUT"
echo "EOF" >> "$GITHUB_OUTPUT"
- name: Post PR comment
if: steps.plan.outputs.response != '{}'
- name: Dry-run reconcile for changed environments
env:
BASE_SHA: ${{ github.event.pull_request.base.sha }}
HEAD_SHA: ${{ github.sha }}
TEST_RECONCILER_TOKEN: ${{ secrets.TEST_RECONCILER_TOKEN }}
TEST_RECONCILER_URL: ${{ secrets.TEST_RECONCILER_URL }}
DEV_RECONCILER_TOKEN: ${{ secrets.DEV_RECONCILER_TOKEN }}
DEV_RECONCILER_URL: ${{ secrets.DEV_RECONCILER_URL }}
PROD_RECONCILER_TOKEN: ${{ secrets.PROD_RECONCILER_TOKEN }}
PROD_RECONCILER_URL: ${{ secrets.PROD_RECONCILER_URL }}
GIT_TOKEN: ${{ secrets.GIT_TOKEN }}
GIT_URL: ${{ secrets.GIT_URL }}
REPO: ${{ github.repository }}
PR_NUMBER: ${{ github.event.pull_request.number }}
run: |
curl -sf \
-X POST \
-H "Authorization: token ${GIT_TOKEN}" \
-H "Content-Type: application/json" \
-d "{\"body\": $(echo '${{ steps.format.outputs.comment }}' | jq -Rs .)}" \
"${{ secrets.GIT_URL }}/api/v1/repos/${{ github.repository }}/issues/${{ github.event.pull_request.number }}/comments"
python3 <<'SCRIPT'
import json, os, subprocess, urllib.request
# Detect changed state files
diff = subprocess.run(
["git", "diff", "--name-only", os.environ["BASE_SHA"], os.environ["HEAD_SHA"], "--", "state/*.json"],
capture_output=True, text=True, check=True,
)
envs = [os.path.basename(f).replace(".json", "") for f in diff.stdout.strip().split("\n") if f.strip()]
if not envs:
print("No state files changed")
exit(0)
print(f"Changed environments: {envs}")
for env in envs:
key = env.upper().replace("-", "_")
token = os.environ.get(f"{key}_RECONCILER_TOKEN", "")
url = os.environ.get(f"{key}_RECONCILER_URL", "")
if not token or not url:
print(f"[{env}] No secrets configured — skipping")
continue
# Call reconciler dry-run
with open(f"state/{env}.json", "rb") as f:
state_data = f.read()
req = urllib.request.Request(
f"{url}/reconcile?dry_run=true",
data=state_data,
method="POST",
headers={
"Authorization": f"Bearer {token}",
"Content-Type": "application/json",
},
)
try:
resp = urllib.request.urlopen(req)
data = json.loads(resp.read())
except Exception as e:
print(f"[{env}] Reconciler call failed: {e}")
continue
# Format as markdown grouped by action
ops = data.get("operations", [])
summary = data.get("summary", {})
lines = [f"## Reconciliation Plan: `{env}`\n"]
if not ops:
lines.append("No changes detected.\n")
else:
groups = {"Create": [], "Update": [], "Delete": []}
for op in ops:
t = op["type"]
if t.startswith("create"): groups["Create"].append(op)
elif t.startswith("delete"): groups["Delete"].append(op)
else: groups["Update"].append(op)
for action, items in groups.items():
if not items:
continue
emoji = {"Create": "+", "Update": "~", "Delete": "-"}[action]
lines.append(f"### {action} ({len(items)})\n")
lines.append("| Resource | Name |")
lines.append("|----------|------|")
for op in items:
resource = op["type"].split("_", 1)[1] if "_" in op["type"] else op["type"]
lines.append(f"| {resource} | {op['name']} |")
lines.append("")
c, u, d = summary.get("created", 0), summary.get("updated", 0), summary.get("deleted", 0)
lines.append(f"**Total: {c} create, {u} update, {d} delete**")
comment = "\n".join(lines)
print(comment)
# Post PR comment
git_token = os.environ.get("GIT_TOKEN", "")
git_url = os.environ.get("GIT_URL", "")
if git_token and git_url:
api_url = f"{git_url}/api/v1/repos/{os.environ['REPO']}/issues/{os.environ['PR_NUMBER']}/comments"
body = json.dumps({"body": comment}).encode()
req = urllib.request.Request(api_url, data=body, method="POST", headers={
"Authorization": f"token {git_token}",
"Content-Type": "application/json",
})
urllib.request.urlopen(req)
print(f"Posted comment to PR #{os.environ['PR_NUMBER']}")
SCRIPT

View File

@ -8,103 +8,98 @@ on:
- "state/*.json"
jobs:
detect:
reconcile:
runs-on: ubuntu-latest
outputs:
envs: ${{ steps.changed.outputs.envs }}
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 2
- name: Detect changed environments
id: changed
run: |
FILES=$(git diff --name-only HEAD~1 HEAD -- 'state/*.json')
ENVS="[]"
for f in $FILES; do
ENV=$(basename "$f" .json)
ENVS=$(echo "$ENVS" | jq -c ". + [\"$ENV\"]")
done
echo "envs=$ENVS" >> "$GITHUB_OUTPUT"
echo "Changed environments: $ENVS"
reconcile:
needs: detect
runs-on: ubuntu-latest
if: needs.detect.outputs.envs != '[]'
strategy:
matrix:
env: ${{ fromJson(needs.detect.outputs.envs) }}
steps:
- uses: actions/checkout@v4
- name: Resolve environment secrets
id: env
run: |
ENV_UPPER=$(echo "${{ matrix.env }}" | tr '[:lower:]-' '[:upper:]_')
echo "token_key=${ENV_UPPER}_RECONCILER_TOKEN" >> "$GITHUB_OUTPUT"
echo "url_key=${ENV_UPPER}_RECONCILER_URL" >> "$GITHUB_OUTPUT"
echo "age_key=${ENV_UPPER}_AGE_PUBLIC_KEY" >> "$GITHUB_OUTPUT"
- name: Sync events
- name: Reconcile changed environments
env:
RECONCILER_TOKEN: ${{ secrets[steps.env.outputs.token_key] }}
RECONCILER_URL: ${{ secrets[steps.env.outputs.url_key] }}
TEST_RECONCILER_TOKEN: ${{ secrets.TEST_RECONCILER_TOKEN }}
TEST_RECONCILER_URL: ${{ secrets.TEST_RECONCILER_URL }}
DEV_RECONCILER_TOKEN: ${{ secrets.DEV_RECONCILER_TOKEN }}
DEV_RECONCILER_URL: ${{ secrets.DEV_RECONCILER_URL }}
PROD_RECONCILER_TOKEN: ${{ secrets.PROD_RECONCILER_TOKEN }}
PROD_RECONCILER_URL: ${{ secrets.PROD_RECONCILER_URL }}
run: |
if [ -z "$RECONCILER_URL" ] || [ -z "$RECONCILER_TOKEN" ]; then
echo "No secrets configured for environment '${{ matrix.env }}' — skipping"
exit 0
fi
curl -sf \
-X POST \
-H "Authorization: Bearer ${RECONCILER_TOKEN}" \
"${RECONCILER_URL}/sync-events"
python3 <<'SCRIPT'
import json, os, subprocess, urllib.request, sys
- name: Pull latest (poller may have committed)
run: git pull --rebase
# Detect changed state files
diff = subprocess.run(
["git", "diff", "--name-only", "HEAD~1", "HEAD", "--", "state/*.json"],
capture_output=True, text=True, check=True,
)
envs = [os.path.basename(f).replace(".json", "") for f in diff.stdout.strip().split("\n") if f.strip()]
- name: Apply reconcile
id: reconcile
env:
RECONCILER_TOKEN: ${{ secrets[steps.env.outputs.token_key] }}
RECONCILER_URL: ${{ secrets[steps.env.outputs.url_key] }}
run: |
RESPONSE=$(curl -sf \
-X POST \
-H "Authorization: Bearer ${RECONCILER_TOKEN}" \
-H "Content-Type: application/json" \
-d @state/${{ matrix.env }}.json \
"${RECONCILER_URL}/reconcile")
echo "response<<EOF" >> "$GITHUB_OUTPUT"
echo "$RESPONSE" >> "$GITHUB_OUTPUT"
echo "EOF" >> "$GITHUB_OUTPUT"
if not envs:
print("No state files changed")
exit(0)
STATUS=$(echo "$RESPONSE" | jq -r '.status')
if [ "$STATUS" = "error" ]; then
echo "Reconcile failed for ${{ matrix.env }}"
echo "$RESPONSE" | jq .
exit 1
fi
print(f"Changed environments: {envs}")
failed = []
- name: Encrypt and upload setup keys
if: success()
env:
AGE_PUBLIC_KEY: ${{ secrets[steps.env.outputs.age_key] }}
run: |
KEYS=$(echo '${{ steps.reconcile.outputs.response }}' | jq -r '.created_keys // empty')
if [ -n "$KEYS" ] && [ "$KEYS" != "{}" ] && [ "$KEYS" != "null" ] && [ -n "$AGE_PUBLIC_KEY" ]; then
echo "$KEYS" | age -r "$AGE_PUBLIC_KEY" -o setup-keys-${{ matrix.env }}.age
echo "Setup keys for ${{ matrix.env }} encrypted"
else
echo "No new keys created for ${{ matrix.env }}"
exit 0
fi
for env in envs:
key = env.upper().replace("-", "_")
token = os.environ.get(f"{key}_RECONCILER_TOKEN", "")
url = os.environ.get(f"{key}_RECONCILER_URL", "")
- name: Upload artifact
if: success()
uses: actions/upload-artifact@v4
with:
name: setup-keys-${{ matrix.env }}
path: setup-keys-${{ matrix.env }}.age
if-no-files-found: ignore
if not token or not url:
print(f"[{env}] No secrets configured — skipping")
continue
# Sync events first
try:
req = urllib.request.Request(
f"{url}/sync-events", method="POST",
headers={"Authorization": f"Bearer {token}"},
)
urllib.request.urlopen(req)
print(f"[{env}] Synced events")
except Exception as e:
print(f"[{env}] Sync events failed (non-fatal): {e}")
# Apply reconcile
with open(f"state/{env}.json", "rb") as f:
state_data = f.read()
req = urllib.request.Request(
f"{url}/reconcile",
data=state_data,
method="POST",
headers={
"Authorization": f"Bearer {token}",
"Content-Type": "application/json",
},
)
try:
resp = urllib.request.urlopen(req)
data = json.loads(resp.read())
except Exception as e:
print(f"[{env}] Reconcile FAILED: {e}")
failed.append(env)
continue
status = data.get("status", "ok")
if status == "error":
print(f"[{env}] Reconcile returned error:")
print(json.dumps(data, indent=2))
failed.append(env)
continue
summary = data.get("summary", {})
print(f"[{env}] Reconcile OK: "
f"{summary.get('created',0)} created, "
f"{summary.get('updated',0)} updated, "
f"{summary.get('deleted',0)} deleted")
keys = data.get("created_keys", {})
if keys:
print(f"[{env}] Created setup keys: {list(keys.keys())}")
if failed:
print(f"\nFailed environments: {failed}")
sys.exit(1)
SCRIPT

227
poc/TEST-SCENARIOS.md Normal file
View File

@ -0,0 +1,227 @@
# Test Scenarios for NetBird GitOps PoC
Test instance: `vps-a.networkmonitor.cc`
State file: `state/test.json`
Gitea: `gitea.vps-a.networkmonitor.cc`
Current state on the instance: 2 groups, 3 setup keys, 1 policy, 1 user.
Each scenario: create a branch, edit `state/test.json`, push, open PR (dry-run),
review plan, merge (apply), verify on NetBird dashboard.
---
## Scenario 1: Add a new group and policy
**Goal:** Verify creating multiple resources in one PR.
**Changes to `state/test.json`:**
Add a new group `observers` and a policy allowing observers to see
ground-stations:
```json
"groups": {
"ground-stations": { "peers": [] },
"pilots": { "peers": [] },
"observers": { "peers": [] }
},
"policies": {
"pilots-to-gs": { ... },
"observers-to-gs": {
"description": "Observers can view ground stations",
"enabled": true,
"sources": ["observers"],
"destinations": ["ground-stations"],
"bidirectional": false,
"protocol": "all",
"action": "accept"
}
}
```
**Expected dry-run:**
- Create: group `observers`, policy `observers-to-gs`
**Verify after merge:**
- Dashboard shows the `observers` group
- Policy `observers-to-gs` exists with correct sources/destinations
---
## Scenario 2: Update an existing policy
**Goal:** Verify update detection works.
**Changes to `state/test.json`:**
Disable the `pilots-to-gs` policy:
```json
"pilots-to-gs": {
"enabled": false,
...
}
```
**Expected dry-run:**
- Update: policy `pilots-to-gs`
**Verify after merge:**
- Policy shows as disabled on the dashboard
---
## Scenario 3: Delete a resource
**Goal:** Verify deletion works safely.
**Changes to `state/test.json`:**
Remove `Pilot-Vlad-2` from `setup_keys` (delete the entire key).
**Expected dry-run:**
- Delete: setup_key `Pilot-Vlad-2`
**Verify after merge:**
- Setup key no longer appears on the dashboard
---
## Scenario 4: Enroll a peer (full lifecycle)
**Goal:** Verify the enrollment detection and peer rename flow.
**Prerequisite:** Runner and Gitea token must be configured for the reconciler
poller. Run ansible-playbook with filled vault.yml first.
**Steps:**
1. Make sure `state/test.json` has an unenrolled setup key, e.g.:
```json
"GS-TestHawk-1": {
"type": "one-off",
"expires_in": 604800,
"usage_limit": 1,
"auto_groups": ["ground-stations"],
"enrolled": false
}
```
2. Copy the setup key value from the NetBird dashboard (or from a previous
reconcile run's created_keys output)
3. Enroll a peer:
```bash
sudo netbird up --management-url https://vps-a.networkmonitor.cc --setup-key <KEY>
```
4. Wait for the poller to detect enrollment (~30 seconds)
5. Verify:
- Peer is renamed to `GS-TestHawk-1` on the dashboard
- `state/test.json` in Gitea repo has `"enrolled": true` for that key
- The commit was made by the reconciler automatically
---
## Scenario 5: Multi-resource create (bigger change)
**Goal:** Test a realistic initial deployment scenario.
**Changes to `state/test.json`:**
Add network, posture check, and DNS in one PR:
```json
"posture_checks": {
"geo-restrict-ua": {
"description": "Allow only UA/PL locations",
"checks": {
"geo_location_check": {
"locations": [
{ "country_code": "UA" },
{ "country_code": "PL" }
],
"action": "allow"
}
}
}
},
"dns": {
"nameserver_groups": {
"cloudflare": {
"nameservers": [
{ "ip": "1.1.1.1", "ns_type": "udp", "port": 53 }
],
"domains": [],
"enabled": true,
"primary": true,
"groups": ["pilots", "ground-stations"]
}
}
}
```
**Expected dry-run:**
- Create: posture_check `geo-restrict-ua`, dns `cloudflare`
**Verify after merge:**
- Posture check appears in dashboard
- DNS nameserver group exists
---
## Scenario 6: No-op (idempotency check)
**Goal:** Verify that pushing state that matches what's already deployed
produces no operations.
**Steps:**
1. Export current state:
```bash
deno task export -- \
--netbird-api-url https://vps-a.networkmonitor.cc/api \
--netbird-api-token <TOKEN> > state/test.json
```
2. Push to a branch, open PR
3. **Expected dry-run:** "No changes detected."
---
## Scenario 7: Conflicting change (error handling)
**Goal:** Verify the reconciler handles errors gracefully.
**Steps:**
1. Reference a group that doesn't exist in a policy:
```json
"bad-policy": {
"enabled": true,
"sources": ["nonexistent-group"],
"destinations": ["pilots"],
"bidirectional": true
}
```
2. This should fail schema validation before hitting the API.
3. **Expected:** CI job fails with a clear error message.
---
## Quick reference
```bash
# Create test branch
git checkout -b test-scenario-N
# Edit state/test.json
# Push and open PR
git push poc test-scenario-N
# After testing, clean up
git checkout main && git branch -D test-scenario-N
```

View File

@ -12,18 +12,21 @@
"type": "one-off",
"expires_in": 604800,
"usage_limit": 1,
"auto_groups": [
"ground-stations"
],
"auto_groups": ["ground-stations"],
"enrolled": false
},
"Pilot-TestHawk-1": {
"type": "one-off",
"expires_in": 604800,
"usage_limit": 1,
"auto_groups": [
"pilots"
],
"auto_groups": ["pilots"],
"enrolled": false
},
"Pilot-Vlad-2": {
"type": "one-off",
"expires_in": 604800,
"usage_limit": 1,
"auto_groups": ["pilots"],
"enrolled": false
}
},
@ -31,12 +34,8 @@
"pilots-to-gs": {
"description": "",
"enabled": true,
"sources": [
"pilots"
],
"destinations": [
"ground-stations"
],
"sources": ["pilots"],
"destinations": ["ground-stations"],
"bidirectional": true,
"protocol": "all",
"action": "accept",