feat: improve Zabbix multi-version compatibility and introduce local development environment
This update enhances compatibility across multiple Zabbix versions and introduces tools for easier local development and testing. Key improvements and verified version support: - Verified Zabbix version support: 6.2, 6.4, 7.0, and 7.4. - Version-specific feature handling: - `history.push` is enabled only for Zabbix 7.0+; older versions skip it with a clear error or notice. - Conditional JSON-RPC authentication: the `auth` field is automatically added to the request body for versions older than 6.4. - Implemented static Zabbix version caching in the datasource to minimize redundant API calls. - Query optimization refinements: - Added mapping for implied fields (e.g., `state` -> `items`, `deviceType` -> `tags`). - Automatically prune unnecessary Zabbix parameters (like `selectItems` or `selectTags`) when not requested. - Local development environment: - Added a new `zabbix-local` Docker Compose profile that includes PostgreSQL, Zabbix Server, and Zabbix Web. - Supports testing different versions by passing the `ZABBIX_VERSION` environment variable (e.g., 6.2, 6.4, 7.0, 7.4). - Provided a sample environment file at `samples/zabbix-local.env`. - Documentation and Roadmap: - Updated README with a comprehensive version compatibility matrix and local environment instructions. - Created a new guide: `docs/howtos/local_development.md`. - Updated maintenance guides and added "Local Development Environment" as an achieved milestone in the roadmap. - Test suite enhancements: - Improved Smoketest and RegressionTest executors with more reliable resource cleanup and error reporting. - Made tests version-aware to prevent failures on older Zabbix instances. BREAKING CHANGE: Dropped Zabbix 6.0 specific workarounds; the minimum supported version is now 6.2.
This commit is contained in:
parent
7c2dee2b6c
commit
fb5e9cbe81
36 changed files with 470 additions and 172 deletions
38
README.md
38
README.md
|
|
@ -52,7 +52,7 @@ Before you begin, ensure you have met the following requirements:
|
|||
|
||||
- **Node.js**: Version 24 (LTS) or higher recommended.
|
||||
- **Docker**: Version 27 or higher and **Docker Compose** v2.29 or higher (use `docker compose` instead of `docker-compose`).
|
||||
- **Zabbix**: A running Zabbix instance (compatible with Zabbix 6.0+) with API access.
|
||||
- **Zabbix**: A running Zabbix instance (**Zabbix 6.2+ mandatory**) with API access. See [Zabbix Version Compatibility](#-zabbix-version-compatibility) for details.
|
||||
- **Zabbix Super Admin Token** (for full functionality / privilege escalation).
|
||||
- **Zabbix User Access** (groups and roles depending on your use case).
|
||||
|
||||
|
|
@ -81,6 +81,20 @@ Builds the project and runs the compiled code:
|
|||
npm run prod
|
||||
```
|
||||
|
||||
#### 🐳 Local Zabbix Environment
|
||||
For development and testing, you can start a complete environment including Zabbix from scratch:
|
||||
|
||||
```bash
|
||||
# Start with local Zabbix (latest 7.0)
|
||||
docker compose --profile zabbix-local up -d
|
||||
|
||||
# Start with a specific Zabbix version (e.g. 6.4)
|
||||
ZABBIX_VERSION=alpine-6.4-latest docker compose --profile zabbix-local up -d
|
||||
```
|
||||
|
||||
> **Guide**: For detailed setup and configuration of the local environment, see [Local Development Environment](./docs/howtos/local_development.md).
|
||||
> **Important**: On fresh Zabbix installations, you must manually create the base host group (e.g., `Roadwork`) before the API can import devices.
|
||||
|
||||
The API will be available at `http://localhost:4000/`.
|
||||
|
||||
## ⚙️ Configuration
|
||||
|
|
@ -236,7 +250,27 @@ The API version is automatically set during the Docker build process based on th
|
|||
|
||||
### 🔧 Zabbix Version Compatibility
|
||||
|
||||
This API is designed to work with Zabbix 7.4, which is the version it runs productively with. While it may work with earlier versions (like 6.0+), 7.4 is the officially supported and tested version.
|
||||
This API is officially supported and productively used with **Zabbix 7.0 (LTS)**, **7.4**, and newer. It maintains compatibility with **Zabbix 6.4** and **6.2**, with the following version-specific behaviors:
|
||||
|
||||
- **Zabbix 7.0+ (including 7.4)**:
|
||||
- Full feature support.
|
||||
- **History Push**: Uses the native `history.push` API for efficient data ingestion.
|
||||
- **Zabbix 6.4**:
|
||||
- **History Push**: Not supported (requires Zabbix 7.0+). The `pushHistory` mutation returns a clear error.
|
||||
- **Group Propagation**: Fully supported via the `hostgroup.propagate` API.
|
||||
- **UUIDs**: Fully supported for both Host Groups and Template Groups.
|
||||
- **Zabbix 6.2**:
|
||||
- **History Push**: Not supported.
|
||||
- **Authentication**: Fully supported. The API automatically falls back to using the `auth` field in JSON-RPC request bodies since Bearer token headers were only introduced in 6.4.
|
||||
|
||||
#### ⚠️ Dropped Support for Zabbix 6.0
|
||||
Support for Zabbix 6.0 (LTS) has been discontinued due to the excessive complexity of maintaining backward compatibility with its legacy API structure. The high amount of differences between 6.0 and 6.2 would have required several intrusive fallbacks:
|
||||
- **API Methods**: A translation layer to redirect `templategroup.*` calls to `hostgroup.*` methods, as these entities were not yet separated.
|
||||
- **Permission Management**: Manual recursive expansion of group rights during import because `hostgroup.propagate` was unavailable.
|
||||
- **Entity Matching**: Unreliable name-based fallback for host groups due to the lack of UUID support in the 6.0 API.
|
||||
- **JSON-RPC**: Complexity in restoring the `auth` field in request bodies for versions lacking modern Bearer token header support.
|
||||
|
||||
By requiring **Zabbix 6.2+**, the API leverages native modern features, ensuring higher reliability and a more maintainable codebase.
|
||||
|
||||
## 🛠️ Technical Maintenance
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue