Ana içeriğe geç

Hızlı başlangıç

Yapmak istediğiniz: bir agent'a vermeden önce OpenConsole'u bir terminalden API anahtarıyla çağırmak.

curl ve jq gerekir. Örnekler, kod repository'sindeki hack/k3d/crashlab.yaml ile oluşturulan crashlab namespace'ine sahip bir test cluster'ında çalıştırıldı; sizdeki adlar farklı olacaktır.

1. Anahtar oluşturun​

OpenConsole'da: adınız (sağ üst) → API anahtarları → Yeni API anahtarı. Cluster'ı, namespace'leri ve Salt okuma (güvenli) şablonunu seçin, sonra anahtarı kopyalayın (oc_ ve 40 karakter). Anahtar yalnızca bir kez gösterilir. Ayrıntılar: API anahtarlarınız.

export OC_URL=https://openconsole.example.com # your OpenConsole address, no trailing slash
export OPENCONSOLE_API_KEY=oc_… # the key you copied

2. Ben kimim​

curl -s -H "Authorization: Bearer $OPENCONSOLE_API_KEY" "$OC_URL/api/auth/me" \
| jq '{key: .apiKey.name, grants: .apiKey.grants, namespaces}'
{
"key": "claude-code",
"grants": ["deployments:get", "deployments:list", "pods:get", "pods:list", "pods:logs"],
"namespaces": ["crashlab"]
}

