tencent cloud

Service Registry and Governance

Register and discovery

PDF
Focus Mode
Font Size
Last updated: 2026-05-07 18:12:22

Scenarios

This document describes how to develop a Java application locally, access Polaris (North Star) via the polaris-sdk, and implement service registration and discovery.

Prerequisite

Before development, please ensure you have downloaded and installed Java and Maven.

Operation Steps

For your convenience in quick access, we have prepared a Demo application for you. Click to download.

Step 1: Introduce Polaris Dependencies

Step 1: Adding the polaris SDK Dependency

Modify the pom.xml in the application's root directory to add dependencyManagement for polaris-java:
<dependencyManagement>
<dependencies>
<dependency>
<groupId>com.tencent.polaris</groupId>
<artifactId>polaris-dependencies</artifactId>
<version>${version}</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>
Note:
For polaris-sdk version information, see: Version Information.

2. Introduce polaris starter

<dependencies>
<dependency>
<groupId>com.tencent.polaris</groupId>
<artifactId>polaris-all</artifactId>
</dependency>
</dependencies>

Step 2: Add Polaris Configuration File polaris.yml

1. Create a polaris.yml file in the project's main/resources directory to initialize the polaris-java SDK.
2. Configure the application name, polaris (North Star) server IP address, and other information in the polaris.yml file. For server IP address details, refer to: Engine Management > Client Access Address.
global:
serverConnectors:
- id: polaris
protocol: grpc
addresses:
# The IP address needs to be replaced with the client access IP address of the North Star engine you created.
- 127.0.0.1:8091
# Description: Configuration related to monitoring and log data reporting
statReporter:
# Description: Whether to Enable Reporting
enable: true
plugin:
prometheus:
type: push
# Description: Configure the pushgateway IP address, effective only when type == push
# The IP address needs to be replaced with the client access IP address of the North Star engine you created.
address: 127.0.0.1:9091
# Description: Set the execution interval for pushing metric data to pushgateway
# Range: [1s:...], Default value: 10s
pushInterval: 10s
For more polaris.yml configuration information, see default-config.yml.

Step 3: Application Development

1. Service Registration (Service Provider)

1.1 Initialize the DiscoveryAPI instance
import com.tencent.polaris.factory.api.DiscoveryAPIFactory;

public static void main(String[] args) throws Exception {
ProviderAPI providerAPI = DiscoveryAPIFactory.createProviderAPI();
}
1.2 Construct the registration request body, configure health check, metadata, and other information. For the complete content, see InstanceRegisterRequest.java.
public class InstanceRegisterRequest extends CommonProviderBaseEntity {
// ...
}
Note:
For authentication documentation, see: Access Control (Permission Center).
1.3 Send the registration request
After initializing the InstanceRegisterRequest struct, simply call the ProviderAPI.RegisterInstance method to complete instance registration. The RegisterInstance method automatically maintains heartbeat reporting for the instance internally.
InstanceRegisterResponse registerResp = providerAPI.registerInstance(registerRequest)

2. Service Discovery (Service Consumer)

2.1 Initialize the polaris SDK instance.
import com.tencent.polaris.factory.api.DiscoveryAPIFactory;


public static void main(String[] args) throws Exception {
ConsumerAPI consumerAPI = DiscoveryAPIFactory.createConsumerAPI();
}
2.2 Obtain instance information of the service provider
Polaris provides three methods to obtain target service instances: GetAllInstances, GetHealthyInstances, GetOneInstances, which obtain all instances, healthy instances, and a single instance respectively. Details are as follows:
(1)GetAllInstances
All instances under the target service are returned directly, including unhealthy, isolated, zero-weight, and circuit-broken instances, which will be included in the returned instance list.
GetAllInstancesRequest request = new GetAllInstancesRequest();
// Set the service namespace
request.setNamespace(String namespace);
// Set the service name
request.setService(String service);
// Set the timeout period
request.setTimeoutMs(long timeoutMs);

// Call ConsumerAPI to execute the request
consumerAPI.getAllInstance(request);
(2)GetHealthyInstances
Each time, obtain a batch of available service provider instances. This method by default filters out unhealthy, isolated, zero-weight, and circuit-broken instances.
GetInstancesRequest request = new GetInstancesRequest();
// Set the service namespace
request.setNamespace(String namespace);
// Set the service name
request.setService(String service);

// Optional, set caller service information, only for routing rule matching
SourceService serviceInfo = new SourceService();
// Set the caller service namespace
serviceInfo.setNamespace(String namespace);
// Set the caller service name
serviceInfo.setService(String service);
// Set the request Tag information for the caller
serviceInfo.setArguments(Set<RouteArgument> arguments);
request.setServiceInfo(serviceInfo);

// Set the timeout period
request.setTimeoutMs(long timeoutMs);

// Call ConsumerAPI to execute the request
consumerAPI.getInstances(request);
(3)GetOneInstances
Each time, only one available service provider instance is obtained. This method executes the routing and load balancing process in sequence. By default, this method filters out unhealthy, isolated, zero-weight, and circuit-broken instances.
Note:
Conditions for performing the routing process
Setting the GetOneInstanceRequest.ServiceInfo.Metadata property will trigger the custom routing process.
Setting the GetOneInstanceRequest.Metadata property will trigger the metadata routing process.
public class Criteria {
/**
* Specify the CLB policy
*/
private String lbPolicy;
/**
* key for consistent hashing
*/
private String hashKey;
}

GetOneInstanceRequest request = new GetOneInstanceRequest();
// Set the service namespace
request.setNamespace(String namespace);
// Set the service name
request.setService(String service);
// Optional. The metadata, only used for filtering by the dstMetadata routing plugin.
request.setMetadata(Map<String, String> metadata);
// Optional. Set the fallback mechanism for metadata routing.
// The currently supported fallback mechanisms for metadata routing are as follows:
// - Default: no failover: METADATAFAILOVERNONE("metadataFailoverNone")
// - Failover to return all nodes: METADATAFAILOVERALL("metadataFailoverAll")
// - Returning nodes without the metadata routing key: METADATAFAILOVERNOTKEY("metadataFailoverNoKey")
request.setMetadataFailoverType();
// Optional. Corresponds to the Method in the request Tag of custom routing rules
request.setMethod(String method);

// If you need to use Hash load balancing, it needs to be set
Criteria criteria = new Criteria();
request.setCriteria(criteria);

// Optional, set caller service information, only for routing rule matching
SourceService serviceInfo = new SourceService();
// Set the caller service namespace
serviceInfo.setNamespace(String namespace);
// Set the caller service name
serviceInfo.setService(String service);
// Set the request Tag information for the caller
serviceInfo.setArguments(Set<RouteArgument> arguments);
request.setServiceInfo(serviceInfo);

// Set the timeout period
request.setTimeoutMs(long timeoutMs);

// Call ConsumerAPI to execute the request
consumerAPI.getOneInstance(request);

Step 4: Application Deployment

For Demo application deployment, refer to: Polaris - Java Integration.


Help and Support

Was this page helpful?

Help us improve! Rate your documentation experience in 5 mins.

Feedback