> 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/gateway/quickstart.md).

# İlk API'nizi yayınlayın

Bu rehber, bir HTTP service'ini Kangal üzerinden yayınlamanızı, herkese açık proxy yolunu doğrulamanızı ve policy eklemeden önce kontrol edilmesi gereken hata sinyallerini tanımanızı sağlar.

## Ön koşullar

Şunlara ihtiyacınız vardır:

* çalışan bir Kangal kontrol düzlemi;
* bir tenant için yönetici token'ı;
* tenant ID;
* trafiği proxy edecek runtime'ın erişebildiği bir backend URL'i;
* komut olarak kurulmamışsa repository entrypoint'i `python scripts/kangalctl.py` üzerinden kullanılabilen `kangalctl`.

Örneklerde şu shell değişkenleri kullanılır:

```bash
export KANGAL_API_URL="https://control.example.com"
export KANGAL_ADMIN_TOKEN="replace-with-admin-token"
export KANGAL_TENANT_ID="tenant-acme"
export KANGAL_PROXY_BASE="https://proxy.example.com"
```

`KANGAL_API_URL`, `kangalctl` tarafından kullanılan kontrol düzlemi kök adresidir; CLI, Admin API path'lerini bu adrese ekler. `KANGAL_PROXY_BASE`, erişilebilir birleşik runtime veya bağımsız veri düzlemi adresidir. Birleşik deployment'ta iki değişken aynı adresi kullanabilir.

## 1. CLI context'ini yapılandırın

```bash
kangalctl login \
  --api-url "$KANGAL_API_URL" \
  --token "$KANGAL_ADMIN_TOKEN" \
  --tenant-id "$KANGAL_TENANT_ID" \
  --context-name quickstart

kangalctl status
```

`status`; `/health`, `/ready` ve tenant kapsamındaki gateway listesini kontrol eder. Production trafiğini göndermeden önce veri düzlemini ve backend'i ayrıca doğrulayın.

## 2. Gateway oluşturun

Şuna benzer bir payload kullanın:

```yaml
tenant_id: tenant-acme
name: orders-prod
description: Orders API production gateway
deployment_profile: serverless
plan_code: serverless_starter
labels:
  environment: production
  owner: platform
```

Gateway'i oluşturun ve listeleyin:

```bash
kangalctl create gateways -f gateway.yaml
kangalctl get gateways --tenant-id "$KANGAL_TENANT_ID"
```

Dönen gateway `id` değerini kaydedin:

```bash
export KANGAL_GATEWAY_ID="replace-with-gateway-id"
```

Konsol, gateway adının en az üç karakter uzunluğunda olmasını ve `^[a-z0-9][a-z0-9-_.]*$` kalıbıyla eşleşmesini zorunlu kılar; seçilen deployment profilini ilgili plan code ile eşleştirir. Admin API, gönderilen profil ve plan metadata'sını saklar. Gateway oluşturma response'u `proxy_host`, `proxy_url` ve workspace metadata'sını da içerir. Adresi trafiğe açmadan önce herkese açık DNS ve TLS kontrollerini tamamlayın.

## 3. Doğrudan service oluşturun

Bir service doğrudan URL'e veya bir upstream havuzuna yönlenebilir. Route eşleştirmesini load balancing'den bağımsız test etmek için doğrudan URL ile başlayın.

```yaml
tenant_id: tenant-acme
name: orders-service
url: http://orders.internal:8080/api
retries: 2
connect_timeout_ms: 5000
read_timeout_ms: 15000
write_timeout_ms: 15000
labels:
  application: orders
```

```bash
kangalctl create services --gateway-id "$KANGAL_GATEWAY_ID" -f service.yaml
kangalctl get services --gateway-id "$KANGAL_GATEWAY_ID"
```

Dönen service `id` değerini kaydedin:

```bash
export KANGAL_SERVICE_ID="replace-with-service-id"
```

URL, `http://` veya `https://` içermelidir. Alternatif olarak `protocol`, `host`, `port` ve `path` alanlarını kullanabilirsiniz; Kangal bu alanları runtime'da bir URL olarak birleştirir.

## 4. Prefix route oluşturun

```yaml
tenant_id: tenant-acme
name: orders-public
path: /orders
path_type: prefix
methods:
  - GET
  - HEAD
service_id: replace-with-service-id
service_name: orders-service
hosts: []
snis: []
headers: {}
query_params: {}
strip_path: true
preserve_host: false
priority: 100
plugins: []
labels:
  exposure: public
```

`service_id` değerini değiştirin, ardından route'u oluşturun:

```bash
kangalctl create routes --gateway-id "$KANGAL_GATEWAY_ID" -f route.yaml
kangalctl get routes --gateway-id "$KANGAL_GATEWAY_ID"
```

Sonraki güncellemeler ve temizlik için dönen route `id` değerini kaydedin:

