Tutorial kagent Kubernetes: AI Agent di Cluster Laptop

CNCF menerbitkan walkthrough kagent di laptop pada 2026-10-12, lalu saya mencoba mencocokkannya dengan dokumentasi resmi project. Hasilnya tidak sama. Walkthrough memasang Helm chart 0.10.2 dan menulis manifest kagent.dev/v1alpha2. Branch main, halaman install, dan panduan first agent justru menjelaskan api.kagent.dev/v1alpha3, resource Harness baru, dan cluster yang wajib Kubernetes 1.37 atau lebih baru.

Saya tidak menjalankan cluster untuk tulisan ini. Saya membaca halaman project CNCF, README repo, architecture guide, schema CRD di Helm chart, halaman install dan first agent versi 1.x, wiki repo tools, serta walkthrough-nya, dan hanya mengutip angka yang memang tercetak di sana. Tujuannya satu peta untuk kedua jalur, supaya setup laptop yang Anda bangun sesuai versi yang Anda mau.

Apa itu kagent dan apa yang diterima CNCF

Halaman project CNCF menyebut kagent sebagai framework open source untuk DevOps dan platform engineer yang menjalankan AI agent di Kubernetes. Tingkat maturity-nya Sandbox, tanggal diterima 22 Mei 2025, dan commit pertama 21 Januari 2025. Sandbox adalah tingkat maturity paling awal di CNCF, jadi anggap ini project tahap awal, bukan jaminan stabilitas.

README menyebut komponennya. Controller memantau custom resource kagent, menyiapkan agent, mengelola session, dan membuka API gRPC, A2A, serta MCP. UI web dan CLI berbicara dengannya. PostgreSQL menyimpan session, task, dan riwayat percakapan terpisah dari agent yang berjalan. Runtime agent (Go atau Python ADK, Codex, Claude, atau runtime custom) dipilih lewat Harness, dan komponen Substrate menjalankannya serta mengurus suspend, resume, dan snapshot. Lisensinya Apache 2.0.

Dua kagent dirilis bersamaan

Halaman releases di GitHub menunjukkan kedua jalur berjalan paralel. v0.10.3 terbit pada 2026-10-02, sedangkan v1.0.0-alpha1 pada 2026-09-18 disusul tiga belas tag alpha lagi, terbaru v1.0.0-alpha14 pada 2026-10-16. Artinya empat belas tag alpha dalam 28 hari. Tabel berikut membandingkan keduanya dengan hanya memakai yang dicetak di sumber.

Sisa tulisan ini memisahkan kedua jalur. Kalau butuh yang cukup stabil untuk demo, jalur 0.10 adalah yang dijalankan tuntas oleh post ambassador CNCF. Kalau ingin melihat arah project, jalur 1.0 adalah tempat semua commit mendarat, dan dokumentasinya sendiri tertinggal satu tag dari rilis terbaru pada hari saya membacanya.

Jalur laptop 0.10: Ollama, kind, dan tool server read-only

Walkthrough karya Antonio Berben dan Felipe Vicens memasang chart 0.10.2 ke cluster kind bernama kagent-builder dan mengarahkan kagent ke Ollama lokal. File values mereka menjadikan Ollama provider default, membatasi tool server ke provider Kubernetes yang mereka sebut memuat 22 tool, mengaktifkan RBAC read-only, dan mematikan sample agent. Saya menyusun ulang file values dari values.yaml chart di v0.10.3, tempat blok Ollama memang providers.ollama.config.host ditambah options.num_ctx.

# kagent-values.yaml  (0.10.x line, as in the CNCF walkthrough)
providers:
  default: ollama
  ollama:
    provider: Ollama
    model: "qwen3-coder:30b-a3b-q4_K_M"   # ~18 GB on disk; smaller models failed
    config:
      host: host.docker.internal:11434    # Docker Desktop. On Linux this changes.
      options:
        num_ctx: "32768"

kagent-tools:
  tools:
    enabledTools: [k8s]       # only the Kubernetes provider: 22 tools
  rbac:
    readOnly: true            # the default would be cluster-admin

