版本：v1.12

自定义资源解释器

资源解释器框架

在将资源从 karmada-apiserver 分发到成员集群的过程中，Karmada 可能需要了解资源的定义结构。以 Propagating Deployment 为例，在构建 ResourceBinding 的阶段，karmada-controller-manager 组件需要解析 deployment 资源的 replicas 字段。

对于 Kubernetes 原生资源来说，Karmada 知道如何解析它们，但是对于由 CRD 定义的资源（或是由聚合层方式注册）来说，由于缺乏对该资源结构信息的了解，它们将仅被当作普通资源来对待，因此，高级调度算法将不能应用于这些资源。

Resource Interpreter Framework 专为解释资源结构而设计，它包括两类解释器：

内置解释器：用于解释常见的 Kubernetes 原生资源或一些知名的扩展资源；
自定义解释器: 用于解释自定义资源或覆盖内置解释器。

注意：上述两类解释器之间的主要区别在于，内置解释器由 Karmada 社区实现并维护，并将其内置到 Karmada 组件中，例如 karmada-controller-manager。相反，自定义解释器是由用户实现和维护的，它应该作为 Interpreter Webhook 或声明式配置注册到 Karmada（更多详细信息，请参考 Customized Interpreter）。

解释器操作

在解释资源时，我们经常会提取多条信息。Karmada 中定义了多种解释器操作，资源解释器框架为每个操作类型提供服务。

关于资源解释器框架定义的各种操作类型的具体含义，可以参考 Interpreter Operations 。

注意：并非所有设计的操作类型均受支持（有关支持的操作，请参见下文）：

注意：在使用特定的解释器操作解释资源时，最多只会咨询一个解释器；对于同一个资源，自定义解释器比内置解释器具有更高的优先级。例如，内置解释器为 apps/v1 version 的 Deployment 提供 InterpretReplica 服务，如果有一个自定义解释器注册到 Karmada 来解释该资源，则自定义解释器获胜，内置解释器将被忽略。

内置解释器

对于常见的 Kubernetes 原生资源或一些知名的扩展资源来说，解释器操作是内置的，这意味着用户通常不需要实现自定义解释器。如果你希望内置更多资源，请随时提交问题让我们了解您的用户案例。

内置解释器现在支持以下解释器操作：

InterpretReplica

支持资源：

Deployment(apps/v1)
StatefulSet(apps/v1)
Job(batch/v1)
Pod(v1)

ReviseReplica

支持资源：

Deployment(apps/v1)
StatefulSet(apps/v1)
Job(batch/v1)

Retain

支持资源：

Pod(v1)
Service(v1)
ServiceAccount(v1)
PersistentVolumeClaim(v1)
PersistentVolume(V1)
Job(batch/v1)

AggregateStatus

支持资源：

Deployment(apps/v1)
Service(v1)
Ingress(networking.k8s.io/v1)
CronJob(batch/v1)
Job(batch/v1)
DaemonSet(apps/v1)
StatefulSet(apps/v1)
Pod(v1)
PersistentVolume(V1)
PersistentVolumeClaim(v1)
PodDisruptionBudget(policy/v1)

InterpretStatus

支持资源：

Deployment(apps/v1)
Service(v1)
Ingress(networking.k8s.io/v1)
Job(batch/v1)
DaemonSet(apps/v1)
StatefulSet(apps/v1)
PodDisruptionBudget(policy/v1)

InterpretDependency

支持资源：

Deployment(apps/v1)
Job(batch/v1)
CronJob(batch/v1)
Pod(v1)
DaemonSet(apps/v1)
StatefulSet(apps/v1)
Ingress(networking.k8s.io/v1)

InterpretHealth

支持资源：

Deployment(apps/v1)
StatefulSet(apps/v1)
ReplicaSet(apps/v1)
DaemonSet(apps/v1)
Service(v1)
Ingress(networking.k8s.io/v1)
PersistentVolumeClaim(v1)
PodDisruptionBudget(policy/v1)
Pod(v1)

自定义解释器

自定义解释器由用户实现和维护，它可以通过两种方式扩展，通过定义声明式配置文件或在运行时作为 webhook 运行。