```bash
export KANGAL_ROUTE_ID="replace-with-route-id"
```

Bu yapılandırmayla `/orders/health` isteği `/orders` prefix'iyle eşleşir. `strip_path` değeri `true` olduğu için Kangal, service URL'ine `/api/health` path'ini gönderir. `strip_path` değeri `false` olsaydı `/api/orders/health` gönderilirdi.

## 5. Proxy üzerinden trafik gönderin

Edge host gateway ile eşlenene kadar kapsam header'larını açıkça gönderin:

```bash
curl -i \
  "$KANGAL_PROXY_BASE/proxy/orders/health?verbose=true" \
  -H "X-Tenant-ID: $KANGAL_TENANT_ID" \
  -H "X-Gateway-ID: $KANGAL_GATEWAY_ID" \
  -H "X-Request-ID: quickstart-001"
```

Herkese açık `/proxy/{path}` entrypoint'i yönetici oturumu gerektirmez. Consumer kimlik doğrulaması, route'a atanan plugin'ler tarafından uygulanır. `KANGAL_ADMIN_TOKEN` değerini proxy isteğine göndermeyin.

Oturum tabanlı trafik için kimlik doğrulamalı `/api/proxy/{path}` endpoint'i de kullanılabilir. Herkese açık consumer trafiği için `/proxy/{path}` kullanın.

## 6. Sonucu doğrulayın

Authentication veya rate limiting eklemeden önce şunların tümünü doğrulayın:

1. Response, beklenen backend ve path'ten geldi.
2. Status, Kangal tarafından döndürülen `404`, `405`, `502` veya `503` değil.
3. Backend beklenen query string'i aldı.
4. `X-Request-ID`, response'ta veya ilgili trafik telemetry'sinde yer alıyor.
5. Gateway genel görünümünde service ve route görünüyor.
6. Bağımsız deployment'ta gerekli düğüm online ve mevcut yapılandırma sürümü hedef sürümle eşleşiyor.

Ardından bir [upstream ve target](/tr/gateway/upstreams-targets.md), [trafik policy'si](/tr/gateway/traffic-management.md) veya consumer authentication ekleyin.

## Sık karşılaşılan hatalar

### `400 X-Tenant-ID header is required`

İstek host'u bir gateway ile eşlenmemiş ve tenant header'ı gönderilmemiştir. Test için iki kapsam header'ını da ekleyin veya edge host eşlemesini yapılandırın.

### `404 Route not found`

`/proxy` sonrasındaki proxy path'ini, `path_type` değerini, host kısıtlamalarını, SNI'ı, header/query eşleştiricilerini, tenant'ı ve gateway'i kontrol edin. `/orders` için tanımlanan bir `exact` route, `/orders/health` ile eşleşmez.

### `405 Method not allowed for route`

Kangal, diğer istek ölçütleriyle eşleşen bir route bulmuş ancak method listede yer almamıştır. `GET` izinliyse `HEAD` de kabul edilir; diğer method'lar açıkça tanımlanmalıdır.

### `502 Route service not resolved`

Route, aynı tenant ve gateway içinde artık bulunmayan bir service ID'sine veya adına başvuruyordur. Route'u başka bir service'e yönlendirin veya service'i yeniden oluşturun.

### `502 Upstream target not resolved`

Doğrudan URL'i, başvurulan upstream'i ve target'ın kullanılabilir HTTP/HTTPS URL'ini kontrol edin. Şema içermeyen target adresleri saklanabilir; proxy trafiği için adresi `http://` veya `https://` ile tanımlayın.

### `503 Data plane has no valid last-known-good configuration`

Bağımsız düğümün geçerli bir paketi kabul edip etkinleştirmesi gerekir. Mevcut ve hedef sürümleri, `last_config_ack_status` değerini, NACK mesajını, cache güven materyalini ve kontrol düzlemi bağlantısını inceleyin.

### Kontrol düzlemi hazır ancak trafik başarısız

Yönetim API'sinin, veri düzleminin, edge'in ve backend'in hazırlık durumunu bu sırayla kontrol edin. Trafik hazırlığını `proxy_url` ile birlikte DNS, TLS, ingress ve proxy isteği kontrolleriyle doğrulayın.

## Güvenli temizlik

Kaynakları bağımlılık sırasıyla silin: route, service, ardından gateway. Böylece gateway kapsamındaki bağlı kaynaklar kontrollü biçimde temizlenir.

```bash
kangalctl delete routes "$KANGAL_ROUTE_ID" --gateway-id "$KANGAL_GATEWAY_ID"
kangalctl delete services "$KANGAL_SERVICE_ID" --gateway-id "$KANGAL_GATEWAY_ID"
kangalctl delete gateways "$KANGAL_GATEWAY_ID"
```


---

# 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/gateway/quickstart.md?ask=<question>&goal=<endgoal>
```

`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.