cluster (per-user K8s view)

CRITICAL — before doing anything, MUST use the Read tool to read ../olares-shared/SKILL.md for the profile model, login flow, automatic token refresh, and the auth-error recovery table.

> Source of truth for flags & wire shapes is always olares-cli cluster --help. This file only carries what --help cannot give: routing, the mental model of nouns, the identity-vs-server principle, the mutating-verb safety contract, cross-verb output conventions, and the common-errors → fix table.

When to use this skill

Against the cluster the active profile can see:

• "What pods / containers / workloads / jobs / cronjobs / namespaces / nodes are running?"
• "Tail / show logs of (or of )"
• "Restart / scale / stop / start / delete " — the K8s controller, not the Olares app
• "Suspend / resume " or "rerun "
• "Who am I on this cluster, what's my role?" (cluster context)
• "What does this object's YAML look like?" (cluster yaml)

When NOT to use — route to a sibling skill

| User intent | Use instead | Why |

|---|---|---|

| Install / uninstall / upgrade / start / stop an Olares app | olares-market | App-store lifecycle, not K8s object lifecycle |

| Edit app entrances / domains / env / policy / ACL from the user perspective | olares-settings | The settings UI mirror, scoped to the user's apps |

| Browse / sync drive files | olares-files | File API, not K8s |

| Cluster install / node join / OS upgrade / GPU drivers | olares-cli node, olares-cli os, olares-cli gpu | Kubeconfig-based host maintenance, NOT profile-based |

| Profile management, login, token refresh | olares-shared | Auth lives there |

> Mental model: if the question is runtime state of an existing cluster, you are here. If it's lifecycle of an Olares app or day-zero host setup, you are not.

Core concepts

| Noun | Identifier grammar | What it is |

|---|---|---|

| Pod | / (or -n NS ) | One running pod with one or more containers |

| Container | // (or -n NS -c NAME) | A single container inside a pod (logs / env target) |

| Workload | / + --kind deployment\|statefulset\|daemonset | The controller that owns pods. Subject of scale / restart / stop / start / rollout-status |

| Application space | | A KubeSphere-grouped K8s namespace; the "Olares Application Space" framing groups namespaces by workspace |

| Namespace | | The same K8s namespace, kubectl-style framing (no workspace grouping) |

| Node | | A K8s node visible to the active profile. Different from olares-cli node (host maintenance) |

| Job | / | A one-shot batch run (apis/batch/v1) |

| CronJob | / | A scheduled Job template (apis/batch/v1) |

