Mastering Apollo Config Center: Dynamic Spring Boot Configuration from Basics to Kubernetes Deployment

Basic concepts

Apollo is an open‑source distributed configuration center (originally from Ctrip) that solves the limitations of file‑based or database‑based configuration management for micro‑services. It provides real‑time configuration push, gray release, multi‑environment isolation, permission control, and version management.

Core features

Simple deployment : stateless Config Service and Admin Service can be registered to Eureka or any service‑discovery mechanism.

Real‑time push : clients keep a long‑poll HTTP connection; the server pushes updates immediately.

Version control & gray release : configurations are versioned and can be released to specific clusters.

Namespace support : separate logical groups (e.g., application, database) similar to multiple property files.

Java/.NET native clients with hot‑push and fallback to local cache.

Permission & audit : fine‑grained access control and operation logging.

Architecture overview

Apollo consists of two main services:

Config Service : provides read‑only APIs for clients to fetch and receive configuration updates.

Admin Service : offers management UI (Apollo Portal) and REST APIs for publishing configuration changes.

Both services are stateless, register to Eureka (or a custom Meta Server) and can be scaled horizontally. Clients maintain a long‑poll HTTP request (up to 60 seconds). If a change occurs, the server returns the changed namespace immediately; otherwise it returns HTTP 304. Clients also poll the server periodically (default every 5 minutes) using the apollo.refreshInterval property.

Client design and local cache

The Apollo client caches the latest configuration in memory and on the local file system (default path /opt/data/{appId}/config-cache on Linux or C:\opt\data\{appId}\config-cache on Windows). When the Config Service is unreachable, the client falls back to the cached file, ensuring the application can still start with the last known configuration.

Cache file naming convention:

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

Hands‑on tutorial

Create a Spring Boot project 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 Apollo Create src/main/resources/application.yml with the following minimal configuration (replace the meta server address with your own):

app:
  id: apollo-test

apollo:
  meta: http://192.168.2.11:30002   # Apollo meta server address
  cluster: default
  bootstrap:
    enabled: true
    namespaces: application
    eagerLoad:
      enabled: false
  cacheDir: /opt/data/

The app.id uniquely identifies the application in Apollo. The cluster field selects a specific cluster (e.g., data‑center). The bootstrap.namespaces defines which namespaces are loaded at startup (default is application ).

Write a test controller Use Spring's @Value to inject a configuration key:

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

    @GetMapping("/test")
    public String test() {
        return "test value: " + test;
    }
}

If the key test is not defined in Apollo, the default value default will be used.

Run the application Pass the required JVM arguments to point to the Config Service and select the environment:

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

Start the Spring Boot application (e.g., via IDE or java -jar ) and access http://localhost:8080/test . The response should show the value stored in Apollo.

Failure handling If the Config Service cannot be reached, the client reads the configuration from the local cache. Deleting the cache directory forces the client to fall back to the default value defined in the @Value expression.

Exploring clusters and namespaces

By changing apollo.cluster (e.g., beijing or shanghai) and apollo.bootstrap.namespaces (e.g., dev-1, dev-2), the same application can retrieve different configuration values without code changes. This is useful for multi‑data‑center deployments or separating configuration domains (e.g., database vs. feature flags).

Kubernetes deployment

Docker image Build a slim OpenJDK image that copies the built JAR and defines two environment variables: JAVA_OPTS for JVM options and APP_OPTS for Apollo 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"]

Kubernetes manifests Create a Service (NodePort) and a Deployment that inject the required Apollo parameters via env entries. The example below uses a placeholder ${K8S_IP} for the node IP.

apiVersion: v1
kind: Service
metadata:
  name: springboot-apollo
spec:
  type: NodePort
  ports:
    - name: http
      port: 8080
      targetPort: 8080
      nodePort: 31080
  selector:
    app: springboot-apollo
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: 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
          env:
            - name: JAVA_OPTS
              value: "-Denv=DEV"
            - name: APP_OPTS
              value: "--app.id=apollo-demo --apollo.bootstrap.enabled=true --apollo.meta=http://service-apollo-config-server-dev.mydlqcloud:8080"
          ports:
            - containerPort: 8080
          resources:
            limits:
              memory: 1000Mi
              cpu: 1000m
            requests:
              memory: 500Mi
              cpu: 500m"

Apply the manifest:

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

After the pod is running, test the endpoint via the node IP: http://${K8S_IP}:31080/test The response should display the value stored in Apollo, confirming that the application reads configuration from the distributed center inside Kubernetes.

Key configuration parameters

apollo.meta : URL of the Apollo meta server (or Config Service when apollo.configService is used).

apollo.cluster : Name of the cluster (e.g., default, beijing).

apollo.bootstrap.enabled : Enable or disable Apollo client at startup.

apollo.bootstrap.namespaces : List of namespaces to load (comma‑separated).

apollo.cacheDir : Directory for local cache files.

apollo.autoUpdateInjectedSpringProperties : Whether Spring ${...} placeholders are refreshed automatically (default true).

apollo.refreshInterval : Period (in minutes) for the fallback pull request (default 5).

Typical failure scenarios

Config Service unavailable : client reads from the local cache; if the cache is missing, the default values defined in the code are used.

Parameter deleted in Apollo : after deletion and republishing, the client returns the default value on the next pull.

Rollback : publishing a previous version restores the old value instantly.

Summary

This guide demonstrates how to integrate Apollo with a Spring Boot microservice, manage configurations across environments, clusters, and namespaces, and deploy the service to Kubernetes with Docker. Apollo ensures that configuration changes are propagated to running instances in real time while providing a reliable fallback mechanism via local caching.