Quản Lý Cấu Hình Tập Trung với Spring Cloud Config: Chặng Tiếp Theo Trên Lộ Trình Java Spring

Spring Cloud Config không làm cấu hình “tập trung” theo nghĩa nhiều người tưởng. Nó biến một kho Git thành API đọc cấu hình, rồi để client import lúc khởi động. Ai đọc gì, secret ở đâu và thay đổi đến tiến trình ra sao vẫn là việc bạn quyết định.

Config Server không bị deprecated: bản 5.0.6 trong Spring Cloud 2025.1.4 vẫn được maintain cho Boot 4.1.2. Nhưng “được maintain” khác “mặc định nên dùng”: trên Kubernetes, ConfigMap và Secret đã làm được phần lớn việc này mà không cần thêm một service phải vá lỗi. Bức tranh release train nằm ở bài Spring Cloud là gì.

Cập nhật 2026

  • Config Server 5.0.6 trong Spring Cloud 2025.1.4, chạy với Boot 4.1.2. Bản 5.1.0-RC2 là preview, đừng đưa vào production.
  • bootstrap.yml là legacy. Từ Boot 2.4, cách mặc định là spring.config.import; muốn dùng bootstrap phải thêm spring-cloud-starter-bootstrap hoặc bật spring.cloud.bootstrap.enabled=true.
  • Không còn javax. Boot 4.1 dựa trên Jakarta EE 11; mọi import trong bài cũ đổi sang jakarta.

Vấn đề thật sự: mười service, mười bản sao cấu hình

Ban đầu mỗi service giữ một application.yml. Thêm dev, staging, prod thì số file tăng gấp ba. Địa chỉ Kafka, timeout, URL của service thanh toán bị copy sang từng repo. Một lần đổi broker phải sửa mười chỗ, build lại mười pipeline, và không ai chắc tất cả đã khớp.

Config Server giải quyết đúng ba việc:

  • Một nguồn cho nhiều service. File application.yml trong repo cấu hình áp cho mọi client; file order-service.yml chỉ áp cho một service.
  • Override theo môi trường và service. Cùng một artifact chạy ở dev và prod, khác nhau đúng phần cấu hình, không build lại chỉ vì đổi URL.
  • Lịch sử audit được. Mỗi thay đổi là một commit: ai đổi, lúc nào, diff ra sao. Đây là lợi ích lớn nhất khi phải trả lời “prod đang chạy version cấu hình nào”.

Nó không quản lý secret cho tốt, không đảm bảo thay đổi được áp ngay, và không quyết định service nào đọc cấu hình nào. Ba giới hạn đó là phần còn lại của bài.

Kiến trúc: một server, nhiều client

Config Server là ứng dụng Spring Boot riêng, đọc backend (Git, Vault, JDBC) và phục vụ cấu hình qua HTTP; client gọi server lúc khởi động, nhận property source rồi đưa vào Environment như file local. Server không giữ state, nguồn sự thật là Git — mất một instance không mất cấu hình, mất Git thì mất cả hệ thống.

Dựng Config Server

Thêm BOM spring-cloud-dependencies phiên bản 2025.1.4 (import scope) và dependency org.springframework.cloud:spring-cloud-config-server. Không tự điền version cho starter; BOM quyết định. Class chính chỉ cần thêm một annotation:

// File: configserver/src/main/java/com/evotek/configserver/ConfigServerApplication.java
package com.evotek.configserver;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.cloud.config.server.EnableConfigServer;