注意：声明式配置比 webhook 有更高的优先级，即用户如果同时注册了这两种解释方式，将优先应用相应资源的声明式配置

内置资源声明性配置

Karmada捆绑了一些流行、开源的资源，以便用户可以直接使用。声明式配置的解释器现在支持以下解释器操作：

InterpretReplica

支持资源：

BroadcastJob(apps.kruise.io/v1alpha1)
CloneSet(apps.kruise.io/v1alpha1)
AdvancedStatefulSet(apps.kruise.io/v1beta1)
Workflow(argoproj.io/v1alpha1)

ReviseReplica

支持资源：

BroadcastJob(apps.kruise.io/v1alpha1)
CloneSet(apps.kruise.io/v1alpha1)
AdvancedStatefulSet(apps.kruise.io/v1beta1)
Workflow(argoproj.io/v1alpha1)

Retain

支持资源：

BroadcastJob(apps.kruise.io/v1alpha1)
Workflow(argoproj.io/v1alpha1)
HelmRelease(helm.toolkit.fluxcd.io/v2beta1)
Kustomization(kustomize.toolkit.fluxcd.io/v1)
GitRepository(source.toolkit.fluxcd.io/v1)
Bucket(source.toolkit.fluxcd.io/v1beta2)
HelmChart(source.toolkit.fluxcd.io/v1beta2)
HelmRepository(source.toolkit.fluxcd.io/v1beta2)
OCIRepository(source.toolkit.fluxcd.io/v1beta2)

AggregateStatus

支持资源：

AdvancedCronJob(apps.kruise.io/v1alpha1)
AdvancedDaemonSet(apps.kruise.io/v1alpha1)
BroadcastJob(apps.kruise.io/v1alpha1)
CloneSet(apps.kruise.io/v1alpha1)
AdvancedStatefulSet(apps.kruise.io/v1beta1)
HelmRelease(helm.toolkit.fluxcd.io/v2beta1)
Kustomization(kustomize.toolkit.fluxcd.io/v1)
ClusterPolicy(kyverno.io/v1)
Policy(kyverno.io/v1)
GitRepository(source.toolkit.fluxcd.io/v1)
Bucket(source.toolkit.fluxcd.io/v1beta2)
HelmChart(source.toolkit.fluxcd.io/v1beta2)
HelmRepository(source.toolkit.fluxcd.io/v1beta2)
OCIRepository(source.toolkit.fluxcd.io/v1beta2)

InterpretStatus

支持资源：

AdvancedDaemonSet(apps.kruise.io/v1alpha1)
BroadcastJob(apps.kruise.io/v1alpha1)
CloneSet(apps.kruise.io/v1alpha1)
AdvancedStatefulSet(apps.kruise.io/v1beta1)
HelmRelease(helm.toolkit.fluxcd.io/v2beta1)
Kustomization(kustomize.toolkit.fluxcd.io/v1)
ClusterPolicy(kyverno.io/v1)
Policy(kyverno.io/v1)
GitRepository(source.toolkit.fluxcd.io/v1)
Bucket(source.toolkit.fluxcd.io/v1beta2)
HelmChart(source.toolkit.fluxcd.io/v1beta2)
HelmRepository(source.toolkit.fluxcd.io/v1beta2)
OCIRepository(source.toolkit.fluxcd.io/v1beta2)

InterpretDependency

支持资源：

AdvancedCronJob(apps.kruise.io/v1alpha1)
AdvancedDaemonSet(apps.kruise.io/v1alpha1)
BroadcastJob(apps.kruise.io/v1alpha1)
CloneSet(apps.kruise.io/v1alpha1)
AdvancedStatefulSet(apps.kruise.io/v1beta1)
Workflow(argoproj.io/v1alpha1)
HelmRelease(helm.toolkit.fluxcd.io/v2beta1)
Kustomization(kustomize.toolkit.fluxcd.io/v1)
GitRepository(source.toolkit.fluxcd.io/v1)
Bucket(source.toolkit.fluxcd.io/v1beta2)
HelmChart(source.toolkit.fluxcd.io/v1beta2)
HelmRepository(source.toolkit.fluxcd.io/v1beta2)
OCIRepository(source.toolkit.fluxcd.io/v1beta2)

