Kong KIC自定义资源开发：扩展控制器功能的完整指南

姬忆慈Loveable

1079人浏览 · 2026-04-18 09:40:42

姬忆慈Loveable · 2026-04-18 09:40:42 发布

Kong KIC自定义资源开发：扩展控制器功能的完整指南

【免费下载链接】kubernetes-ingress-controller :gorilla: Kong for Kubernetes: The official Ingress Controller for Kubernetes. 项目地址: https://gitcode.com/gh_mirrors/ku/kubernetes-ingress-controller

Kong Kubernetes Ingress Controller（KIC）作为官方的Kubernetes Ingress控制器，提供了强大的流量管理能力。通过自定义资源（CRD）开发，您可以轻松扩展控制器功能，满足特定业务需求。本文将详细介绍如何开发Kong KIC自定义资源，从基础概念到实际应用，帮助您快速掌握扩展控制器的核心技巧。

什么是Kong KIC自定义资源？

自定义资源（Custom Resource Definitions, CRD）是Kubernetes提供的扩展机制，允许用户定义新的API对象类型。Kong KIC通过CRD实现了对Kong特定功能的抽象，如KongPlugin、KongConsumer和KongUpstreamPolicy等。这些资源使Kubernetes用户能够以声明式方式配置Kong网关，而无需直接操作Kong Admin API。

Kong KIC的自定义资源主要定义在项目的CRD目录中，例如：

这些目录包含了所有自定义资源的定义文件，您可以通过修改这些文件或创建新文件来扩展控制器功能。

开发自定义资源的基本步骤

开发Kong KIC自定义资源通常需要以下几个步骤：

1. 定义CRD结构

首先，您需要定义自定义资源的结构。这包括指定资源的API版本、组、名称、作用域（命名空间或集群范围）以及Schema定义。Schema定义了资源的字段、类型和验证规则。

例如，KongUpstreamPolicy的CRD定义可能包含以下关键部分：

apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
  name: kongupstreampolicies.configuration.konghq.com
spec:
  group: configuration.konghq.com
  names:
    kind: KongUpstreamPolicy
    listKind: KongUpstreamPolicyList
    plural: kongupstreampolicies
    singular: kongupstreampolicy
  scope: Namespaced
  versions:
  - name: v1beta1
    served: true
    storage: true
    schema:
      openAPIV3Schema:
        type: object
        properties:
          spec:
            type: object
            properties:
              algorithm:
                type: string
                enum: [round_robin, least_connections, ip_hash, sticky_sessions]
              sessionAffinity:
                type: object
                properties:
                  cookieName:
                    type: string
                  cookiePath:
                    type: string
                  cookieSecure:
                    type: boolean

2. 实现控制器逻辑

定义CRD后，需要实现控制器逻辑来处理自定义资源的创建、更新和删除事件。Kong KIC使用controller-runtime库来实现控制器，您可以在以下目录找到相关代码：

internal/controllers/configuration/kongupstreampolicy_controller.go

控制器逻辑通常包括：

设置Reconcile循环，监听资源事件
处理资源变更，更新Kong配置
管理资源状态，设置条件和状态信息

例如，KongUpstreamPolicy控制器的Reconcile函数可能如下所示：

func (r *KongUpstreamPolicyReconciler) Reconcile(ctx context.Context, req ctrl.Request) (ctrl.Result, error) {
    log := log.FromContext(ctx)
    
    // 获取KongUpstreamPolicy实例
    policy := &configurationv1beta1.KongUpstreamPolicy{}
    if err := r.Get(ctx, req.NamespacedName, policy); err != nil {
        log.Error(err, "unable to fetch KongUpstreamPolicy")
        return ctrl.Result{}, client.IgnoreNotFound(err)
    }
    
    // 处理策略，更新Kong配置
    if err := r.updateKongConfiguration(ctx, policy); err != nil {
        log.Error(err, "failed to update Kong configuration")
        return ctrl.Result{}, err
    }
    
    // 更新策略状态
    policy.Status.ObservedGeneration = policy.Generation
    if err := r.Status().Update(ctx, policy); err != nil {
        log.Error(err, "unable to update status")
        return ctrl.Result{}, err
    }
    
    return ctrl.Result{}, nil
}

