kubernetes

ソース

kubernetes プラグインは、Kubernetes クラスターからゾーンデータを読み込むことを可能にします。

説明

このプラグインは、Kubernetes DNSベースのサービスディスカバリ仕様を実装しています。

kubernetes プラグインを実行している CoreDNS は、Kubernetes クラスター内で kube-dns の代替として使用できます。 デプロイメントリポジトリで、Kubernetes に CoreDNS をデプロイする方法の詳細を参照してください。

stubDomains と upstreamNameservers は、forward プラグインを通じて実装されます。以下の例を参照してください。

このプラグインは、サーバーブロックごとに1回のみ使用できます。

構文

kubernetes [ZONES...]

プラグインのみが指定された場合、kubernetes プラグインは、サーバーのブロックで指定されたゾーンをデフォルトとします。そのゾーン内のすべてのクエリを処理し、クラスター内の Kubernetes に接続します。サービス用の PTR レコードやポッド用の A レコードは提供しません。ZONES が使用されている場合、プラグインが権威を持つすべてのゾーンを指定します。

kubernetes [ZONES...] {
    endpoint URL
    tls CERT KEY CACERT
    kubeconfig KUBECONFIG [CONTEXT]
    namespaces NAMESPACE...
    labels EXPRESSION
    pods POD-MODE
    endpoint_pod_names
    ttl TTL
    noendpoints
    fallthrough [ZONES...]
    ignore empty_service
}

  • endpoint は、リモート k8s API エンドポイントの URL を指定します。省略すると、クラスターサービスアカウントを使用してクラスター内の k8s に接続します。

  • tls CERT KEY CACERT は、リモート k8s 接続用の TLS 証明書、キー、および CA 証明書ファイル名です。このオプションは、クラスター内接続（つまり、エンドポイントが指定されていない場合）では無視されます。

  • kubeconfig KUBECONFIG [CONTEXT] は、kubeconfig ファイルを使用してリモート k8s クラスターへの接続を認証します。 [CONTEXT] はオプションで、設定されていない場合は、kubeconfig で指定された現在のコンテキストが使用されます。TLS、ユーザー名とパスワード、またはトークンベースの認証をサポートします。このオプションは、クラスター内接続（つまり、エンドポイントが指定されていない場合）では無視されます。

  • namespaces NAMESPACE [NAMESPACE...] は、リストされた k8s 名前空間のみを公開します。このオプションが省略された場合、すべての名前空間が公開されます。

  • namespace_labels EXPRESSION は、このラベルセレクターに一致する Kubernetes 名前空間のレコードのみを公開します。ラベルセレクターの構文は、Kubernetes ユーザーガイド - ラベルで説明されています。「istio-injection=enabled」というラベルが付いた名前空間のみを公開する例は、labels istio-injection=enabled を使用します。

  • labels EXPRESSION は、このラベルセレクターに一致する Kubernetes オブジェクトのレコードのみを公開します。ラベルセレクターの構文は、Kubernetes ユーザーガイド - ラベルで説明されています。「staging」または「qa」環境で「application=nginx」というラベルが付いたオブジェクトのみを公開する例は、labels environment in (staging, qa),application=nginx を使用します。

  • pods POD-MODE は、IP ベースのポッド A レコードを処理するモードを設定します。例：1-2-3-4.ns.pod.cluster.local. in A 1.2.3.4。このオプションは、ポッドに直接接続するときに SSL 証明書の使用を容易にするために提供されています。POD-MODE の有効な値

    • disabled：デフォルト。ポッドリクエストを処理せず、常に NXDOMAIN を返します。
    • insecure：常にリクエストからIPを持つAレコードを返します（k8sを確認せずに）。このオプションは、ワイルドカードSSL証明書と組み合わせて悪意を持って使用された場合、悪用される可能性があります。このオプションは、kube-dnsとの下位互換性のために提供されています。
    • verified：同じ名前空間に一致するIPを持つポッドが存在する場合に、Aレコードを返します。このオプションは、すべてのポッドの監視を維持するため、insecureモードよりも実質的に多くのメモリを必要とします。

  • endpoint_pod_names は、A レコードのエンドポイント名として、エンドポイントによってターゲットにされるポッドのポッド名を使用します。例：endpoint-name.my-service.namespace.svc.cluster.local. in A 1.2.3.4。デフォルトでは、endpoint-name の名前選択は次のとおりです。エンドポイントのホスト名を使用するか、ホスト名が設定されていない場合は、エンドポイントの IP アドレスのダッシュ形式を使用します（例：1-2-3-4.my-service.namespace.svc.cluster.local.）。このディレクティブが含まれている場合、エンドポイントの名前選択は次のように変更されます。エンドポイントのホスト名を使用するか、ホスト名が設定されていない場合は、エンドポイントによってターゲットにされるポッドのポッド名を使用します。エンドポイントによってターゲットにされるポッドがない場合、またはポッド名が63文字を超える場合は、ダッシュ付きのIPアドレス形式を使用します。

  • ttl を使用すると、応答にカスタム TTL を設定できます。デフォルトは5秒です。許可される最小TTLは0秒で、最大は3600秒に制限されています。TTLを0に設定すると、レコードはキャッシュされなくなります。

  • noendpoints は、エンドポイントの監視を無効にすることで、エンドポイントレコードの提供をオフにします。すべてのエンドポイントクエリとヘッドレスサービスクエリは、NXDOMAIN になります。

  • fallthrough [ZONES...] プラグインが権威を持つゾーンのレコードに対するクエリが NXDOMAIN になる場合、通常はその応答になります。ただし、このオプションを指定すると、クエリは代わりにプラグインチェーンに渡され、クエリを処理するために別のプラグインを含めることができます。 [ZONES...] が省略されている場合、プラグインが権威を持つすべてのゾーンでフォールスルーが発生します。特定のゾーン（たとえば、in-addr.arpa および ip6.arpa）がリストされている場合、これらのゾーンに対するクエリのみがフォールスルーの対象になります。

  • ignore empty_service は、準備完了のエンドポイントアドレス（例：準備完了のポッド）を持たないサービスに対して NXDOMAIN を返します。これにより、クエリを実行するポッドは、検索パスでサービスの検索を続行できます。たとえば、検索パスには別の Kubernetes クラスターを含めることができます。