k8s-agent:
  enabled: false              # the chart ships sample agents; switch them off

kind create cluster --name kagent-builder

helm upgrade --install kagent-crds \
  oci://ghcr.io/kagent-dev/kagent/helm/kagent-crds \
  --version 0.10.2 --namespace kagent --create-namespace

helm upgrade --install kagent \
  oci://ghcr.io/kagent-dev/kagent/helm/kagent \
  --version 0.10.2 --namespace kagent --values kagent-values.yaml

kubectl -n kagent rollout status deployment/kagent-controller --timeout=300s
kubectl -n kagent rollout status deployment/kagent-ui --timeout=300s
kubectl -n kagent rollout status deployment/kagent-tools --timeout=300s

# Bind to loopback only. The UI has no real authentication in this setup.
kubectl -n kagent port-forward --address 127.0.0.1 svc/kagent-ui 8080:8080

Dua detail di file itu mengandung pelajarannya. Pertama, default chart memberi ServiceAccount tool server hak cluster-admin menurut walkthrough, jadi readOnly adalah penurunan yang disengaja, dan satu rule tambahan hanya mengizinkan menulis agents.kagent.dev. Kedua, modelnya penting: penulis melaporkan qwen2.5:7b-instruct mengarang format blok tool sendiri, qwen2.5:14b-instruct kadang menjawab sopan tanpa memanggil tool apply, dan hanya qwen3-coder:30b-a3b yang berhasil di setiap run. Model itu sekitar 18 GB di disk, kebutuhan laptop yang nyata.

Jalur 1.0 alpha: Harness, AgentTemplate, Agent, dan Session

Halaman install 1.x mencantumkan cluster Kubernetes 1.37 sebagai prasyarat dan memberi perintah kind dengan node image v1.37.0, yang butuh kind v0.32.0 atau lebih baru. Halaman itu juga meminta Anda memastikan API certificates.k8s.io tersedia. Installer-nya adalah kagent CLI, bukan helm install manual, dan ia membuat Secret yang diperlukan. Halaman itu mengunci CLI ke v1.0.0-alpha13.

# Node image 1.37.0 and kind v0.32.0 or later, per the 1.x install page.
kind create cluster --name kagent --image kindest/node:v1.37.0
export OPENAI_API_KEY="your-api-key-here"

# The CLI installs CRDs, Agent Substrate (ate-system), the PodCertificate
# controller, a development PostgreSQL and kagent itself.
kagent --config kagent-config.yaml install --namespace kagent
kubectl rollout status deployment/kagent-controller -n kagent --timeout=300s
kubectl get workerpools -n kagent      # one replica should be ready

Panduan first agent lalu memecah satu objek lama menjadi tiga. Harness menentukan cara agent berjalan: image runtime, worker pool Substrate, dan lokasi snapshot. AgentTemplate menyimpan perilaku yang portabel: model, prompt, tool. Agent menggabungkan keduanya. YAML di bawah ini milik panduan itu, dengan digest image diganti placeholder.

apiVersion: api.kagent.dev/v1alpha3
kind: Harness
metadata:
  name: my-first-harness
  namespace: kagent
spec:
  kagent: {}
  workload:
    image: ghcr.io/kagent-dev/kagent/golang-adk@<digest>   # pinned by digest
  substrate:
    workerPoolRef:
      name: kagent-default
    snapshotPolicy:
      location: s3://ate-snapshots/kagent/
---
apiVersion: api.kagent.dev/v1alpha3
kind: AgentTemplate
metadata:
  name: my-first-template
  namespace: kagent
spec:
  description: My first kagent agent
  modelConfig:
    name: default-model-config    # created at install from your API key
  systemPrompt: "You are a concise, helpful assistant."
---
apiVersion: api.kagent.dev/v1alpha3
kind: Agent
metadata:
  name: my-first-agent
  namespace: kagent
spec:
  template:
    ref:
      name: my-first-template     # or inline: { ... }, never both
  harnessRef:
    name: my-first-harness

