3.5 KiB
Nomad API Integration
This document explains how the Nomad API integration works in this application, the recent improvements made, and how to test the functionality.
Overview
This application uses Hashicorp Nomad for job orchestration, interacting with Nomad through its HTTP API. The integration allows starting, stopping, and monitoring jobs in Nomad.
Recent Improvements
The following improvements have been made to the Nomad service integration:
-
Simplified Namespace Handling:
- Clear priority order for determining which namespace to use:
- Explicitly specified in job spec (highest priority)
- Service instance namespace (default: "development")
- Consistent namespace handling across all API operations
- Better logging of namespace resolution
- Clear priority order for determining which namespace to use:
-
Standardized Job Specification Formatting:
- Consistent normalization of job specifications to ensure proper structure
- Always ensures job specs are wrapped in a "Job" key as required by Nomad
- Maintains any existing structure while normalizing as needed
-
Enhanced Error Handling:
- Improved error messages with more context
- Added logging of API responses for better troubleshooting
- Returns namespace information in responses
-
Automated Testing:
- Added pytest tests to verify job start/stop functionality
- Tests cover different job specification formats
- Auto-cleanup of test jobs
How to Run Tests
Prerequisites
-
Set up the environment variables:
NOMAD_ADDR
: URL of your Nomad server (e.g.,http://pjmldk01.ds.meisheng.group:4646
)NOMAD_TOKEN
: Authentication token (if your Nomad cluster uses ACLs)NOMAD_NAMESPACE
: Default namespace to use (defaults to "development")
-
Install test dependencies:
pip install pytest pytest-cov
Running the Tests
From the project root directory:
python -m pytest tests/test_nomad_service.py -v
Add coverage reporting:
python -m pytest tests/test_nomad_service.py --cov=app.services.nomad_client -v
Manual API Testing
You can use PowerShell to test Nomad API operations directly:
List Jobs
Invoke-RestMethod -Uri "http://pjmldk01.ds.meisheng.group:4646/v1/jobs?namespace=development" -Method GET
Get Job Details
Invoke-RestMethod -Uri "http://pjmldk01.ds.meisheng.group:4646/v1/job/example-job?namespace=development" -Method GET
Start a Job
$jobSpec = @{
"Job" = @{
"ID" = "example-job"
"Name" = "example-job"
"Namespace" = "development"
# Other job properties
}
} | ConvertTo-Json -Depth 20
Invoke-RestMethod -Uri "http://pjmldk01.ds.meisheng.group:4646/v1/jobs" -Method POST -Body $jobSpec -ContentType "application/json"
Stop a Job
Invoke-RestMethod -Uri "http://pjmldk01.ds.meisheng.group:4646/v1/job/example-job?namespace=development" -Method DELETE
API Documentation
For more comprehensive documentation on the Nomad API integration, refer to the nomad_job_api_docs.md
file.
Troubleshooting
Common Issues
- Job Not Found: Ensure you're specifying the correct namespace
- Failed to Start Job: Check job specification format and resource requirements
- Permission Denied: Verify ACL token has appropriate permissions
Debugging Tips
- Check the application logs for detailed error messages
- Use the
-v
flag with pytest to see more verbose output - Try direct API requests to isolate application vs. Nomad API issues