InterpretHealth

支持资源：

AdvancedCronJob(apps.kruise.io/v1alpha1)
AdvancedDaemonSet(apps.kruise.io/v1alpha1)
BroadcastJob(apps.kruise.io/v1alpha1)
CloneSet(apps.kruise.io/v1alpha1)
AdvancedStatefulSet(apps.kruise.io/v1beta1)
Workflow(argoproj.io/v1alpha1)
HelmRelease(helm.toolkit.fluxcd.io/v2beta1)
Kustomization(kustomize.toolkit.fluxcd.io/v1)
ClusterPolicy(kyverno.io/v1)
Policy(kyverno.io/v1)
GitRepository(source.toolkit.fluxcd.io/v1)
Bucket(source.toolkit.fluxcd.io/v1beta2)
HelmChart(source.toolkit.fluxcd.io/v1beta2)
HelmRepository(source.toolkit.fluxcd.io/v1beta2)
OCIRepository(source.toolkit.fluxcd.io/v1beta2)

声明式配置

什么是解释器声明式配置？

用户可以通过 ResourceInterpreterCustomization API 规范中声明的规则，快速为 Kubernetes 原生资源和 CR 资源自定义资源解释器。

配置编写

你可以通过创建或更新 ResourceInterpreterCustomization 资源来配置资源解释规则，当前支持在 ResourceInterpreterCustomization 中定义 lua 脚本。你可以在 API 定义中学习如何定义 lua 脚本，以 retention 为例。

下面我们提供一个ResourceInterpreterCustomization资源的yaml编写示例：

resource-interpreter-customization.yaml

apiVersion: config.karmada.io/v1alpha1
kind: ResourceInterpreterCustomization
metadata:
  name: declarative-configuration-example
spec:
  target:
    apiVersion: apps/v1
    kind: Deployment
  customizations:
    replicaResource:
      luaScript: >
        local kube = require("kube")
        function GetReplicas(obj)
          replica = obj.spec.replicas
          requirement = kube.accuratePodRequirements(obj.spec.template)
          return replica, requirement
        end
    replicaRevision:
      luaScript: >
        function ReviseReplica(obj, desiredReplica)
          obj.spec.replicas = desiredReplica
          return obj
        end
    retention:
      luaScript: >
        function Retain(desiredObj, observedObj)
          desiredObj.spec.paused = observedObj.spec.paused
          return desiredObj
        end
    statusAggregation:
      luaScript: >
        function AggregateStatus(desiredObj, statusItems)
          if statusItems == nil then
            return desiredObj
          end
          if desiredObj.status == nil then
            desiredObj.status = {}
          end
          replicas = 0
          for i = 1, #statusItems do
            if statusItems[i].status ~= nil and statusItems[i].status.replicas ~= nil then
              replicas = replicas + statusItems[i].status.replicas
            end
          end
          desiredObj.status.replicas = replicas
          return desiredObj
        end
    statusReflection:
      luaScript: >
        function ReflectStatus (observedObj)
          return observedObj.status
        end
    healthInterpretation:
      luaScript: >
        function InterpretHealth(observedObj)
          return observedObj.status.readyReplicas == observedObj.spec.replicas
        end
    dependencyInterpretation:
      luaScript: >
        function GetDependencies(desiredObj)
          dependentSas = {}
          refs = {}
          if desiredObj.spec.template.spec.serviceAccountName ~= nil and desiredObj.spec.template.spec.serviceAccountName ~= 'default' then
            dependentSas[desiredObj.spec.template.spec.serviceAccountName] = true
          end
          local idx = 1
          for key, value in pairs(dependentSas) do
            dependObj = {}
            dependObj.apiVersion = 'v1'
            dependObj.kind = 'ServiceAccount'
            dependObj.name = key
            dependObj.namespace = desiredObj.metadata.namespace
            refs[idx] = dependObj
            idx = idx + 1
          end
          return refs
        end

