為 CoreDNS 撰寫外掛程式

CoreDNS 外掛程式撰寫的簡介。

外掛程式為 CoreDNS 增加功能,例如快取指標和基本的區域檔案服務都是外掛程式。

如果您想撰寫新的外掛程式,並希望預設包含在內,也就是合併到程式碼庫中,請先開啟一個 issue 來討論初始設計和其他可能出現的問題。通常,從一份 README 檔案開始,從使用者的角度解釋事情是如何運作的,會是一個不錯的主意。

請參閱範例外掛程式,了解如何架構、撰寫和測試外掛程式。程式碼中有許多註解可以幫助您。

如何註冊 CoreDNS 外掛程式?

當您撰寫外掛程式碼時,您需要向 CoreDNS 註冊它。這可以透過呼叫以下函式來完成

func init() { plugin.Register("foo", setup) }

每個外掛程式都必須有一個名稱,在此範例中為 foo。當在設定中遇到 foo 時,將會呼叫此套件中的 setup 函式。

設定函式

setup 函式(它可能被稱為不同的名稱,但幾乎每個外掛程式都只是稱之為 setup)會解析組態並填入內部資料結構。

設定函式接收一個 caddy.Controller 並返回一個錯誤:(我們使用 plugin.Error 在返回的錯誤前加上 plugin/foo:,以改進錯誤報告)。

func setup(c *caddy.Controller) error {
  if err != nil {
    return plugin.Error("foo", err)
  }

  // various other code

  return nil
}

如果我們在 Corefile 中看到如下一行

foo gizmo

我們可以這樣取得第一個參數(“gizmo”)的值

for c.Next() {              // Skip the plugin name, "foo" in this case.
    if !c.NextArg() {       // Expect at least one value.
        return c.ArgErr()   // Otherwise it's an error.
    }
    value := c.Val()        // Use the value.
}

您透過迭代 c.Next() 來解析外掛程式的 tokens,只要還有 tokens 可以解析,c.Next() 就會為 true。由於外掛程式可能會多次出現,您必須迭代 c.Next() 以取得外掛程式的所有出現位置並消耗 tokens。

加入 CoreDNS

若要將您的外掛程式插入 CoreDNS 中,請將其放入 plugin.cfg 並執行 go generate

如果您正在使用外部、非核心的外掛程式,最簡單的方法是從外掛程式目錄建立一個符號連結到您的外掛程式。例如:

cd plugin
ln -s ../../example .
cd ..
vi plugin.cfg # add example:example
go generate
go build

外掛程式如何在 CoreDNS 中運作

請查看plugin 套件的 godoc。最重要的類型是 plugin.Handler

Handler 是一個處理 DNS 請求的函式。CoreDNS 會為您完成設置 DNS 伺服器的所有簿記工作,但您需要實作這兩種類型。

撰寫 Handler

plugin.Handler 是一個類似於 http.Handler 的介面,不同之處在於它處理 DNS,並且 ServeDNS 方法返回 (int, error)int 是狀態碼,而 error 會被記錄(如果不是 nil)。請參閱 plugin.md 以取得有關這些回傳值的詳細資訊。

Handler 通常是一個結構體,至少有一個欄位,即鏈中的下一個 Handler

type MyHandler struct {
  Next plugin.Handler
}

若要實作 plugin.Handler 介面,我們編寫一個名為 ServeDNS 的方法。此方法是實際的處理函式,除非它完全自行處理請求,否則它應該呼叫鏈中的下一個 Handler。

func (h MyHandler) ServeDNS(ctx context.Context, w dns.ResponseWriter, r *dns.Msg) (int, error) {
  return h.Next.ServeDNS(ctx, w, r)
}

該介面還需要一個方法 func Name() string

func (h MyHandler) Name() string { return "foo" }

這就是全部(除了編寫實際處理 DNS 請求的所有程式碼之外)。

延伸閱讀

在 CoreDNS 中可以找到的簡單外掛程式範例有

  • root;不會將自己註冊為外掛程式。它只是執行一些設定。
  • chaos;一個 DNS 外掛程式,會回應 CH txt version.bind 請求。
  • example;一個範例外掛程式,會在回應查詢時印出「example」。

別忘了:最好的文件是 godoc程式碼 本身!

Miek Gieben
發布時間:,標籤為 corednsdocumentationpluginplugins,使用了 674 個字。