ゾーン転送の有効化は、transfer プラグインを使用することによって行われます。

起動

CoreDNS が kubernetes プラグインを有効にして起動すると、Kubernetes API に接続してすべてのオブジェクト監視を同期できるようになるまで、最大5秒間 DNS の提供が遅延します。これが5秒以内に発生しない場合、CoreDNS は DNS の提供を開始しますが、kubernetes プラグインは接続とすべてのオブジェクト監視の同期を継続しようとします。CoreDNS は、まだ同期されていない Kubernetes レコードに対して行われたリクエストに対して SERVFAIL を返します。

Kubernetes エンドポイントの監視

kubernetes プラグインは、discovery.EndpointSlices API を介してエンドポイントを監視します。

準備完了

このプラグインは、準備完了プラグインに準備完了を報告します。これは、Kubernetes API に同期した後に行われます。

例

cluster.local ゾーン内のすべてのクエリを処理します。クラスター内の Kubernetes に接続します。また、10.0.0.0/17 のすべての in-addr.arpa PTR リクエストも処理します。ポッドリクエストに応答するときにポッドの存在を確認します。

10.0.0.0/17 cluster.local {
    kubernetes {
        pods verified
    }
}

または、一部の名前空間を選択的に公開できます

kubernetes cluster.local {
    namespaces test staging
}

クラスター外で実行されている CoreDNS で Kubernetes に接続します

