nomad_mcp/nomad_job_api_docs.md

# Nomad Job Management API Documentation

## Overview

This document outlines the process for managing jobs (starting, stopping, and monitoring) in Hashicorp Nomad via its HTTP API. These operations are essential for deploying, updating, and terminating workloads in a Nomad cluster.

## Prerequisites

- A running Nomad cluster
- Network access to the Nomad API endpoint (default port 4646)
- Proper authentication credentials (if ACLs are enabled)

## API Basics

- Base URL: `http://<nomad-server>:4646`
- API Version: `v1`
- Content Type: `application/json`

## Job Lifecycle

A Nomad job goes through multiple states during its lifecycle:

1. **Pending**: The job has been submitted but not yet scheduled
2. **Running**: The job is active and its tasks are running
3. **Dead**: The job has been stopped or failed

## Job Management Operations

### 1. List Jobs

List all jobs in a namespace to get an overview of the cluster's workloads.

```
GET /v1/jobs?namespace=<namespace>
```

Example PowerShell command:
```powershell
Invoke-RestMethod -Uri "http://nomad-server:4646/v1/jobs?namespace=development" -Method GET
```

### 2. Starting a Job

Starting a job in Nomad involves registering a job specification with the API server.

```
POST /v1/jobs
```

With a job specification in the request body:

```json
{
  "Job": {
    "ID": "example-job",
    "Name": "example-job",
    "Namespace": "development",
    "Type": "service",
    "Datacenters": ["dc1"],
    "TaskGroups": [
      {
        "Name": "app",
        "Count": 1,
        "Tasks": [
          {
            "Name": "server",
            "Driver": "docker",
            "Config": {
              "image": "nginx:latest"
            }
          }
        ]
      }
    ]
  }
}
```

Example PowerShell command:
```powershell
$jobSpec = @{ 
  Job = @{
    ID = "example-job"
    # ... other job properties
  }
} | ConvertTo-Json -Depth 20

Invoke-RestMethod -Uri "http://nomad-server:4646/v1/jobs" -Method POST -Body $jobSpec -ContentType "application/json"
```

To start an existing (stopped) job:
1. Retrieve the job specification with `GET /v1/job/<job_id>?namespace=<namespace>`
2. Set `Stop = false` in the job specification
3. Submit the modified spec with `POST /v1/jobs`

### 3. Stopping a Job

Stopping a job is simpler and requires a DELETE request:

```
DELETE /v1/job/<job_id>?namespace=<namespace>
```

This marks the job for stopping but preserves its configuration in Nomad.

Example PowerShell command:
```powershell
Invoke-RestMethod -Uri "http://nomad-server:4646/v1/job/example-job?namespace=development" -Method DELETE
```

Optional parameters:
- `purge=true` - Completely removes the job from Nomad's state

### 4. Reading Job Status

To check the status of a job:

```
GET /v1/job/<job_id>?namespace=<namespace>
```

This returns detailed information about the job, including:
- Current status (`running`, `pending`, `dead`)
- Task group count and health
- Version information

Example PowerShell command:
```powershell
Invoke-RestMethod -Uri "http://nomad-server:4646/v1/job/example-job?namespace=development" -Method GET
```

### 5. Reading Job Allocations

To see all allocations (instances) of a job:

```
GET /v1/job/<job_id>/allocations?namespace=<namespace>
```

This returns information about where the job is running and in what state.

Example PowerShell command:
```powershell
Invoke-RestMethod -Uri "http://nomad-server:4646/v1/job/example-job/allocations?namespace=development" -Method GET
```

## Common Issues and Troubleshooting

### Namespace Issues

Nomad requires specifying the correct namespace when managing jobs. If not specified, operations will default to the "default" namespace, which may not contain your jobs.

### Job Specification Formatting

When starting a job, ensure the job specification is properly wrapped in a "Job" object:

```json
{
  "Job": {
    // job details go here
  }
}
```

### Error Codes

- **400**: Bad request, often due to malformed job specification
- **403**: Permission denied, check ACL tokens
- **404**: Job not found, verify job ID and namespace
- **500**: Server error, check Nomad server logs

## Best Practices

1. Always specify the namespace explicitly in API calls
2. Use the job's existing specification when updating, to avoid losing configuration
3. Log API responses to aid in troubleshooting
4. Implement proper error handling for API failures
5. Consider using official client libraries instead of direct API calls when possible

## Conclusion

The Nomad HTTP API provides a robust interface for job lifecycle management. Understanding these API workflows is crucial for building reliable automation and integration with Nomad clusters.