この投稿では、Kubernetes v1.31で利用可能になったCRD（Custom Resource Definition）のField Selectors機能について解説します。

この機能を使うと、Podなどの組み込みリソースと同じように、カスタムリソースを特定のフィールドの値で検索できるようになります。

この投稿で紹介するサンプルコード一式はGitHubに置いてあります。

この投稿で知れること

CRDでField Selectorsを有効にする方法
selectableFieldsの定義と制約事項
実際のカスタムリソースでの検索方法
Field Selectorsを使う際の注意点

Field Selectorsとは？

KubernetesでPodを検索する際、kubectl get pods --field-selector status.phase=Runningのようにフィールドの値で絞り込むことができます。これがField Selectorsです。

従来、カスタムリソースではこの機能が使えませんでしたが、v1.31からCRDでもField Selectorsを定義できるようになりました。今までカスタムリソースではラベルに検索用の値を冗長的に持たせたり、全部取ってきてからフィルタリングしたりする必要がありましたが、CRDのField Selector対応のおかげで特定の条件に合うものを効率的に検索できるようになりました。

開発環境の準備

まず、Kubernetes v1.31以降のクラスターが必要です。今回はKindを使って検証環境を構築します。

# kind.yaml
kind: Cluster
apiVersion: kind.x-k8s.io/v1alpha4
nodes:
- role: control-plane
  image: kindest/node:v1.31.0

kind create cluster --name crd-selectable-fields --config kind.yaml

v1.31以降ではCustomResourceFieldSelectors機能がデフォルトで有効になっているため、追加の設定は不要です。

CRDでField Selectorsを定義する

それでは、実際にField Selectorsを使えるCRDを定義してみます。今回は「Shirt（シャツ）」というリソースを例に説明します。

# crd.yaml
apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
  name: shirts.stable.example.com
spec:
  group: stable.example.com
  versions:
  - name: v1
    served: true
    storage: true
    schema:
      openAPIV3Schema:
        type: object
        properties:
          spec:
            type: object
            properties:
              color:
                type: string
              size:
                type: string
              price:
                type: integer  # 注意: numberではなくintegerを使用
            required:
            - color
            - size
          status:
            type: object
            properties:
              available:
                type: boolean
    # ここがポイント！検索可能なフィールドを定義
    selectableFields:
    - jsonPath: .spec.color
    - jsonPath: .spec.size
    - jsonPath: .spec.price
    additionalPrinterColumns:
    - jsonPath: .spec.color
      name: Color
      type: string
    - jsonPath: .spec.size
      name: Size
      type: string
    - jsonPath: .spec.price
      name: Price
      type: integer
  scope: Namespaced
  names:
    plural: shirts
    singular: shirt
    kind: Shirt

selectableFieldsの重要な制約

Field Selectorsを定義する際には、以下の制約に注意する必要があります。

対応する型: string、boolean、integerのみ
スカラー値のみ: オブジェクトや配列は指定できません
8個制限: 各オブジェクトにつけられるフィールドは8つまで

特にnumber型が使えない点は要注意です。価格などの数値フィールドにはinteger型を使用してください。

CRDを適用します。

kubectl apply -f crd.yaml

カスタムリソースの作成

次に、検索対象となるShirtリソースをいくつか作成します。

# shirts.yaml
apiVersion: stable.example.com/v1
kind: Shirt
metadata:
  name: shirt-blue-small
spec:
  color: blue
  size: S
  price: 26
---
apiVersion: stable.example.com/v1
kind: Shirt
metadata:
  name: shirt-blue-medium
spec:
  color: blue
  size: M
  price: 28
---
apiVersion: stable.example.com/v1
kind: Shirt
metadata:
  name: shirt-red-large
spec:
  color: red
  size: L
  price: 30
---
apiVersion: stable.example.com/v1
kind: Shirt
metadata:
  name: shirt-green-medium
spec:
  color: green
  size: M
  price: 27
---
apiVersion: stable.example.com/v1
kind: Shirt
metadata:
  name: shirt-blue-large
spec:
  color: blue
  size: L
  price: 31

kubectl apply -f shirts.yaml

作成したリソースを確認してみます。

kubectl get shirts

次のような出力が表示されるはずです。

NAME                 COLOR   SIZE   PRICE
shirt-blue-large     blue    L      31
shirt-blue-medium    blue    M      28
shirt-blue-small     blue    S      26
shirt-green-medium   green   M      27
shirt-red-large      red     L      30

Field Selectorsを使った検索

それではField Selectorsを使って、カスタムリソースを検索してみます。

単一条件での検索

まず、青色のシャツだけを検索してみます。

kubectl get shirts --field-selector spec.color=blue

結果：

NAME                COLOR   SIZE   PRICE
shirt-blue-large    blue    L      31
shirt-blue-medium   blue    M      28
shirt-blue-small    blue    S      26

複数条件での検索

Field Selectorsはカンマで区切ることで、複数の条件を組み合わせることができます。青色でMサイズのシャツを検索してみます。

kubectl get shirts --field-selector spec.color=blue,spec.size=M

結果：

NAME                COLOR   SIZE   PRICE
shirt-blue-medium   blue    M      28

数値フィールドでの検索

価格で検索することもできます。

kubectl get shirts --field-selector spec.price=27

結果：

NAME                 COLOR   SIZE   PRICE
shirt-green-medium   green   M      27

まとめ

この投稿では、Kubernetes v1.31で導入されたCRDのField Selectors機能について解説しました。この機能により、カスタムリソースも組み込みリソースと同じようにspecの値などで検索できるようになります。

最後までお読みくださりありがとうございました。Twitter では、Qiita に書かない技術ネタなどもツイートしているので、よかったらフォローしてもらえると嬉しいです→Twitter@suin