配置验证

你可以使用 karmadactl interpret 命令在将 ResourceInterpreterCustomization 配置应用到系统之前来验证该配置的正确性。我们提供了一些示例来帮助用户更好的理解如何使用该验证工具，请参考 examples 。

Webhook

什么是解释器 webhook？

解释器 webhook 是一种 HTTP 回调，它接收解释请求并对其进行处理。

编写一个解释器 webhook 服务器

请参考 Example of Customize Interpreter 的实现，我们在 Karmada E2E 测试中使用该方式进行了验证。webhook 将处理 Karmada 组件（例如 karmada-controller-manager）发送的 ResourceInterpreterRequest 请求，处理完成后将处理结果以 ResourceInterpreterResponse 为形式返回。

部署 admission webhook 服务

在 E2E 测试环境中， Customize Interpreter示例部署在 host 集群上，由 service 暴露为 webhook 服务器前端。

你也可以在集群外部署你的 webhooks，并记得更新你的 webhook 配置。

即时配置 webhook

你可以通过 ResourceInterpreterWebhookConfiguration 来配置哪些资源和解释器操作受 webhook 的约束。

下面提供了一个 ResourceInterpreterWebhookConfiguration 的配置示例：

apiVersion: config.karmada.io/v1alpha1
kind: ResourceInterpreterWebhookConfiguration
metadata:
  name: examples
webhooks:
  - name: workloads.example.com
    rules:
      - operations: [ "InterpretReplica","ReviseReplica","Retain","AggregateStatus" ]
        apiGroups: [ "workload.example.io" ]
        apiVersions: [ "v1alpha1" ]
        kinds: [ "Workload" ]
    clientConfig:
      url: https://karmada-interpreter-webhook-example.karmada-system.svc:443/interpreter-workload
      caBundle: {{caBundle}}
    interpreterContextVersions: [ "v1alpha1" ]
    timeoutSeconds: 3

你可以在 ResourceInterpreterWebhookConfiguration 中配置多个 webhook，每个 webhook 至少服务于一个解释器操作。

编写 ResourceInterpreterCustomization

你可以学习如何编写 ResourceInterpreterCustomization 来定制你的资源。

首先，我们介绍kube库函数。然后，我们以 kyverno.io/v1/ClusterPolicy 为例，介绍如何编写 ResourceInterpreterCustomization。

luavm 的内置函数

ResourceInterpreterCustomization API 规范中声明的规则定义了解释器操作。这些操作由 lua 编写，并通过 luavm 调用。用户在编写解释器操作时，可以使用 luavm 的内置函数。

在 kubeLibrary 中，有两个函数可用于编写解释器操作：accuratePodRequirements 和 getPodDependencies。accuratePodRequirements有助于编写ReplicaResource操作，getPodDependencies有助于编写DependencyInterpretation操作。

accuratePodRequirements 函数功能是获取 pod 的总资源需求。它的参数是PodTemplateSpec，返回值是 ReplicaRequirements。PodTemplateSpec描述了一个pod在从模板创建时应该有的数据，ReplicaRequirements 表示每个副本的需求。

getPodDependencies函数功能是从podTemplate和namespace中获取所有依赖。它的参数是PodTemplateSpec和namespace。它的返回值是dependencies。PodTemplateSpec描述了一个pod在从模板创建时应该有的数据。namespace是定制资源的命名空间。而dependencies是定制资源所依赖的资源。

ReplicaResource

ReplicaResource 描述了Karmada发现资源的副本以及资源需求的规则。它用于那些声明式工作负载类型（如 Deployment）的CRD资源。

Kyverno的ClusterPolicy是一个规则的集合，它没有.spec.replicas或.spec.template.spec.nodeSelector这样的字段。因此这里不需要为ClusterPolicy实现ReplicaResource操作。

ReplicaRevision

ReplicaRevision 描述了Karmada修改资源副本的规则。它用于那些声明式工作负载类型（如 Deployment）的CRD资源。

Kyverno的ClusterPolicy是一个规则的集合，它没有.spec.replicas这样的字段。因此这里不需要为ClusterPolicy实现ReplicaRevision操作。