Tam yanıttaki namespaces ve permissions, anahtarın şu an erişebildikleridir (anahtar ∩ rolleriniz ∩ admin'in politikası); her script'e ya da agent'a bu çağrıyla başlayın.

3. Cluster'ı seçin​

Her istek, X-OpenConsole-Cluster ile adı ya da id'siyle bir cluster belirtmedikçe seçili cluster'ınızda çalışır. Anahtarın kullanabileceği cluster'lar:

curl -s -H "Authorization: Bearer $OPENCONSOLE_API_KEY" "$OC_URL/api/clusters/public"
{"items":[{"id":1,"name":"k3d","isActive":true,"selected":true}]}

Sonra her istekte cluster'ı belirtin:

curl -s -H "Authorization: Bearer $OPENCONSOLE_API_KEY" -H "X-OpenConsole-Cluster: k3d" \
"$OC_URL/api/namespaces/crashlab/pods" \
| jq -r '.items[] | [.metadata.name, .status.phase, .status.containerStatuses[0].restartCount] | @tsv'
agent-598r8 Running 0
badimage-67b7966bb-82lhs Pending 0
brokendb-0 Running 6
db-0 Running 0
db-1 Running 0
…

Listeler, Kubernetes nesnelerini API server'ın gönderdiği haliyle (metadata, spec, status) items altında döndürür.

4. Log okuyun​

curl -s -H "Authorization: Bearer $OPENCONSOLE_API_KEY" \
"$OC_URL/api/namespaces/crashlab/pods/exit1-6bb6b857dc-bbcxg/logs?container=app&previous=true&tailLines=5"
starting
fatal: config missing

Düz metin döner. previous=true, container'ın bir önceki çalışmasıdır (çöken çalışma); tailLines varsayılan olarak 500'dür. Restart'tan hemen sonra Kubernetes bir süre unable to retrieve container logs for containerd://… yanıtı verebilir, tıpkı kubectl logs --previous gibi: container şu an Error durumundaysa previous olmadan okuyun.

5. Tek komut çalıştırın​

Anahtarda pods:exec gerekir (Salt okuma şablonlarında yoktur):

curl -s -H "Authorization: Bearer $OPENCONSOLE_API_KEY" -H "Content-Type: application/json" \
-d '{"container": "app", "command": ["uname", "-sr"], "timeoutSeconds": 30}' \
"$OC_URL/api/namespaces/crashlab/pods/healthy-66fb4fb769-4cjqs/exec"
{"stdout":"Linux 6.8.0-110-generic\n","stderr":"","exitCode":0,"truncated":false,"durationMs":496}

command bir argv dizisidir, shell içinde çalıştırılmaz (pipe için ["sh", "-c", "…"]). Sıfırdan farklı bir çıkış kodu da 200 döner. Komut bir shell oturumu gibi kaydedilir; audit olayı argümanları değil, yalnızca programı (uname) tutar.

Hatalar​

Her ret audit'e yazılır. Hata cevabı, RFC 9457'nin problem details biçiminde JSON'dır; Content-Type: application/problem+json:

{"type":"about:blank","title":"Bad Request","status":400,"error":"invalid_input","detail":"cluster \"nope\" is unknown or not yours to use"}
  • error her zaman bir neden kodudur (snake_case): kararı buna göre verin.
  • detail (her zaman yoktur) bir insan için İngilizce metindir: hangi alan, hangi ad. Gösterin ya da loglayın; ayrıştırmayın.
  • title HTTP durum metnidir, type her zaman about:blank'tır.

API'nin yolunda sürüm yoktur. Yalnızca büyür (yeni alanlar, yeni kodlar, yeni uçlar); bu yüzden bilmediğiniz şeyleri yok sayın. /api/openapi.json içindeki info.version sunucunun sürümüdür. Bilinmeyen bir /api/… yolu 404 not_found, bilinen bir yola yanlış metotla gelen istek Allow header'ıyla 405 method_not_allowed cevabı alır.

DurumerrorAnlamı
401unauthorizedAnahtar yok, anahtar bilinmiyor ya da sahibi devre dışı.
401api_key_expired / api_key_revokedAnahtarın süresi doldu / anahtar iptal edildi.
403password_change_requiredSahibinin parolasını değiştirmesi gerekiyor (ilk giriş ya da admin sıfırlaması).
403forbiddenAnahtarda listelenmiyor ya da o namespace'te sizde yok.
403api_access_policyWeb'de sizde var, ama admin'in API erişim politikası anahtarlara vermiyor.
403api_access_offPolitika anahtarlarınıza hiçbir şey vermiyor; /api/auth/me dahil her çağrı reddedilir.
403api_key_not_allowedYalnızca web oturumunda yapılabilir (anahtar yönetimi, parola, kayıtlı görünümler).
403feature_disabledOperatör özelliği kapattı (FEATURE_*=false).
403admin_onlyBir admin ucu ve anahtar bir admin'in Admin API anahtarı değil.
400invalid_inputBir değer kabul edilmedi; hangisi olduğunu detail söyler. Örneğin X-OpenConsole-Cluster var olmayan bir cluster'ı belirtiyor (anahtarın kapsamadığı biri için 403 forbidden).
404not_found / pod_not_foundNesne ya da yol yok.
403cluster_forbiddenCluster okumayı reddetti: OpenConsole'un oradaki ClusterRole'ü buna izin vermiyor.
502 / 503 / 504cluster_unreachable / not_connected / cluster_timeoutCluster'a ulaşılamıyor ya da OpenConsole'un kimlik bilgilerini reddetti / bağlı değil / zamanında cevap vermedi.
429rate_limitedBu anahtar için saniyede 10'dan fazla istek; Retry-After kadar (1 saniye) bekleyin. Bkz. Limitler.

Tüm kodlar: Sorun giderme → Hata cevapları.

Test cluster'ında şu komutlarla görüldü:

curl -s -w ' %{http_code}\n' -H "Authorization: Bearer $OPENCONSOLE_API_KEY" "$OC_URL/api/namespaces/kube-system/pods"
# {"type":"about:blank","title":"Forbidden","status":403,"error":"forbidden"}
# 403
curl -s -w ' %{http_code}\n' -H "Authorization: Bearer $OPENCONSOLE_API_KEY" "$OC_URL/api/me/api-keys"
# {"type":"about:blank","title":"Forbidden","status":403,"error":"api_key_not_allowed"}
# 403
curl -s -w ' %{http_code}\n' -H "Authorization: Bearer $OPENCONSOLE_API_KEY" -H "X-OpenConsole-Cluster: nope" \
"$OC_URL/api/namespaces/crashlab/pods"
# {"type":"about:blank","title":"Bad Request","status":400,"error":"invalid_input","detail":"cluster \"nope\" is unknown or not yours to use"}
# 400
curl -s -w ' %{http_code}\n' -H "Authorization: Bearer $OPENCONSOLE_API_KEY" "$OC_URL/api/admin/users"
# {"type":"about:blank","title":"Forbidden","status":403,"error":"admin_only"}
# 403
curl -s -w ' %{http_code}\n' -H "Authorization: Bearer oc_notarealkey" "$OC_URL/api/auth/me"
# {"type":"about:blank","title":"Unauthorized","status":401,"error":"unauthorized"}
# 401
curl -s -i -X DELETE -H "Authorization: Bearer $OPENCONSOLE_API_KEY" "$OC_URL/api/namespaces/crashlab/pods" | grep -E '^(HTTP|Allow)|"error"'
# HTTP/1.1 405 Method Not Allowed
# Allow: GET
# {"type":"about:blank","title":"Method Not Allowed","status":405,"error":"method_not_allowed"}

Sonraki adım: anahtarı bir agent'a verin: Agent tarifleri. Tüm uçlar: uç referansı.