Apollo Configuration Center: Complete Guide from Core Concepts to Kubernetes Deployment

1. Core Concepts of Apollo

Apollo is an open-source configuration management center developed by Ctrip's framework department. It centrally manages configurations across different environments and clusters, pushes changes in real-time to clients, and provides standardized permission and governance features.

1.1 Background

As applications grow complex, configuration needs increase: feature flags, parameter tuning, service addresses. Requirements include real-time effect, canary releases, per-environment/cluster management, and audit trails. Traditional file- or database-based approaches fall short.

1.2 Features

Simple deployment

Canary release

Versioned release management

Open platform APIs

Client configuration monitoring

Native Java and .NET clients

Real-time configuration push (hot publish)

Permission management, release approval, operation audit

Unified management across environments and clusters

1.3 Basic Model

User modifies and publishes config in the portal.

Config center notifies Apollo client of updates.

Client pulls latest config, updates local cache, and notifies the application.

1.4 Four Management Dimensions

Application : Unique app identity via app.id.

Environment : FAT (feature test), UAT (integration test), DEV (development), PRO (production). Set via env variable.

Cluster : Logical grouping of instances (e.g., by data center). Same config key can have different values per cluster.

Namespace : Configuration grouping, analogous to separate config files. Types: private (app-scoped), public (globally unique, accessible by any app), and associated/inheritance (private, inherits from public namespace with overrides).

1.5 Local Caching

Client caches configs locally to survive server/network outages. Default paths: /opt/data/{appId}/config-cache (Linux/Mac) or C:\opt\data\{appId}\config-cache (Windows). File naming: {appId}+{cluster}+{namespace}.properties.

1.6 Client Design

Long-lived HTTP connection (HTTP Long Polling) for instant push. Server holds request for 60 seconds; returns immediately on change with changed namespace list.

Fallback: periodic pull every 5 minutes (configurable via apollo.refreshInterval in minutes) reporting local version; server typically returns 304 Not Modified.

Configs stored in memory and local disk.

Application reads from client and subscribes to change notifications.

Long polling implementation: client issues HTTP request; server holds 60s; if config changes, returns changed namespaces; else returns 304. Client immediately reconnects. Server uses async servlet (Spring DeferredResult) to handle tens of thousands of connections.

1.7 Overall Architecture

Config Service : Serves config reads/pushes to clients. Stateless, multi-instance.

Admin Service : Serves config writes/publishes to Portal. Stateless, multi-instance.

Both register with Eureka and heartbeat.

Meta Server : Wraps Eureka discovery APIs.

Client accesses Meta Server via domain to get Config Service list (IP+Port), then direct IP+Port with client-side load balancing and retry.

Portal similarly gets Admin Service list via Meta Server.

For simplicity, Config Service, Eureka, and Meta Server run in same JVM process.

1.8 Availability Considerations

Single config service down : No impact. Stateless; client reconnects to another.

All config services down : Clients cannot fetch new configs; Portal unaffected. Fallback: client restart reads local cache.

Single admin service down : No impact. Stateless; Portal reconnects.

All admin services down : Clients unaffected; Portal cannot update configs.

Single portal down : No impact. SLB routes to healthy portal.

All portals down : Clients unaffected; Portal cannot update configs.

Entire data center down : No impact. Multi-DC deployment with full sync; Meta Server/Portal domain via SLB auto-failover.

2. Creating Project and Configuration in Apollo Portal

2.1 Login

Default credentials: apollo / admin.

2.2 Department Management

Portal UI lacks department CRUD; must edit ApolloPortalDB table, key organizations, JSON value.

2.3 Create Project

Set App ID apollo-test, name apollo-demo, select custom department.

2.4 Create Config Parameter

Key test, value 123456, then publish.

3. Building Apollo Client Test Project (SpringBoot)

3.1 Maven Dependency

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

3.2 Configuration (application.yml)

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

Key properties: apollo.meta (config center address), apollo.cluster, apollo.bootstrap.enabled, apollo.bootstrap.namespaces, apollo.cacheDir, apollo.autoUpdateInjectedSpringProperties (controls runtime placeholder updates), apollo.bootstrap.eagerLoad.enabled (load before logging init; true enables log config management but disables Apollo logs).

3.3 Test Controller

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

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

3.4 Startup Class

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

3.5 JVM Startup Parameters

For Kubernetes-deployed Apollo, must set: -Denv=DEV (environment) -Dapollo.configService=http://192.168.2.11:30002 (bypasses Meta Server; required in K8s)

Note: env must match the environment of the apollo.meta address.

4. Functional Testing

4.1 Fetch Apollo Value

GET http://localhost:8080/test returns test的值为:123456 (Apollo value, not default).

4.2 Dynamic Update

Change test to 666666 in Portal, publish. Immediate refresh shows new value.

4.3 Rollback

Rollback in Portal reverts to previous version; client reflects 123456 instantly.

4.4 Offline Behavior

Point apollo.configService to wrong address. Client still returns 123456 from local cache. Delete cache file

/opt/data/apollo-test/config-cache/apollo-test+default+application.properties

, restart → returns default 默认值.

4.5 Parameter Deletion

Delete test in Portal, publish. Client falls back to default 默认值.

5. Exploring Cluster and Namespace

5.1 Environment Isolation

Add same key test with value abcdefg in PRO environment. Update client apollo.meta to PRO address, env=PRO, apollo.configService to PRO. Client now returns PRO value.

5.2 Cluster Isolation

Create clusters beijing and shanghai. Set test to Cluster-BeiJing and Cluster-ShangHai respectively. Client apollo.cluster=beijing → Beijing value; shanghai → Shanghai value.

5.3 Namespace Isolation

Create private namespaces dev-1 and dev-2. Set test to dev-1 Namespace and dev-2 Namespace. Client apollo.bootstrap.namespaces=dev-1 → dev-1 value; dev-2 → dev-2 value.

6. Kubernetes Deployment of SpringBoot with Apollo

6.1 Docker Image Build

$ mvn clean install

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:

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

6.2 Kubernetes Deployment YAML

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

Note: apollo.meta uses K8s service DNS service-apollo-config-server-dev.mydlqcloud:8080 (service name + namespace).

6.3 Deploy and Test

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

Access via NodePort: http://192.168.2.11:31081/test returns test的值为:123456, confirming Apollo integration in K8s.