kubernetes-architecture-analyser

name	kubernetes-architecture-analyser
description	Analyses a live Kubernetes cluster and produces .crux/docs/kubernetes.md and .crux/summaries/kubernetes.md. Read-only — does not modify any cluster resources. Use when: (1) .crux/docs/kubernetes.md is missing during onboarding, (2) user requests an architecture review, (3) cluster configuration has significantly changed.
license	MIT
compatibility	opencode
metadata	{"owner":"kubernetes-admin","type":"read-only","approval":"No"}

kubernetes-architecture-analyser

Owner: kubernetes-admin Type: read-only Approval: No

---

What I Do

Connects to a live Kubernetes cluster via kubectl, collects cluster facts (nodes, namespaces, CNI, storage, workload health), and writes a structured architecture document to .crux/docs/kubernetes.md with a token-efficient summary at .crux/summaries/kubernetes.md.

---

When to Use Me

• .crux/docs/kubernetes.md is missing and cluster is reachable
• User requests: "analyse cluster", "generate architecture doc", "update architecture"
• Cluster configuration has significantly changed since last analysis
• Onboarding Step 4 triggers me automatically

---

Context Requirements

Requires already loaded:
  .crux/workspace/kubernetes-admin/MEMORY.md   (cluster-endpoint, kubectl-version)

Does not load additional docs — all data comes from live cluster.

Estimated token cost: ~600 tokens
Unloaded after: docs written and MANIFEST.md updated

---

Inputs

Input	Source	Required
kubectl access	environment / KUBECONFIG	Yes
cluster-endpoint	MEMORY.md	Yes
production-namespaces	MEMORY.md	No — used for annotations in output

---

Steps

1. Verify access
   Run: kubectl cluster-info --request-timeout=5s
   IF unreachable → stop, notify:
     "Cannot reach cluster. Check kubeconfig and try again."

2. Collect cluster-level facts
   kubectl version -o json
   kubectl get nodes -o wide
   kubectl get nodes -o json  (extract: roles, taints, conditions, capacity)

3. Collect namespace inventory
   kubectl get namespaces -o wide
   For each namespace (up to 20):
     kubectl get pods -n {ns} --no-headers | wc -l
     kubectl get deployments -n {ns} --no-headers 2>/dev/null
     kubectl get services -n {ns} --no-headers 2>/dev/null
   IF more than 20 namespaces: collect names only, note in output

4. Collect networking facts
   kubectl get pods -n kube-system -o wide | grep -Ei "cilium|calico|flannel|weave"
   kubectl get ingressclass
   kubectl get svc -A | grep LoadBalancer
   kubectl get networkpolicies -A --no-headers 2>/dev/null | wc -l

5. Collect storage facts
   kubectl get storageclass
   kubectl get pv --no-headers
   kubectl get pvc -A --no-headers

6. Collect workload health
   kubectl get pods -A --field-selector=status.phase!=Running 2>/dev/null
   kubectl get events -A --field-selector=type=Warning \
     --sort-by='.lastTimestamp' 2>/dev/null | tail -20

7. Write .crux/docs/kubernetes.md  (see Output section)

8. Write .crux/summaries/kubernetes.md  (max 200 tokens)

9. Update MANIFEST.md docs entry:
     last-updated: {DATE}
     tokens: {estimated}
     summary: .crux/summaries/kubernetes.md

10. Skill complete — notify: "Architecture document written to .crux/docs/kubernetes.md"

---

Output

Writes to: .crux/docs/kubernetes.md and .crux/summaries/kubernetes.md Format: markdown

docs/kubernetes.md

# Kubernetes Architecture

> Generated by kubernetes-architecture-analyser on {DATE}.
> Source: live cluster at {endpoint}.
> Update: @kubernetes-admin analyse cluster

## Cluster

- **Endpoint**: {endpoint}
- **Kubernetes version**: {version}
- **Node count**: {n} ({control-plane} control-plane, {workers} workers)

## Nodes

| Name | Role | Status | CPU | Memory | OS |
|---|---|---|---|---|---|
| {name} | {role} | {status} | {cpu} | {mem} | {os} |

## Namespaces

| Namespace | Pods | Deployments | Notes |
|---|---|---|---|
| {ns} | {n} | {n} | {production flag if applicable} |

## Networking

- **CNI**: {cni} {version}
- **Ingress classes**: {list}
- **Load balancer services**: {count}
- **Network policies defined**: {count}

## Storage

| Storage Class | Provisioner | Default |
|---|---|---|
| {name} | {provisioner} | {yes/no} |

- **Persistent Volumes**: {count}
- **Persistent Volume Claims**: {count} across {n} namespaces

## Workload Health

- **Non-running pods**: {count}  {list if > 0}
- **Recent warning events**: {count}  {top 5 if > 0}

## Notes

{Anomalies, partial data, or manual additions}

---
*Last updated: {DATE} — source: live-analysis*

summaries/kubernetes.md

# Kubernetes — Summary

{n}-node cluster ({roles}) at {endpoint}.
CNI: {cni}. Storage: {storage-classes}.
{n} namespaces — production: {list or none}.
Health: {ok | {n} non-running pods, {n} warning events}.
Last analysed: {DATE}.

---

Error Handling

Condition	Action
kubectl not found	Stop. Notify: "kubectl is required. Install it or provide path."
Cluster unreachable	Stop. Notify with endpoint, suggest kubeconfig check.
Partial data (some commands fail)	Continue. Mark affected sections (partial — {reason}).
More than 20 namespaces	Collect names only beyond 20. Note in doc.
.crux/docs/ not writable	Write to .crux/workspace/output/kubernetes.md. Notify user.