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

In this tutorial, the author introduces Apollo, an open‑source distributed configuration center developed by Ctrip, and explains why it is needed when traditional file‑based or database configuration methods no longer meet the demands of modern microservices.

1. Basic Concepts

Apollo provides centralized management of configuration across environments, clusters, and namespaces, supporting real‑time updates, gray releases, version control, permission management, and client monitoring.

1.1 Background

As applications become more complex, the number of configuration items (feature switches, parameters, server addresses, etc.) grows, requiring a solution that can handle real‑time updates, environment‑specific settings, and robust audit mechanisms.

1.2 Overview

Apollo is a Ctrip‑maintained open‑source configuration management center that centralizes configuration for different environments and clusters, pushes updates instantly, and enforces permission and workflow controls.

1.3 Features

Simple deployment

Gray release support

Version management

Open API platform

Client configuration monitoring

Native Java and .Net clients

Hot‑update of configurations

Permission management, release audit, operation audit

Unified management of configurations across environments and clusters

1.4 Core Model

The basic workflow is: (1) a user modifies and publishes a configuration in the center; (2) the center notifies Apollo clients of the change; (3) clients pull the latest configuration, update locally, and notify the application.

1.5 Four Dimensions

Apollo manages key‑value configurations across four dimensions:

application (the app identifier)

environment (DEV, FAT, UAT, PRO, etc.)

cluster (e.g., data‑center grouping)

namespace (logical grouping similar to separate config files)

Each dimension can be set via code, for example:

app.id

env

1.6 Local Cache

Clients cache configuration files locally (e.g., /opt/data/{appId}/config-cache on Linux or C:\opt\data\{appId}\config-cache on Windows) to ensure operation when the server is unavailable.

1.7 Client Design

Clients maintain a long‑polling HTTP connection to receive push notifications, fall back to periodic polling (default every 5 minutes, configurable via apollo.refreshInterval ), and store configurations in memory and on disk.

1.8 Overall Architecture

The system consists of Config Service (provides read and push), Admin Service (provides modify and publish), Eureka for service discovery, a Meta Server that abstracts Eureka, and load‑balanced client access to Config Service.

1.9 Availability Considerations

Both Config Service and Admin Service are stateless; if a single instance goes down, clients automatically reconnect to other instances without impact.

2. Creating a Project and Configuration in Apollo

Log in to the Apollo portal (default credentials: user apollo , password admin ), create a new project, set app.id to apollo-test and app.name to apollo-demo , then add a configuration key test with value 123456 and publish it.

3. Building a Spring Boot Client

3.1 Maven Dependency

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

3.2 Application.yml Settings

server:
  port: 8080
spring:
  application:
    name: apollo-demo
app:
  id: apollo-test
apollo:
  cacheDir: /opt/data/
  cluster: default
  meta: http://192.168.2.11:30002
  autoUpdateInjectedSpringProperties: true
  bootstrap:
    enabled: true
    namespaces: application
    eagerLoad:
      enabled: false

3.3 Test Controller

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

3.4 Application Entry

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

3.5 JVM Arguments

When running in Kubernetes, add -Denv=DEV and -Dapollo.configService=http://192.168.2.11:30002 either via IDE run configuration or java -jar command.

4. Testing the Client

Start the application and access http://localhost:8080/test – the response should be test的值为:123456 . Modifying the value in Apollo to 666666 and republishing updates the response instantly. Rolling back, deleting the key, or breaking the connection demonstrates cache fallback behavior.

5. Exploring Clusters and Namespaces

Configure different environments (DEV, PRO), clusters (beijing, shanghai), and private namespaces (dev-1, dev-2) in Apollo, then adjust apollo.cluster or apollo.bootstrap.namespaces in application.yml to see the client pick the corresponding values.

6. Deploying to Kubernetes

6.1 Docker Image

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

6.2 Kubernetes Manifest

apiVersion: v1
kind: Service
metadata:
  name: springboot-apollo
spec:
  type: NodePort
  ports:
    - name: server
      nodePort: 31080
      port: 8080
      targetPort: 8080
    - name: management
      nodePort: 31081
      port: 8081
      targetPort: 8081
  selector:
    app: springboot-apollo
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: springboot-apollo
  labels:
    app: springboot-apollo
spec:
  replicas: 1
  selector:
    matchLabels:
      app: springboot-apollo
  template:
    metadata:
      name: springboot-apollo
      labels:
        app: springboot-apollo
    spec:
      restartPolicy: Always
      containers:
        - name: springboot-apollo
          image: mydlqclub/springboot-apollo:0.0.1
          imagePullPolicy: Always
          ports:
            - containerPort: 8080
              name: server
          env:
            - name: JAVA_OPTS
              value: "-Denv=DEV"
            - name: APP_OPTS
              value: "\
                --app.id=apollo-demo\
                --apollo.bootstrap.enabled=true\
                --apollo.bootstrap.eagerLoad.enabled=false\
                --apollo.cacheDir=/opt/data/\
                --apollo.cluster=default\
                --apollo.bootstrap.namespaces=application\
                --apollo.autoUpdateInjectedSpringProperties=true\
                --apollo.meta=http://service-apollo-config-server-dev.mydlqcloud:8080\
                "
          resources:
            limits:
              memory: 1000Mi
              cpu: 1000m
            requests:
              memory: 500Mi
              cpu: 500m

Apply the manifest with kubectl apply -f springboot-apollo.yaml -n mydlqcloud and access the service via the NodePort (e.g., http:// :31080/test ) to verify that Apollo configuration is correctly consumed inside Kubernetes.

The article concludes that Apollo provides a reliable, real‑time configuration solution for Spring Boot microservices, both on bare‑metal and in Kubernetes environments.