k8s

name	k8s
description	Kubernetes workload management for homelab clusters. ArgoCD apps, deployments, pods, logs, storage, networking, and debugging.

Kubernetes Workload Management

You are managing Kubernetes workloads on Talos Linux clusters in a homelab environment. Workloads are deployed via ArgoCD (app-of-apps pattern) on the shared cluster.

Clusters

Cluster	VIP	Kubeconfig Path
shared	10.0.1.10	infrastructure/prod/compute/k8s-shared/configs/kubeconfig-shared
apps	10.0.2.10	infrastructure/prod/compute/k8s-apps/configs/kubeconfig-apps

Default cluster is shared when not specified.

Always use kubectl --kubeconfig <path> explicitly.

ArgoCD Setup

• Namespace: argocd
• Cluster: shared (hub cluster)
• Git repo: https://github.com/svnlto/homelab (branch: main)
• Root app path: kubernetes/argocd-apps/ (directory recurse, auto-sync with prune + selfHeal)
• App definitions: kubernetes/argocd-apps/*.yaml (one per app)
• App manifests: kubernetes/apps/<app-name>/ (Kustomize: base + overlays/shared)

Deployed Apps

App	Namespace	Description
arr-stack	arr-stack	Sonarr, Radarr, Prowlarr, Lidarr, SABnzbd
jellyfin	jellyfin	Jellyfin media server + Seerr
cnpg-operator	cnpg-system	CloudNativePG operator
postgresql	database	Shared PostgreSQL cluster (CNPG)
navidrome	navidrome	Music streaming server
dumper	dumper	Backup/dump utility
metrics-server	kube-system	Kubernetes metrics server (Helm)
signoz	signoz	SigNoz observability platform (Helm)
signoz-k8s-infra	signoz	SigNoz K8s infrastructure collector (Helm)
infrastructure	infrastructure	TrueNAS NFS PV/PVC definitions

Commands Reference

When the user invokes /k8s, parse $ARGUMENTS to determine the action. First argument is the command, second (optional) is the cluster name (default: shared).

ArgoCD

• /k8s apps [cluster] — List all ArgoCD applications and their sync status

  kubectl --kubeconfig <config> -n argocd get applications
  

• /k8s app <app-name> [cluster] — Show detailed status of a specific ArgoCD application

  kubectl --kubeconfig <config> -n argocd get application <app-name> -o yaml
  

• /k8s sync <app-name> [cluster] — Trigger an ArgoCD sync for an app Ask for confirmation before syncing.

  kubectl --kubeconfig <config> -n argocd patch application <app-name> \
    --type merge -p '{"operation":{"sync":{"revision":"HEAD"}}}'
  

• /k8s diff <app-name> — Show what would change on next sync Read the ArgoCD app spec and compare with the manifests in kubernetes/apps/<app-name>/.

Workloads

• /k8s pods [cluster] [namespace] — List pods, optionally filtered by namespace

  kubectl --kubeconfig <config> get pods -A  # or -n <namespace>
  

• /k8s deployments [cluster] [namespace] — List deployments

  kubectl --kubeconfig <config> get deployments -A
  

• /k8s services [cluster] [namespace] — List services with IPs

  kubectl --kubeconfig <config> get svc -A
  

• /k8s logs <pod-name> [cluster] [namespace] [container] — Get pod logs

  kubectl --kubeconfig <config> -n <namespace> logs <pod-name> [-c <container>] --tail=100
  

• /k8s describe <resource-type> <name> [cluster] [namespace] — Describe a resource

  kubectl --kubeconfig <config> [-n <namespace>] describe <resource-type> <name>
  

• /k8s events [cluster] [namespace] — Show recent events

  kubectl --kubeconfig <config> get events [-n <namespace> | -A] --sort-by='.lastTimestamp' | tail -30
  

• /k8s restart <deployment-name> [cluster] [namespace] — Rolling restart a deployment Ask for confirmation before restarting.

  kubectl --kubeconfig <config> -n <namespace> rollout restart deployment/<deployment-name>
  

Storage

• /k8s storage [cluster] — Show storage classes, PVs, and PVCs

  kubectl --kubeconfig <config> get sc
  kubectl --kubeconfig <config> get pv
  kubectl --kubeconfig <config> get pvc -A
  

• /k8s pvc [cluster] [namespace] — List PVCs with capacity and status

  kubectl --kubeconfig <config> get pvc -A -o wide
  

Networking

• /k8s ingress [cluster] — List all ingress resources and their hosts

  kubectl --kubeconfig <config> get ingress -A
  

• /k8s endpoints [cluster] [namespace] — List service endpoints

  kubectl --kubeconfig <config> get endpoints -A
  

• /k8s metallb [cluster] — Show MetalLB IP assignments

  kubectl --kubeconfig <config> -n metallb-system get ipaddresspool,l2advertisement
  kubectl --kubeconfig <config> get svc -A --field-selector spec.type=LoadBalancer
  

Debugging

• /k8s top [cluster] — Show resource usage (nodes and top pods)

  kubectl --kubeconfig <config> top nodes
  kubectl --kubeconfig <config> top pods -A --sort-by=memory | head -20
  

• /k8s failed [cluster] — Show pods not in Running/Succeeded state

  kubectl --kubeconfig <config> get pods -A --field-selector=status.phase!=Running,status.phase!=Succeeded
  

• /k8s exec <pod-name> [cluster] [namespace] -- <command> — Execute a command in a pod Ask for confirmation before executing.

  kubectl --kubeconfig <config> -n <namespace> exec -it <pod-name> -- <command>
  

Manifests

• /k8s show <app-name> — Read and display the Kubernetes manifests for an app Read files from kubernetes/apps/<app-name>/ and kubernetes/argocd-apps/<app-name>.yaml.

• /k8s edit <app-name> — Edit manifests for an ArgoCD app Open files in kubernetes/apps/<app-name>/ for editing. After edits, remind the user to commit and push for ArgoCD auto-sync.

Helm

• /k8s helm [cluster] — List Helm releases

  kubectl --kubeconfig <config> get secrets -A -l owner=helm --field-selector type=helm.sh/release.v1 \
    -o jsonpath='{range .items[*]}{.metadata.namespace}{"\t"}{.metadata.labels.name}{"\t"}{.metadata.labels.version}{"\n"}{end}'
  

Argument Parsing Rules

1. If no arguments: show help summary of available commands
2. If only a command: default to the shared cluster
3. Cluster can be shared, apps, or all
4. Namespace defaults to all (-A) unless specified

Safety Rules

• NEVER delete pods, deployments, or namespaces without explicit user confirmation
• NEVER run kubectl delete or kubectl apply without confirmation
• For ArgoCD syncs, explain what will happen before proceeding
• When editing manifests, remind the user that ArgoCD will auto-sync on push