Practical Guide to Using Ctrip's Apollo Distributed Configuration Center with Spring Boot

The article introduces Apollo, an open‑source configuration management center developed by Ctrip, explaining why traditional file‑based configuration is insufficient for modern microservices and how Apollo addresses these challenges.

Basic Concepts

Apollo manages configuration across four dimensions—application, environment, cluster, and namespace—allowing real‑time updates, gray releases, version control, and fine‑grained permission management.

Key Features

Simple deployment

Gray release support

Version management

Open API platform

Client configuration monitoring

Java and .Net native clients

Hot‑reload of configurations

Permission, audit, and approval workflows

Unified management of multi‑environment and multi‑cluster settings

Four‑Dimensional Model

Configuration keys are organized by application, environment (DEV, FAT, UAT, PRO), cluster (e.g., Beijing, Shanghai), and namespace (public or private configuration files).

Client Design and Update Mechanism

Apollo clients maintain a long‑polling HTTP connection to receive push notifications; they also periodically pull configurations as a fallback. The refresh interval defaults to 5 minutes and can be overridden with apollo.refreshInterval.

Overall Architecture

Config Service handles configuration reads and pushes, while Admin Service manages modifications via the Apollo Portal. Both services are stateless, register with Eureka, and are often co‑deployed with Meta Server for service discovery.

Availability Considerations

The system tolerates individual Config or Admin service failures without impact, and uses local file caching ( /opt/data/{appId}/config-cache or C:\opt\data\{appId}\config-cache) to survive network outages.

Creating a Spring Boot Demo Project

Add Maven dependencies:

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

Configure application.yml with Apollo settings such as apollo.meta, apollo.cluster, apollo.cacheDir, and enable bootstrap.

server:
  port: 8080
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

Implement a controller to read a configuration key:

@RestController
public class TestController {
    @Value("${test:默认值}")
    private String test;
    @GetMapping("/test")
    public String test() { return "test的值为:" + test; }
}

Provide a standard Spring Boot main class.

@SpringBootApplication
public class Application {
    public static void main(String[] args) { SpringApplication.run(Application.class, args); }
}

Run the application with JVM arguments, e.g., -Dapollo.configService=http://192.168.2.11:30002 -Denv=DEV, and verify the value via http://localhost:8080/test. Changing the value in Apollo and publishing updates the response instantly; rollbacks, service outages, and deletions are also demonstrated, showing fallback to cached or default values.

Exploring Clusters and Namespaces

By setting apollo.cluster to beijing or shanghai, the client retrieves cluster‑specific values. Similarly, switching apollo.bootstrap.namespaces to dev-1 or dev-2 fetches namespace‑specific configurations.

Kubernetes Deployment

Build a Docker image with a lightweight OpenJDK base, exposing JAVA_OPTS and APP_OPTS environment variables for JVM and application parameters.

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"]

Create a Kubernetes Deployment and Service (NodePort) that injects JAVA_OPTS (e.g., -Denv=DEV) and a comprehensive APP_OPTS string containing all Apollo parameters, including

--apollo.meta=http://service-apollo-config-server-dev.mydlqcloud:8080

. After applying the manifests, the service is reachable at http://<K8S_IP>:31081/test, returning the configuration value from Apollo.

The tutorial concludes with links to additional video courses, PDF resources, and community groups.