Comprehensive Guide to Using Ctrip’s Apollo Distributed Configuration Center with Spring Boot

Apollo is an open‑source configuration management center developed by Ctrip that centralizes application configuration across environments, clusters, and namespaces, offering real‑time updates, version control, and fine‑grained permissions.

Basic concepts include the four dimensions of configuration: application (identified by app.id ), environment (DEV, FAT, UAT, PRO), cluster (e.g., beijing, shanghai), and namespace (public or private groups of configuration files).

The basic model follows three steps: modify and publish configuration in the portal, the config service notifies Apollo clients, and clients pull the latest values and apply them locally.

Key features include simple deployment, gray releases, version management, open API, client monitoring, Java/.Net native clients, hot‑publish, permission management, and multi‑environment support.

Configuration is stored in files such as {appId}+{cluster}+{namespace}.properties and cached locally under /opt/data/{appId}/config-cache (Linux/macOS) or C:\opt\data\{appId}\config-cache (Windows) to ensure resilience when the server is unavailable.

Creating an Apollo Project and Configuring It

Log in to the Apollo portal (default credentials: user apollo , password admin ) and create a project with an app.id (e.g., apollo-test ) and an application name (e.g., apollo-demo ). Add a configuration key test with value 123456 and publish it.

Spring Boot Client Setup

Add the Apollo client dependency to pom.xml :

<dependency>
  <groupId>com.ctrip.framework.apollo</groupId>
  <artifactId>apollo-client</artifactId>
  <version>1.4.0</version>
</dependency>

Configure application.yml with Apollo settings, for example:

app:
  id: apollo-test
apollo:
  meta: http://192.168.2.11:30002
  cluster: default
  cacheDir: /opt/data/
  bootstrap:
    enabled: true
    namespaces: application
    eagerLoad:
      enabled: false

Create a TestController that injects the test property using @Value("${test:default}") and returns it via /test . The main class simply runs the Spring Boot application.

Runtime Tests

Start the application and request http://localhost:8080/test – the response shows the value from Apollo ( 123456 ). Modify the value in the portal, publish, and the client reflects the change instantly. Rolling back, deleting the key, or breaking the Apollo connection demonstrates fallback to cached values or default values, respectively.

Exploring Clusters and Namespaces

Define multiple clusters (e.g., beijing , shanghai ) and assign different values to the same key. Set apollo.cluster in application.yml to switch clusters and observe the corresponding values.

Similarly, create private namespaces (e.g., dev-1 , dev-2 ) and configure apollo.bootstrap.namespaces to select which namespace to read from.

Kubernetes Deployment

Build a Docker image using a Dockerfile that copies the built JAR and defines two environment variables: JAVA_OPTS (e.g., -Denv=DEV ) and APP_OPTS (Apollo client arguments). Example Dockerfile snippet:

FROM openjdk:8u222-jre-slim
VOLUME /tmp
ADD target/*.jar app.jar
ENV JAVA_OPTS "-XX:MaxRAMPercentage=80.0 -Duser.timezone=Asia/Shanghai"
ENV APP_OPTS ""
ENTRYPOINT ["sh","-c","java $JAVA_OPTS -jar /app.jar $APP_OPTS"]

Deploy to Kubernetes with a Service (NodePort) and a Deployment that sets JAVA_OPTS and APP_OPTS accordingly, pointing apollo.meta to the internal service name (e.g., http://service-apollo-config-server-dev.mydlqcloud:8080 ).

After applying the manifest, access the service via the NodePort (e.g., http://192.168.2.11:31081/test ) and verify that the configuration value is retrieved from Apollo.