编辑“︁Kubernetes扩展API”︁

{{DISPLAYTITLE:Kubernetes扩展API}}

'''Kubernetes扩展API'''是Kubernetes的核心功能之一，允许用户通过自定义资源（Custom Resource, CR）和自定义控制器（Custom Controller）扩展原生API的功能。它为开发者提供了灵活的方式来定义和管理Kubernetes集群中的新资源类型，从而满足特定业务需求。

== 概述 ==
Kubernetes原生API提供了如Pod、Service、Deployment等核心资源，但在实际场景中，用户可能需要定义自己的资源类型。通过扩展API，用户可以：
* 创建自定义资源定义（Custom Resource Definitions, CRDs）
* 开发自定义控制器以实现业务逻辑
* 集成第三方工具或服务到Kubernetes生态系统中

扩展API的核心组件包括：
* '''CustomResourceDefinition (CRD)'''：声明自定义资源的Schema
* '''Aggregation Layer'''：将多个API服务器聚合为一个统一入口
* '''API Server Extension'''：通过独立的API服务器提供扩展功能

== 核心概念 ==

=== CustomResourceDefinition (CRD) ===
CRD是最常见的扩展方式，允许用户定义新的资源类型。以下是一个典型的CRD示例：

<syntaxhighlight lang="yaml">
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:
          type: object
          properties:
            spec:
              type: object
              properties:
                replicas:
                  type: integer
                image:
                  type: string
  scope: Namespaced
  names:
    plural: myresources
    singular: myresource
    kind: MyResource
    shortNames:
    - mr
</syntaxhighlight>

创建后，用户可以通过kubectl操作自定义资源：
<syntaxhighlight lang="bash">
kubectl get myresources  # 列出所有MyResource实例
</syntaxhighlight>

=== API Aggregation ===
对于更复杂的场景，可以通过独立的API服务器扩展功能。聚合层将请求路由到相应的后端服务器：

<mermaid>
graph LR
    A[Kubernetes API Server] --> B[Aggregator]
    B --> C[Core API]
    B --> D[Custom API Server 1]
    B --> E[Custom API Server 2]
</mermaid>

== 实际案例 ==

=== 案例1：数据库自动伸缩 ===
定义一个DatabaseScale CRD来自动管理数据库实例：

<syntaxhighlight lang="yaml">
apiVersion: "db.example.com/v1"
kind: DatabaseScale
metadata:
  name: mysql-production
spec:
  minReplicas: 2
  maxReplicas: 5
  cpuThreshold: 80
</syntaxhighlight>

自定义控制器会监控CPU使用率，在阈值超过80%时自动扩容。

=== 案例2：CI/CD流水线集成 ===
通过扩展API将CI/CD系统集成到Kubernetes：

<syntaxhighlight lang="yaml">
apiVersion: "ci.example.com/v1alpha1"
kind: Pipeline
metadata:
  name: frontend-deploy
spec:
  stages:
    - name: build
      image: node:14
      commands: ["npm install", "npm run build"]
    - name: deploy
      image: kubectl
      commands: ["kubectl apply -f deployment.yaml"]
</syntaxhighlight>

== 开发自定义控制器 ==
自定义控制器通常包含以下组件：
1. '''Informer/SharedIndexInformer'''：监控资源变化
2. '''Workqueue'''：处理事件队列
3. '''Reconcile Loop'''：实现业务逻辑

以下是Go语言控制器的简化结构：

<syntaxhighlight lang="go">
func (c *Controller) Run(stopCh <-chan struct{}) {
    defer utilruntime.HandleCrash()
    defer c.workqueue.ShutDown()

    if !cache.WaitForCacheSync(stopCh, c.informerSynced) {
        return
    }

    go wait.Until(c.runWorker, time.Second, stopCh)
    <-stopCh
}

func (c *Controller) runWorker() {
    for c.processNextWorkItem() {
    }
}
</syntaxhighlight>

== 数学基础 ==
Kubernetes控制器通常遵循'''Reconcile'''模式，其基本公式表示为：

<math>
Reconcile(state_{desired}, state_{actual}) \rightarrow action
</math>

其中：
* <math>state_{desired}</math> 是期望状态（来自CRD spec）
* <math>state_{actual}</math> 是实际状态（来自集群）
* <math>action</math> 是使实际状态趋近期望状态的操作

== 最佳实践 ==
* 版本控制：为CRD定义清晰的版本策略（如v1alpha1, v1beta1, v1）
* 验证：使用OpenAPI schema验证自定义资源
* 命名空间：合理选择Cluster-scoped或Namespaced资源
* RBAC：为自定义资源配置适当的权限
* 监控：为自定义控制器添加指标和日志

== 常见问题 ==
{{Q&A
|问题1 = CRD与Operator有什么区别？
|答案1 = CRD是资源定义，Operator是包含CRD+自定义控制器的完整解决方案。
|问题2 = 何时选择API聚合而非CRD？
|答案2 = 当需要完全控制API行为（如存储后端、鉴权机制）时选择聚合API。
|问题3 = 如何调试自定义控制器？
|答案3 = 使用kubectl get events和控制器日志，配合kubectl get --raw /apis/...
}}

== 总结 ==
Kubernetes扩展API为平台开发者提供了强大的扩展能力，使得Kubernetes能够适应各种定制化场景。通过合理使用CRD和自定义控制器，可以实现从简单资源管理到复杂业务逻辑的全方位扩展。

[[Category:集成部署]]
[[Category:Kubernetes]]
[[Category:Kubernetes扩展]]