Jump to content

Connect Leeroopedia MCP: Equip your AI agents to search best practices, build plans, verify code, diagnose failures, and look up hyperparameter defaults.

Implementation:Apache Paimon DLFECSTokenLoader

From Leeroopedia


Knowledge Sources
Domains Authentication, Alibaba Cloud, ECS, Token Management
Last Updated 2026-02-08 00:00 GMT

Overview

DLFECSTokenLoader loads DLF authentication tokens from Alibaba Cloud ECS metadata service for instance role-based authentication.

Description

DLFECSTokenLoader is a specialized token loader implementation that retrieves authentication credentials from the Alibaba Cloud Elastic Compute Service (ECS) metadata service. This enables applications running on ECS instances to automatically authenticate with DLF using instance RAM roles, without requiring hardcoded credentials or configuration files.

The loader operates by making HTTP requests to the ECS metadata service endpoint, which is a special link-local address (100.100.100.200) available only from within ECS instances. The metadata service provides temporary security credentials associated with the instance's RAM role, including an access key ID, access key secret, security token, and expiration time.

The token loading process involves two steps: first, retrieving the role name from the metadata service if not explicitly configured (by querying the base metadata URL), and second, fetching the actual token by appending the role name to the base URL. The retrieved token is automatically parsed as JSON into a DLFToken object containing all necessary credential components.

The implementation includes debugging support through optional logging when detailed logging is enabled, which can be helpful for troubleshooting metadata service connectivity or role configuration issues. Error handling provides clear messages when role or token retrieval fails, making it easier to diagnose authentication problems.

Usage

Use DLFECSTokenLoader when running Apache Paimon applications on Alibaba Cloud ECS instances that have RAM roles attached. This provides secure, automatic credential management without requiring manual credential distribution or rotation, as the credentials are managed by Alibaba Cloud's IAM system.

Code Reference

Source Location

Signature

public class DLFECSTokenLoader implements DLFTokenLoader {
    private final String ecsMetadataURL;
    private String roleName;

    public DLFECSTokenLoader(String ecsMetaDataURL, @Nullable String roleName);

    @Override
    public DLFToken loadToken();

    @Override
    public String description();
}

Import

import org.apache.paimon.rest.auth.DLFECSTokenLoader;

I/O Contract

Inputs

Name Type Required Description
ecsMetaDataURL String Yes ECS metadata service base URL
roleName String No ECS RAM role name (auto-detected if not provided)

Outputs

Name Type Description
loadToken() DLFToken Returns loaded token with temporary credentials
description() String Returns metadata URL for logging/debugging

Usage Examples

import org.apache.paimon.rest.auth.DLFECSTokenLoader;
import org.apache.paimon.rest.auth.DLFToken;

// Example 1: Auto-detect role name (recommended)
DLFECSTokenLoader loader = new DLFECSTokenLoader(
    "http://100.100.100.200/latest/meta-data/Ram/security-credentials/",
    null  // Role name will be auto-detected
);

DLFToken token = loader.loadToken();
System.out.println("Access Key: " + token.getAccessKeyId());
System.out.println("Expires at: " + token.getExpirationAtMills());

// Example 2: Explicit role name
DLFECSTokenLoader explicitLoader = new DLFECSTokenLoader(
    "http://100.100.100.200/latest/meta-data/Ram/security-credentials/",
    "my-app-role"
);

DLFToken explicitToken = explicitLoader.loadToken();

// Example 3: Use with DLFAuthProvider
import org.apache.paimon.rest.auth.DLFAuthProvider;

DLFECSTokenLoader tokenLoader = new DLFECSTokenLoader(
    "http://100.100.100.200/latest/meta-data/Ram/security-credentials/",
    null
);

DLFAuthProvider authProvider = DLFAuthProvider.fromTokenLoader(
    tokenLoader,
    "https://dlf.cn-hangzhou.aliyuncs.com",
    "cn-hangzhou",
    "default"
);

// Token is automatically refreshed when needed

// Example 4: Custom metadata URL (for testing or custom endpoints)
DLFECSTokenLoader customLoader = new DLFECSTokenLoader(
    "http://custom-metadata-service:8080/security-credentials/",
    "test-role"
);

// Example 5: Check token expiration
DLFToken token = loader.loadToken();
long expiresIn = token.getExpirationAtMills() - System.currentTimeMillis();
long expiresInMinutes = expiresIn / (60 * 1000);

System.out.println("Token expires in " + expiresInMinutes + " minutes");

if (expiresInMinutes < 5) {
    System.out.println("Token expiring soon, will be refreshed");
}

// Example 6: Handle token loading errors
try {
    DLFECSTokenLoader loader = new DLFECSTokenLoader(
        "http://100.100.100.200/latest/meta-data/Ram/security-credentials/",
        null
    );
    DLFToken token = loader.loadToken();
    System.out.println("Token loaded successfully");
} catch (RuntimeException e) {
    System.err.println("Failed to load token: " + e.getMessage());
    // Possible causes:
    // - Not running on ECS instance
    // - No RAM role attached to instance
    // - Network connectivity issues
    // - Metadata service unavailable
}

// Example 7: Multiple loaders for different roles
DLFECSTokenLoader readOnlyLoader = new DLFECSTokenLoader(
    "http://100.100.100.200/latest/meta-data/Ram/security-credentials/",
    "readonly-role"
);

DLFECSTokenLoader readWriteLoader = new DLFECSTokenLoader(
    "http://100.100.100.200/latest/meta-data/Ram/security-credentials/",
    "readwrite-role"
);

// Use different tokens for different operations
DLFToken readToken = readOnlyLoader.loadToken();
DLFToken writeToken = readWriteLoader.loadToken();

// Example 8: Token refresh pattern
public class TokenManager {
    private final DLFECSTokenLoader loader;
    private DLFToken currentToken;
    private static final long REFRESH_MARGIN_MS = 5 * 60 * 1000; // 5 minutes

    public TokenManager() {
        this.loader = new DLFECSTokenLoader(
            "http://100.100.100.200/latest/meta-data/Ram/security-credentials/",
            null
        );
    }

    public synchronized DLFToken getToken() {
        if (shouldRefresh()) {
            currentToken = loader.loadToken();
            System.out.println("Token refreshed");
        }
        return currentToken;
    }

    private boolean shouldRefresh() {
        if (currentToken == null) {
            return true;
        }
        Long expiresAt = currentToken.getExpirationAtMills();
        if (expiresAt == null) {
            return false;
        }
        return System.currentTimeMillis() + REFRESH_MARGIN_MS >= expiresAt;
    }
}

// Example 9: Loader description for logging
String description = loader.description();
System.out.println("Using token loader: " + description);
// Output: http://100.100.100.200/latest/meta-data/Ram/security-credentials/

// Example 10: Full configuration example
import org.apache.paimon.rest.RESTCatalogOptions;
import org.apache.paimon.options.Options;

Options options = new Options();
options.set(RESTCatalogOptions.URI, "https://dlf.cn-hangzhou.aliyuncs.com");
options.set(RESTCatalogOptions.TOKEN_PROVIDER, "dlf");
options.set(RESTCatalogOptions.DLF_TOKEN_LOADER, "ecs");
options.set(RESTCatalogOptions.DLF_TOKEN_ECS_ROLE_NAME, "my-app-role");
// DLF_TOKEN_ECS_METADATA_URL has a default value and usually doesn't need to be set

// The factory will create DLFECSTokenLoader automatically

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.
Principle
Implementation
Heuristic
Environment
Retrieved from "https://leeroopedia.com/index.php?title=Implementation:Apache_Paimon_DLFECSTokenLoader&oldid=11501"