Netflix Archaius with Spring Cloud: Dynamic Config Management

I've been building microservices since the early Netflix stack days, and let me tell you: dynamic configuration management is one of those things that separates a resilient production system from a house of cards. You can't afford to restart your services every time you need to tweak a rate limit, toggle a feature, or adjust a database connection pool. That's where Netflix Archaius comes in.

Archaius is the configuration library behind Netflix's own microservices. It's battle-tested at massive scale, handling millions of configuration changes per day without a hiccup. When combined with Spring Cloud, you get a powerful dynamic configuration system that supports cascading property sources, real-time updates, and fine-grained control over your application's behavior.

But here's the hard truth: most teams misuse Archaius. They treat it like a static properties file reader, missing out on its dynamic capabilities. They don't configure polling intervals properly, ignore thread safety, or fail to handle configuration change events. I've seen production outages caused by stale configurations that should have been updated dynamically.

In this guide, I'll show you how to properly integrate Netflix Archaius with Spring Cloud, share war stories from real production systems, and point out the gotchas that the official documentation glosses over. By the end, you'll be able to build services that adapt to configuration changes in real time, without restarts.

Why Archaius? The Case for Dynamic Configuration

Let's face it: static configuration files are a relic. In a world of microservices, where you might have hundreds of instances running, restarting each one to change a single property is not just inefficient—it's dangerous. I've seen teams deploy a new version just to change a database connection pool size, only to introduce a regression that took down their entire stack.

Archaius solves this by providing a dynamic configuration framework that can poll multiple sources (files, URLs, databases, cloud stores) and update properties at runtime. It's built on top of Apache Commons Configuration but adds Netflix's production-hardened features like cascading property sources, callbacks, and metrics.

When you combine Archaius with Spring Cloud, you get the best of both worlds: Spring's familiar @ConfigurationProperties and @Value annotations, plus Archaius's dynamic polling and event-driven updates. But—and this is a big but—you need to use Archaius correctly. The default Spring Cloud integration uses Archaius as a property source, but it doesn't automatically make all @Value fields dynamic. You have to opt in.

Here's the rule of thumb: if a configuration value can change without a code deploy, it should be a DynamicProperty. Don't use static @Value for anything that might need to change in production. Trust me, you'll thank me later when you're toggling feature flags at 3 AM without a deployment.

import com.netflix.config.DynamicStringProperty;
import com.netflix.config.DynamicPropertyFactory;

public class DynamicConfigExample {
    private static final DynamicStringProperty myProp =
        DynamicPropertyFactory.getInstance().getStringProperty("my.dynamic.property", "default");

    public String getMyProp() {
        return myProp.get();
    }

    // Register a callback to react to changes
    public void registerCallback() {
        myProp.addCallback(() -> {
            System.out.println("Property changed to: " + myProp.get());
            // Trigger side effects like cache invalidation
        });
    }
}

Setting Up Archaius with Spring Cloud

Adding Archaius to your Spring Cloud project is straightforward—just add the dependency. But the devil is in the details. Here's the minimal setup you need.

First, add the Spring Cloud Netflix Archaius starter to your pom.xml:

<dependency> <groupId>org.springframework.cloud</groupId> <artifactId>spring-cloud-starter-netflix-archaius</artifactId> </dependency>

This pulls in Archaius and automatically configures it as a property source for Spring's Environment. Now you can use @Value or @ConfigurationProperties, and they will resolve from Archaius's dynamic configuration.

But here's the catch: Archaius initializes its configuration from the default configuration sources (like config.properties on the classpath) during startup. If you want to use a custom source—like a URL or a database—you need to configure that before Spring's context loads. I recommend using a Spring Factories or a custom ApplicationContextInitializer to set up your configuration sources early.

Another critical aspect is the polling interval. By default, Archaius polls file-based sources every 60 seconds. That's fine for most cases, but if you need faster updates, you can set archaius.configurationSource.defaultPollingInterval in your bootstrap.properties. I usually set it to 5 seconds for critical properties.

Finally, remember that Archaius's dynamic properties are not automatically injected into Spring beans. You have to explicitly use DynamicPropertyFactory or inject the Archaius Configuration object. But you can also use Spring's @RefreshScope to make beans refresh when properties change—though this only works if the property is accessed via Spring's Environment, not directly via Archaius.

