GCO Manifest Processor API — API spec sheet¶

Service manifest-processor · OpenAPI 3.1.0 · API version 2.0.0 · 37 endpoints · 11 schemas

Kubernetes manifest submission and management service for GCO (Global Capacity Orchestrator on AWS)

• Machine-readable document: docs/openapi/manifest-processor.json — the FastAPI app.openapi() export (scripts/generate_openapi.py) this sheet is rendered from
• Interactive console (Swagger UI): https://aws-solutions-library-samples.github.io/global-capacity-orchestrator-on-aws/swagger/manifest-processor/
• Catalogue index: README.md · interaction diagram

Endpoints¶

Endpoint details¶

GET /¶

Root endpoint with basic service information and API overview.

• Operation ID: root__get
• Tags: Info

Responses

GET /api/v1/cost/reports¶

List this region's most recent cost report objects in S3.

• Operation ID: list_cost_reports_api_v1_cost_reports_get
• Tags: Cost

Parameters

Responses

POST /api/v1/cost/reports¶

Generate an ad-hoc cost report for the trailing window.

• Operation ID: generate_cost_report_api_v1_cost_reports_post
• Tags: Cost

Request body (required): application/json: CostReportRequest

Responses

GET /api/v1/cost/status¶

Cost monitoring status for this region, including OpenCost health.

• Operation ID: get_cost_status_api_v1_cost_status_get
• Tags: Cost

Responses

GET /api/v1/health¶

Health check endpoint for load balancer health checks.

• Operation ID: health_check_api_v1_health_get
• Tags: Health

Responses

GET /api/v1/jobs¶

List Kubernetes Jobs with pagination and filtering.

• Operation ID: list_jobs_api_v1_jobs_get
• Tags: Jobs

Parameters

Responses

DELETE /api/v1/jobs¶

Bulk delete jobs based on filters.

• Operation ID: bulk_delete_jobs_api_v1_jobs_delete
• Tags: Jobs

Request body (required): application/json: BulkDeleteRequest

Responses

POST /api/v1/jobs/from-template/{name}¶

Create a job from a template with parameter substitution.

• Operation ID: create_job_from_template_api_v1_jobs_from_template__name__post
• Tags: Templates

Parameters

Request body (required): application/json: JobFromTemplateRequest

Responses

GET /api/v1/jobs/{namespace}/{name}¶

Get details of a specific Job, including where its pods were scheduled.

• Operation ID: get_job_api_v1_jobs__namespace___name__get
• Tags: Jobs

Parameters

Responses

DELETE /api/v1/jobs/{namespace}/{name}¶

Delete a Job, optionally requiring its immutable Kubernetes UID.

• Operation ID: delete_job_api_v1_jobs__namespace___name__delete
• Tags: Jobs

Parameters

Responses

GET /api/v1/jobs/{namespace}/{name}/events¶

Get events related to a Job.

• Operation ID: get_job_events_api_v1_jobs__namespace___name__events_get
• Tags: Jobs

Parameters

Responses

GET /api/v1/jobs/{namespace}/{name}/logs¶

Get logs from a Job's pods.

• Operation ID: get_job_logs_api_v1_jobs__namespace___name__logs_get
• Tags: Jobs

Parameters

Responses

GET /api/v1/jobs/{namespace}/{name}/metrics¶

Get resource usage metrics for a Job's pods.

• Operation ID: get_job_metrics_api_v1_jobs__namespace___name__metrics_get
• Tags: Jobs

Parameters

Responses

GET /api/v1/jobs/{namespace}/{name}/pods¶

Get pods belonging to a Job, with the hardware each one landed on.

• Operation ID: get_job_pods_api_v1_jobs__namespace___name__pods_get
• Tags: Jobs

Parameters

Responses

GET /api/v1/jobs/{namespace}/{name}/pods/{pod_name}/logs¶

Get logs from a specific pod belonging to a Job.

• Operation ID: get_pod_logs_api_v1_jobs__namespace___name__pods__pod_name__logs_get
• Tags: Jobs

Parameters

Responses

POST /api/v1/jobs/{namespace}/{name}/retry¶

Retry a failed job by creating a new job from its spec.

• Operation ID: retry_job_api_v1_jobs__namespace___name__retry_post
• Tags: Jobs

Parameters

Responses

POST /api/v1/manifests¶

Submit Kubernetes manifests for processing.

• Operation ID: submit_manifests_api_v1_manifests_post
• Tags: Manifests

Request body (required): application/json: ManifestSubmissionAPIRequest

Responses

POST /api/v1/manifests/validate¶

Validate manifests without applying them.

• Operation ID: validate_manifests_api_v1_manifests_validate_post
• Tags: Manifests

Request body (required): application/json: ManifestSubmissionAPIRequest

Responses

GET /api/v1/manifests/{namespace}/{name}¶

Get the status of a specific resource.

• Operation ID: get_resource_status_api_v1_manifests__namespace___name__get
• Tags: Manifests

Parameters

Responses

DELETE /api/v1/manifests/{namespace}/{name}¶

Delete a specific resource from the cluster.

• Operation ID: delete_resource_api_v1_manifests__namespace___name__delete
• Tags: Manifests

Parameters

Responses

GET /api/v1/policy¶

The validation policy this region actually enforces, as deployed.

Answers "will this cluster admit the job I am about to pay to run?" before submission, so a policy conflict surfaces at plan time instead of after a region has been provisioned and billed.

Reads the live ManifestProcessor instance rather than any config file. A local cdk.json is the input to a deploy, not the state of one: the cluster may have been deployed from a different checkout, and CDK augments trusted_registries with the project's own ECR hostnames at synth time, so the effective allowlist is strictly larger than the configured one.

Three layers govern admission and all three are reported:

