自定义crd资源显示信息的配置

原生crd yaml的方法

在 Kubernetes 中，kubectl get 命令输出的列信息是由资源的 API 定义 控制的。内置资源（如 Pod、Deployment）的列信息是预先定义好的，而 自定义资源（Custom Resource，CR） 需要开发者在其 CRD（Custom Resource Definition） 中显式声明需要展示的列。以下是详细解释和配置方法：

---

一、为何自定义资源默认只有两列？

1. 默认行为 ：

   Kubernetes 默认仅显示资源的 NAME 和 AGE（创建时间），因为这是所有资源的共有元数据。 • NAME：取自 .metadata.name。 • AGE：通过 .metadata.creationTimestamp 计算得出。

2. 内置资源为何有多列 ：

   内置资源（如 Pod、Deployment）在它们的 API 定义中已经通过 additionalPrinterColumns 字段声明了需要展示的列。

---

二、如何为自定义资源添加更多列？

在 CRD 的 YAML 定义 中，通过 additionalPrinterColumns 字段定义要展示的列。每个列需要指定以下信息： • name：列名（如 STATUS）。 • type：数据类型（如 string、integer、date）。 • jsonPath：指向资源中对应字段的 JSON 路径。 • description：列的说明（可选）。

示例：为自定义资源添加 STATUS 和 READY 列

apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
  name: myresources.example.com
spec:
  group: example.com
  versions:
    - name: v1
      served: true
      storage: true
      schema:
        openAPIV3Schema:
          # ... 你的 CRD 结构定义 ...
      additionalPrinterColumns:
        - name: Status
          type: string
          jsonPath: .status.phase  # 假设你的 CR 的 Status 字段是 .status.phase
          description: 当前资源状态
        - name: Ready
          type: integer
          jsonPath: .status.readyReplicas
          description: 就绪的副本数
  scope: Namespaced
  names:
    plural: myresources
    singular: myresource
    kind: MyResource

---

三、验证和效果

1. 应用更新后的 CRD：

   kubectl apply -f my-crd.yaml

2. 检查列信息：

   kubectl get myresources

   输出示例：

   NAME           STATUS    READY   AGE
   my-resource-1  Running   2/3     5d

---

四、高级配置

1. 条件列（Conditional Columns）

通过 priority 字段控制列的显示优先级：

additionalPrinterColumns:
  - name: Priority
    type: string
    jsonPath: .status.priority
    priority: 1  # 0-1000，数字越小优先级越高（默认 0）

2. 格式化时间

使用 format 字段自定义时间格式：

additionalPrinterColumns:
  - name: Created
    type: date
    jsonPath: .metadata.creationTimestamp
    format: date  # 可选值：date、date-time、duration

---

五、常见问题

Q1：列未显示或显示错误

• 可能原因 ：

• JSON 路径错误（如 .status.phase 不存在）。

• 未正确应用更新的 CRD。

• 解决方案 ：

• 使用 kubectl get <crd> -o json 检查资源结构。

• 确保 CRD 中 additionalPrinterColumns 的 jsonPath 正确。

Q2：如何隐藏 AGE 列？

• 无法直接隐藏 ：AGE 是 Kubernetes 默认列，但可以通过设置 --show-aging=false 临时隐藏：

kubectl get myresources --show-aging=false

---

总结

• 内置资源 ：列信息由 Kubernetes 核心代码预定义。

• 自定义资源 ：通过 CRD 的 additionalPrinterColumns 字段声明需要展示的列，并确保 jsonPath 指向有效字段。

• 灵活控制：支持自定义列名、数据类型、格式和优先级，满足不同场景需求。

---

kubebuilder的方法

步骤 1：在 API 类型文件中定义列（api/v1/foo_types.go）

在您生成的 api/v1/foo_types.go 文件中，通过 +kubebuilder:printcolumn 注释标记定义要展示的列：

type FooSpec struct {
    // 定义 Spec 字段
    Replicas int32 `json:"replicas"`
    Image    string `json:"image"`
}

type FooStatus struct {
    // 定义 Status 字段（必须要有 Status 才能展示动态信息）
    ReadyReplicas int32 `json:"readyReplicas"`
    Phase         string `json:"phase"`
    LastUpdated   metav1.Time `json:"lastUpdated"`
}

// +kubebuilder:object:root=true
// +kubebuilder:subresource:status
// +kubebuilder:printcolumn:name="Replicas",type=integer,JSONPath=`.spec.replicas`,description="期望副本数"
// +kubebuilder:printcolumn:name="Ready",type=integer,JSONPath=`.status.readyReplicas`,description="就绪副本数"
// +kubebuilder:printcolumn:name="Status",type=string,JSONPath=`.status.phase`,description="当前状态"
// +kubebuilder:printcolumn:name="LastUpdated",type=date,JSONPath=`.status.lastUpdated`,description="最后更新时间"
// +kubebuilder:printcolumn:name="Age",type=date,JSONPath=`.metadata.creationTimestamp`
type Foo struct {
    metav1.TypeMeta   `json:",inline"`
    metav1.ObjectMeta `json:"metadata,omitempty"`

    Spec   FooSpec   `json:"spec,omitempty"`
    Status FooStatus `json:"status,omitempty"`
}

---

步骤 2：重新生成 CRD 清单

运行以下命令，将注释标记生成到 CRD YAML 文件中：

make manifests

这会更新 config/crd/bases/apps.foo.yaml 文件，其中包含生成的 additionalPrinterColumns 字段。

---

步骤 3：应用更新后的 CRD

kubectl apply -f config/crd/bases/apps.foo.yaml

---

步骤 4：验证列显示

创建一个 Foo 资源实例后，使用 kubectl get 查看列信息：

kubectl get foos

输出示例：

NAME       REPLICAS   READY   STATUS    LASTUPDATED          AGE
my-foo     3          2       Running   2023-10-05T14:30:00Z 5m

---

关键参数说明

标记参数	作用
name	列名（如 Replicas）
type	数据类型（string、integer、date、boolean）
JSONPath	指向资源字段的 JSON 路径（如 .spec.replicas）
description	列的说明（可选）
priority	优先级（0-1000，数字越小优先级越高，控制列是否默认显示）
format	格式（如 date、date-time，仅对 type=date 有效）

---

完整示例参考

# config/crd/bases/apps.foo.yaml
apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
  name: foos.apps.example.com
spec:
  versions:
    - name: v1
      served: true
      storage: true
      schema:
        openAPIV3Schema:
          # ... 自动生成的 Schema ...
      additionalPrinterColumns:
        - name: Replicas
          type: integer
          jsonPath: .spec.replicas
          description: 期望副本数
        - name: Ready
          type: integer
          jsonPath: .status.readyReplicas
          description: 就绪副本数
        - name: Status
          type: string
          jsonPath: .status.phase
          description: 当前状态
        - name: LastUpdated
          type: date
          jsonPath: .status.lastUpdated
          description: 最后更新时间
        - name: Age
          type: date
          jsonPath: .metadata.creationTimestamp

---

注意事项

1. Status 字段必须存在 ：动态信息（如 READY、STATUS）需要依赖 .status 字段，请确保资源控制器会更新状态。

2. JSONPath 准确性 ：使用 kubectl get foos -o json 验证 JSON 路径是否正确。

3. 列优先级 ：若列过多，低优先级列（priority > 0）可能需要通过 -o wide 显示：

   kubectl get foos -o wide

通过以上步骤，您可以为自定义资源实现类似 Pod 的列显示效果。