132 lines
5.5 KiB
Markdown
132 lines
5.5 KiB
Markdown
# v1 → v2 Breaking Changes
|
|
|
|
This document lists breaking changes when upgrading from IPAM v1.x to v2.0.
|
|
|
|
**Upgrade steps:** pull/deploy the v2 image or code, restart the application. Database migrations run automatically on startup via `init_db()`. No manual SQL is required for standard upgrades.
|
|
|
|
---
|
|
|
|
## Removed features
|
|
|
|
| Feature | v1 | v2 |
|
|
|---------|----|----|
|
|
| Response caching / rate limiting | Flask-Limiter + in-app cache layer | Removed — direct DB queries |
|
|
| In-app update checker | `/check_update` + header toast | Removed — check releases yourself |
|
|
| Feature flags | Admin toggles for racks, tags, IP notes, bulk ops | Removed — features always available, gated by permissions only |
|
|
| Backup & restore | Admin UI + `/backup/*` routes | Removed — use your own DB backup strategy |
|
|
| Help page | `/help` | Removed |
|
|
| Interactive API docs | `/api-docs` web page | Removed — see [API.md](API.md) |
|
|
| Custom field “searchable” flag | UI checkbox + DB column | Removed — was never wired to search |
|
|
| Device types | Device type CRUD, `device_type_id` on devices, rack placement filters | Removed — devices are untyped; use tags or custom fields instead |
|
|
|
|
### Dependencies removed
|
|
|
|
- `requests` (update checker)
|
|
- `Flask-Limiter` and the custom cache module (already gone in v2 prep)
|
|
|
|
---
|
|
|
|
## Removed routes
|
|
|
|
| Method | v1 path | Notes |
|
|
|--------|---------|-------|
|
|
| GET | `/check_update` | Update checker |
|
|
| GET/POST | `/backup`, `/backup/create`, `/backup/download/<file>`, `/backup/restore`, `/backup/delete/<file>` | Backup UI |
|
|
| GET | `/help` | Help page |
|
|
| GET | `/api-docs` | Swagger-style docs |
|
|
| GET/POST | `/admin/feature_flags` | Feature flag toggles |
|
|
| GET | `/custom_fields/<entity_type>` | Duplicate of API; use `/api/v1/custom_fields/{entity_type}` |
|
|
| GET | `/api/device/<id>/ip_history` | Moved — see below |
|
|
| GET | `/api/ip/<ip>/history` | Moved — see below |
|
|
| GET/POST/PUT/DELETE | `/api/v1/device-types`, `/api/v2/device-types` | Device types removed |
|
|
|
|
---
|
|
|
|
## API changes
|
|
|
|
### v2 is API-only + Vue SPA
|
|
|
|
v2 removes **all Jinja/HTML routes**. The UI is a Vue 3 SPA served from `static/dist/`. All functionality goes through `/api/v2/*`.
|
|
|
|
| v1 | v2 |
|
|
|----|-----|
|
|
| `/api/v1/*` | **`/api/v2/*`** (v1 removed) |
|
|
| Session via HTML login forms | `POST /api/v2/auth/login` + session cookie |
|
|
| API key only on API routes | **Same routes** accept session cookie **or** API key |
|
|
| `{ "devices": [...] }` list responses | **`{ "items": [...] }`** for all list endpoints |
|
|
| `{ "tags" }`, `{ "users" }`, `{ "roles" }`, `{ "racks" }`, `{ "logs" }`, `{ "fields" }` wrappers | **`{ "items" }`** (audit also includes `total`; devices-by-tag includes `meta`) |
|
|
|
|
### Version
|
|
|
|
`GET /api/v2/info` reports `"api_version": "2.0"`.
|
|
|
|
### IP history endpoints
|
|
|
|
| v1 (removed) | v2 replacement | Auth |
|
|
|--------------|----------------|------|
|
|
| `GET /api/device/<id>/ip_history` | `GET /api/v2/devices/<id>/ip-history` | Session or API key |
|
|
| `GET /api/ip/<ip>/history` | `GET /api/v2/ips/<ip>/history` | Session or API key |
|
|
|
|
### Audit logging for API calls
|
|
|
|
v1 logged **every** API request (including GETs) to the audit log as `api_usage`.
|
|
|
|
v2 logs **mutating** requests only: `POST`, `PUT`, `DELETE`, `PATCH`. GET traffic is no longer audited. If you relied on GET audit entries for compliance, adjust your monitoring.
|
|
|
|
---
|
|
|
|
## Database migrations (automatic)
|
|
|
|
On startup, v2 runs these migrations against existing databases:
|
|
|
|
1. **Drop `FeatureFlags` table** — feature flags removed
|
|
2. **Drop `CustomFieldDefinition.searchable` column** — if present
|
|
3. **Remove orphaned permission `view_help`** — help page removed
|
|
4. **Drop `Device.device_type_id` column and `DeviceType` table** — device types removed
|
|
5. **Remove device-type permissions** — `view_device_types`, `add_device_type`, etc.
|
|
|
|
No data loss for core IPAM entities (subnets, IPs, devices, racks, tags, users, audit log). Device type labels are not migrated; use tags or custom fields if you need classification.
|
|
|
|
---
|
|
|
|
## Permissions & sessions
|
|
|
|
- **`view_help`** permission is removed from the database on upgrade.
|
|
- **Device-type permissions** (`view_device_types`, `add_device_type`, etc.) are removed on upgrade.
|
|
- Feature-flag toggles no longer hide UI; use **roles and permissions** instead.
|
|
- Permissions are **cached in the session at login**. If an admin changes a user's role, that user must **log out and back in** for permission changes to take effect.
|
|
|
|
---
|
|
|
|
## Configuration
|
|
|
|
No new required environment variables. Removed features did not introduce new config keys.
|
|
|
|
Docker images no longer need a `/backups` volume mount for in-app backup (remove if you added it only for IPAM backup).
|
|
|
|
---
|
|
|
|
## Codebase layout (operators / fork maintainers)
|
|
|
|
| v1 | v2 |
|
|
|----|----|
|
|
| `app.py` + `routes.py` + `cache.py` + `totp_utils.py` | Single `app.py` + `db.py` |
|
|
| `templates/`, legacy `static/js` | **Deleted** — replaced by `frontend/` → `static/dist/` |
|
|
| Server-rendered Tailwind | Vue 3 + Vite + Tailwind (auto light/dark, cyan accents) |
|
|
|
|
---
|
|
|
|
## Recommended pre-upgrade checklist
|
|
|
|
1. **Back up your MariaDB/MySQL database** using your normal tooling (`mysqldump`, volume snapshot, etc.).
|
|
2. Note any integrations using removed routes (update checker, backup API, legacy IP history paths).
|
|
3. Deploy v2 and restart the container/process once.
|
|
4. Verify login, home page, devices, and one API call with your API key.
|
|
5. Have affected users re-login if roles were changed recently.
|
|
|
|
---
|
|
|
|
## Questions
|
|
|
|
For API reference after upgrade, see [API.md](API.md).
|