1. policy — the front-door checks the manifest processor and the SQS queue processor both apply (they read the same env vars, so neither submission path is a bypass).
2. cluster_enforcement.limit_ranges — per-container ceilings.
3. cluster_enforcement.resource_quotas — namespace aggregate ceilings.

A manifest must clear all three. Layers 2 and 3 are read live from the Kubernetes API and degrade to status="unavailable" rather than failing the whole response.

• Operation ID: get_job_validation_policy_api_v1_policy_get
• Tags: Health

Responses

GET /api/v1/queue/jobs¶

List one bounded page of jobs with optional filters.

• Operation ID: list_queued_jobs_api_v1_queue_jobs_get
• Tags: Job Queue

Parameters

Responses

POST /api/v1/queue/jobs¶

Submit one validated batch/v1 Job exactly once.

• Operation ID: submit_job_to_queue_api_v1_queue_jobs_post
• Tags: Job Queue

Parameters

Request body (required): application/json: QueuedJobRequest

Responses

GET /api/v1/queue/jobs/{job_id}¶

Get details of a specific queued job.

• Operation ID: get_queued_job_api_v1_queue_jobs__job_id__get
• Tags: Job Queue

Parameters

Responses

DELETE /api/v1/queue/jobs/{job_id}¶

Cancel a job only while it remains unclaimed in the queue.

• Operation ID: cancel_queued_job_api_v1_queue_jobs__job_id__delete
• Tags: Job Queue

Parameters

Responses

POST /api/v1/queue/poll¶

Run one immediate queue-worker pass for this region.

The manifest API also runs this same processor continuously when the deployment enables CENTRAL_QUEUE_WORKER_ENABLED. This endpoint remains useful for an authenticated operator-triggered pass and diagnostics.

• Operation ID: poll_and_process_jobs_api_v1_queue_poll_post
• Tags: Job Queue

Parameters

Responses

GET /api/v1/queue/stats¶

Get job queue statistics by region and status.

• Operation ID: get_queue_stats_api_v1_queue_stats_get
• Tags: Job Queue

Responses

GET /api/v1/status¶

Service status endpoint with detailed information.

• Operation ID: get_service_status_api_v1_status_get
• Tags: Health

Responses

GET /api/v1/templates¶

List all job templates.

• Operation ID: list_templates_api_v1_templates_get
• Tags: Templates

Responses

POST /api/v1/templates¶

Create a new job template.

• Operation ID: create_template_api_v1_templates_post
• Tags: Templates

Request body (required): application/json: JobTemplateRequest

Responses

GET /api/v1/templates/{name}¶

Get a specific job template.

• Operation ID: get_template_api_v1_templates__name__get
• Tags: Templates

Parameters

Responses

DELETE /api/v1/templates/{name}¶

Delete a job template.

• Operation ID: delete_template_api_v1_templates__name__delete
• Tags: Templates

Parameters

Responses

GET /api/v1/webhooks¶

List all registered webhooks.

• Operation ID: list_webhooks_api_v1_webhooks_get
• Tags: Webhooks

Parameters

Responses

POST /api/v1/webhooks¶

Register a new webhook for job events.

• Operation ID: create_webhook_api_v1_webhooks_post
• Tags: Webhooks

Request body (required): application/json: WebhookRequest

Responses

DELETE /api/v1/webhooks/{webhook_id}¶

Delete a webhook.

• Operation ID: delete_webhook_api_v1_webhooks__webhook_id__delete
• Tags: Webhooks

Parameters

Responses

GET /healthz¶

Kubernetes-style liveness probe.

• Operation ID: kubernetes_health_check_healthz_get
• Tags: Health

Responses

GET /readyz¶

Kubernetes readiness includes the enabled queue worker task.

• Operation ID: kubernetes_readiness_check_readyz_get
• Tags: Health

Responses

Schemas¶

BulkDeleteRequest¶

Example:

{
  "dry_run": false,
  "namespace": "gco-jobs",
  "older_than_days": 7,
  "status": "completed"
}

CostReportRequest¶

Request body for POST /api/v1/cost/reports.

HTTPValidationError¶

JobFromTemplateRequest¶

Example:

{
  "name": "my-training-job",
  "namespace": "gco-jobs",
  "parameters": {
    "image": "my-custom-image:v1"
  }
}

JobStatus¶

• Type: enum: "pending", "running", "completed", "succeeded", "failed"

JobTemplateRequest¶

Example:

{
  "description": "Template for GPU training jobs",
  "manifest": {
    "apiVersion": "batch/v1",
    "kind": "Job",
    "metadata": {
      "name": "{{name}}"
    }
  },
  "name": "gpu-training-template",
  "parameters": {
    "image": "pytorch/pytorch:latest"
  }
}

ManifestSubmissionAPIRequest¶

API model for manifest submission requests.

Example:

{
  "dry_run": false,
  "manifests": [
    {
      "apiVersion": "batch/v1",
      "kind": "Job",
      "metadata": {
        "name": "example"
      }
    }
  ],
  "namespace": "gco-jobs"
}

QueuedJobRequest¶

Example:

{
  "manifest": {
    "apiVersion": "batch/v1",
    "kind": "Job",
    "metadata": {
      "name": "my-training-job"
    }
  },
  "max_spot_price": 0.5,
  "namespace": "gco-jobs",
  "priority": 10,
  "spot_instance_type": "g5.xlarge",
  "target_region": "us-east-1"
}

ValidationError¶

WebhookEvent¶

• Type: enum: "job.completed", "job.failed", "job.started"

WebhookRequest¶

Example:

{
  "events": [
    "job.completed",
    "job.failed"
  ],
  "namespace": "gco-jobs",
  "url": "https://example.com/webhook"
}