> For the complete documentation index, see [llms.txt](https://docs.kangal.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kangal.dev/tr/configuration-ve-otomasyon/kangalctl.md). # kangalctl `scripts/kangalctl.py`; Admin API context'leri, yapılandırma akışları, durum kontrolleri ve kaynak CRUD işlemleri için kaynak kodla dağıtılan operatör CLI'ıdır. Bağımsız sürümlenen bir çalıştırılabilir dosya veya Python paketi değildir. Aracı, yönettiğiniz kontrol düzlemiyle tam olarak eşleşen Kangal sürüm etiketinden edinin ve betiği o etiketin kaynak ağacındaki diğer dosyalarla birlikte tutun. ## Çalışma zamanı ve uyumluluk Eşleşen sürüm checkout'unda ayrı bir ortam oluşturun ve o etiketin sabitlenmiş bağımlılıklarını kurun: ```bash git describe --tags --exact-match python3.12 -m venv .venv source .venv/bin/activate python -m pip install -r requirements.txt python scripts/kangalctl.py --help ``` Bu sürüm Python 3.11, 3.12 ve 3.13'ü destekler. Başka bir sürüm için o etiketin belirttiği Python sürümlerini ve bağımlılık sabitlemelerini kullanın. CLI; Kangal yapılandırma şemalarını, doğrulayıcılarını ve YAML desteğini kaynak ağacından içe aktarır. Yalnızca `scripts/kangalctl.py` dosyasını kopyalamak veya sabitlenmemiş bağımlılıklar kurmak desteklenmez. Sunucu sürümüyle tam olarak eşleşen CLI etiketini kullanın. Ortak `/api/v1` öneki, farklı bir sürümdeki CLI komutlarının, payload şemalarının, doğrulama davranışının veya yanıt işlemenin uyumlu olduğunu garanti etmez. Sunucuyu ve CLI'ı tek uyumluluk birimi olarak yükseltin; değişiklik uygulamadan önce `validate`, sunucu tarafı deneme çalışması ve salt okunur durum kontrolünü yeniden çalıştırın. Global seçenekler komuttan önce gelmelidir: ```bash python scripts/kangalctl.py \ --api-url https://kangal.example.com \ --token "$KANGAL_TOKEN" \ status ``` Global seçenekler `--api-url`, `--token` ve `--context`'tir. ## Context dosyası ve kimlik bilgileri Context'ler varsayılan olarak `~/.kangalctl/config.json` içinde saklanır. CI ve izole operatör profilleri için yolu `KANGALCTL_CONFIG` ile değiştirin. ```bash export KANGALCTL_CONFIG="$HOME/.config/kangal/production.json" mkdir -p "$(dirname "$KANGALCTL_CONFIG")" umask 077 ``` CLI bearer token'ı bu dosyada plaintext saklar. Context display/list çıktısında redakte edilir, ancak dosyanın kendisi hassastır. İzinleri sınırlandırın, commit etmeyin ve CI'da kısa ömürlü enjekte edilmiş dosya tercih edin. Mevcut Admin API token ile context oluşturun: ```bash python scripts/kangalctl.py login \ --context-name production \ --api-url https://kangal.example.com \ --token "$KANGAL_TOKEN" \ --tenant-id tenant-acme chmod 600 "$KANGALCTL_CONFIG" ``` Ya da username/password ile kullanıcı session'ı açın: ```bash python scripts/kangalctl.py login \ --context-name production \ --api-url https://kangal.example.com \ --username admin@example.com \ --password 'REDACTED' \ --tenant-id tenant-acme ``` İkinci biçim `POST /auth/login` çağırır. Context adı varsayılan olarak `default`'tur; başarılı login, ilgili seçenekle kapatılmadıkça context'i aktif yapar. Context yönetimi: ```bash python scripts/kangalctl.py context list python scripts/kangalctl.py context show production python scripts/kangalctl.py context use production python scripts/kangalctl.py context delete staging ``` ## Durum kontrolü ```bash python scripts/kangalctl.py status ``` Status `/health` ve `/ready` endpoint'lerini kontrol eder; context veya komut `tenant_id` sağlıyorsa gateway listesini de almaya çalışır. Erişilemeyen bloklar çıktıda ayrı gösterilir; yalnızca process exit status'una güvenmek yerine her bölümü inceleyin. ## Yerel validation Validation yereldir ve API context gerektirmez: ```bash python scripts/kangalctl.py validate config/tenant-acme.yaml python scripts/kangalctl.py validate config/tenant-acme.yaml --strict ``` Katı mod, paket içindeki eksik route-to-service ve route/service-to-upstream referanslarını hataya dönüştürür. Her kaynak alanını doğrulamaz veya canlı durumdaki referansları çözmez. Yerel doğrulama hızlı geri bildirim sağlar; ancak dağıtılmış sözleşme ve canlı durumun sahibi sunucu olduğu için uygulamadan önce sunucu tarafı doğrulama/deneme çalışması yine zorunludur. ## Export ve diff ```bash python scripts/kangalctl.py export \ --tenant-id tenant-acme \ --format yaml \ --output backups/tenant-acme.yaml python scripts/kangalctl.py diff desired/tenant-acme.yaml \ --tenant-id tenant-acme \ --strict ``` `--current` verilmezse `diff`, canlı state için Admin API'yi çağırır. İki yerel dosyayı karşılaştırmak için: ```bash python scripts/kangalctl.py diff desired/tenant-acme.yaml \ --current backups/tenant-acme.yaml \ --strict ``` YAML, `.yaml`/`.yml` output uzantısından anlaşılır veya `--format` ile açıkça seçilir. ## Import ve sync Doğrudan import varsayılan olarak apply yapar. Preview için `--dry-run` ekleyin: ```bash python scripts/kangalctl.py import desired/tenant-acme.yaml --dry-run python scripts/kangalctl.py import desired/tenant-acme.yaml --overwrite --dry-run # Yalnızca preview incelendikten sonra uygulayın. python scripts/kangalctl.py import desired/tenant-acme.yaml --overwrite ``` Sync'in CLI varsayılanları daha güvenlidir: `--apply` verilmedikçe dry-run çalışır; overwrite, strict validation ve pre-apply snapshot açıktır. ```bash # Preview python scripts/kangalctl.py sync desired/tenant-acme.yaml \ --tenant-id tenant-acme \ --snapshot-note 'release 2026.07.17' \ --created-by 'change-1842' # İncelenen planı uygula python scripts/kangalctl.py sync desired/tenant-acme.yaml \ --tenant-id tenant-acme \ --apply \ --snapshot-note 'release 2026.07.17' \ --created-by 'change-1842' ``` Bilinçli değişiklikler için: * `--no-overwrite`, eşleşen canlı kaynakları atlar. * `--no-snapshot`, pre-apply snapshot'ı kapatır. * `--strict` / `--no-strict`, referans validation davranışını seçer. Managed promotion için sync'i tercih edin; tek işlem validation, live diff, count ve snapshot bilgisini birlikte döndürür. Import veya sync'in bundle'da olmayan kaynakları silmediğini unutmayın. ## Kaynak CRUD işlemleri Desteklenen entity adları: ``` gateways, services, routes, upstreams, targets, certificates, ca-certificates, snis, vaults, redis-configs, data-planes, consumers, consumer-groups, consumer-credentials, realms, api-tokens ``` Tekil alias'lar da kabul edilir. Tam seçenekleri help ile inceleyin: ```bash python scripts/kangalctl.py get --help python scripts/kangalctl.py create --help python scripts/kangalctl.py update --help python scripts/kangalctl.py delete --help ``` Kaynak listeleme: ```bash python scripts/kangalctl.py get gateways \ --tenant-id tenant-acme python scripts/kangalctl.py get services \ --tenant-id tenant-acme \ --gateway-id gw-production \ --label-selector 'environment=production' \ --limit 100 \ --offset 0 \ --sort name \ --order asc python scripts/kangalctl.py get targets \ --tenant-id tenant-acme \ --gateway-id gw-production \ --upstream-id orders-upstream ``` Gateway-scoped entity'ler `--gateway-id`; target listesi ayrıca `--upstream-id` gerektirir. Tenant, consumer, label selector, limit, offset, sort ve order filtreleri CLI tarafından iletilir; hangilerinin uygulanacağını ilgili Admin API endpoint'i belirler. Create, update ve delete: ```bash python scripts/kangalctl.py create services \ --gateway-id gw-production \ --file service.yaml python scripts/kangalctl.py update services service-id \ --gateway-id gw-production \ --file service-update.yaml python scripts/kangalctl.py delete services service-id \ --gateway-id gw-production ``` Input dosyaları JSON veya YAML olabilir; uzantı parse biçimini belirler. CRUD izinleri HTTP method'una bağlıdır: read için `admin:read`, write için `admin:write` gerekir. ## SDK artifact export Yayınlanmış bir portal API version'ı için üretilen SDK'yı indirin: ```bash mkdir -p artifacts python scripts/kangalctl.py sdk export \ --service-id SERVICE_ID \ --version-id VERSION_ID \ --tenant-id tenant-acme \ --gateway-id gw-production \ --target python \ --output artifacts/orders-python.zip ``` Hedefler `typescript-fetch`, `python`, `go`, `java`, `csharp` ve `php`'dir. CLI dönen Base64 payload'ı, media type'ı, bildirilen boyutu, SHA-256 checksum'ı ve output dosya adını doğrular. `--force` verilmedikçe mevcut artifact'i değiştirmez; hedef dizin önceden var olmalıdır. ## Otomasyon örüntüsü İzole context dosyası kullanın ve validation/preview başarısızsa pipeline'ı apply'dan önce durdurun: ```bash set -euo pipefail export KANGALCTL_CONFIG="$RUNNER_TEMP/kangalctl.json" python scripts/kangalctl.py login \ --context-name ci \ --api-url "$KANGAL_URL" \ --token "$KANGAL_TOKEN" \ --tenant-id "$TENANT_ID" chmod 600 "$KANGALCTL_CONFIG" python scripts/kangalctl.py validate desired.yaml --strict python scripts/kangalctl.py sync desired.yaml --tenant-id "$TENANT_ID" # Bunu deployment ortamının approval gate'i arkasında çalıştırın. python scripts/kangalctl.py sync desired.yaml \ --tenant-id "$TENANT_ID" \ --apply \ --snapshot-note "$RELEASE_REF" \ --created-by "$CI_ACTOR" ``` HTTP istemci timeout'u 30 saniyedir. Büyük export/import veya aşırı yüklü API bu süreyi aşabilir; bundle'ı küçültün, API/veritabanı sağlığını kontrol edin ve write işleminin kısmen uygulanıp uygulanmadığını belirlemeden tekrar denemeyin. ## Snapshot işlemleri Configuration snapshot oluşturma, listeleme, preview ve apply işlemleri için [Import, export ve rollback](/tr/configuration-ve-otomasyon/import-export-rollback.md) bölümündeki Admin API çağrılarını kullanın. Bu snapshot akışının validation, live diff, import ve sync adımlarında `kangalctl` kullanmaya devam edin. ## Sorun giderme | Belirti | Çözüm | | ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `No active context` | `login` veya `context use` çalıştırın; ya da komuttan önce global `--api-url` ve `--token` verin. | | Global seçenek reddediliyor | `--api-url`, `--token` veya `--context` seçeneğini subcommand'dan önce taşıyın. | | Context yerelde çalışıyor, CI'da çalışmıyor | `KANGALCTL_CONFIG` yolunu açıkça ayarlayın ve job içinde create/login yapın. | | `401` | Token eksik, süresi dolmuş, revoke edilmiş veya başka ortama ait. Yeniden login olun veya Admin API token'ını rotate edin. | | Write işleminde `403` | Writer/admin rolü ve `admin:write` scope'lu token kullanın; tenant izinlerini doğrulayın. | | CLI ve sunucu davranışı farklı | `git describe --tags --exact-match` çıktısının sunucunun tam sürüm etiketini gösterdiğini doğrulayın; ardından ortamı o etiketin `requirements.txt` dosyasından yeniden oluşturun. | | İstek gönderilmeden önce import hatası oluşuyor | Seçilen etiketin desteklediği Python sürümünü kullanıp sabitlenmiş bağımlılıkları yeniden kurun; tek başına kopyalanmış betik çalıştırmayın. | | Request timeout oluyor | `/health`, `/ready`, API logları, MongoDB ve bundle boyutunu inceleyin. Timeout olan write kısmen uygulanmış olabilir. | | Import canlı state'i beklenmedik değiştirdi | Doğrudan import `--dry-run` olmadan apply yapar; hemen export/diff alın ve forward fix veya test edilmiş rollback seçin. | | Output dosyasında redakte secret var | Beklenen davranış. Bunu secret yedeği olarak kullanmayın, placeholder ile secret overwrite etmeyin. | --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.kangal.dev/tr/configuration-ve-otomasyon/kangalctl.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.