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:

```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
```