How to Configure AcrossClusterRuleService for Cross-Cluster Resource Sharing in Apache Linkis

The AcrossClusterRuleService in Apache Linkis enables cross-cluster resource sharing by storing routing policies as JSON in the configuration database and exposing them via REST APIs and RPC methods that return target cluster and queue names to the job scheduler.

Apache Linkis provides the AcrossClusterRuleService as part of the linkis-configuration module to manage cross-cluster resource sharing and data access. This service allows administrators to define rules that route specific users to remote clusters while enforcing CPU, memory, and time-window constraints stored in the Linkis metadata database.

Architecture of the AcrossClusterRuleService

The service follows a three-layer architecture that separates data persistence, business logic, and API exposure.

Data Layer Persistence

At the data layer, the AcrossClusterRule entity maps to a MySQL table via MyBatis. The AcrossClusterRuleMapper handles CRUD operations for rule definitions, storing fields such as clusterName, crossQueue, time windows, and threshold configurations in the Linkis configuration database.

Service Layer Implementation

The AcrossClusterRuleService interface defines the contract for rule management, while AcrossClusterRuleServiceImpl provides the concrete implementation in linkis-public-enhancements/linkis-configuration/src/main/java/org/apache/linkis/configuration/service/impl/AcrossClusterRuleServiceImpl.java. This implementation uses PageHelper for pagination and GSON to convert the stored rules JSON into a map (see implementation lines 54–73). The critical RPC method getAcrossClusterRuleByUsername accepts an AcrossClusterRequest and returns an AcrossClusterResponse containing the target cluster name and cross-queue name for job routing.

REST API Layer

The AcrossClusterRuleRestfulApi class exposes the service via HTTP endpoints in linkis-public-enhancements/linkis-configuration/src/main/java/org/apache/linkis/configuration/restful/api/AcrossClusterRuleRestfulApi.java. The API validates admin rights, constructs the rule JSON using CommonUtils.ruleMap2String, and delegates to the service layer (see the add endpoint, lines 70–88).

Core Rule Structure and JSON Serialization

Each cross-cluster rule consists of several key fields serialized into a JSON string stored in the rules column.

Rule Fields

• clusterName: The remote cluster identifier (stored lower-cased)
• crossQueue: The target queue on the remote cluster
• priorityCluster: The preferred local cluster for fallback scenarios
• startTime / endTime: The active time window for the rule
• CPU and Memory thresholds: Absolute and percentage limits for both source and target clusters

JSON Conversion Utilities

The CommonUtils.ruleMap2String method in linkis-public-enhancements/linkis-configuration/src/main/java/org/apache/linkis/configuration/util/CommonUtils.java (lines 89–106) constructs the JSON payload. Two constants defined in AcrossClusterRuleKeys (lines 20–29) drive the parsing:

• KEY_QUEUE_RULE: The top-level map key for queue-related rules
• KEY_CROSS_QUEUE: The sub-key storing the cross-queue name

Configuring Rules via the REST API

Administrators must use the REST API to create and manage cross-cluster rules. All endpoints require admin privileges.

Adding a New Rule

Send a POST request to the /add endpoint with the rule parameters:

curl -X POST "http://<linkis-host>/api/rest_j/v1/configuration/acrossClusterRule/add" \
     -H "Content-Type: application/json" \
     -d '{
           "clusterName":"remote-cluster",
           "creator":"admin",
           "username":"alice",
           "isValid":"true",
           "startTime":"2024-01-01 00:00:00",
           "endTime":"2024-12-31 23:59:59",
           "crossQueue":"remote-queue",
           "priorityCluster":"local-cluster",
           "targetCPUThreshold":"80",
           "targetMemoryThreshold":"75",
           "originCPUPercentageThreshold":"50",
           "originMemoryPercentageThreshold":"50"
         }'

This maps to the insertAcrossClusterRule method in AcrossClusterRuleRestfulApi (lines 70–88), which validates the input and calls CommonUtils.ruleMap2String to build the JSON before persisting via the service layer.

Managing Existing Rules

• Update: PUT /configuration/acrossClusterRule/update (requires the rule id)
• Delete: DELETE /configuration/acrossClusterRule/delete?id=123
• Toggle Validity: PUT /configuration/acrossClusterRule/isValid with payload { "id": 123, "isValid": "false" }

Querying Rules

