# Gyro DNS'i API, gyro CLI ve Terraform ile yönetin

https://www.gyrohosting.com/bilgi-bankasi/makale/gyro-dns-api-cli-terraform

- **Bu rehberde ne öğreneceksiniz**: Gyro DNS'teki her işlemi (zone, kayıt, DNSSEC, sağlık kontrolü) REST API, `gyro` komut satırı aracı ve Terraform ile yapmayı; hangi işlemlerin açık onay (`confirm`) istediğini ve sık hataları.
- **Süre**: 15 dakika
- **Kimin için**: DNS kayıtlarını betik, CI hattı ya da altyapı-kod (IaC) ile yöneten geliştiriciler ve sistem yöneticileri.
- **Gerekenler**: Gyro DNS hizmeti (Ücretsiz ve Pro'da API açıktır), `services_read` ve `services_write` izinli bir API anahtarı ([Gyro API'ye ilk adım](https://www.gyrohosting.com/bilgi-bankasi/makale/gyro-api-ilk-adim)).

## 1. Hizmet numarası ve kimlik

Tüm DNS uçları **Gyro DNS hizmet numaranızla** çalışır: `/cloud/dns/{id}/...`. Bu numarayı müşteri panelindeki hizmet adresinde ya da hizmetin **Yönetim → Bağlantı ve API** sayfasında görürsünüz; o sayfadaki CLI ve Terraform örneklerinde numaranız hazır yazılıdır.

![Bağlantı ve API: CLI ve Terraform örneklerinde hizmet numaranız hazır yazılıdır; kopyalayıp kullanabilirsiniz.](https://www.gyrohosting.com/resources/uploads/bilgi-merkezi/L13-01-tr.webp)

API listesinden de bulabilirsiniz: hizmet listesinde Gyro DNS hizmetleri `product_line: "dns"` ile döner.

| Gereken izin (kapsam) | İşlemler |
| --- | --- |
| `services_read` | Listeleme, zone ve kayıt okuma, dışa aktarma, DNSSEC durumu |
| `services_write` | Zone ekleme/silme, kayıt yazma/silme, içe aktarma, DNSSEC, sağlık kontrolü |

Anahtarı ortam değişkenine koyun:

```
read -rs GYRO_TOKEN && export GYRO_TOKEN
```

## 2. Uç listesi

| İşlem | Uç | Onay |
| --- | --- | --- |
| Zone'ları listele | `GET /cloud/dns/{id}/zones` |  |
| Zone ekle | `POST /cloud/dns/{id}/zones` |  |
| Zone'u kayıtlarıyla getir | `GET /cloud/dns/{id}/zones/{zone}` |  |
| Zone'u sil | `DELETE /cloud/dns/{id}/zones/{zone}` | `confirm` |
| Sahipliği şimdi doğrula | `POST /cloud/dns/{id}/zones/{zone}/verify` |  |
| BIND içe aktar | `POST /cloud/dns/{id}/zones/{zone}/import` | `confirm` |
| BIND dışa aktar | `GET /cloud/dns/{id}/zones/{zone}/export` |  |
| Kayıt kümelerini listele | `GET /cloud/dns/{id}/zones/{zone}/records` |  |
| Kayıt kümesi yaz (oluştur ya da değiştir) | `PUT /cloud/dns/{id}/zones/{zone}/records` |  |
| Kayıt kümesi sil | `DELETE /cloud/dns/{id}/zones/{zone}/records` | `confirm` |
| DNSSEC durumu ve DS | `GET /cloud/dns/{id}/zones/{zone}/dnssec` |  |
| DNSSEC aç | `POST /cloud/dns/{id}/zones/{zone}/dnssec` |  |
| DNSSEC kapat | `DELETE /cloud/dns/{id}/zones/{zone}/dnssec` | `confirm` |
| Sağlık kontrollerini listele | `GET /cloud/dns/{id}/health-checks` |  |
| Sağlık kontrollü kayıt oluştur | `POST /cloud/dns/{id}/health-checks` |  |
| Sağlık kontrolünü sil | `DELETE /cloud/dns/{id}/health-checks/{hid}` | `confirm` |

Tam alan listesi ve yanıt örnekleri: [geliştirici belgeleri](https://www.gyrohosting.com/developers/tr/) ("Managed DNS" bölümü).

> **Dikkat**
> 
> Onay sütunu dolu işlemler veri siler ya da değiştirir; gövdede `"confirm": true` (DELETE isteklerinde `?confirm=true` de olur) yoksa `422 confirm_required` döner. Bu, yanlışlıkla çalışan bir betiğin zone'unuzu silmesine karşı korumadır.

## 3. API ile (curl)

Bir kayıt kümesi yazın. Aynı ad ve tipte küme varsa **tamamen değiştirilir**:

```
curl -s -X PUT "https://www.gyrohosting.com/api/v1/client/cloud/dns/12345/zones/ornekfirma.com/records" \
  -H "Authorization: Bearer $GYRO_TOKEN" -H "Content-Type: application/json" \
  -d '{"name":"www","type":"A","ttl":300,"records":["203.0.113.10","203.0.113.11"]}'
```

- `name`: zone'a göre ad (`@` kök, `*` joker) ya da sonu noktalı tam ad.
- `records`: her değer ayrı öğe, zone dosyası yazımıyla (MX için `"10 mx1.ornekfirma.com."`; TXT'de tırnak isteğe bağlı).

Kayıt kümesini silin:

```
curl -s -X DELETE "https://www.gyrohosting.com/api/v1/client/cloud/dns/12345/zones/ornekfirma.com/records?name=www&type=A&confirm=true" \
  -H "Authorization: Bearer $GYRO_TOKEN"
```

Zone ekleyin (ad sunucuları zaten Gyro DNS'teyse hemen yayına girer; değilse yanıttaki `txt_name` ve `txt_value` ile doğrulayın):

```
curl -s -X POST "https://www.gyrohosting.com/api/v1/client/cloud/dns/12345/zones" \
  -H "Authorization: Bearer $GYRO_TOKEN" -H "Content-Type: application/json" \
  -d '{"name":"ornekfirma.com"}'
```

## 4. gyro CLI ile

`gyro` aracını kurmadıysanız: [gyro CLI kurulumu ve ilk komutlar](https://www.gyrohosting.com/bilgi-bankasi/makale/gyro-cli-kurulum). DNS komutları dört grupta durur (v1.5.0 ve sonrası):

| Grup | Komutlar |
| --- | --- |
| `gyro dns zone` | `list`, `create`, `get`, `delete`, `verify`, `import`, `export` |
| `gyro dns rrset` | `list`, `set`, `delete` |
| `gyro dns dnssec` | `status`, `enable`, `disable` |
| `gyro dns health` | `list`, `create`, `delete` |

Örnekler (`12345` = Gyro DNS hizmet numaranız):

```
gyro dns zone list 12345
gyro dns zone create 12345 --name ornekfirma.com
gyro dns rrset set 12345 ornekfirma.com --name www --type A --ttl 300 --records 203.0.113.10,203.0.113.11
gyro dns rrset set 12345 ornekfirma.com --name @ --type MX --records "10 mx1.ornekfirma.com."
gyro dns rrset delete 12345 ornekfirma.com --name www --type A --yes
gyro dns zone export 12345 ornekfirma.com -o text --query bind > ornekfirma.com.zone
gyro dns dnssec enable 12345 ornekfirma.com
gyro dns health create 12345 --zone ornekfirma.com --name @ --type A \
  --primary 203.0.113.10 --backup 198.51.100.20 --check https --port 443 --path /saglik --ttl 60
```

- Silme, kapatma ve içe aktarma komutları onay sorar; betiklerde `--yes` ekleyin (içe aktarmada gyro 1.5.1 ve sonrası gerekir; `gyro version --check` ile sürümünüze bakın, eskiyse kurulum komutunu yeniden çalıştırın).
- `--records` virgülle ayrılmış birden çok değer alır. Değerin kendisinde virgül varsa (ör. bazı TXT kayıtları) `--data '{"name":"@","type":"TXT","records":["..."]}'` ile JSON gövde verin.
- Zone dosyası içe aktarma: bash`gyro dns zone import 12345 ornekfirma.com --bind "$(cat ornekfirma.com.zone)" --mode merge --yes`
- `--mode merge` dosyadaki kayıtları ekler/değiştirir, diğerlerine dokunmaz; `--mode replace` dosyada olmayanları siler.

> **Bilgi**
> 
> Kayıt komutlarının adı `rrset`'tir (kayıt kümesi). `gyro dns record` komutları ise Gyro'da kayıtlı alan adlarının klasik DNS yönetimi içindir; Gyro DNS zone'larında `rrset` kullanın.

## 5. Terraform ile

Gyro sağlayıcısının **0.5.0 ve üstü** `gyro_dns_zone` ve `gyro_dns_record` kaynaklarını içerir. Sağlayıcıyı ilk kez kullanıyorsanız: [Terraform ile Gyro Bulut](https://www.gyrohosting.com/bilgi-bankasi/makale/terraform-ile-gyro-bulut).

```
terraform {
  required_providers {
    gyro = {
      source  = "gyro-hosting/gyro"
      version = ">= 0.5.0"
    }
  }
}

provider "gyro" {}   # anahtarı GYRO_TOKEN ortam değişkeninden okur

resource "gyro_dns_zone" "ornek" {
  service_id = 12345           # Gyro DNS hizmet numaranız
  name       = "ornekfirma.com"
  dnssec     = true
}

resource "gyro_dns_record" "www" {
  service_id = gyro_dns_zone.ornek.service_id
  zone       = gyro_dns_zone.ornek.name
  name       = "www"
  type       = "A"
  ttl        = 300
  records    = ["203.0.113.10"]
}

resource "gyro_dns_record" "mx" {
  service_id = gyro_dns_zone.ornek.service_id
  zone       = gyro_dns_zone.ornek.name
  name       = "@"
  type       = "MX"
  records    = ["10 mx1.ornekfirma.com."]
}

output "ad_sunuculari" { value = gyro_dns_zone.ornek.nameservers }
output "dogrulama_txt" { value = "${gyro_dns_zone.ornek.verification_txt_name} = ${gyro_dns_zone.ornek.verification_txt_value}" }
output "ds"            { value = gyro_dns_zone.ornek.ds_records }
```

Bilmeniz gerekenler:

- `gyro_dns_record` için zone'un **yayında** olması gerekir. Zone `status = "pending"` iken önce ad sunucularını değiştirin ya da `dogrulama_txt` çıktısındaki TXT kaydını ekleyin; sonra `terraform apply`'ı yeniden çalıştırın.
- `zone_file` alanı yalnız zone **ilk oluşturulurken** bir kez içe aktarılır; sonraki değişiklikleri `gyro_dns_record` kaynaklarıyla yönetin.
- Mevcut zone ve kayıtları içe alma: `terraform import gyro_dns_zone.ornek 12345/ornekfirma.com` ve `terraform import gyro_dns_record.www 12345/ornekfirma.com/www/A` (kök için ad `@`).
- `terraform destroy` zone'u ve kayıtlarını ad sunucularımızdan **hemen** kaldırır.

## 6. Sınırlar

| Konu | Değer |
| --- | --- |
| TTL | 60-86400 saniye (sağlık kontrollü kayıtta 30-300) |
| Kayıt sayısı | Zone başına 1.000; bir kümede en çok 100 değer |
| Zone dosyası | En çok 2 MB; SOA ve kök NS atlanır |
| Kayıt tipleri | A, AAAA, CNAME, MX, TXT, SRV, CAA, ALIAS, NS (kök dışında), PTR |
| İstek hızı | API'nin genel hız sınırı geçerlidir ([ayrıntı](https://www.gyrohosting.com/bilgi-bankasi/makale/gyro-api-ilk-adim)); çok sık değişiklikte `rate_limited` döner |

## 7. Sık hatalar

| Hata kodu | Sebep | Çözüm |
| --- | --- | --- |
| `401` | Anahtar yok ya da geçersiz | `Authorization: Bearer` başlığını kontrol edin |
| `403 insufficient_scope` | Anahtarın `services_write` izni yok | Anahtara yazma izni verin |
| `404 service_not_found` | Hizmet numarası yanlış ya da bir Gyro DNS hizmeti değil | Doğru hizmet numarasını kullanın |
| `422 confirm_required` | Silme/kapatma/içe aktarma onaysız | `"confirm": true` ekleyin; CLI'da `--yes` |
| `422` + "Kök adda CNAME olamaz" | `@` için CNAME | `type: "ALIAS"` kullanın |
| `422` + "DNSSEC açık zone'da ALIAS kullanılamaz" | DNSSEC ve ALIAS birlikte | Birinden vazgeçin |
| "Zone bulunamadı" | Zone bu hizmete ait değil ya da henüz eklenmedi | `gyro dns zone list` ile kontrol edin |

## 8. Sık sorulan sorular

**API ile yaptığım değişiklik ne zaman yayına girer?**

Panelle aynı: istek döndüğünde iki ad sunucusuna gönderilmiştir, yanıtların değişmesi en geç yaklaşık bir dakika sürer.

**Hosting (cPanel) hesabımdan gelen zone'u API'den okuyabilir miyim?**

Evet, salt okunur: `GET .../zones/{zone}/records?source=cpanel`. Bu zone'lar yazılamaz; değişikliği cPanel'den yapın.

**Ücretsiz pakette API kullanılabilir mi?**

Evet. API, CLI ve Terraform iki pakette de vardır; fark zone sayısındadır (Ücretsiz 5, Pro 50).

**Terraform planında TXT ya da göreli adlar için neden sürekli fark çıkıyor?**

Sağlayıcı 0.5.0, tırnaksız TXT ve göreli adları sunucudaki biçimle eşleştirir. Eski sürüm kullanıyorsanız `terraform init -upgrade` ile güncelleyin.

**Birden çok zone'u tek seferde taşımanın en hızlı yolu nedir?**

Her zone için `gyro dns zone create` ve ardından zone dosyasıyla `gyro dns zone import` çalıştıran kısa bir betik. Zone dosyasını zone oluştururken `--bind` ile vermek de mümkündür; dosya, zone doğrulanınca içe aktarılır.

> **Biliyor muydunuz?**
> 
> Aynı API anahtarıyla bulut sunucu açıp IP'sini doğrudan DNS kaydına yazabilirsiniz: Terraform'da `records = [gyro_server.web.ipv4]` gibi. Sunucu açmak için [İlk bulut sunucunuz](https://www.gyrohosting.com/bilgi-bankasi/makale/ilk-bulut-sunucu).

## Sıradaki adım

- **Sorun mu var?** [DNS sık sorunlar ve kontrol komutları](https://www.gyrohosting.com/bilgi-bankasi/makale/dns-sik-sorunlar)
- Paketler ve fiyatlar: [Gyro DNS](https://www.gyrohosting.com/gyro-dns)