Retention

Retention 描述了Karmada对成员集群组件的变化做出反应的所希望的行为。这可以避免系统进入一个无意义的循环，即Karmada资源控制器和成员集群组件，用不同的值不断应用于资源的同一个字段。

Kyverno的ClusterPolicy是一个规则的集合，通常不会被成员集群中的组件改变。因此这里不需要为ClusterPolicy实现Retention操作。

StatusAggregation

StatusAggregation描述了Karmada将从成员集群收集的状态汇总到资源模板的规则。

Kyverno的ClusterPolicy是一个规则的集合。这里我们定义了ClusterPolicy的状态聚合规则。

StatusAggregation-Defined-In-ResourceInterpreterCustomization

statusAggregation:
  luaScript: >
    function AggregateStatus(desiredObj, statusItems)
      if statusItems == nil then
        return desiredObj
      end
      desiredObj.status = {}
      desiredObj.status.conditions = {}
      rulecount = {}
      rulecount.validate = 0
      rulecount.generate = 0
      rulecount.mutate = 0
      rulecount.verifyimages = 0
      conditions = {}
      local conditionsIndex = 1
      for i = 1, #statusItems do
        if statusItems[i].status ~= nil and statusItems[i].status.autogen ~= nil then
          desiredObj.status.autogen = statusItems[i].status.autogen
        end
        if statusItems[i].status ~= nil and statusItems[i].status.ready ~= nil then
          desiredObj.status.ready = statusItems[i].status.ready
        end                        
        if statusItems[i].status ~= nil and statusItems[i].status.rulecount ~= nil then
          rulecount.validate = rulecount.validate + statusItems[i].status.rulecount.validate
          rulecount.generate = rulecount.generate + statusItems[i].status.rulecount.generate
          rulecount.mutate = rulecount.mutate + statusItems[i].status.rulecount.mutate
          rulecount.verifyimages = rulecount.verifyimages + statusItems[i].status.rulecount.verifyimages
        end
        if statusItems[i].status ~= nil and statusItems[i].status.conditions ~= nil then
          for conditionIndex = 1, #statusItems[i].status.conditions do
            statusItems[i].status.conditions[conditionIndex].message = statusItems[i].clusterName..'='..statusItems[i].status.conditions[conditionIndex].message
            hasCondition = false
            for index = 1, #conditions do
              if conditions[index].type == statusItems[i].status.conditions[conditionIndex].type and conditions[index].status == statusItems[i].status.conditions[conditionIndex].status and conditions[index].reason == statusItems[i].status.conditions[conditionIndex].reason then
                conditions[index].message = conditions[index].message..', '..statusItems[i].status.conditions[conditionIndex].message
                hasCondition = true
                break
              end
            end
            if not hasCondition then
              conditions[conditionsIndex] = statusItems[i].status.conditions[conditionIndex]
              conditionsIndex = conditionsIndex + 1                  
            end
          end
        end
      end
      desiredObj.status.rulecount = rulecount
      desiredObj.status.conditions = conditions
      return desiredObj
    end

StatusReflection

StatusReflection 描述了Karmada挑选资源状态的规则。

Kyverno的ClusterPolicy是一个规则的集合，其.status包含运行时数据。StatusReflection决定了Karmada从成员集群中收集哪些字段。这里我们从成员集群的资源中挑选了一些字段。

StatusReflection-Defined-In-ResourceInterpreterCustomization

statusReflection:
  luaScript: >
    function ReflectStatus (observedObj)
      status = {}
      if observedObj == nil or observedObj.status == nil then 
        return status
      end
      status.ready = observedObj.status.ready
      status.conditions = observedObj.status.conditions
      status.autogen = observedObj.status.autogen
      status.rulecount = observedObj.status.rulecount
      return status
    end

HealthInterpretation

HealthInterpretation 描述了健康评估规则，Karmada可以通过这些规则评估资源类型的健康状态。

Kyverno的ClusterPolicy是一个规则的集合。我们通过定义健康评估规则来确定成员集群中的ClusterPolicy是否健康。