Retrieve paginated rules for a specific user:

curl "http://<linkis-host>/api/rest_j/v1/configuration/acrossClusterRule/list?username=alice&pageNow=1&pageSize=20"

This invokes queryAcrossClusterRuleList in the service implementation (lines 115–135), which returns the acrossClusterRuleList and total count.

Programmatic Rule Management

For custom integrations, inject the service and manipulate rules directly in Java.

Creating Rules Programmatically

@Autowired
private AcrossClusterRuleService ruleService;

// Build the rules JSON using the utility method
String rules = CommonUtils.ruleMap2String(
    "2024-01-01 00:00:00", "2024-12-31 23:59:59",
    "remote-queue", "local-cluster",
    "80", "75", "80", "75",
    "50", "50");

AcrossClusterRule rule = new AcrossClusterRule();
rule.setClusterName("remote-cluster");
rule.setCreator("admin");
rule.setUsername("alice");
rule.setCreateBy("admin");
rule.setUpdateBy("admin");
rule.setRules(rules);
rule.setIsValid("true");

ruleService.insertAcrossClusterRule(rule);

Batch Operations

Disable multiple rules by ID:

List<Long> ids = Arrays.asList(101L, 102L, 103L);
ruleService.validAcrossClusterRuleByBatch(ids, "false");

Runtime Rule Retrieval for Job Scheduling

When Linkis receives a job submission, the scheduler invokes AcrossClusterRuleService#getAcrossClusterRuleByUsername to determine routing. The method fetches the user's rule, parses the rules JSON using KEY_CROSS_QUEUE, and returns an AcrossClusterResponse containing the remote cluster name and queue (see implementation lines 54–73 in AcrossClusterRuleServiceImpl.java).

@Autowired
private AcrossClusterRuleService ruleService;

// RPC call invoked during job submission
AcrossClusterResponse resp = ruleService.getAcrossClusterRuleByUsername(
        new AcrossClusterRequest("alice"), null);
String remoteCluster = resp.getClusterName();  // e.g., "remote-cluster"
String remoteQueue = resp.getCrossQueue();     // e.g., "remote-queue"

Downstream components use these values to route the job to the specified cross-cluster resources while respecting the defined thresholds and time windows.

Summary

• AcrossClusterRuleService provides the central mechanism for cross-cluster resource sharing in Apache Linkis through a three-layer architecture (Data, Service, and API).
• Rules are stored as JSON in the MySQL database via the AcrossClusterRule entity and AcrossClusterRuleMapper, with serialization handled by CommonUtils.ruleMap2String.
• Administrators manage rules via REST endpoints (/add, /update, /delete, /isValid, /list) exposed by AcrossClusterRuleRestfulApi.
• The RPC method getAcrossClusterRuleByUsername enables the job scheduler to retrieve target cluster and queue information at runtime based on the requesting username.
• Configuration keys KEY_QUEUE_RULE and KEY_CROSS_QUEUE defined in AcrossClusterRuleKeys control the JSON structure used for rule parsing.

Frequently Asked Questions

What is the AcrossClusterRuleService in Linkis?

The AcrossClusterRuleService is a Spring-managed service in the linkis-configuration module that manages policies allowing users to submit jobs to remote clusters. It provides CRUD operations, batch updates, and an RPC interface for runtime cluster resolution based on stored JSON rules.

How does Linkis store cross-cluster routing rules?

Linkis persists rules in the configuration database via the AcrossClusterRule entity and MyBatis mapper. The rule details—including cluster names, queues, time windows, and resource thresholds—are serialized into a JSON string using CommonUtils.ruleMap2String and stored in the rules column.

Which REST API endpoints manage cross-cluster rules?

The AcrossClusterRuleRestfulApi exposes several admin-only endpoints: POST /add for creation, PUT /update for modification, DELETE /delete for removal, PUT /isValid for enabling/disabling, and GET /list for paginated queries. All endpoints validate administrative privileges before delegating to AcrossClusterRuleServiceImpl.

How does the scheduler know which cluster to route a job to?

During job submission, Linkis calls AcrossClusterRuleService#getAcrossClusterRuleByUsername, which queries the database for the user's active rule. The service parses the stored JSON using GSON and constants from AcrossClusterRuleKeys to extract the crossQueue and clusterName, returning them in an AcrossClusterResponse that directs the scheduler to the appropriate remote resources.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}