Documentation: Missing guidance on task cleanup and lifecycle management
Nobody has claimed this yet.
- 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
-
Task cleanup is mentioned but not explained:
- Line 343 mentions
spec.ttlSecondsAfterFinishedin the Task Spec table - Line 313 mentions "Owner References" ensuring automatic cleanup
- Line 494 lists
axon deleteas a CLI command - But there's no example or explanation of when/how to use these
- Line 343 mentions
-
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
- After running
-
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
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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