3. 实现数据平面转换逻辑

Kong KIC需要将Kubernetes资源转换为Kong配置。这一转换逻辑通常在数据平面模块中实现，您可以在以下目录找到相关代码：

internal/dataplane/translator/

例如，将KongUpstreamPolicy转换为Kong Upstream配置的代码可能如下所示：

func (t *Translator) translateKongUpstreamPolicy(policy *configurationv1beta1.KongUpstreamPolicy) (*kong.Upstream, error) {
    upstream := &kong.Upstream{
        Name: kong.String(policy.Name),
    }
    
    if policy.Spec.Algorithm != nil {
        upstream.Algorithm = policy.Spec.Algorithm
    }
    
    if policy.Spec.SessionAffinity != nil {
        upstream.SessionAffinity = &kong.SessionAffinity{
            CookieName:  policy.Spec.SessionAffinity.CookieName,
            CookiePath:  policy.Spec.SessionAffinity.CookiePath,
            CookieSecure: policy.Spec.SessionAffinity.CookieSecure,
        }
    }
    
    return upstream, nil
}

4. 注册自定义资源

最后，需要在控制器管理器中注册自定义资源和控制器。这通常在main函数或控制器设置代码中完成：

例如，注册KongUpstreamPolicy控制器的代码可能如下所示：

func (m *Manager) setupControllers(ctx context.Context) error {
    // ...其他控制器注册
    
    if err := (&controllers.KongUpstreamPolicyReconciler{
        Client:   m.Client,
        Scheme:   m.Scheme,
        Recorder: m.Recorder,
    }).SetupWithManager(m.Manager); err != nil {
        return fmt.Errorf("failed to create controller: %w", err)
    }
    
    return nil
}

自定义资源开发最佳实践

1. 遵循Kubernetes API设计原则

开发自定义资源时，应遵循Kubernetes API设计原则，包括：

使用复数名词作为资源名称
版本控制策略（如v1alpha1, v1beta1, v1）
适当的作用域（命名空间或集群范围）
明确的状态管理

2. 实现适当的验证

为自定义资源添加验证规则，确保资源配置的有效性。可以使用OpenAPI v3 Schema定义验证规则，如必填字段、枚举值、格式验证等。

3. 管理资源状态

为自定义资源实现状态管理，包括设置观察到的生成版本、条件和状态信息。这有助于用户和其他系统了解资源的当前状态。

4. 处理依赖关系

考虑自定义资源与其他资源的依赖关系，如Service、Ingress等。确保在Reconcile过程中正确处理这些依赖，避免出现不一致状态。

5. 添加测试

为自定义资源和控制器添加单元测试和集成测试，确保功能正确性和稳定性。Kong KIC的测试代码主要位于以下目录：

实际应用示例：自定义限流策略

假设您需要实现一个自定义限流策略，允许按客户端IP地址限制请求速率。以下是实现此功能的简要步骤：

创建KongRateLimitPolicy CRD，定义限流规则和参数。
实现控制器，监听KongRateLimitPolicy资源事件。
在数据平面转换逻辑中，将KongRateLimitPolicy转换为Kong的rate-limiting插件配置。
注册控制器并更新CRD定义。

通过这种方式，您可以轻松扩展Kong KIC的功能，满足特定的业务需求。

总结

Kong KIC自定义资源开发是扩展控制器功能的强大方式。通过定义CRD、实现控制器逻辑和数据平面转换，您可以将Kong的高级功能集成到Kubernetes中，以声明式方式管理API网关配置。遵循本文介绍的最佳实践，您可以开发出稳定、可维护的自定义资源，为您的Kubernetes集群提供更强大的流量管理能力。

要深入了解Kong KIC自定义资源开发，建议参考项目中的官方文档和示例代码：

通过这些资源，您可以进一步探索Kong KIC的高级功能和扩展可能性。