kagent agent get my-first-agent
# READY=False right after apply is normal while the runtime snapshot builds.
kubectl get agent my-first-agent -n kagent -o jsonpath='{.status.conditions}' | jq
# Conditions: Accepted, ResolvedRefs, Compatible, Ready

export SESSION_ID=$(kagent agent session create --agent my-first-agent -o json | jq -r '.session.id')
kagent agent invoke --session $SESSION_ID --task "What is 2+2?"
kagent agent invoke --session $SESSION_ID --task "What did I just ask you?"

CLI menghubungi controller di localhost:8083 dan menjalankan kubectl port-forward sendiri bila tidak ada yang mendengarkan. Panduan menyebut pertanyaan kedua terjawab benar karena Session menyimpan transkrip, dan Ready bisa False sekitar satu menit setelah apply selagi snapshot runtime dibangun. Condition yang dibaca adalah Accepted, ResolvedRefs, Compatible, dan Ready, sedangkan status.warnings memuat keputusan kompatibilitas yang tidak memblokir.

Tool: RemoteMCPServer, allow-list, dan approval

Agent tidak pernah memegang tool langsung. Ia terikat ke resource RemoteMCPServer yang bisa dibagi antar agent. Template chart merender satu resource dengan nama release plus akhiran tool-server, menunjuk port 8084 di service tools dengan timeout 30 detik dan SSE read timeout lima menit. Di CRD v1alpha3, allowedNamespaces default-nya Same, meminjam pola cross-namespace Gateway API, jadi agent di namespace lain tidak bisa memakai server Anda kecuali Anda mengizinkan.

apiVersion: api.kagent.dev/v1alpha3
kind: RemoteMCPServer
metadata:
  name: kagent-tool-server
  namespace: kagent
spec:
  # Chart default shape: http://<tools service>.<namespace>:8084/mcp
  url: "http://kagent-tools.kagent:8084/mcp"
  protocol: STREAMABLE_HTTP     # default; SSE is the other allowed value
  timeout: 30s                  # default
  sseReadTimeout: 5m0s
  description: "Official KAgent tool server"
  allowedNamespaces:
    from: Same                  # default: only Agents in this namespace may use it
---
# Inside an AgentTemplate (or the inline form of an Agent):
spec:
  tools:
    - mcp:
        server:
          kind: RemoteMCPServer   # the CRD rejects any other kind
          name: kagent-tool-server
        tools:                    # allow-list, at most 50 names
          - k8s_get_resources
          - k8s_get_pod_logs
          - k8s_apply_manifest
        requireApproval: true     # pause before EVERY listed tool call

Server bawaan menyediakan tool untuk Kubernetes, Istio, Helm, Argo, Prometheus, Grafana, Cilium, dan lainnya. Saya memeriksa wiki kagent-dev/tools untuk isinya. Anggap angka ini potret README tersebut, bukan kontrak.

Perhatikan ketidakcocokannya: wiki mencantumkan 16 tool Kubernetes, sedangkan walkthrough menyebut provider k8s memuat 22. Jumlah tool bergeser antar versi, jadi jangan hard-code angka di prompt atau test. Wiki yang sama mendokumentasikan flag --read-only yang mematikan tool penulisan dan flag --tools untuk memilih provider yang didaftarkan. Di CRD v1alpha3, daftar tools pada sebuah binding dibatasi 50 nama, dan daftar yang kosong atau dihilangkan membuka semua tool di server.

Session: tempat percakapan sebenarnya disimpan

Session bukan resource Kubernetes, dan ini mengejutkan saya. Architecture guide menyebut PostgreSQL menyimpan identitas runtime, riwayat A2A, dan status lifecycle, serta session diekspos lewat gRPC. Jadi kubectl get tidak akan menampilkannya; pakai kagent agent session list, dan hapus Session sebelum menghapus Agent pemiliknya, seperti langkah cleanup di panduan first agent.

Yang didokumentasikan bisa dilakukan dengan Session lebih menarik daripada sekadar riwayat chat.

