zabbix/zabbix-graphql-api
1
0
Fork 0
Code Pull requests Activity

feat: verify and enhance compatibility with Zabbix 6.0, 6.2, 6.4, and 7.0

Browse source 
This commit comprehensive updates the API to ensure full compatibility across all major Zabbix versions (6.0 LTS, 6.2, 6.4, and 7.0 LTS) and introduces a local development environment for multi-version testing.

Verified Zabbix Versions:
- Zabbix 7.0 (LTS): Full support, including native `history.push` for telemetry.
- Zabbix 6.4: Supported (excluding `history.push`); uses `hostgroup.propagate` and UUID-based matching.
- Zabbix 6.2: Supported (excluding `history.push`); uses `hostgroup.propagate` and `templategroup.*` methods.
- Zabbix 6.0 (LTS): Supported (excluding `history.push`); includes specific fallbacks:
    - JSON-RPC: Restored `auth` field in request body for versions lacking Bearer token support.
    - Permissions: Implemented name-based fallback for host/template groups (no UUIDs in 6.0).
    - Group Expansion: Automatic manual expansion of group rights during import.
    - API Methods: Fallback from `templategroup.*` to `hostgroup.*` methods.

Key Technical Changes:
- Local Development: Added `zabbix-local` Docker Compose profile to launch a complete Zabbix stack (Server, Web, Postgres) from scratch with dynamic versioning via `ZABBIX_VERSION`.
- Query Optimization: Refined dynamic field selection to handle implied fields and ensure consistent output regardless of initial Zabbix parameters.
- Documentation:
    - New `local_development.md` HOWTO guide.
    - Updated `README.md` with detailed version compatibility matrix.
    - Expanded `roadmap.md` with achieved milestones.
- Testing:
    - Updated entire Jest test suite (23 suites, 96 tests) to be version-aware and robust against naming collisions.
    - Enhanced Smoketest and Regression Test executors with better cleanup and error reporting.
This commit is contained in:
Andreas Hilbig 2026-02-04 04:41:36 +01:00
parent ec6ed422b1
commit 14a0df4c18
21 changed files with 397 additions and 111 deletions
Download patch file Download diff file Expand all files Collapse all files

88
docs/howtos/local_development.md Normal file
View file

@ -0,0 +1,88 @@
# 💻 Local Development Environment
This guide provides detailed instructions on how to set up a fully isolated local development environment for the Zabbix GraphQL API using Docker Compose.
## 🚀 Overview
The project includes a Docker Compose profile that launches a complete Zabbix stack alongside the GraphQL API and MCP server. This allows you to develop and test features against different Zabbix versions without needing an external Zabbix installation.
### Included Services
- **`zabbix-graphql-api`**: The main GraphQL server.
- **`apollo-mcp-server`**: The Model Context Protocol server for AI integration.
- **`postgres-server`**: PostgreSQL 16 database for Zabbix.
- **`zabbix-server`**: Zabbix Server (PostgreSQL version).
- **`zabbix-web`**: Zabbix Web interface (Nginx/PostgreSQL).
## 🛠️ Step-by-Step Setup
### 1. Start the Environment
Use the `zabbix-local` profile to start all services. You can optionally specify the Zabbix version using the `ZABBIX_VERSION` environment variable.
```bash
# Start the latest 7.0 (default)
docker compose --profile zabbix-local up -d
# Start Zabbix 6.0 (LTS)
ZABBIX_VERSION=alpine-6.0-latest docker compose --profile zabbix-local up -d
```
### 2. Configure Zabbix
Once the containers are running, you need to perform a minimal setup in the Zabbix UI:
1. Open `http://localhost:8080` in your browser.
2. Log in with the default credentials:
- **User**: `Admin`
- **Password**: `zabbix`
3. Navigate to **Administration** > **Users** > **API tokens**.
4. Create a new token for the `Admin` user (or a dedicated service user) and copy it.
5. **Create Base Host Group**: The API requires a base host group to exist for importing devices.
- Navigate to **Configuration** > **Host groups** (or **Data collection** > **Host groups** in Zabbix 7.0).
- Create a host group named `Roadwork` (or the value of `ZABBIX_EDGE_DEVICE_BASE_GROUP` in your `.env`).
- **Note**: If your base group is nested (e.g., `Roadwork/Devices`), ensure the full path exists. Zabbix does not automatically create parent groups when creating child groups via the API.
### 3. Connect the API
To connect the GraphQL API to your local Zabbix instance, update your `.env` file with the following values (referenced in `samples/zabbix-local.env`):
```env
# Internal Docker network URL
ZABBIX_BASE_URL=http://zabbix-web:8080/
# The token you created in Step 2
ZABBIX_PRIVILEGE_ESCALATION_TOKEN=your-newly-created-token
```
### 4. Restart the API
Apply the configuration by restarting the API container:
```bash
docker compose restart zabbix-graphql-api
```
## ✅ Verification
You can verify the setup by running a simple query against the local API:
```bash
curl -X POST -H "Content-Type: application/json" \
-d '{"query": "{ apiVersion zabbixVersion }"}' \
http://localhost:4001/
```
The `zabbixVersion` should match the version you specified in `ZABBIX_VERSION`.
## 💡 Advanced Usage
### Data Persistence
Zabbix data is stored in a named Docker volume called `zbx_db_data`. This ensures that your configuration, templates, and hosts are preserved even if you stop or remove the containers.
To perform a clean reset of the environment:
```bash
docker compose --profile zabbix-local down -v
```
### Testing Multiple Versions
The local environment is perfect for testing the API's version-specific logic (e.g. `history.push` vs `zabbix_sender`). Simply change the `ZABBIX_VERSION` variable and restart the stack.
Supported tags can be found on the [Zabbix Docker Hub](https://hub.docker.com/u/zabbix).
---
**Related Guide**: [Technical Maintenance](./maintenance.md)
**Related Reference**: [Zabbix Version Compatibility](../../README.md#-zabbix-version-compatibility)