kubernetes cluster.local {
    endpoint https://k8s-endpoint:8443
    tls cert key cacert
}

stubDomains と upstreamNameservers

ここでは、forward プラグインを使用して、example.local をネームサーバー 10.100.0.10:53 に転送するスタブドメインを実装します。また、cluster.local または example.local に該当しない名前を解決するために使用される upstreamNameserver 8.8.8.8:53 も構成されています。

cluster.local:53 {
    kubernetes cluster.local
}
example.local {
    forward . 10.100.0.10:53
}

. {
    forward . 8.8.8.8:53
}

上記の構成は、次の Kube-DNS のスタブドメインとアップストリームネームサーバーの構成を表します。

stubDomains: |
   {“example.local”: [“10.100.0.10:53”]}
upstreamNameservers: |
   [“8.8.8.8:53”]

AutoPath

kubernetes プラグインは、autopath プラグインと組み合わせて使用できます。この機能を使用すると、Kubernetes クラスターでサーバー側のドメイン検索パス補完が可能になります。注：これが適切に機能するためには、pods を verified に設定する必要があります。さらに、CoreDNS が受信した DNS パケットのリモート IP アドレスは、リクエストを送信したポッドの IP アドレスである必要があります。

cluster.local {
    autopath @kubernetes
    kubernetes {
        pods verified
    }
}

メタデータ

metadata プラグインも有効になっている場合、kubernetes プラグインは次のメタデータを公開します

  • kubernetes/endpoint：クエリ内のエンドポイント名
  • kubernetes/kind：クエリ内のリソースの種類（ポッドまたは svc）
  • kubernetes/namespace：クエリ内の名前空間
  • kubernetes/port-name：SRV クエリのポート名
  • kubernetes/protocol：SRV クエリのプロトコル
  • kubernetes/service：クエリ内のサービス名
  • kubernetes/client-namespace：クライアントポッドの名前空間（以下の要件を参照）
  • kubernetes/client-pod-name：クライアントポッドの名前（以下の要件を参照）

kubernetes/client-namespace および kubernetes/client-pod-name メタデータは、DNS リクエストパケット内のクライアント IP アドレスを既知のポッド IP アドレスに調整することによって機能します。したがって、以下が必要です

  • pods verified モードを有効にする必要があります
  • CoreDNS が受信した DNS パケットのリモート IP アドレスは、リクエストを送信したポッドの IP アドレスである必要があります。

メトリクス

監視が有効になっている場合（prometheus プラグインを介して）、次のメトリクスがエクスポートされます

  • coredns_kubernetes_dns_programming_duration_seconds{service_kind} - DNS プログラミング遅延 SLI をエクスポートします。メトリクスには、kubernetes サービスの種類を識別する service_kind ラベルがあります。次の3つの値のいずれかを取ることができます
    • cluster_ip
    • headless_with_selector
    • headless_without_selector

以下は、apiserver リクエストの遅延とステータスコードを監視するためのクライアントレベルのメトリクスです。 verb は apiserver の リクエストタイプを識別し、host は apiserver エンドポイントを示します。

  • coredns_kubernetes_rest_client_request_duration_seconds{verb, host} - クライアントによって認識される apiserver リクエストの遅延を、verb と host でグループ化してキャプチャします。
  • coredns_kubernetes_rest_client_rate_limiter_duration_seconds{verb, host} - クライアント側のレートリミッターによって発生する apiserver リクエストの遅延を、verb と host でグループ化してキャプチャします。
  • coredns_kubernetes_rest_client_requests_total{method, code, host} - method、status_code、host でグループ化された apiserver リクエストの合計をキャプチャします。

バグ

期間メトリクスは、現在「headless_with_selector」サービスのみをサポートしています。

関連情報

検索パスの最適化を有効にするには、autopath プラグインを参照してください。また、送信ゾーン転送を有効にするには、transfer プラグインを使用してください。

このファイルの正規ソース