116 lines
3.5 KiB
Markdown
116 lines
3.5 KiB
Markdown
# 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:
|
|
|
|
1. **Simplified Namespace Handling**:
|
|
- Clear priority order for determining which namespace to use:
|
|
1. Explicitly specified in job spec (highest priority)
|
|
2. Service instance namespace (default: "development")
|
|
- Consistent namespace handling across all API operations
|
|
- Better logging of namespace resolution
|
|
|
|
2. **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
|
|
|
|
3. **Enhanced Error Handling**:
|
|
- Improved error messages with more context
|
|
- Added logging of API responses for better troubleshooting
|
|
- Returns namespace information in responses
|
|
|
|
4. **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
|
|
|
|
1. 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")
|
|
|
|
2. Install test dependencies:
|
|
```
|
|
pip install pytest pytest-cov
|
|
```
|
|
|
|
### Running the Tests
|
|
|
|
From the project root directory:
|
|
|
|
```bash
|
|
python -m pytest tests/test_nomad_service.py -v
|
|
```
|
|
|
|
Add coverage reporting:
|
|
|
|
```bash
|
|
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
|
|
|
|
```powershell
|
|
Invoke-RestMethod -Uri "http://pjmldk01.ds.meisheng.group:4646/v1/jobs?namespace=development" -Method GET
|
|
```
|
|
|
|
### Get Job Details
|
|
|
|
```powershell
|
|
Invoke-RestMethod -Uri "http://pjmldk01.ds.meisheng.group:4646/v1/job/example-job?namespace=development" -Method GET
|
|
```
|
|
|
|
### Start a Job
|
|
|
|
```powershell
|
|
$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
|
|
|
|
```powershell
|
|
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
|
|
|
|
1. **Job Not Found**: Ensure you're specifying the correct namespace
|
|
2. **Failed to Start Job**: Check job specification format and resource requirements
|
|
3. **Permission Denied**: Verify ACL token has appropriate permissions
|
|
|
|
### Debugging Tips
|
|
|
|
1. Check the application logs for detailed error messages
|
|
2. Use the `-v` flag with pytest to see more verbose output
|
|
3. Try direct API requests to isolate application vs. Nomad API issues |