| Middleware | --type T --name N --namespace NS | An Olares-managed database / queue / object store; NOT a K8s native resource (separate /middleware/v1/* aggregator) |

Resource relationships

Application space (namespace)
├── Workload  (Deployment | StatefulSet | DaemonSet)
│   └── Pod
│       └── Container       (logs | env)
├── Job
│   └── Pod
└── CronJob
    └── Job
        └── Pod

Cluster
├── Node                    (per-user view, not host maintenance)
└── Middleware              (DB / queue / object store, separate aggregator)

cluster context             (identity / role / accessible workspaces)

The identity-vs-server-decides principle (cross-cutting)

1. Identity = the currently-selected profile. Switch with olares-cli profile use ahead of time. There is no per-invocation --profile override — agents must commit to one role up-front.
2. The server decides what the active profile can see; the CLI never preflights. Pass the request, render whatever the server returns. A 403 is the authoritative "no" — surface it. Never gate a call against the locally cached cluster context; that cache is for display only.
3. All requests go through https://control-hub. and ride the active profile's access_token via the auto-refreshing transport. See ../olares-shared/SKILL.md for refresh mechanics and ErrTokenInvalidated recovery.
4. The same nginx fans out four prefixes: /capi/ (Olares aggregator), /api/v1/ + /apis/// (K8s native), /kapis/ (KubeSphere paginated), /middleware/v1/* (Olares middleware aggregator). The right helper is picked per-call by the CLI.

> cluster context is identity-only — it does NOT own resources. Use it once at the start of a session to confirm "I am , role , can see ". Never gate other verbs on its cached value.

Verb index

For flags, examples, and wire shapes, always start with olares-cli cluster --help.

| Noun | Verbs | --help first, then... |

|---|---|---|

| context | (single verb) | olares-cli cluster context --help |

| pod | list, get, yaml, events, logs, delete, restart | references/olares-cluster-pod.md |

| container | list, env, logs | olares-cli cluster container --help |

| workload (alias wl) | list, get, yaml, rollout-status, scale, restart, stop, start, delete | references/olares-cluster-workload.md |

| application (alias app) | list, get, workloads, pods, status | references/olares-cluster-application.md |

| namespace (alias ns) | list, get | olares-cli cluster namespace --help |

| node (alias nodes) | list, get | olares-cli cluster node --help |

| job (alias jobs) | list, get, yaml, pods, events, rerun | references/olares-cluster-job.md |

| cronjob (aliases cronjobs / cj) | list, get, yaml, jobs, suspend, resume | references/olares-cluster-cronjob.md |

| middleware (alias mw) | list | references/olares-cluster-middleware.md |

Mutating verb safety contract (cross-cutting)

Every mutating verb — pod delete / pod restart, all of workload scale|restart|stop|start|delete, cronjob suspend, job rerun — follows the same contract:

1. Wrapped in a ConfirmDestructive y/N prompt. Even for "reversible" changes — the prompt is the safety net. --yes / -y opts out for scripts.
2. No client-side authorization preflight — server is the only authority. A 403 surfaces; the CLI does not gate against cluster context.
3. Stable JSON summary on success, not the apiserver's response. JSON consumers care whether the change took, not every field of the object.

Non-destructive verbs (cronjob resume, workload start, pod logs) are NOT wrapped. Confirm intent with the user BEFORE invoking any destructive verb, even when scripts pass --yes.

Output conventions

• -o table (default): tabwriter columns. List verbs add a NAMESPACE column when scope is cross-namespace; get verbs render a vertical key/value layout. Paginated lists print (showing X of Y total — pass --limit Y to see more) to stderr when truncated.
• -o json: pretty-printed JSON. List/get verbs decode through minimal typed structs and re-emit only the fields the CLI knows about. The four * yaml verbs forward server bytes verbatim through JSON→YAML.
• -q / --quiet: suppress all stdout; exit code carries success/failure.
• --no-headers: omit table headers (handy for shell pipelines).

Pagination (--page N / --all)

Every list verb under pod / cronjob / job / namespace / node / workload (and the application pods / application workloads wrappers) supports pagination. Defaults: --limit 100, --page 1. Pass --page N to walk pages, or --all to drain every page.

--watch / --follow semantics (uniform)

pod get -w, workload rollout-status -w, application status -w, pod logs -f, container logs -f all share the same plumbing:

• Polling, never streaming. Avoids chunked transfer encoding; matches olares-cli market --watch.
• signal.NotifyContext(os.Interrupt, SIGTERM) for graceful Ctrl-C; exits nil on voluntary stop.
• Tolerates up to 5 consecutive transient errors (network blips, 5xx) before aborting. Terminal 4xx responses short-circuit immediately — a NotFound / Forbidden / Unauthorized won't fix itself on the next poll. 408 and 429 are still retried.
• TTY detection: clear-screen-redraw for table, raw stream for piped output, JSONL for -o json.
• --interval D / --timeout D are rejected with an error when their gate flag (-w or -f) isn't also set — don't silently waste a flag.

Common errors → fixes

| Error message starts with | Meaning | Fix |

|---|---|---|

| server rejected the request (HTTP 401: ...); please run: olares-cli profile login --olares-id | Auto-refresh failed, OR refreshed token still rejected | Run the suggested profile login |

| server rejected the request (HTTP 403: ...) | The active profile's role can't perform this | cluster context --refresh to confirm the cached role matches the server. If still 403, the user genuinely lacks permission |

| ... HTTP 404 (NotFound): ... on a list verb | Namespace doesn't exist OR the user can't see it (KubeSphere often returns 404 instead of 403 for "no access") | cluster application list to see what the server thinks is visible |

| --field-selector: field "..." is not supported (supported: ...) (from cluster pod list) | The pod list --field-selector accepts only a translatable subset of kubectl selectors (KubeSphere doesn't speak the raw fieldSelector= wire syntax) | Use one of the supported fields (status.phase, spec.nodeName, metadata.name, metadata.namespace), or drop --field-selector and filter client-side |

| --field-selector: "..." uses the '!=' operator which the upstream KubeSphere pods endpoint does not support | KubeSphere only matches equality | Rephrase as a positive match, or filter the output through jq |

| aborted by user / stdin is not a terminal — pass --yes to confirm: ... | Destructive prompt rejected, or non-TTY context without --yes | Interactive: answer y. Scripted: add --yes |

| --interval requires --follow / --interval requires --watch / --timeout requires --watch | Polling cadence flags set without their gate flag | Add -f / -w, or drop the offending flag |

| decode ... response: ... | Endpoint returned something we couldn't parse | Re-run with -o json to see the raw shape; may indicate a server-side schema change |

| refresh token for ... became invalid at ... (typed *credential.ErrTokenInvalidated) | The refresh_token itself is dead — auto-refresh can't recover | olares-cli profile login |

For the full auth-error matrix see ../olares-shared/SKILL.md.