kelos-dev / kelos-dev/kelos

Documentation: Missing guidance on task cleanup and lifecycle management

Open
#242 2 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

actor/kelos generated-by-kelos kelos/needs-input kind/docs priority/important-longterm triage-accepted
Dominant language
Go
Stars
331
Forks
40
Avg merge
1d 21h
Merged PRs (30d)
70

Description

Problem

The README doesn't provide clear guidance on how to manage task lifecycle and cleanup, which could lead to confusion for new users.

Current State

  1. Task cleanup is mentioned but not explained:

    • Line 343 mentions spec.ttlSecondsAfterFinished in the Task Spec table
    • Line 313 mentions "Owner References" ensuring automatic cleanup
    • Line 494 lists axon delete as a CLI command
    • But there's no example or explanation of when/how to use these
  2. Quick Start doesn't mention cleanup:

    • After running axon run -p "Create a hello world program", the task stays in the cluster
    • New users might not know they need to clean up or that automatic cleanup is available
    • No guidance on what happens to completed vs failed tasks
  3. No lifecycle best practices:

    • Should users set TTL for all tasks?
    • What's a reasonable TTL value?
    • How do you list old completed tasks?
    • Do failed tasks auto-delete?

Suggested Improvements

1. Add a cleanup example in Quick Start or Examples section
### Task Cleanup

Tasks remain in the cluster after completion. You have several options for cleanup:

**Option 1: Manual deletion**
```bash
# Delete a specific task
axon delete task hello-world-xyz

# Or using kubectl
kubectl delete task hello-world-xyz

Option 2: Automatic cleanup with TTL

spec:
  ttlSecondsAfterFinished: 3600  # Delete 1 hour after completion
  # Use 0 for immediate deletion after completion

Option 3: List and bulk delete

# List completed tasks
kubectl get tasks --field-selector status.phase=Succeeded

# Delete all completed tasks
kubectl delete tasks --field-selector status.phase=Succeeded

### 2. Update Task Spec reference (line 343)

Change from:

| spec.ttlSecondsAfterFinished | Auto-delete task after N seconds (0 for immediate) | No |


To:

| spec.ttlSecondsAfterFinished | Auto-delete task N seconds after completion (0 for immediate deletion). Useful for keeping the cluster clean in production. | No |


### 3. Mention cleanup in the Quick Start

After step 3, add:
```markdown
# 4. Clean up (optional)
axon delete task <task-name>

# Or set automatic cleanup by default in your config:
# ttlSecondsAfterFinished: 3600

Impact

For new users:

  • Confusion about task accumulation over time
  • May not discover the TTL feature
  • No clear guidance on production best practices

For production users:

  • May accumulate many old tasks without realizing cleanup is available
  • No clear recommendation on TTL values

Related

This is particularly relevant for:

  • TaskSpawner users who will create many tasks over time
  • CI/CD pipelines where tasks should be cleaned up automatically
  • Production deployments where resource cleanup is important

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start in the README sections around the Quick Start, Task Spec table, Owner References, and axon delete command referenced in the issue. Verify the documented cleanup behavior and commands, then add lifecycle guidance, a cleanup example, and practical TTL usage notes. Done means new users can understand completed and failed task cleanup and choose manual or automatic cleanup.

Written by the indexing model from the issue text.

Assessment

Tech stack
kubernetes
Domain
cli, devops, documentation
Issue type
Documentation
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
52/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.