ResourceInterpreterCustomization v1alpha1

apiVersion: config.karmada.io/v1alpha1

import "github.com/karmada-io/karmada/pkg/apis/config/v1alpha1"

ResourceInterpreterCustomization

ResourceInterpreterCustomization describes the configuration of a specific resource for Karmada to get the structure. It has higher precedence than the default interpreter and the interpreter webhook.

ResourceInterpreterCustomizationSpec

ResourceInterpreterCustomizationSpec describes the configuration in detail.

  • customizations (CustomizationRules), required

    Customizations describe the interpretation rules.

    CustomizationRules describes the interpretation rules.

    • customizations.dependencyInterpretation (DependencyInterpretation)

      DependencyInterpretation describes the rules for Karmada to analyze the dependent resources. Karmada provides built-in rules for several standard Kubernetes types, see: https://karmada.io/docs/userguide/globalview/customizing-resource-interpreter/#interpretdependency If DependencyInterpretation is set, the built-in rules will be ignored.

      DependencyInterpretation holds the rules for interpreting the dependent resources of a specific resources.

      • customizations.dependencyInterpretation.luaScript (string), required

        LuaScript holds the Lua script that is used to interpret the dependencies of a specific resource. The script should implement a function as follows:

        1.   luaScript: >
        2.       function GetDependencies(desiredObj)
        3.           dependencies = []
        4.           serviceAccountName = desiredObj.spec.template.spec.serviceAccountName
        5.           if serviceAccountName ~= nil and serviceAccountName ~= "default" then
        6.               dependency = []
        7.               dependency.apiVersion = "v1"
        8.               dependency.kind = "ServiceAccount"
        9.               dependency.name = serviceAccountName
        10.               dependency.namespace = desiredObj.metadata.namespace
        11.               dependencies[1] = dependency
        12.           end
        13.           return dependencies
        14.       end

        The content of the LuaScript needs to be a whole function including both declaration and implementation.

        The parameters will be supplied by the system:

        • desiredObj: the object represents the configuration to be applied to the member cluster.

        The returned value should be expressed by a slice of DependentObjectReference.

    • customizations.healthInterpretation (HealthInterpretation)

      HealthInterpretation describes the health assessment rules by which Karmada can assess the health state of the resource type.

      HealthInterpretation holds the rules for interpreting the health state of a specific resource.

      • customizations.healthInterpretation.luaScript (string), required

        LuaScript holds the Lua script that is used to assess the health state of a specific resource. The script should implement a function as follows:

        1.   luaScript: >
        2.       function InterpretHealth(observedObj)
        3.           if observedObj.status.readyReplicas == observedObj.spec.replicas then
        4.               return true
        5.           end
        6.       end

        The content of the LuaScript needs to be a whole function including both declaration and implementation.

        The parameters will be supplied by the system:

        • observedObj: the object represents the configuration that is observed from a specific member cluster.

        The returned boolean value indicates the health status.

    • customizations.replicaResource (ReplicaResourceRequirement)

      ReplicaResource describes the rules for Karmada to discover the resource’s replica as well as resource requirements. It would be useful for those CRD resources that declare workload types like Deployment. It is usually not needed for Kubernetes native resources(Deployment, Job) as Karmada knows how to discover info from them. But if it is set, the built-in discovery rules will be ignored.

      ReplicaResourceRequirement holds the scripts for getting the desired replicas as well as the resource requirement of each replica.

      • customizations.replicaResource.luaScript (string), required

        LuaScript holds the Lua script that is used to discover the resource’s replica as well as resource requirements

        The script should implement a function as follows:

        1.   luaScript: >
        2.       function GetReplicas(desiredObj)
        3.           replica = desiredObj.spec.replicas
        4.           requirement = []
        5.           requirement.nodeClaim = []
        6.           requirement.nodeClaim.nodeSelector = desiredObj.spec.template.spec.nodeSelector
        7.           requirement.nodeClaim.tolerations = desiredObj.spec.template.spec.tolerations
        8.           requirement.resourceRequest = desiredObj.spec.template.spec.containers[1].resources.limits
        9.           return replica, requirement
        10.       end

        The content of the LuaScript needs to be a whole function including both declaration and implementation.

        The parameters will be supplied by the system:

        • desiredObj: the object represents the configuration to be applied to the member cluster.

        The function expects two return values:

        • replica: the declared replica number
        • requirement: the resource required by each replica expressed with a ResourceBindingSpec.ReplicaRequirements. The returned values will be set into a ResourceBinding or ClusterResourceBinding.

    • customizations.replicaRevision (ReplicaRevision)

      ReplicaRevision describes the rules for Karmada to revise the resource’s replica. It would be useful for those CRD resources that declare workload types like Deployment. It is usually not needed for Kubernetes native resources(Deployment, Job) as Karmada knows how to revise replicas for them. But if it is set, the built-in revision rules will be ignored.

      ReplicaRevision holds the scripts for revising the desired replicas.

      • customizations.replicaRevision.luaScript (string), required

        LuaScript holds the Lua script that is used to revise replicas in the desired specification. The script should implement a function as follows:

        1.   luaScript: >
        2.       function ReviseReplica(desiredObj, desiredReplica)
        3.           desiredObj.spec.replicas = desiredReplica
        4.           return desiredObj
        5.       end

        The content of the LuaScript needs to be a whole function including both declaration and implementation.

        The parameters will be supplied by the system:

        • desiredObj: the object represents the configuration to be applied to the member cluster.
        • desiredReplica: the replica number should be applied with.

        The returned object should be a revised configuration which will be applied to member cluster eventually.

    • customizations.retention (LocalValueRetention)

      Retention describes the desired behavior that Karmada should react on the changes made by member cluster components. This avoids system running into a meaningless loop that Karmada resource controller and the member cluster component continually applying opposite values of a field. For example, the “replicas” of Deployment might be changed by the HPA controller on member cluster. In this case, Karmada should retain the “replicas” and not try to change it.

      LocalValueRetention holds the scripts for retention. Now only supports Lua.

      • customizations.retention.luaScript (string), required

        LuaScript holds the Lua script that is used to retain runtime values to the desired specification.

        The script should implement a function as follows:

        1.   luaScript: >
        2.       function Retain(desiredObj, observedObj)
        3.           desiredObj.spec.fieldFoo = observedObj.spec.fieldFoo
        4.           return desiredObj
        5.       end

        The content of the LuaScript needs to be a whole function including both declaration and implementation.

        The parameters will be supplied by the system:

        • desiredObj: the object represents the configuration to be applied to the member cluster.
        • observedObj: the object represents the configuration that is observed from a specific member cluster.

        The returned object should be a retained configuration which will be applied to member cluster eventually.

    • customizations.statusAggregation (StatusAggregation)

      StatusAggregation describes the rules for Karmada to aggregate status collected from member clusters to resource template. Karmada provides built-in rules for several standard Kubernetes types, see: https://karmada.io/docs/userguide/globalview/customizing-resource-interpreter/#aggregatestatus If StatusAggregation is set, the built-in rules will be ignored.

      StatusAggregation holds the scripts for aggregating several decentralized statuses.

      • customizations.statusAggregation.luaScript (string), required

        LuaScript holds the Lua script that is used to aggregate decentralized statuses to the desired specification. The script should implement a function as follows:

        1.   luaScript: >
        2.       function AggregateStatus(desiredObj, statusItems)
        3.           for i = 1, #statusItems do
        4.               desiredObj.status.readyReplicas = desiredObj.status.readyReplicas + items[i].readyReplicas
        5.           end
        6.           return desiredObj
        7.       end

        The content of the LuaScript needs to be a whole function including both declaration and implementation.

        The parameters will be supplied by the system:

        • desiredObj: the object represents a resource template.
        • statusItems: the slice of status expressed with AggregatedStatusItem.

        The returned object should be a whole object with status aggregated.

    • customizations.statusReflection (StatusReflection)

      StatusReflection describes the rules for Karmada to pick the resource’s status. Karmada provides built-in rules for several standard Kubernetes types, see: https://karmada.io/docs/userguide/globalview/customizing-resource-interpreter/#interpretstatus If StatusReflection is set, the built-in rules will be ignored.

      StatusReflection holds the scripts for getting the status.

      • customizations.statusReflection.luaScript (string), required

        LuaScript holds the Lua script that is used to get the status from the observed specification. The script should implement a function as follows:

        1.   luaScript: >
        2.       function ReflectStatus(observedObj)
        3.           status = []
        4.           status.readyReplicas = observedObj.status.observedObj
        5.           return status
        6.       end

        The content of the LuaScript needs to be a whole function including both declaration and implementation.

        The parameters will be supplied by the system:

        • observedObj: the object represents the configuration that is observed from a specific member cluster.

        The returned status could be the whole status or part of it and will be set into both Work and ResourceBinding(ClusterResourceBinding).

  • target (CustomizationTarget), required

    CustomizationTarget represents the resource type that the customization applies to.

    CustomizationTarget represents the resource type that the customization applies to.

    • target.apiVersion (string), required

      APIVersion represents the API version of the target resource.

    • target.kind (string), required

      Kind represents the Kind of target resources.