@SpringBootApplication
@EnableConfigServer
public class ConfigServerApplication {

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

Phần cấu hình bạn sẽ chỉnh nhiều nhất là nguồn Git:

# File: configserver/src/main/resources/application.yml
server:
  port: 8888
spring:
  application:
    name: configserver
  cloud:
    config:
      server:
        git:
          uri: https://git.evotek.vn/platform/config-repo.git
          search-paths:
            - config
            - services/*
          default-label: main
          clone-on-start: true
          refresh-rate: 30
management:
  endpoint:
    health:
      show-details: always

search-paths giới hạn thư mục được quét và nhận wildcard kiểu services/*. default-label là nhánh dùng khi client không gửi label; mặc định hiệu dụng là main. clone-on-start: true buộc server clone ngay lúc khởi động và fail sớm nếu Git sai URL hoặc thiếu quyền.

refresh-rate mặc định là 0: server đọc Git ở mỗi request. Đặt 30 giây giảm tải Git nhưng thay đổi có thể trễ tới 30 giây.

Client: spring.config.import, không phải bootstrap

Thêm org.springframework.cloud:spring-cloud-starter-config và khai báo import trong application.yml. Đây là cách tài liệu hiện hành mô tả là mặc định, thay cho bootstrap.yml:

# File: order-service/src/main/resources/application.yml
spring:
  application:
    name: order-service
  profiles:
    active: dev
  config:
    import: configserver:http://localhost:8888
  cloud:
    config:
      label: main

spring.application.name quyết định file nào trên server được chọn; đổi tên service mà quên đổi tên file sẽ khiến nó lặng lẽ nhận cấu hình chung. Bỏ tiền tố optional: như trên nghĩa là client fail nếu không gọi được server. Dùng optional:configserver: khi chấp nhận chạy bằng giá trị mặc định local — tiện cho dev, nguy hiểm cho prod.

Một điểm dễ hiểu sai: trong Config Data, tài liệu import được chèn ngay dưới file khai báo nó, nên giá trị từ Config Server thắng application.yml trong jar. Biến môi trường và tham số dòng lệnh vẫn thắng tất cả, nên override khẩn cấp hãy dùng env var.

Tài liệu cũ dùng bootstrap.yml với spring.cloud.config.uri là luồng legacy, chỉ chạy khi bật bootstrap bằng starter hoặc system property. Đừng trộn hai luồng.

Profile, label và thứ tự override

Server phục vụ theo đường dẫn /{application}/{profile}[/{label}]. Curl trước khi debug bất cứ thứ gì trong code:

# Xem server thật sự trả gì cho service ở profile dev
curl -s http://localhost:8888/order-service/dev

# Ép label cụ thể (nhánh hoặc tag)
curl -s http://localhost:8888/order-service/dev/release-2026.11

Với application order-service và profile dev, server tổng hợp từ chung đến riêng: application.yml, application-dev.yml, order-service.yml, order-service-dev.yml. Nguồn cụ thể hơn thắng nguồn chung. Label là nhánh hoặc tag Git, cho phép ghim một bản release vào đúng bộ cấu hình.

Cái bẫy ở đây rất im lặng: profile development không khớp file order-service-dev.yml, và client vẫn khởi động bình thường với chỉ application.yml. Không cảnh báo, không lỗi, chỉ có hành vi sai. Hãy curl đúng cặp application/profile trong CI và coi đó là bước kiểm tra deploy; profile lấy từ spring.profiles.active, đặt qua SPRING_PROFILES_ACTIVE khi chạy production.

Mã hóa giá trị nhạy cảm

Giá trị bắt đầu bằng {cipher} được server giải mã trước khi gửi client, nên repo Git chỉ chứa ciphertext “at rest”. Nếu giải mã lỗi, server bỏ property đó và thêm khóa invalid.<tên> — dấu hiệu để tìm trong response JSON.

Có hai cách cấu hình khóa. Đối xứng: đặt encrypt.key, tốt nhất qua biến môi trường ENCRYPT_KEY. Bất đối xứng: dùng keystore, mã hóa bằng public key và giải mã bằng private key:

encrypt:
  keyStore:
    location: file:/etc/configserver/keys.p12
    password: ${CONFIG_KEYSTORE_PASSWORD}
    alias: config-key
    type: pkcs12
curl -s http://localhost:8888/encrypt --data-urlencode "=S3cr3t!Pass"

Cảnh báo: /encrypt và /decrypt là endpoint nguy hiểm. Ai gọi được /decrypt đọc được toàn bộ secret; phải chặn ở network và yêu cầu xác thực. Nếu khóa mã hóa nằm cùng repo, bạn chỉ đang che mắt người review. Secret thật nên đến từ Vault hoặc SOPS, không commit vào Git.

Refresh mà không restart

Client đọc cấu hình một lần lúc khởi động; thay đổi trong Git không tự đến tiến trình đang chạy. Cơ chế có sẵn là /actuator/refresh, nhưng chỉ tác dụng với bean đánh dấu @RefreshScope:

// File: order-service/src/main/java/com/evotek/order/config/PricingProperties.java
package com.evotek.order.config;

import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.cloud.context.config.annotation.RefreshScope;
import org.springframework.stereotype.Component;

@Component
@RefreshScope
@ConfigurationProperties(prefix = "pricing")
public class PricingProperties {

    private int maxDiscountPercent;

    public int getMaxDiscountPercent() {
        return maxDiscountPercent;
    }

    public void setMaxDiscountPercent(int maxDiscountPercent) {
        this.maxDiscountPercent = maxDiscountPercent;
    }
}
# File: order-service/src/main/resources/application.yml (phần Actuator)
management:
  endpoints:
    web:
      exposure:
        include: health,refresh
# Trả về danh sách key đã đổi; bean @RefreshScope được tạo lại
curl -s -X POST http://localhost:8081/actuator/refresh

Đây là write operation: bảo vệ endpoint, đừng expose ra Internet. Với nhiều instance, gọi từng instance là cách đơn giản nhất; Spring Cloud Bus (AMQP/Kafka) và spring-cloud-config-monitor mới phát refresh cho tất cả qua /monitor. Bus là tuỳ chọn, có thêm broker phải vận hành.

Đừng kỳ vọng mọi thứ refresh được: connection pool, port, tham số bind của Kafka, singleton đã khởi tạo đều không. Với những thay đổi đó, roll restart trung thực hơn là giả vờ hot-reload.

High availability: Git là nguồn sự thật

Server không có state riêng, nên hai instance sau load balancer là đủ. Client khai báo nhiều URL và chọn chiến lược failover:

spring:
  config:
    import: configserver:
  cloud:
    config:
      uri: http://cfg-1:8888,http://cfg-2:8888
      multiple-uri-strategy: connection-timeout-only

Mặc định client thử URL kế tiếp với mọi lỗi; connection-timeout-only chỉ chuyển khi không kết nối được, còn 401/500 thì dừng — lỗi xác thực ở mọi instance là lỗi cấu hình, không phải hạ tầng. Với backend Git, lỗi Git thường trả 404 và cũng không nên thử instance khác.

Điểm chết thật sự là Git: Git down thì mọi instance trả cùng một lỗi. Đặt repo cấu hình trên hạ tầng có SLA tương đương service nghiệp vụ. Nếu đặt refresh-rate lớn hơn 0, giữa hai lần fetch server trả bản đọc gần nhất mà không gọi Git — đủ để chịu một lần Git chập chờn, không đủ để coi là dự phòng.

Với startup, chọn giữa fail-fast (không có cấu hình thì không chạy) và optional (chạy bằng mặc định). Production nên fail-fast kèm retry: thêm spring-retry và spring-boot-starter-aop, đặt spring.cloud.config.fail-fast=true. Circuit breaker không cứu được vì lỗi xảy ra trước khi bean tồn tại; xem bài circuit breaker.

Bảo mật: server này giữ mọi thứ

Config Server tập trung toàn bộ cấu hình, kể cả connection string có mật khẩu. Bảo vệ nó như database: không public ingress, chỉ cho dải IP của service đọc, xác thực bằng Spring Security (basic auth qua TLS hoặc mTLS).

Đừng để credential của chính Config Server đến từ Config Server: nếu server cần token đọc Git hoặc Vault, inject bằng biến môi trường hoặc file mount, nếu không bạn tạo vòng lặp khởi động không thể giải.

Đừng commit secret plaintext vào Git, kể cả private repo. Chọn một trong ba: {cipher} với khóa ngoài repo, backend Vault của Config Server, hoặc file SOPS mã hóa bằng KMS/age. Plaintext trong Git không có chi phí cho tới ngày repo bị lộ.

Config Server so với các lựa chọn khác

Lựa chọn Điểm mạnh Dùng khi
Spring Cloud Config Git history, override theo service/profile, một API cho nhiều client Nhiều service trên VM, cần audit cấu hình, không muốn rebuild image khi đổi cấu hình
K8s ConfigMap/Secret Không thêm service, gắn vào Pod, rollout theo Deployment Toàn bộ hệ thống trên Kubernetes, đổi cấu hình đi kèm rollout
Vault / secret manager Secret xoay vòng, phân quyền chi tiết, audit truy cập Có secret thật, yêu cầu compliance, nhiều môi trường và nhiều team
Biến môi trường thuần Đơn giản nhất, 12-factor, không phụ thuộc dịch vụ Config ít thay đổi, ít service, chấp nhận restart để đổi

Secret của ConfigMap/Secret chỉ là base64, không mã hóa khi lưu mặc định; mã hóa at-rest phụ thuộc etcd của cluster. Đừng coi “đã là Secret” là “đã an toàn”. Với secret thật, External Secrets Operator hoặc SOPS + KMS giữ Git làm nguồn mà không lưu plaintext.

Khi nào bỏ qua Config Server

Nếu toàn bộ hệ thống chạy trên Kubernetes và mọi thay đổi cấu hình đều đi qua rollout, Config Server thường là chi phí không cần thiết. Bạn đã có ConfigMap/Secret, RBAC và audit ở tầng cluster; thêm Config Server nghĩa là thêm một service phải vá lỗi và một chỗ để rò secret.

Config Server vẫn đáng dùng khi có nhiều service trên VM hoặc môi trường hỗn hợp; khi cần một lịch sử Git duy nhất cho cấu hình mọi service; khi muốn đổi cấu hình mà không build lại artifact. Nếu đã vận hành Spring Cloud Gateway ở biên (bài gateway), chi phí thêm một Config Server là tương tự — câu hỏi là bạn có nhận lại giá trị tương ứng.

Sáu cái bẫy

  • Config Server chết lúc startup. Dùng optional: trong prod khiến service chạy bằng giá trị mặc định mà không ai biết. Chọn fail-fast + retry và test bằng cách tắt server trong CI.
  • Secret plaintext trong Git. {cipher} với khóa nằm cùng repo là vô nghĩa. Khóa phải ở env/mount, hoặc secret phải ở Vault.
  • Refresh không lan. Thiếu @RefreshScope, thiếu expose endpoint, hoặc chỉ gọi một trong ba instance. Kiểm tra bằng key trả về từ /actuator/refresh.
  • Profile mismatch. dev khác development; client nhận cấu hình chung mà không báo lỗi. Curl đúng cặp application/profile trong CI.
  • Tưởng client có cache. Client không poll; giá trị chỉ đổi sau refresh hoặc restart. refresh-rate của server chỉ ảnh hưởng việc đọc Git.
  • Trộn bootstrap và import. Hai luồng cùng chạy gọi server hai lần và thứ tự ưu tiên khó đoán. Với code mới, chọn spring.config.import.

Nhìn về 2027

Spring Cloud 2026.0.0-RC2 và Config 5.1.0-RC2 đang là preview; chưa có gì đảm bảo API giữ nguyên. Hướng đi rõ hơn nằm ở Kubernetes: external secret operator, SOPS và secret manager native ngày càng thay thế vai trò “server cấu hình”. Config Server sẽ sống ở hệ thống nhiều VM và nơi cần lịch sử Git làm bằng chứng, nhưng ngày càng là lựa chọn có lý do.

Checklist

  • Ghim Spring Cloud 2025.1.4 và Boot 4.1.2; xác nhận Config Server 5.0.6 trong BOM.
  • Repo cấu hình chỉ chứa cấu hình không nhạy cảm; secret đi qua Vault/SOPS hoặc {cipher} với khóa ngoài repo.
  • Client dùng spring.config.import, không còn bootstrap.yml; production bỏ optional:.
  • CI gọi /{application}/{profile} và kiểm tra key bắt buộc có mặt để bắt profile mismatch trước khi deploy.
  • Bật health indicator, chạy tối thiểu hai instance, client khai báo nhiều URL với multiple-uri-strategy.
  • Quyết định rõ thứ nào refresh được (@RefreshScope) và thứ nào phải rollout.

Bước tiếp theo hợp lý là đưa cấu hình vào CI/CD: kiểm tra cấu hình như kiểm tra code, thay vì sửa tay trên server. Bức tranh tổng thể nằm ở Spring Boot Roadmap.