netbird-gitops/poc/TEST-SCENARIOS.md

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:

"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:

"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.:

   "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:

   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:

"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:

   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:

   "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

# 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