ResourceInterpreterCustomizationList

ResourceInterpreterCustomizationList contains a list of ResourceInterpreterCustomization.

  • apiVersion: config.karmada.io/v1alpha1

  • kind: ResourceInterpreterCustomizationList

  • metadata (ListMeta)

  • items ([][ResourceInterpreterCustomization](../config-resources/resource-interpreter-customization-v1alpha1#resourceinterpretercustomization)), required

Operations

get read the specified ResourceInterpreterCustomization

HTTP Request

GET /apis/config.karmada.io/v1alpha1/resourceinterpretercustomizations/{name}

Parameters

  • name (in path): string, required

    name of the ResourceInterpreterCustomization

  • pretty (in query): string

    pretty

Response

200 (ResourceInterpreterCustomization): OK

get read status of the specified ResourceInterpreterCustomization

HTTP Request

GET /apis/config.karmada.io/v1alpha1/resourceinterpretercustomizations/{name}/status

Parameters

  • name (in path): string, required

    name of the ResourceInterpreterCustomization

  • pretty (in query): string

    pretty

Response

200 (ResourceInterpreterCustomization): OK

list list or watch objects of kind ResourceInterpreterCustomization

HTTP Request

GET /apis/config.karmada.io/v1alpha1/resourceinterpretercustomizations

Parameters

Response

200 (ResourceInterpreterCustomizationList): OK

create create a ResourceInterpreterCustomization

HTTP Request

POST /apis/config.karmada.io/v1alpha1/resourceinterpretercustomizations

Parameters

Response

200 (ResourceInterpreterCustomization): OK

201 (ResourceInterpreterCustomization): Created

202 (ResourceInterpreterCustomization): Accepted

update replace the specified ResourceInterpreterCustomization

HTTP Request

PUT /apis/config.karmada.io/v1alpha1/resourceinterpretercustomizations/{name}

Parameters

Response

200 (ResourceInterpreterCustomization): OK

201 (ResourceInterpreterCustomization): Created

update replace status of the specified ResourceInterpreterCustomization

HTTP Request

PUT /apis/config.karmada.io/v1alpha1/resourceinterpretercustomizations/{name}/status

Parameters

Response

200 (ResourceInterpreterCustomization): OK

201 (ResourceInterpreterCustomization): Created

patch partially update the specified ResourceInterpreterCustomization

HTTP Request

PATCH /apis/config.karmada.io/v1alpha1/resourceinterpretercustomizations/{name}

Parameters

  • name (in path): string, required

    name of the ResourceInterpreterCustomization

  • body: Patch, required

  • dryRun (in query): string

    dryRun

  • fieldManager (in query): string

    fieldManager

  • fieldValidation (in query): string

    fieldValidation

  • force (in query): boolean

    force

  • pretty (in query): string

    pretty

Response

200 (ResourceInterpreterCustomization): OK

201 (ResourceInterpreterCustomization): Created

patch partially update status of the specified ResourceInterpreterCustomization

HTTP Request

PATCH /apis/config.karmada.io/v1alpha1/resourceinterpretercustomizations/{name}/status

Parameters

  • name (in path): string, required

    name of the ResourceInterpreterCustomization

  • body: Patch, required

  • dryRun (in query): string

    dryRun

  • fieldManager (in query): string

    fieldManager

  • fieldValidation (in query): string

    fieldValidation

  • force (in query): boolean

    force

  • pretty (in query): string

    pretty

Response

200 (ResourceInterpreterCustomization): OK

201 (ResourceInterpreterCustomization): Created

delete delete a ResourceInterpreterCustomization

HTTP Request

DELETE /apis/config.karmada.io/v1alpha1/resourceinterpretercustomizations/{name}

Parameters

Response

200 (Status): OK

202 (Status): Accepted

deletecollection delete collection of ResourceInterpreterCustomization

HTTP Request

DELETE /apis/config.karmada.io/v1alpha1/resourceinterpretercustomizations

Parameters

Response

200 (Status): OK