Skip to Content
リファレンスアクションDNS

DNSアクション

dnsアクションは、名前のレコードをDNSサーバーに問い合わせ、サーバーの応答を返します。名前が期待どおりのアドレスに解決されること、メールの流れが依存するMX、SPF、DKIM、DMARCのレコードが揃っていること、ゾーンの変更がネームサーバーに届いたことなどを確認できます。

基本構文

DNSのステップには、問い合わせる名前と、アドレス以外を問い合わせる場合はレコードの種類を指定します。

steps:
  - name: Where the mail of example.com goes
    uses: dns
    with:
      name: example.com
      type: MX
    test: res.rcode == "NOERROR" && res.answers[0].host == "mail.example.com"

パラメータ

キー必須デフォルト説明
nameはい問い合わせるドメイン名。末尾のドットは省略できます。type: PTRではIPv4またはIPv6のアドレスも指定でき、その逆引きの名前として問い合わせます
typeいいえAレコードの種類。大文字小文字は問いません。A、AAAA、CNAME、MX、TXT、NS、SOA、SRV、PTR、CAAのほか、DNSにある種類を指定できます。ゾーン転送のAXFRとIXFRは送りません
serverいいえマシンのリゾルバ問い合わせ先のサーバー。hostまたはhost:port。IPv6アドレスはそのまま、または角括弧で囲んで指定し、ポートを付けるときは角括弧で囲みます
protocolいいえudpudp、tcp、またはDNS over TLSのtls
timeoutいいえ5s問い合わせ全体にかけてよい時間。500msや10sのような期間、または秒数

serverを省略すると、/etc/resolv.confからリゾルバを読み、応答があるまで順に問い合わせます。ポートは53、protocol: tlsでは853です。

UDPで途中までしか返らなかった応答は、digと同じくTCPで問い合わせ直し、そのときres.protocolはtcpになります。protocol: tlsでは、サーバーの証明書をserverに指定したホストに対して検証します。

レスポンス

フィールド説明
res.rcodeサーバーの応答コード。NOERROR、NXDOMAIN、SERVFAIL、REFUSEDなど
res.answers応答のレコード。サーバーが返した順
res.values問い合わせた種類の各レコードのdata。途中の別名は含まないので、Aの問い合わせのres.valuesはアドレスだけになります
res.authoritativeサーバーがそのゾーンを持つ権威サーバーとして応答したときtrue
res.server応答したサーバー。host:port
res.protocol応答を受け取ったプロトコル
statusres.rcodeがNOERRORなら0、それ以外は1

res.answersの各要素にはname、type、ttl、dataがあります。ホスト名は末尾のドットを付けずに返します。複数の部分からなる種類は、それぞれを名前でも参照できます。

種類dataそのほかのフィールド
A、AAAAアドレス
CNAME、NS、PTRホスト名
TXTテキスト。分割して送られたテキストは1つにつなげます
MX10 mail.example.compreference、host
SRV10 60 5060 sip.example.compriority、weight、port、target
SOAns1.example.com hostmaster.example.com 2026101001 7200 3600 1209600 300ns、mbox、serial、refresh、retry、expire、minimum
CAA0 issue letsencrypt.orgflag、tag、value
そのほかゾーンファイルでの表記

名前はあるが問い合わせた種類のレコードがない場合は、DNSの仕様どおりNOERRORで、レコードは空です。

例

名前のアドレス

- name: api.example.com points at the load balancer
  uses: dns
  with:
    name: api.example.com
  test: res.values == ["203.0.113.10"]

別名を挟む名前は、別名とアドレスの両方を返します。res.answersには両方が入り、res.valuesにはアドレスだけが入ります。

- name: www is an alias of the CDN
  uses: dns
  with:
    name: www.example.com
  test: res.answers[0].type == "CNAME" && res.answers[0].data == "example.cdn.net" && len(res.values) > 0

メールのレコード

- name: SPF allows the mail service
  uses: dns
  with:
    name: example.com
    type: TXT
  test: 'any(res.values, {# startsWith "v=spf1" && # contains "include:_spf.example.net"})'
 
- name: DMARC rejects what fails
  uses: dns
  with:
    name: _dmarc.example.com
    type: TXT
  test: res.values[0] contains "p=reject"

引用符で始まるテストや #を含むテストは、YAMLが#をコメントとして扱わないように、全体を引用符で囲みます。

変更がすべてのネームサーバーに届いたか

ゾーンの各ネームサーバーに直接問い合わせ、権威サーバーとして応答していることを確かめます。

- name: ns1 serves the new address
  uses: dns
  with:
    name: api.example.com
    server: ns1.example.com
  test: res.authoritative && res.values == ["203.0.113.10"]

存在しないはずの名前

サーバーがエラーで応答した場合も、ステップの失敗ではなく、テストで確認できる結果になります。

- name: The old name is gone
  uses: dns
  with:
    name: old.example.com
  test: res.rcode == "NXDOMAIN"

アドレスの名前

- name: The mail server has a reverse name
  uses: dns
  with:
    name: 203.0.113.25
    type: PTR
  test: res.values == ["mail.example.com"]

DNS over TLS

- name: Ask a public resolver over TLS
  uses: dns
  with:
    name: example.com
    server: dns.google
    protocol: tls
  test: res.rcode == "NOERROR" && res.protocol == "tls"

ガードの下で

問い合わせは何も書き込まないので、--read-onlyの下でもそのまま実行されます。--allow-hostの下では、実行が許可するサーバーにだけ問い合わせを送ります。ポートは、serverに指定がなければ53、protocol: tlsでは853として照合します。serverを省略した場合は、問い合わせがどのリゾルバにも送られうるため、マシンのすべてのリゾルバが許可されている必要があります。そうでなければステップは拒否され、serverを指定するように伝えます。問い合わせる名前はアクションが接続するホストではないので、照合しません。拒否されたステップは種類refusedで失敗します。ガードを参照してください。

probe --allow-host 1.1.1.1 workflow.yml

エラー処理

サーバーが応答すれば、その内容にかかわらず結果になります。res.rcodeが内容を示し、NOERRORでなければstatusは1です。どのサーバーも応答しないとき、タイムアウトしたとき、DNSにない種類などパラメータが正しくないときは、ステップはアクションエラーで失敗します。

更新日時
GRPCHELLO