Comprehensive Guide to Using Apollo Configuration Center with Spring Boot

1. Basic Concepts

Apollo is an open‑source configuration management center developed by Ctrip, designed to centralize configuration for applications across environments and clusters, supporting real‑time updates, gray releases, and robust permission and audit mechanisms.

1.1 Background

As applications become more complex, traditional configuration files or databases can no longer meet the demand for dynamic, environment‑specific, and cluster‑specific settings, prompting the creation of Apollo.

1.2 Overview

Apollo enables centralized management of configuration for different environments and clusters, pushing changes to clients in real time and providing a complete permission and workflow system.

1.3 Features

Simple deployment

Gray release support

Version management

Open API platform

Client configuration monitoring

Native Java and .NET clients

Hot‑update of configuration

Permission management, release audit, operation audit

Unified management of different environments and clusters

1.4 Basic Model

The basic workflow is:

User modifies and publishes configuration in the portal.

Apollo notifies clients of the update.

Clients pull the latest configuration, update local cache, and notify the application.

1.5 Four Dimensions of Apollo

Apollo manages configuration in four dimensions:

application : unique identifier of the application (set via app.id ).

environment : e.g., DEV, FAT, UAT, PRO.

cluster : logical grouping of instances, such as data‑center based clusters.

namespace : logical grouping of configuration files (similar to separate property files).

1.6 Local Cache

Apollo client caches configuration locally (e.g., /opt/data/{appId}/config-cache on Linux/Mac or C:\opt\data\{appId}\config-cache on Windows) to ensure availability when the server is unreachable.

{appId}+{cluster}+{namespace}.properties

1.7 Client Design

The client maintains a long‑lived HTTP connection (long‑polling) to receive push notifications, periodically pulls configuration, and falls back to cached files if the server is unavailable.

1.8 Overall Architecture

Key components:

Config Service – provides configuration read and push services.

Admin Service – handles configuration modification and publishing via the portal.

Meta Server – abstracts Eureka service discovery for both services.

Clients – access Config Service directly using the discovered address.

1.9 Availability Considerations

Scenario

Impact

Degradation

Reason

Single Config Service down

No impact

Stateless service, client reconnects to another instance.

All Config Services down

Clients cannot read new config; portal unaffected

Clients use local cache on restart

Single Admin Service down

No impact

Stateless service, portal reconnects.

All Admin Services down

Clients unaffected; portal cannot update config

Single Portal down

No impact

SLB redirects to other portal instances.

All Portals down

Clients unaffected; portal cannot update config

Data center down

No impact

Multi‑data‑center deployment with automatic SLB failover.

2. Creating a Project and Configuration in Apollo

2.1 Login to Apollo

Access the portal (e.g., via NodePort) with username apollo and password admin .

2.2 Modify Department Data

Since the portal only provides default test departments, modify the organizations key in the ApolloPortalDB database to add custom departments.

2.3 Create a Project

After updating the department data, create a new project with appId=apollo-test and appName=apollo-demo .

2.4 Add a Configuration Parameter

Create a key test with value 123456 and a remark, then publish it.

3. Building a Spring Boot Client Project

3.1 Add Apollo Dependency (Maven)

<project xmlns="http://maven.apache.org/POM/4.0.0" ...>
  <modelVersion>4.0.0</modelVersion>
  <parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>2.1.8.RELEASE</version>
  </parent>
  <groupId>club.mydlq</groupId>
  <artifactId>apollo-demo</artifactId>
  <version>0.0.1</version>
  <properties>
    <java.version>1.8</java.version>
  </properties>
  <dependencies>
    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    <dependency>
      <groupId>com.ctrip.framework.apollo</groupId>
      <artifactId>apollo-client</artifactId>
      <version>1.4.0</version>
    </dependency>
  </dependencies>
  <build>
    <plugins>
      <plugin>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-maven-plugin</artifactId>
      </plugin>
    </plugins>
  </build>
</project>

3.2 Add Configuration Parameters (application.yml)

# Application configuration
server:
  port: 8080
spring:
  application:
    name: apollo-demo

# Apollo configuration
app:
  id: apollo-test
apollo:
  cacheDir: /opt/data/
  cluster: default
  meta: http://192.168.2.11:30002   # DEV environment address
  autoUpdateInjectedSpringProperties: true
  bootstrap:
    enabled: true
    namespaces: application
    eagerLoad:
      enabled: false

3.3 Create Test Controller

@RestController
public class TestController {

    @Value("${test:默认值}")
    private String test;

    @GetMapping("/test")
    public String test() {
        return "test的值为:" + test;
    }
}

3.4 Create Application Entry Point

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

3.5 JVM Startup Parameters

Set the environment and config service address:

-Dapollo.configService=http://192.168.2.11:30002 -Denv=DEV

Or run via Java command:

java -Dapollo.configService=http://192.168.2.11:30002 -Denv=DEV -jar apollo-demo.jar

4. Running Tests

4.1 Verify Initial Value

After starting the application, http://localhost:8080/test returns test的值为:123456 , confirming the value from Apollo.

4.2 Update Value in Apollo

Change test to 666666 in the portal, publish, and the endpoint now returns the new value without restarting.

4.3 Rollback Test

Rollback the configuration; the endpoint reverts to the previous value 123456 .

4.4 Simulate Config Center Unavailability

Change the JVM parameter to an incorrect address; the client still returns the cached value 123456 . Deleting the local cache forces the fallback to the default value.

4.5 Delete Parameter

After deleting the test key in Apollo and publishing, the endpoint falls back to the default value defined in the code.

5. Exploring Cluster, Namespace, and Environment

5.1 Different Environments

Create a PRO environment configuration with the same key but different value, then switch the client by setting env=PRO and updating apollo.meta to the PRO address.

5.2 Different Clusters

Create beijing and shanghai clusters, each with its own test value. Set apollo.cluster=beijing or shanghai in application.yml to retrieve the corresponding value.

5.3 Different Namespaces

Create private namespaces dev-1 and dev-2 with distinct values. Configure apollo.bootstrap.namespaces=dev-1 (or dev-2 ) to fetch the appropriate value.

6. Deploying to Kubernetes

6.1 Build Docker Image

Compile the project with Maven and create a Dockerfile:

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

Build the image:

docker build -t mydlqclub/springboot-apollo:0.0.1 .

6.2 Kubernetes Deployment

Create springboot-apollo.yaml with Service and Deployment definitions. Important environment variables:

JAVA_OPTS="-Denv=DEV"

APP_OPTS="--app.id=apollo-demo --apollo.bootstrap.enabled=true ... --apollo.meta=http://service-apollo-config-server-dev.mydlqcloud:8080"

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:
      labels:
        app: springboot-apollo
    spec:
      containers:
        - name: springboot-apollo
          image: mydlqclub/springboot-apollo:0.0.1
          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

Deploy with:

kubectl apply -f springboot-apollo.yaml -n mydlqcloud

6.3 Test Deployed Service

Access the service via NodePort, e.g., http://192.168.2.11:31081/test , which should return the value 123456 from Apollo.

This concludes the end‑to‑end demonstration of using Apollo as a configuration center for Spring Boot applications, both locally and in a Kubernetes environment.