import com.netflix.config.ConfigurationManager;
import com.netflix.config.DynamicConfiguration;
import com.netflix.config.FixedDelayPollingScheduler;
import com.netflix.config.sources.URLConfigurationSource;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class ArchaiusConfig {

    @Bean
    public DynamicConfiguration dynamicConfiguration() {
        // Poll a URL every 10 seconds
        URLConfigurationSource source = new URLConfigurationSource("http://config-server/myapp/config");
        FixedDelayPollingScheduler scheduler = new FixedDelayPollingScheduler(0, 10000, false);
        DynamicConfiguration config = new DynamicConfiguration(source, scheduler);
        ConfigurationManager.install(config);
        return config;
    }
}

Dynamic Properties in Practice: Callbacks and Listeners

The real power of Archaius lies in its callback mechanism. When a property changes, you can trigger arbitrary code—like resizing a thread pool, invalidating a cache, or re-establishing a connection. This is what makes your application truly adaptive.

To register a callback, use the addCallback method on any DynamicProperty. You can also use the @ArchaiusPropertyChangeListener annotation if you're using Spring, but I prefer explicit callbacks for clarity.

One pattern I've used in production is a configuration-driven circuit breaker. Instead of hardcoding thresholds, we used DynamicIntProperty for the failure count and timeout. When those values changed, a callback would reconfigure the circuit breaker without any downtime.

Another common use case is feature toggles. You can have a DynamicBooleanProperty that controls whether a new feature is enabled. When you flip the toggle, the callback can start routing traffic to the new code path.

But beware: callbacks run on the polling thread. If your callback does something slow (like a database call), it will block the polling and delay other property updates. Keep callbacks fast and asynchronous if needed.

Also, note that callbacks are not triggered for the initial value—only for changes. So if you need to initialize something based on the property, do that separately.

import com.netflix.config.DynamicIntProperty;
import com.netflix.config.DynamicPropertyFactory;

public class ConnectionPoolManager {
    private static final DynamicIntProperty maxConnections =
        DynamicPropertyFactory.getInstance().getIntProperty("db.maxConnections", 10);

    public ConnectionPoolManager() {
        // Initialize pool with current value
        resizePool(maxConnections.get());
        // Register callback for future changes
        maxConnections.addCallback(() -> {
            System.out.println("Max connections changed to: " + maxConnections.get());
            resizePool(maxConnections.get());
        });
    }

    private void resizePool(int size) {
        // Implementation to resize the connection pool
    }
}

Cascading Configuration Sources: Priority and Overrides

One of Archaius's killer features is its ability to cascade configuration from multiple sources with a well-defined priority order. This allows you to have a base configuration (e.g., from a JAR file), environment-specific overrides (e.g., from a local file), and dynamic overrides (e.g., from a database or cloud).

By default, Archaius uses the following order (highest priority first): 1. Properties set via System properties 2. Properties from the command line 3. Properties from the application's configuration file (config.properties) 4. Properties from default configuration files (default.properties)

But you can add custom sources with any priority. For example, you might have a source that reads from a database table, and you want it to override everything except system properties. You can set the priority when adding the source.

Here's the trick: Spring Cloud's property sources (like application.yml) are added as a separate source with a default priority. If you want your Archaius dynamic properties to override Spring's static ones, you need to ensure Archaius sources have higher priority. This is controlled by the order in which they are added.

In practice, I always add my dynamic sources last (so they have the highest priority) after Spring's property sources have been loaded. This ensures that runtime overrides take precedence.

Another gotcha: Archaius caches the resolved value of a property. If you have multiple sources with the same key, the first one that defines it wins (based on priority). Changing the value in a lower-priority source will not override a higher-priority source until the higher-priority source is removed or updated.

import com.netflix.config.*;

public class CascadingSourcesExample {
    public static void setup() {
        // Create a base source from classpath
        URLConfigurationSource baseSource = new URLConfigurationSource("default.properties");
        DynamicConfiguration baseConfig = new DynamicConfiguration(baseSource, new FixedDelayPollingScheduler());
        
        // Create an override source from a database (example)
        // Assume DatabaseConfigurationSource is a custom implementation
        DatabaseConfigurationSource dbSource = new DatabaseConfigurationSource();
        DynamicConfiguration dbConfig = new DynamicConfiguration(dbSource, new FixedDelayPollingScheduler(0, 5000, false));
        
        // Create a concurrent composite configuration with priority
        ConcurrentCompositeConfiguration finalConfig = new ConcurrentCompositeConfiguration();
        finalConfig.addConfiguration(dbConfig, "dbOverride");
        finalConfig.addConfiguration(baseConfig, "baseConfig");
        
        // Install as the system configuration
        ConfigurationManager.install(finalConfig);
    }
}

