Skip to content

Epic: complete API parity — make stackctl a full headless client for k8s-stack-manager #59

Open
Open
Epic: complete API parity — make stackctl a full headless client for k8s-stack-manager#59
@omattsson

Description

@omattsson
omattsson
opened on May 11, 2026

Summary

Close the remaining gap between the k8s-stack-manager HTTP API and stackctl. Today several common workflows still require direct API calls (curl/HTTPie) because the corresponding stackctl subcommands either don't exist or only cover a subset of the endpoints. This epic tracks the work to make stackctl a complete client for the API so that the UI is strictly optional and any user/CI workflow can run headless.

This epic was sized after a full sweep of the k8s-stack-manager /api/v1 surface against the current stackctl command tree (cli/cmd/).

Goals

  • A user can perform every supported k8s-stack-manager operation through stackctl (built-in commands or the documented plugin pattern).
  • CI/CD pipelines never need a hand-rolled curl/jq script for a first-class API operation.
  • The k8s-stack-manager UI becomes optional — useful for browsing, but not required for any workflow.

Non-goals

  • Replacing the UI for visual exploration (favorites/notifications can stay UI-first features even when a CLI exists).
  • Building a TUI dashboard.
  • Wrapping /health/* and /metrics — those are infra scrape endpoints, not CLI surface.

Gap analysis (API → stackctl)

Legend: ✅ covered · ⚠️ partial · ❌ missing

Templates

  • ✅ template list / get / instantiate / quick-deploy / delete
  • ❌ template create
  • ❌ template update
  • ❌ template publish / unpublish
  • ❌ template clone
  • ❌ template versions list / get / diff
  • ❌ bulk template delete / publish / unpublish (up to 50)

Clusters

  • ✅ cluster list / get / shared-values …
  • ❌ cluster create / update / delete
  • ❌ cluster test-connection
  • ❌ cluster health
  • ❌ cluster quotas (get/set/delete)
  • ❌ cluster utilization

Cleanup policies

  • ❌ cleanup-policy list / get / create / update / delete
  • ❌ cleanup-policy run <id> [--dry-run]

Users & API keys

  • ❌ user list / get / create / update / delete (admin)
  • ❌ auth register
  • ❌ apikey list / create / revoke

Observability / read-only admin

  • ❌ analytics overview / analytics templates / analytics users
  • ❌ audit log list --filter … / audit log export

User-facing extras

  • ❌ notification list / read / unread / count / prefs
  • ❌ favorite list / add / remove
  • ❌ git providers status

Real-time

  • ❌ stack watch / events (subscribe to /ws for deploy/stop/status changes)
  • ⚠️ stack logs exists but is not a live deploy/event stream

Headless deployment readiness (k8s-stack-manager side)

Tracked here for completeness; these are server/Helm changes that benefit headless stackctl users but live in the k8s-stack-manager repo:

  • Helm frontend.enabled: false toggle (skip frontend Deployment/Service/ConfigMap and the / Traefik route).
  • Docker Compose api-only profile.
  • OIDC CLI loopback flow (return tokens as JSON when redirect_uri=http://127.0.0.1:<port>) so stackctl login --sso works without the web UI.
  • WebSocket auth via query param / subprotocol for non-browser clients (verify /ws accepts JWT outside an Authorization header).
  • README "Headless / API-only" section pointing at stackctl.

These will be filed as separate issues in omattsson/k8s-stack-manager and linked back here.

Phased plan

Each phase is a standalone PR / set of PRs. Phases are ordered by impact-per-effort.

Phase 1 — Template authoring (highest daily-use gap)

  • template create --from-file template.json
  • template update <id> [--name|--description|--file]
  • template publish <id> / template unpublish <id>
  • template clone <id> --name <new>
  • template versions list <id>
  • template versions get <id> <version>
  • template versions diff <id> <v1> <v2>
  • bulk template delete|publish|unpublish (mirror existing bulk UX)

Acceptance: full template lifecycle without the UI; tests cover each verb + table/json/yaml output.

Phase 2 — Cluster admin

  • cluster create --from-file cluster.json (kubeconfig-data or kubeconfig-path)
  • cluster update <id> [--name|--registry-…|--default]
  • cluster delete <id> [--yes]
  • cluster test-connection <id>
  • cluster health <id>
  • cluster quota get|set|delete <id>
  • cluster utilization <id>

Acceptance: register a new cluster, validate connectivity, set quotas, deploy to it — all via stackctl.

Phase 3 — Cleanup policies & scheduled ops

  • cleanup-policy list|get|create|update|delete
  • cleanup-policy run <id> [--dry-run]

Acceptance: a DevOps user can author and dry-run a policy without opening the UI.

Phase 4 — Users & API keys

  • auth register --username --email
  • user list|get|create|update|delete (admin role gated; surface 403 cleanly)
  • apikey list <user-id> / apikey create <user-id> --name / apikey revoke <user-id> <key-id>

Acceptance: bootstrap a CI service account end-to-end with stackctl alone.

Phase 5 — Observability surface

  • analytics overview|templates|users
  • audit log list --user --action --entity --since --until --limit
  • audit log export -o json|csv

Acceptance: pipeable JSON/CSV audit export for compliance jobs.

Phase 6 — User-facing extras

  • notification list|read|unread|count
  • notification prefs get|set
  • favorite list|add|remove
  • git providers status

Acceptance: parity for the small but useful per-user features.

Phase 7 — Real-time events

  • stack watch [--id … | --owner … | --status …] — subscribe to /ws, render deploy/stop/clean events as they happen.
  • stack logs --follow — already exists for logs, ensure it tails through deploy completion.

Acceptance: stackctl stack deploy X && stackctl stack watch X blocks until the new instance is running or failed, then exits with the right code.

Implementation notes

  • Follow the existing structure documented in stackctl's README:
    1. Add types to pkg/types/types.go if the API returns new structs.
    2. Add client methods to pkg/client/client.go (httptest.NewServer for unit tests).
    3. New file in cmd/ per command group; register in init().
    4. Always go through pkg/output for table/json/yaml/quiet rendering.
    5. Tests: success, error, every output format, t.Parallel() where possible.
  • Reuse the existing name-or-ID resolver (cmd/resolve.go) for any command that takes an instance/template/cluster argument.
  • bulk template … should mirror the existing bulk deploy/stop/clean/delete UX (positional args or --ids, up to 50).
  • For stack watch, prefer Gorilla websocket client; reuse the same JWT/API-key auth chain as the HTTP client and pass the token via query param if header auth isn't supported on /ws upgrades.

Tracking

Plugin-friendly endpoints (e.g. cleanup-policy CRUD, analytics) can ship as stackctl-<name> plugins first if needed for early adopters, then be promoted into core once the UX stabilizes.

Sub-issues — stackctl

Phase 1 — Template authoring

Phase 2 — Cluster admin

Phase 3 — Cleanup policies

Phase 4 — Users & API keys

Phase 5 — Observability

Phase 6 — User-facing extras

Phase 7 — Real-time

Sub-issues — k8s-stack-manager (headless deployment readiness)

Out of scope / explicit non-features

  • /health/live, /health/ready, /metrics — infra scrape endpoints, not CLI surface.
  • WebSocket beyond stack events (no chat/presence features in the API).
  • A TUI dashboard.

References

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions