Kehittäjät → DNS koodina

DNS koodina

Pidä vyöhykkeesi yhdessä YAML- tai JSON-tiedostossa koodisi rinnalla. Tarkista DNS-muutokset pull requesteissa, näe tarkalleen mitä muuttuu ennen kuin se muuttuu, ja ota muutokset käyttöön yhdellä kertaa.

Aloita vyöhykkeestäsi

nameocean

$ nameocean dns export example.com > dns.yaml
$ $EDITOR dns.yaml
$ nameocean dns plan -f dns.yaml
+  CNAME  blog  example.netlify.app
~  A      @     203.0.113.10  ttl 1h → 5m
-  A      old   203.0.113.9
example.com: 1 to add, 1 to change, 1 to delete, 6 unchanged.
$ nameocean dns apply -f dns.yaml
Apply these changes? [y/N] y
Applied: 1 added, 1 changed, 1 deleted. example.com is at serial 214.

Tiedosto

dns.yaml

# yaml-language-server: $schema=https://nameocean.net/schemas/dns-zone.json
zone: example.com
records:
  - name: "@"
    type: A
    value: 203.0.113.10
    ttl: 5m
  - name: www
    type: CNAME
    value: "@"
  - name: "@"
    type: MX
    value: mail.example.com
    priority: 10
  - name: "@"
    type: TXT
    value: "v=spf1 mx -all"
  - name: _sip._tcp
    type: SRV
    value: sip.example.com
    priority: 10
    weight: 5
    port: 5060
  - name: old
    type: REDIRECT
    value: https://example.com/new

name on @ itse vyöhykkeelle tai siihen nähden suhteellinen nimi (www, _dmarc); myös täydellinen nimi loppupisteineen toimii.
type on A, AAAA, CNAME, MX, TXT, SRV, PTR tai REDIRECT (HTTP-uudelleenohjaus value-kentän URL-osoitteeseen).
ttl on 5m, 15m, 30m, 1h tai 1d; ilman sitä tietue saa tiedoston ttl-arvon tai 1h. MX ottaa arvon priority (oletus 10), SRV arvot priority, weight ja port, REDIRECT arvon save_path (oletus true).
Sama dokumentti toimii myös JSON-muodossa. JSON Schema tarjoaa automaattisen täydennyksen ja tarkistukset VS Codessa ja muissa editoreissa.

Miten suunnitelma muodostetaan

Tiedosto on koko vyöhyke: tietue, joka on vyöhykkeessä mutta ei tiedostossa, poistetaan. Käytä valitsinta --keep-unlisted (API:ssa prune=false), jos haluat vain lisätä ja muuttaa.

A-, AAAA-, MX- ja TXT-tietueet yhdistetään nimen ja arvon (sekä MX-tietueilla prioriteetin) perusteella, koska yhdellä nimellä voi olla useita tällaisia tietueita. CNAME-, SRV-, PTR- ja REDIRECT-tietueet yhdistetään nimen perusteella. Eri ttl tai SRV-tietueen eri prioriteetti, paino tai portti katsotaan muutokseksi; kaikki muu on lisäys tai poisto.

Apply suoritetaan yhtenä transaktiona: ensin poistot, sitten muutokset ja lopuksi uudet tietueet, joten CNAME voi korvata A-tietueen samassa tiedostossa. Jos yksikin tietue hylätään, mitään ei muuteta. Jos joku muuttaa vyöhykettä suunnitelman ja käyttöönoton välillä, apply hylätään ja suunnitelma on tehtävä uudelleen.

Tietueita, jotka NameOcean pitää omaan käyttöönsä – HTTP-uudelleenohjauksen taustalla olevaa osoitetta ja SSL:n ACME-haasteita – ei koskaan viedä, suunnitella eikä poisteta.

GitHub Actions

Luo API-avain oikeudella dns:write (tai pelkällä dns:read-oikeudella työlle, joka vain suunnittelee) ja tallenna se NAMEOCEAN_API_KEY-salaisuudeksi.

.github/workflows/dns.yml

name: dns
on:
  pull_request: {paths: [dns.yaml]}
  push: {branches: [main], paths: [dns.yaml]}
jobs:
  dns:
    runs-on: ubuntu-latest
    env:
      NAMEOCEAN_API_KEY: ${{ secrets.NAMEOCEAN_API_KEY }}
    steps:
      - uses: actions/checkout@v4
      - run: curl -fsSL https://nameocean.net/install.sh | sh
      - run: nameocean dns plan -f dns.yaml
      - if: github.event_name == 'push'
        run: nameocean dns apply -f dns.yaml --yes

dns plan --detailed-exitcode palauttaa poistumiskoodin 2, kun muutoksia on – töihin, joiden pitää vain raportoida poikkeamat.

REST API:n avulla

GET /dns/{zone}/export?output=yaml	Vyöhyke tiedostona (JSON ilman output=yaml); X-Zone-Serial-otsake on sen sarjanumero
POST /dns/{zone}/plan	Mitä apply tekisi; ei muuta mitään ja vaatii vain dns:read-oikeuden
POST /dns/{zone}/apply?serial=N	Tee vyöhykkeestä tiedoston mukainen; 409 zone_changed, jos vyöhyke ei ole enää suunnitelman sarjanumerossa

curl

$ curl -X POST https://nameocean.net/api/v1/dns/example.com/plan \
    -H "Authorization: Bearer $NAMEOCEAN_API_KEY" \
    -H "Content-Type: application/yaml" --data-binary @dns.yaml

Lähetä YAML-muodossa otsakkeella Content-Type: application/yaml tai sama dokumentti JSON-muodossa. Jos palvelin ei voi hyväksyä tiedostoa, se vastaa 400 invalid_zone_file ja palauttaa errors-luettelon, jossa nimetään jokainen tietue ja kenttä. Kaikki tämä löytyy API-dokumentaatiosta.

Tekoälystäsi

MCP:n kautta avustaja voi viedä vyöhykkeen, suunnitella muutoksen useisiin tietueisiin kerralla plan_dns_zone-toiminnolla ja näytettyään suunnitelman teille ottaa sen käyttöön apply_dns_zone-toiminnolla.