• Checkpoint: disimpan sebagai record PostgreSQL plus tag snapshot Substrate, batas restart yang immutable. Fork membuat Session baru dari sebuah checkpoint.
• Suspend: lifecycle worker menjeda atau men-suspend Actor yang idle secara mandiri, jadi agent yang diam tidak menahan proses yang berjalan.
• A2A: gateway publik memetakan context ID ke Session dan mengekspos tiap Agent. Walkthrough menunjukkan approval yang tertunda kembali sebagai state task input-required, dijawab dengan data part berisi decision_type approve pada taskId dan contextId yang sama.

Apa yang rusak, dan trade-off-nya

Walkthrough-nya cukup jujur soal batasan, begitu pula project-nya. Gabungkan keduanya dan daftar kegagalan untuk setup laptop pendek tetapi tajam.

• Model yang tidak andal memanggil tool menjadikan approval gate sekadar formalitas. Di walkthrough, Agent hasil generate menunjuk kagent-tools alih-alih kagent-tool-server dan controller mengembalikan Accepted=False, karena script penulis menyetujuinya tanpa dibaca. Baca condition-nya, bukan keyakinan model.
• Prompt adalah permintaan, bukan jaminan. Penulis walkthrough mengandalkan allow-list tool, approval manusia, dan RBAC sebagai guardrail yang sebenarnya, dan Anda sebaiknya begitu juga.
• Churn alpha itu nyata: empat belas tag alpha dalam 28 hari, docs terkunci di alpha13 padahal alpha14 sudah ada, dan architecture guide mencantumkan agent binding khusus, delegasi lintas-Session berbasis policy, berbagi checkpoint, serta koordinasi gateway multi-replica sebagai belum diimplementasikan.
• Biaya hardware tersembunyi di jalur murah. Jalur 0.10 tanpa API key butuh model 18 GB, dan jalur 1.0 butuh node image Kubernetes 1.37 plus lokasi snapshot bergaya S3 di Harness panduan.

Saya tidak akan memilih jalur berdasarkan fitur. Saya memilih berdasarkan blast radius: 0.10 dengan RBAC read-only untuk belajar, 1.0 alpha hanya di cluster sekali pakai sampai daftar belum-diimplementasikan menyusut.

Yang dikerjakan hari Senin

Semua ini tidak butuh cluster produksi. Habiskan satu sore di cluster kind sekali pakai dan kerjakan berurutan.

1. Putuskan jalurnya. Mau belajar agent sebagai resource di cluster biasa: 0.10.x. Mau menilai arah kagent: 1.0 alpha di kind dengan node image v1.37.0.
2. Install dengan sample agent mati dan hanya provider tool Kubernetes, memakai file values di atas atau installer.
3. Cek apa yang bisa dilakukan tool server dengan kubectl auth can-i sebelum agent apa pun berjalan, dan targetkan no untuk membuat deployment dan membaca secret.
4. Ikat agent ke allow-list tool yang eksplisit dan aktifkan approval untuk satu tool penulisan. Lalu cek condition Accepted pada setiap Agent yang Anda apply.
5. Buka Session, ajukan pertanyaan, ajukan pertanyaan lanjutan yang bergantung padanya, baru putuskan apakah setup ini layak diteruskan.

# Step 3: prove the tool server cannot do what you did not intend.
SA=system:serviceaccount:kagent:kagent-tools
kubectl auth can-i create deployments -n kagent --as=$SA   # want: no
kubectl auth can-i get secrets        -n kagent --as=$SA   # want: no

# Step 4: an Agent that points at the wrong server is Accepted=False.
# Read the condition before you trust a generated manifest.
kubectl get agent -n kagent \
  -o custom-columns=NAME:.metadata.name,ACCEPTED:.status.conditions[?(@.type=="Accepted")].status

Setelah selesai, kind delete cluster menghapus semuanya. Itulah gunanya mencoba di laptop dulu.

kagent menjadikan agent sebagai objek Kubernetes biasa, dan itu ide yang bagus. Aturan praktis yang saya bawa: kunci versi sebelum menyalin YAML, anggap RBAC tool server sebagai batas keamanan yang sebenarnya, dan baca condition Accepted alih-alih memercayai jawaban model.