kubectl cheat sheet for ML platform teams

kubectl is the primary command-line interface to the Kubernetes API. It can inspect resources, stream logs, explain schemas, preview changes, and start targeted debugging sessions.

The same reach also makes careless commands dangerous. This cheat sheet favors explicit context and namespace arguments, read-only diagnosis before mutation, and declarative changes that can be reviewed and reproduced.

Verify the target first

Start every session by confirming the cluster, identity, and namespace:

kubectl config current-context
kubectl config view --minify
kubectl auth can-i get pods \
  --context acme-staging \
  --namespace ml-team

The official kubectl quick reference contains the complete command catalog. In shared environments, do not rely on a context selected hours earlier or on the default namespace.

Discover available resources

List API resource kinds and inspect the server-supported schema:

kubectl api-resources \
  --context acme-staging

kubectl explain jobs.spec.template.spec.containers.resources \
  --context acme-staging

api-resources answers which kinds and short names the server recognizes. explain is useful when authoring manifests because it follows the schema served by the target cluster rather than a remembered example.

Check client and server versions when a field or command behaves differently across environments:

kubectl version \
  --context acme-staging

List workloads with useful detail

Start broad, then narrow by kind, label, or owner:

kubectl get jobs,pods \
  --context acme-staging \
  --namespace ml-team \
  --output wide

kubectl get pods \
  --context acme-staging \
  --namespace ml-team \
  --selector polyaxon.com/project=fraud-model \
  --show-labels

Use --watch only when you need a live transition. A completed Job can disappear through retention policy, so preserve the relevant run, event, log, and artifact evidence elsewhere.

Describe the current state

describe combines object status, related conditions, scheduling details, and recent events:

kubectl describe pod training-worker-0 \
  --context acme-staging \
  --namespace ml-team

Read from the top and the bottom. The specification shows what Kubernetes was asked to run; conditions and events show what prevented or changed execution. For a controller-managed Pod, inspect its owner as well as the Pod.

Read current and previous logs

Specify the container when a Pod has more than one:

kubectl logs training-worker-0 \
  --context acme-staging \
  --namespace ml-team \
  --container trainer \
  --timestamps

kubectl logs training-worker-0 \
  --context acme-staging \
  --namespace ml-team \
  --container trainer \
  --previous \
  --timestamps

--previous retrieves the terminated instance of a restarted container when that log is still available. Use --since, --tail, and label selectors to limit volume rather than downloading an entire noisy history.

Inspect events in time order

Events explain scheduling, image pulls, mounts, probes, evictions, and controller actions:

kubectl get events \
  --context acme-staging \
  --namespace ml-team \
  --sort-by=.metadata.creationTimestamp

Events are retained for a limited period and may be aggregated. They are diagnostic clues, not a durable audit log.

Preview and apply declarative changes

Ask the API server to calculate a diff before applying reviewed configuration:

kubectl diff \
  --context acme-staging \
  --namespace ml-team \
  --filename operation-resources.yaml

kubectl apply \
  --context acme-staging \
  --namespace ml-team \
  --filename operation-resources.yaml

Keep the manifest in version control and confirm its owner. A direct edit or patch may be overwritten by the Deployment, operator, GitOps controller, or Polyaxon operation that owns the resource.

Follow rollout state

For controller-managed services, read rollout status and history:

kubectl rollout status deployment/model-api \
  --context acme-staging \
  --namespace ml-team \
  --timeout 5m

kubectl rollout history deployment/model-api \
  --context acme-staging \
  --namespace ml-team

A successful Kubernetes rollout confirms controller readiness, not model quality. Validate representative requests, telemetry, and the deployed model version separately.

Use exec and debug deliberately

Run one diagnostic command in a named container:

kubectl exec training-worker-0 \
  --context acme-staging \
  --namespace ml-team \
  --container trainer \
  -- printenv MODEL_VERSION

If a minimal image has no shell or tools, use an approved ephemeral debugging container instead of installing software into the running application. The kubectl exec guide covers access, evidence, and immutability in detail.

Connect Kubernetes evidence to Polyaxon

Kubernetes commands explain cluster execution. Polyaxon preserves the higher-level operation, parameters, code, resources, logs, metrics, lineage, and artifacts that give that execution meaning.

Use run logging and operation metadata before reaching for low-level access. Polyaxon scheduling presets keep repeated resource and placement policy out of one-off live changes.

A useful cheat sheet is not a list of shortcuts. It is a repeatable diagnostic order: confirm the target, read desired and current state, collect evidence, identify the owner, preview the change, and validate the workload outcome.