Task Executor Usage Guide

Introduction

The task-executor is a lightweight component designed to run and manage short-lived tasks (processes or containers) within a Kubernetes Pod context. It acts as a local agent, receiving task specifications from a Kubernetes Controller (e.g., BatchSandboxController) and executing them on the node where it runs. It exposes a simple HTTP API for task creation, status inquiry, and management.

Running the Task Executor

The task-executor can be started using the cmd/task-executor/main.go entry point. It supports various command-line flags and environment variables for configuration.

Basic Startup:

bash

/path/to/cmd/task-executor/main --data-dir=/var/lib/sandbox/tasks --listen-addr=0.0.0.0:5758

Key Configuration Parameters:

Flag / Environment Variable	Description	Default Value
`--data-dir` (DATA_DIR)	Directory for persisting task state and logs.	`/var/lib/sandbox/tasks`
`--listen-addr` (LISTEN_ADDR)	Address and port for the HTTP API server.	`0.0.0.0:5758`
`--enable-sidecar-mode` (ENABLE_SIDECAR_MODE)	If `true`, enables sidecar mode execution, where tasks are run within the PID namespace of a specified main container. Requires `nsenter` and appropriate privileges.	`false`
`--main-container-name` (MAIN_CONTAINER_NAME)	When `enable-sidecar-mode` is `true`, specifies the name of the main container whose PID namespace should be used.	`main`
`--enable-container-mode` (ENABLE_CONTAINER_MODE)	If `true`, enables container mode execution using the CRI runtime. (Note: Current implementation may be a placeholder).	`false`
`--cri-socket` (CRI_SOCKET)	Path to the CRI socket (e.g., `containerd.sock`) when `enable-container-mode` is `true`.	`/var/run/containerd/containerd.sock`
`--reconcile-interval`	The interval at which the internal task manager reconciles task states.	`500ms`

HTTP API Endpoints

The task-executor exposes a RESTful HTTP API. All API calls expect JSON request bodies (where applicable) and return JSON responses.

1. `POST /tasks` - Create a new task

Creates and starts a single task.

Method: POST
Path: /tasks

Request Body (application/json): An object representing the desired task.

json

{
  "name": "my-first-task",
  "spec": {
    "process": {
      "command": ["sh", "-c"],
      "args": ["echo 'Hello from my task!' && sleep 5 && echo 'Task finished.'"]
    }
  }
}

Response Body (application/json): The created task object with its initial status.

json

{
  "name": "my-first-task",
  "spec": {
    "process": {
      "command": ["sh", "-c"],
      "args": ["echo 'Hello from my task!' && sleep 5 && echo 'Task finished.'"]
    }
  },
  "status": {
    "state": {
      "waiting": {
        "reason": "Initialized"
      }
    }
  }
}

Example (using curl):

bash

curl -X POST -H "Content-Type: application/json" -d '{
  "name": "my-first-task",
  "spec": {
    "process": {
      "command": ["sh", "-c"],
      "args": ["echo \"Hello from my task!\" && sleep 5 && echo \"Task finished.\""]
    }
  }
}' http://localhost:5758/tasks

2. `GET /tasks/{id}` - Get task status

Retrieves the current status of a specific task by its name.

Method: GET
Path: /tasks/{taskName}

Response Body (application/json): The task object, including its current status.

json

{
  "name": "my-first-task",
  "spec": {
    "process": {
      "command": ["sh", "-c"],
      "args": ["echo 'Hello from my task!' && sleep 5 && echo 'Task finished.'"]
    }
  },
  "status": {
    "state": {
      "running": {
        "startedAt": "2025-12-17T10:00:00Z"
      }
    }
  }
}

Example (using curl):

bash

curl http://localhost:5758/tasks/my-first-task

3. `DELETE /tasks/{id}` - Delete a task

Marks a task for deletion. The task-executor will attempt to gracefully stop the task and then remove its state.

Method: DELETE
Path: /tasks/{taskName}
Response: 204 No Content on successful marking for deletion.

Example (using curl):

bash

curl -X DELETE http://localhost:5758/tasks/my-first-task

4. `POST /setTasks` - Synchronize tasks

This endpoint is typically used by controllers to synchronize a desired set of tasks. Tasks not present in the desired list will be marked for deletion; new tasks will be created.

Method: POST
Path: /setTasks

Request Body (application/json): An array of task objects representing the desired state.

json

[
  {
    "name": "task-alpha",
    "spec": {
      "process": {
        "command": ["sleep", "10"]
      }
    }
  },
  {
    "name": "task-beta",
    "spec": {
      "process": {
        "command": ["ls", "-l", "/tmp"]
      }
    }
  }
]

Response Body (application/json): The current list of tasks managed by the executor after synchronization.

json

[
  {
    "name": "task-alpha",
    "spec": {
      "process": {
        "command": ["sleep", "10"]
      }
    },
    "status": {
      "state": {
        "waiting": {
          "reason": "Initialized"
        }
      }
    }
  },
  {
    "name": "task-beta",
    "spec": {
      "process": {
        "command": ["ls", "-l", "/tmp"]
      }
    },
    "status": {
      "state": {
        "waiting": {
          "reason": "Initialized"
        }
      }
    }
  }
]

Example (using curl):

bash

