Comprehensive Guide to Using Apollo Configuration Center with Spring Boot

1. Basic Concepts of Apollo

Apollo is an open‑source distributed configuration center developed by Ctrip, offering centralized management of application configurations across environments, clusters, and namespaces, with real‑time push, version control, and permission management.

1.1 Background

As applications become more complex, traditional configuration files or databases can no longer meet the needs for dynamic, granular, and auditable configuration management, prompting the creation of Apollo.

1.2 Overview

Apollo enables centralized management of configuration for different environments and clusters, pushing updates to clients in real time.

1.3 Features

Simple deployment

Gray release support

Version management

Open API platform

Client configuration monitoring

Java and .Net native clients

Hot‑reload of configuration changes

Permission management, release audit, operation audit

Unified management of multi‑environment, multi‑cluster configurations

1.4 Core Model

The basic workflow is: a user modifies and publishes a configuration in the console → the configuration center notifies Apollo clients of the update → clients pull the latest configuration, update local cache, and notify the application.

1.5 Four Configuration Dimensions

Apollo manages configurations across four dimensions: application (the app identifier), environment (e.g., DEV, FAT, UAT, PRO), cluster (group of instances, such as data‑center based clusters), and namespace (logical grouping similar to separate configuration files).

Environment

Supported environments include FAT (Feature Acceptance Test), UAT (User Acceptance Test), DEV (Development), and PRO (Production). The environment is selected by setting the env variable.

Cluster

Clusters allow grouping instances, for example by data‑center (Beijing vs. Shanghai), each with its own configuration values.

Namespace

Namespaces can be public (shared across applications) or private (accessible only by the owning application). They also have three types: private, public, and inherited (linked to a public namespace).

1.6 Local Cache

Apollo clients cache configuration files locally (default under /opt/data/{appId}/config-cache on Linux/macOS or C:\opt\data\{appId}\config-cache on Windows) to ensure service continuity when the server is unavailable.

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

1.7 Client Design

The client maintains a long‑polling HTTP connection to receive push notifications, falls back to periodic polling (default every 5 minutes, configurable via apollo.refreshInterval ), stores configurations in memory, and caches them on disk.

1.8 Overall Architecture

Key components include Config Service (configuration read/push), Admin Service (configuration edit/publish), Eureka for service discovery, and a Meta Server that abstracts Eureka. Clients retrieve service lists from the Meta Server and perform load‑balanced calls.

1.9 Availability Considerations

Apollo is designed for high availability with strategies for handling service failures, network partitions, and configuration rollbacks.

2. Creating a Project and Configuration in Apollo

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

3. Building a Spring Boot Test Application

3.1 Add Apollo Dependency (Maven)

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

3.2 Application.yml Settings

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

# Apollo settings
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 Test Controller

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

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

3.4 Application Entry Point

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

3.5 JVM Startup Parameters

Set -Dapollo.configService=... and -Denv=DEV (or PRO) to specify the configuration service address and environment.

4. Testing the Application

Start the Spring Boot app and access http://localhost:8080/test . The response shows the value from Apollo (e.g., 123456 ). Modifying the value in Apollo and republishing updates the response in real time. Rolling back or deleting the key restores the default value. When the Apollo server is unreachable, the client falls back to the local cache; deleting the cache forces the default value.

5. Exploring Apollo’s Environment, Cluster, and Namespace Features

5.1 Different Environments

Configure env=PRO and point apollo.meta to the production address to fetch PRO‑specific values.

5.2 Different Clusters

Create clusters such as beijing and shanghai , each with its own test value, and set apollo.cluster=beijing (or shanghai ) in application.yml to retrieve the corresponding configuration.

5.3 Different Namespaces

Create private namespaces like dev-1 and dev-2 , each containing a test key with distinct values. Specify the namespace via apollo.bootstrap.namespaces=dev-1 (or dev-2 ) to fetch the appropriate configuration.

6. Deploying the Spring Boot Application on Kubernetes

6.1 Build Docker Image

Compile the project with Maven, create a Dockerfile that copies the JAR, defines JAVA_OPTS (e.g., -Denv=DEV ) and APP_OPTS for Apollo parameters, and build the image:

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

6.2 Kubernetes Manifests

Define a Service (NodePort) and Deployment. In the Deployment, set environment variables:

JAVA_OPTS="-Denv=DEV"
APP_OPTS="--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"

Apply the manifest to the desired namespace:

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

6.3 Verify Deployment

Access the service via the NodePort (e.g., http://192.168.2.11:31081/test ) and confirm the returned value matches the configuration stored in Apollo.