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

> Learn how to configure Apache Linkis AcrossClusterRuleService for seamless cross-cluster resource sharing and data access. Simplify your Linkis deployments.

- Repository: [The Apache Software Foundation/linkis](https://github.com/apache/linkis)
- Tags: how-to-guide
- Published: 2026-02-25

---

**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`](https://github.com/apache/linkis/blob/main/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`](https://github.com/apache/linkis/blob/main/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`](https://github.com/apache/linkis/blob/main/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:

```bash
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:

```bash
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

```java
@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:

```java
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`](https://github.com/apache/linkis/blob/main/AcrossClusterRuleServiceImpl.java)).

```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.