Conditional registration for graceful start (public preview) - Microservices Engine

When you release an application, using a fixed delay for initialization can reduce deployment efficiency or cause errors if the delay is not configured correctly. Conditional registration for graceful start triggers service registration only after the business logic confirms the service is ready. This approach provides precise control over service registration timing. It ensures the service receives traffic only after it is fully prepared, which prevents unnecessary deployment delays.

Background information

In scenarios involving asynchronous initialization or resource loading, a fixed delay is often used before microservice registration. This is one of the graceful start capabilities provided by Microservice Engine (MSE). This method prevents the application from serving requests before it is fully initialized, which can cause failures for the calling service. This method is simple to implement and effectively mitigates call exceptions caused by service unreadiness in most situations.

However, in some complex scenarios, fixed-delay registration may lack precision or adaptability. If a fixed delay does not meet your application's timing requirements, you can use the conditional registration mechanism described in the following sections.

This feature requires you to add logic to your business code to set a system property. Evaluate the cost of this code modification before you proceed. If you are new to the graceful start and shutdown features of MSE, use the fixed-delay registration solution first. It covers most typical application scenarios.

Note

This feature is in public preview and requires MSE agent version 4.6.0 or later. For more information about how to specify an agent version, see Specify an MSE agent version.

How it works

The MSE agent continuously polls a parameter specified in the startup parameters or environment variables. After the application completes its custom initialization logic, the code sets the value of this parameter to true. When the agent detects that this condition is met, it triggers microservice registration.

If you use this feature with a Kubernetes readiness probe, the application startup and publishing flow is as follows:

The pod starts → The application in the container begins business initialization → The business is ready and the condition is set in the code → The agent initiates microservice registration → Microservice registration is successful and the service starts to accept microservice traffic → The Kubernetes readiness probe passes → The pod status changes to Ready.

Procedure

Step 1: Enable conditional registration in startup parameters

In your application's startup parameters or environment variables, add the following configuration to declare the system property key for conditional registration.

Format: mse_lossless_register_condition_on_system_property_true="YOUR_CONDITION_KEY"

Configuration example:

# Use the custom system property key PRODUCT_PRELOAD_COMPLETED with a value of true as the registration condition.
mse_lossless_register_condition_on_system_property_true="PRODUCT_PRELOAD_COMPLETED"

Step 2: Modify the business code to set the readiness condition

After the application finishes all necessary initialization logic, set the system property key that you defined in the previous step to true in your code.

The following code shows a scenario where a product cache is loaded asynchronously. When the cache is loaded, the System.setProperty method is used to set the readiness condition, which triggers service registration.

@Component
public class HotProductInitComponent {
    public ScheduledExecutorService executor = Executors.newScheduledThreadPool(
            1,
            new NameThreadFactory("product-preload-pool"));

    @Value("${demo.product.init.delay.seconds:3}")
    public long initDelaySeconds;

    public void asyncLoadPoductDataIntoCache() {
        executor.schedule(() -> {
            // ...
            
            // ********** Start of new code **********
            System.setProperty("PRODUCT_PRELOAD_COMPLETED", "true");
            // ********** End of new code **********
            
        }, initDelaySeconds, TimeUnit.SECONDS);
    }
}

Considerations

You can use this feature with the readiness probe at the 55199/readiness endpoint.
After you enable conditional registration, you do not need to configure delayed registration for graceful start. After you configure the mse_lossless_register_condition_on_system_property_true parameter in the startup parameters or environment variables, the feature is enabled automatically. You do not need to enable the graceful start option.