HealthInterpretation-Defined-In-ResourceInterpreterCustomization

healthInterpretation:
  luaScript: >
    function InterpretHealth(observedObj)
      if observedObj.status ~= nil and observedObj.status.ready ~= nil then
        return observedObj.status.ready
      end
      if observedObj.status ~= nil and observedObj.status.conditions ~= nil then
        for conditionIndex = 1, #observedObj.status.conditions do
          if observedObj.status.conditions[conditionIndex].type == 'Ready' and observedObj.status.conditions[conditionIndex].status == 'True' and observedObj.status.conditions[conditionIndex].reason == 'Succeeded' then
            return true
          end
        end
      end
      return false
    end

DependencyInterpretation

DependencyInterpretation 描述了Karmada分析依赖资源的规则。

Kyverno的ClusterPolicy是一个规则的集合，它不依赖于其他资源。因此这里不需要为ClusterPolicy实现DependencyInterpretation操作。

注意事项

使用 Retain 解释器解决控制面与成员集群的控制权冲突

问题：Retain是在Karmada控制面与成员集群同时具备对成员集群资源控制权时，用户可自定义的用于解决控制权冲突的解释器。一个典型的场景是当成员集群 Deployment 的副本数同时被控制面资源模版和成员集群 HPA 控制时，两者无限次来回修改成员集群 Deployment 的副本数，导致成员集群的 Deployment 状态会出现异常。

解决措施：

针对您的工作负载类资源实现相应的 Retain 解释器，决策什么场景下该响应控制面资源模版的修改，什么场景下该响应成员集群 HPA 的修改。目前 Karmada 只针对 Deployment 资源实现了相应的 Retain 解释器，具体实现方式为：如果资源模板有 resourcetemplate.karmada.io/retain-replicas 的 label，就由成员集群 HPA 控制，否则就由控制面资源模板控制（在显式开启 hpaReplicasSyncer 控制器情况下，Karmada 可以自动为启用 HPA 的 Deployment 标记该 label）。如果您需要针对其他资源或自定义的 CRD 资源解决该冲突问题，可参考 Deployment 的 Retain 方案。
如果您期望更优雅并彻底地解决上述问题，我们更推荐您将 HPA 更换为 FederatedHPA。

资源解释器框架​

解释器操作​

内置解释器​

InterpretReplica​

ReviseReplica​

Retain​

AggregateStatus​

InterpretStatus​

InterpretDependency​

InterpretHealth​

自定义解释器​

内置资源声明性配置​

InterpretReplica​

ReviseReplica​

Retain​

AggregateStatus​

InterpretStatus​

InterpretDependency​

InterpretHealth​

声明式配置​

什么是解释器声明式配置？​

配置编写​

配置验证​

Webhook​

什么是解释器 webhook？​

编写一个解释器 webhook 服务器​

部署 admission webhook 服务​

即时配置 webhook​

编写 ResourceInterpreterCustomization​

luavm 的内置函数​

ReplicaResource​

ReplicaRevision​

Retention​

StatusAggregation​

StatusReflection​

HealthInterpretation​

DependencyInterpretation​

注意事项​

使用 Retain 解释器解决控制面与成员集群的控制权冲突​

资源解释器框架

解释器操作

内置解释器

InterpretReplica

ReviseReplica

Retain

AggregateStatus

InterpretStatus

InterpretDependency

InterpretHealth

自定义解释器

内置资源声明性配置

InterpretReplica

ReviseReplica

Retain

AggregateStatus

InterpretStatus

InterpretDependency

InterpretHealth

声明式配置

什么是解释器声明式配置？

配置编写

配置验证

Webhook

什么是解释器 webhook？

编写一个解释器 webhook 服务器

部署 admission webhook 服务

即时配置 webhook

编写 ResourceInterpreterCustomization

luavm 的内置函数

ReplicaResource

ReplicaRevision

Retention

StatusAggregation

StatusReflection

HealthInterpretation

DependencyInterpretation

注意事项

使用 Retain 解释器解决控制面与成员集群的控制权冲突