Update README.md

README_NOMAD_API.md

@@ -0,0 +1,116 @@
+# 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