README.md
1 # Task Executor Usage Guide 2 3 ## Introduction 4 5 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. 6 7 ## Running the Task Executor 8 9 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. 10 11 **Basic Startup:** 12 13 ```bash 14 /path/to/cmd/task-executor/main --data-dir=/var/lib/sandbox/tasks --listen-addr=0.0.0.0:5758 15 ``` 16 17 **Key Configuration Parameters:** 18 19 | Flag / Environment Variable | Description | Default Value | 20 | :-------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------- | 21 | `--data-dir` (DATA_DIR) | Directory for persisting task state and logs. | `/var/lib/sandbox/tasks` | 22 | `--listen-addr` (LISTEN_ADDR)| Address and port for the HTTP API server. | `0.0.0.0:5758` | 23 | `--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` | 24 | `--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` | 25 | `--enable-container-mode` (ENABLE_CONTAINER_MODE) | If `true`, enables container mode execution using the CRI runtime. (Note: Current implementation may be a placeholder). | `false` | 26 | `--cri-socket` (CRI_SOCKET) | Path to the CRI socket (e.g., `containerd.sock`) when `enable-container-mode` is `true`. | `/var/run/containerd/containerd.sock` | 27 | `--reconcile-interval` | The interval at which the internal task manager reconciles task states. | `500ms` | 28 29 ## HTTP API Endpoints 30 31 The `task-executor` exposes a RESTful HTTP API. All API calls expect JSON request bodies (where applicable) and return JSON responses. 32 33 ### 1. `POST /tasks` - Create a new task 34 35 Creates and starts a single task. 36 37 * **Method:** `POST` 38 * **Path:** `/tasks` 39 * **Request Body (application/json):** An object representing the desired task. 40 41 ```json 42 { 43 "name": "my-first-task", 44 "spec": { 45 "process": { 46 "command": ["sh", "-c"], 47 "args": ["echo 'Hello from my task!' && sleep 5 && echo 'Task finished.'"] 48 } 49 } 50 } 51 ``` 52 53 * **Response Body (application/json):** The created task object with its initial status. 54 55 ```json 56 { 57 "name": "my-first-task", 58 "spec": { 59 "process": { 60 "command": ["sh", "-c"], 61 "args": ["echo 'Hello from my task!' && sleep 5 && echo 'Task finished.'"] 62 } 63 }, 64 "status": { 65 "state": { 66 "waiting": { 67 "reason": "Initialized" 68 } 69 } 70 } 71 } 72 ``` 73 74 **Example (using `curl`):** 75 76 ```bash 77 curl -X POST -H "Content-Type: application/json" -d '{ 78 "name": "my-first-task", 79 "spec": { 80 "process": { 81 "command": ["sh", "-c"], 82 "args": ["echo \"Hello from my task!\" && sleep 5 && echo \"Task finished.\""] 83 } 84 } 85 }' http://localhost:5758/tasks 86 ``` 87 88 ### 2. `GET /tasks/{id}` - Get task status 89 90 Retrieves the current status of a specific task by its name. 91 92 * **Method:** `GET` 93 * **Path:** `/tasks/{taskName}` 94 * **Response Body (application/json):** The task object, including its current status. 95 96 ```json 97 { 98 "name": "my-first-task", 99 "spec": { 100 "process": { 101 "command": ["sh", "-c"], 102 "args": ["echo 'Hello from my task!' && sleep 5 && echo 'Task finished.'"] 103 } 104 }, 105 "status": { 106 "state": { 107 "running": { 108 "startedAt": "2025-12-17T10:00:00Z" 109 } 110 } 111 } 112 } 113 ``` 114 115 **Example (using `curl`):** 116 117 ```bash 118 curl http://localhost:5758/tasks/my-first-task 119 ``` 120 121 ### 3. `DELETE /tasks/{id}` - Delete a task 122 123 Marks a task for deletion. The `task-executor` will attempt to gracefully stop the task and then remove its state. 124 125 * **Method:** `DELETE` 126 * **Path:** `/tasks/{taskName}` 127 * **Response:** `204 No Content` on successful marking for deletion. 128 129 **Example (using `curl`):** 130 131 ```bash 132 curl -X DELETE http://localhost:5758/tasks/my-first-task 133 ``` 134 135 ### 4. `POST /setTasks` - Synchronize tasks 136 137 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. 138 139 * **Method:** `POST` 140 * **Path:** `/setTasks` 141 * **Request Body (application/json):** An array of task objects representing the desired state. 142 143 ```json 144 [ 145 { 146 "name": "task-alpha", 147 "spec": { 148 "process": { 149 "command": ["sleep", "10"] 150 } 151 } 152 }, 153 { 154 "name": "task-beta", 155 "spec": { 156 "process": { 157 "command": ["ls", "-l", "/tmp"] 158 } 159 } 160 } 161 ] 162 ``` 163 164 * **Response Body (application/json):** The current list of tasks managed by the executor after synchronization. 165 166 ```json 167 [ 168 { 169 "name": "task-alpha", 170 "spec": { 171 "process": { 172 "command": ["sleep", "10"] 173 } 174 }, 175 "status": { 176 "state": { 177 "waiting": { 178 "reason": "Initialized" 179 } 180 } 181 } 182 }, 183 { 184 "name": "task-beta", 185 "spec": { 186 "process": { 187 "command": ["ls", "-l", "/tmp"] 188 } 189 }, 190 "status": { 191 "state": { 192 "waiting": { 193 "reason": "Initialized" 194 } 195 } 196 } 197 } 198 ] 199 ``` 200 201 **Example (using `curl`):** 202 203 ```bash 204 curl -X POST -H "Content-Type: application/json" -d \ 205 '[ 206 { 207 "name": "task-alpha", 208 "spec": { "process": { "command": ["sleep", "10"] } } 209 }, 210 { 211 "name": "task-beta", 212 "spec": { "process": { "command": ["ls", "-l", "/tmp"] } } 213 } 214 ]' http://localhost:5758/setTasks 215 ``` 216 217 ### 5. `GET /getTasks` - List all tasks 218 219 Retrieves a list of all tasks currently managed by the `task-executor`. 220 221 * **Method:** `GET` 222 * **Path:** `/getTasks` 223 * **Response Body (application/json):** An array of task objects. 224 225 ```json 226 [ 227 { 228 "name": "task-alpha", 229 "spec": { 230 "process": { 231 "command": ["sleep", "10"] 232 } 233 }, 234 "status": { 235 "state": { 236 "running": { 237 "startedAt": "2025-12-17T10:05:00Z" 238 } 239 } 240 } 241 }, 242 { 243 "name": "task-beta", 244 "spec": { 245 "process": { 246 "command": ["ls", "-l", "/tmp"] 247 } 248 }, 249 "status": { 250 "state": { 251 "terminated": { 252 "exitCode": 0, 253 "reason": "Succeeded", 254 "startedAt": "2025-12-17T10:06:00Z", 255 "finishedAt": "2025-12-17T10:06:01Z" 256 } 257 } 258 } 259 } 260 ] 261 ``` 262 263 **Example (using `curl`):** 264 265 ```bash 266 curl http://localhost:5758/getTasks 267 ``` 268 269 ### 6. `GET /health` - Health check 270 271 Returns the health status of the `task-executor`. 272 273 * **Method:** `GET` 274 * **Path:** `/health` 275 * **Response Body (application/json):** 276 277 ```json 278 { 279 "status": "healthy" 280 } 281 ``` 282 283 **Example (using `curl`):** 284 285 ```bash 286 curl http://localhost:5758/health 287 ``` 288 289 ## Task Specification (`TaskSpec`) Structure 290 291 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. 292 293 ### Process Task Example 294 295 This mode executes a command directly as a process. 296 297 ```json 298 { 299 "name": "my-process-task", 300 "spec": { 301 "process": { 302 "command": ["python3", "my_script.py"], 303 "args": ["--config", "/etc/app/config.yaml"], 304 "env": [ 305 { "name": "DEBUG_MODE", "value": "true" } 306 ], 307 "workingDir": "/app" 308 } 309 } 310 } 311 ``` 312 313 ### Container Task Example (Placeholder/Future Feature) 314 315 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. 316 317 ```json 318 { 319 "name": "my-container-task", 320 "spec": { 321 "container": { 322 "image": "ubuntu:latest", 323 "command": ["/bin/bash", "-c"], 324 "args": ["apt update && apt install -y curl"], 325 "env": [ 326 { "name": "http_proxy", "value": "http://myproxy.com:5758" } 327 ], 328 "volumeMounts": [ 329 { 330 "name": "data-volume", 331 "mountPath": "/data" 332 } 333 ] 334 } 335 } 336 } 337 ``` 338 339 ## Task Status (`TaskStatus`) Structure 340 341 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. 342 343 ```json 344 { 345 "name": "my-task", 346 "spec": { ... }, 347 "status": { 348 "state": { 349 "waiting": { 350 "reason": "Initialized" 351 } 352 }, 353 // or 354 "state": { 355 "running": { 356 "startedAt": "2025-12-17T10:00:00Z" 357 } 358 }, 359 // or 360 "state": { 361 "terminated": { 362 "exitCode": 0, 363 "reason": "Succeeded", 364 "message": "Task completed successfully", 365 "startedAt": "2025-12-17T10:00:00Z", 366 "finishedAt": "2025-12-17T10:00:05Z" 367 } 368 } 369 } 370 } 371 ``` 372 373 **State Types:** 374 375 * `waiting`: Task is pending execution. 376 * `running`: Task is currently executing. 377 * `terminated`: Task has finished (succeeded or failed). 378 379 ## Example Scenario: Running a Sidecar Task 380 381 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`. 382 383 ```bash 384 # Assume task-executor is running in sidecar mode on a pod with 'my-main-app' 385 # This task will execute 'ls /proc/self/ns' from within the main container's namespace 386 curl -X POST -H "Content-Type: application/json" -d '{ 387 "name": "sidecar-namespace-check", 388 "spec": { 389 "process": { 390 "command": ["ls", "/proc/self/ns"] 391 } 392 } 393 }' http://localhost:5758/tasks 394 ``` 395