curl -X POST -H "Content-Type: application/json" -d \
'[
  {
    "name": "task-alpha",
    "spec": { "process": { "command": ["sleep", "10"] } }
  },
  {
    "name": "task-beta",
    "spec": { "process": { "command": ["ls", "-l", "/tmp"] } }
  }
]' http://localhost:5758/setTasks

5. `GET /getTasks` - List all tasks

Retrieves a list of all tasks currently managed by the task-executor.

Method: GET
Path: /getTasks

Response Body (application/json): An array of task objects.

json

[
  {
    "name": "task-alpha",
    "spec": {
      "process": {
        "command": ["sleep", "10"]
      }
    },
    "status": {
      "state": {
        "running": {
          "startedAt": "2025-12-17T10:05:00Z"
        }
      }
    }
  },
  {
    "name": "task-beta",
    "spec": {
      "process": {
        "command": ["ls", "-l", "/tmp"]
      }
    },
    "status": {
      "state": {
        "terminated": {
          "exitCode": 0,
          "reason": "Succeeded",
          "startedAt": "2025-12-17T10:06:00Z",
          "finishedAt": "2025-12-17T10:06:01Z"
        }
      }
    }
  }
]

Example (using curl):

bash

curl http://localhost:5758/getTasks

6. `GET /health` - Health check

Returns the health status of the task-executor.

Method: GET
Path: /health
Response Body (application/json):
json
```
{
  "status": "healthy"
}
```

Example (using curl):

bash

curl http://localhost:5758/health

Task Specification (`TaskSpec`) Structure

The spec field within a task object (api/v1alpha1.TaskSpec) defines how the task should be executed. It currently supports process and container execution modes.

Process Task Example

This mode executes a command directly as a process.

json

{
  "name": "my-process-task",
  "spec": {
    "process": {
      "command": ["python3", "my_script.py"],
      "args": ["--config", "/etc/app/config.yaml"],
      "env": [
        { "name": "DEBUG_MODE", "value": "true" }
      ],
      "workingDir": "/app"
    }
  }
}

Container Task Example (Placeholder/Future Feature)

This mode is intended for executing tasks within containers managed by the CRI runtime. Note that as per internal/task-executor/runtime/container.go, this mode might still be a placeholder.

json

{
  "name": "my-container-task",
  "spec": {
    "container": {
      "image": "ubuntu:latest",
      "command": ["/bin/bash", "-c"],
      "args": ["apt update && apt install -y curl"],
      "env": [
        { "name": "http_proxy", "value": "http://myproxy.com:5758" }
      ],
      "volumeMounts": [
        {
          "name": "data-volume",
          "mountPath": "/data"
        }
      ]
    }
  }
}

Task Status (`TaskStatus`) Structure

The status field within a task object (internal/task-executor/types/Status mapped to api/v1alpha1.TaskStatus for external API) provides details about the task's current execution state.

json

{
  "name": "my-task",
  "spec": { ... },
  "status": {
    "state": {
      "waiting": {
        "reason": "Initialized"
      }
    },
    // or
    "state": {
      "running": {
        "startedAt": "2025-12-17T10:00:00Z"
      }
    },
    // or
    "state": {
      "terminated": {
        "exitCode": 0,
        "reason": "Succeeded",
        "message": "Task completed successfully",
        "startedAt": "2025-12-17T10:00:00Z",
        "finishedAt": "2025-12-17T10:00:05Z"
      }
    }
  }
}

State Types:

waiting: Task is pending execution.
running: Task is currently executing.
terminated: Task has finished (succeeded or failed).

Example Scenario: Running a Sidecar Task

If task-executor is configured with --enable-sidecar-mode=true and --main-container-name=my-main-app, it can execute tasks within the PID namespace of my-main-app.

bash

# Assume task-executor is running in sidecar mode on a pod with 'my-main-app'
# This task will execute 'ls /proc/self/ns' from within the main container's namespace
curl -X POST -H "Content-Type: application/json" -d '{
  "name": "sidecar-namespace-check",
  "spec": {
    "process": {
      "command": ["ls", "/proc/self/ns"]
    }
  }
}' http://localhost:5758/tasks

This page is sourced from: kubernetes/examples/task-executor/README.md

Task Executor Usage Guide ​

Introduction ​

Running the Task Executor ​

HTTP API Endpoints ​

1. POST /tasks - Create a new task ​

2. GET /tasks/{id} - Get task status ​

3. DELETE /tasks/{id} - Delete a task ​

4. POST /setTasks - Synchronize tasks ​

5. GET /getTasks - List all tasks ​

6. GET /health - Health check ​

Task Specification (TaskSpec) Structure ​

Process Task Example ​

Container Task Example (Placeholder/Future Feature) ​

Task Status (TaskStatus) Structure ​

Example Scenario: Running a Sidecar Task ​

Task Executor Usage Guide

Introduction

Running the Task Executor

HTTP API Endpoints

1. `POST /tasks` - Create a new task

2. `GET /tasks/{id}` - Get task status

3. `DELETE /tasks/{id}` - Delete a task

4. `POST /setTasks` - Synchronize tasks

5. `GET /getTasks` - List all tasks

6. `GET /health` - Health check

Task Specification (`TaskSpec`) Structure

Process Task Example

Container Task Example (Placeholder/Future Feature)

Task Status (`TaskStatus`) Structure

Example Scenario: Running a Sidecar Task