What the Official Docs Won't Tell You

After years of using Archaius in production, here are the gotchas that the official documentation glosses over.

1. Archaius and Spring Cloud Config Server interaction: When you use both, Archaius can conflict with Spring Cloud Config's property sources. The typical symptom is that changes made on the Config Server are not reflected in your application. The fix is to ensure that Archaius's polling is configured to use the Config Server's endpoint as a source, and that the polling interval is set appropriately. Also, disable Spring Cloud Config's automatic refresh if you're relying on Archaius for dynamic updates.
2. Thread safety of DynamicProperty: While DynamicProperty itself is thread-safe, the values it returns are snapshots. If you call get() multiple times, you may get different values if the property changed between calls. This can lead to subtle bugs if you're not careful. For example, if you read a property, then use it in a condition, the value might change mid-execution. I recommend reading the property once and storing it in a local variable if you need consistency within a block.
3. DynamicProperty vs @Value in Spring: If you annotate a field with @Value and the property is dynamic, Spring will inject the value at startup, but it won't update automatically. To get updates, you need to use @RefreshScope on the bean. However, @RefreshScope destroys and recreates the bean, which can be expensive. For high-frequency changes, use DynamicProperty directly.
4. Polling interval and performance: Setting a very low polling interval (e.g., 1 second) can cause high CPU usage if you have many properties. Archaius polls all sources on each cycle, so if you have multiple sources, each poll is a separate operation. Use a reasonable interval (5-10 seconds) and consider push-based sources like ZooKeeper for sub-second updates.
5. ConfigurationManager.install() is global: If you call ConfigurationManager.install() in multiple places, the last call wins. This can cause issues in modular applications where different modules try to install their own configurations. Use ConcurrentCompositeConfiguration to merge sources instead.

import com.netflix.config.DynamicIntProperty;

public class ThreadSafetyExample {
    private static final DynamicIntProperty timeout =
        new DynamicIntProperty("timeout.ms", 1000);

    public void process() {
        // Safe: read once and use local copy
        int currentTimeout = timeout.get();
        if (currentTimeout > 500) {
            // Use currentTimeout, not timeout.get() again
            doSomething(currentTimeout);
        }
    }

    private void doSomething(int timeout) {
        // Implementation
    }
}

Integration with Spring Cloud Config Server

Many teams use Spring Cloud Config Server as their central configuration store. Can you use Archaius with it? Yes, but it's not plug-and-play. The official Spring Cloud integration already makes Config Server properties available via Spring's Environment, so you might wonder why you need Archaius. The answer: Archaius gives you dynamic polling and callbacks that are more robust than Spring's @RefreshScope.

To integrate, you need to configure Archaius to poll the Config Server's endpoint. You can do this by setting up a URLConfigurationSource that points to the Config Server's REST API. But there's a catch: the Config Server returns properties in a JSON format that Archaius doesn't understand natively. You'll need to write a custom source that parses the JSON response.

Alternatively, you can use Spring Cloud Bus to broadcast configuration changes, and have Archaius listen for those events. This is more complex but avoids polling.

My recommendation: if you're already using Spring Cloud Config, don't add Archaius on top unless you have a specific need for its cascading sources or callback mechanism. The two can coexist, but you'll have to manage the overlap carefully.

One pattern I've used is to have Archaius as the primary configuration layer, with Config Server as one of its sources. This gives you the best of both worlds: centralized management via Config Server, and dynamic updates via Archaius.

import com.netflix.config.PolledConfigurationSource;
import com.netflix.config.PollResult;
import org.springframework.web.client.RestTemplate;

import java.util.HashMap;
import java.util.Map;

public class ConfigServerSource implements PolledConfigurationSource {
    private final RestTemplate restTemplate;
    private final String url;

    public ConfigServerSource(String url) {
        this.restTemplate = new RestTemplate();
        this.url = url;
    }

    @Override
    public PollResult poll(boolean initial, Object checkPoint) throws Exception {
        Map<String, Object> props = new HashMap<>();
        // Assume the response is a map of property key-value pairs
        Map<String, String> response = restTemplate.getForObject(url, Map.class);
        if (response != null) {
            props.putAll(response);
        }
        return PollResult.createFull(props);
    }
}