---

name: spring-cloud-config description: | Spring Cloud Config for centralized configuration management in microservices. Covers Config Server, Config Client, Git backend, and dynamic refresh.

USE WHEN: user mentions "spring cloud config", "config server", "centralized configuration", "@RefreshScope", "externalized config"

DO NOT USE FOR: simple properties files - use standard Spring Boot, secrets management - combine with Vault allowed-tools: Read, Grep, Glob, Write, Edit

Spring Cloud Config - Quick Reference

Deep Knowledge: Use mcp__documentation__fetch_docs with technology: spring-cloud-config for comprehensive documentation.

Config Server Setup

Dependencies

<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-config-server</artifactId>
</dependency>

Main Application

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

application.yml (Server)

server:
  port: 8888

spring:
  application:
    name: config-server

  cloud:
    config:
      server:
        git:
          uri: https://github.com/myorg/config-repo
          default-label: main
          search-paths: '{application}'
          clone-on-start: true
          timeout: 10
          # For private repos
          username: ${GIT_USERNAME}
          password: ${GIT_TOKEN}

        # Multiple repositories
        # git:
        #   uri: https://github.com/myorg/default-config
        #   repos:
        #     user-service:
        #       pattern: user-*
        #       uri: https://github.com/myorg/user-config

# Security
management:
  endpoints:
    web:
      exposure:
        include: health,refresh

Native Filesystem Backend

spring:
  profiles:
    active: native
  cloud:
    config:
      server:
        native:
          search-locations:
            - classpath:/config
            - file:///config-repo

Config Client Setup

Dependencies

<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-starter-config</artifactId>
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-actuator</artifactId>
</dependency>

application.yml (Client)

spring:
  application:
    name: user-service
  config:
    import: optional:configserver:http://localhost:8888

  cloud:
    config:
      fail-fast: true
      retry:
        initial-interval: 1000
        max-interval: 2000
        max-attempts: 6
        multiplier: 1.1
      label: main  # Git branch

# For service discovery
# spring:
#   config:
#     import: optional:configserver:
#   cloud:
#     config:
#       discovery:
#         enabled: true
#         service-id: config-server

Config Repository Structure

config-repo/
├── application.yml           # Shared by all apps
├── application-dev.yml       # Shared dev profile
├── application-prod.yml      # Shared prod profile
├── user-service.yml          # user-service defaults
├── user-service-dev.yml      # user-service dev
├── user-service-prod.yml     # user-service prod
├── order-service.yml
└── order-service-prod.yml

Example: user-service.yml

# Base configuration
server:
  port: 8081

app:
  name: User Service
  feature-flags:
    new-dashboard: false
    beta-features: false

database:
  pool-size: 10
  timeout: 5000

Example: user-service-prod.yml

# Production overrides
server:
  port: 80

app:
  feature-flags:
    new-dashboard: true

database:
  pool-size: 50
  timeout: 3000

Accessing Configuration

REST Endpoints

# Get configuration
GET http://localhost:8888/{application}/{profile}
GET http://localhost:8888/{application}/{profile}/{label}

# Examples
GET http://localhost:8888/user-service/default
GET http://localhost:8888/user-service/prod
GET http://localhost:8888/user-service/prod/main

# Get specific file
GET http://localhost:8888/{application}/{profile}/{label}/{filename}

Dynamic Refresh

Enable Refresh

management:
  endpoints:
    web:
      exposure:
        include: refresh,health,info

@RefreshScope

@RestController
@RefreshScope
public class ConfigController {

    @Value("${app.feature-flags.new-dashboard}")
    private boolean newDashboard;

    @Value("${app.name}")
    private String appName;

    @GetMapping("/config")
    public Map<String, Object> getConfig() {
        return Map.of(
            "appName", appName,
            "newDashboard", newDashboard
        );
    }
}

@Configuration
@RefreshScope
@ConfigurationProperties(prefix = "app")
public class AppConfig {
    private String name;
    private Map<String, Boolean> featureFlags;
    // getters, setters
}

Trigger Refresh

# Single service
POST http://localhost:8081/actuator/refresh

# Response: changed properties
["app.feature-flags.new-dashboard", "app.name"]

Spring Cloud Bus (Broadcast Refresh)

Dependencies

<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-starter-bus-amqp</artifactId>
</dependency>
<!-- or Kafka -->
<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-starter-bus-kafka</artifactId>
</dependency>

Configuration

spring:
  rabbitmq:
    host: localhost
    port: 5672
    username: guest
    password: guest

management:
  endpoints:
    web:
      exposure:
        include: busrefresh

Broadcast Refresh

# Refresh all instances
POST http://localhost:8888/actuator/busrefresh

# Refresh specific service
POST http://localhost:8888/actuator/busrefresh/user-service:**

Encryption/Decryption

Setup

# Config Server
encrypt:
  key: ${ENCRYPT_KEY}  # Symmetric key

# Or asymmetric
encrypt:
  key-store:
    location: classpath:/server.jks
    password: ${KEYSTORE_PASSWORD}
    alias: configkey

Encrypt Values

# Encrypt a value
POST http://localhost:8888/encrypt -d "mysecret"
# Returns: AQA...encrypted...

# Decrypt
POST http://localhost:8888/decrypt -d "AQA...encrypted..."

Use in Config

# In config repo
spring:
  datasource:
    password: '{cipher}AQA...encrypted...'

database:
  api-key: '{cipher}AQB...encrypted...'

Health Check

@Configuration
public class ConfigHealthConfig {

    @Bean
    public HealthIndicator configServerHealthIndicator(ConfigClientProperties props) {
        return () -> {
            try {
                // Check config server connectivity
                return Health.up()
                    .withDetail("configServer", props.getUri())
                    .build();
            } catch (Exception e) {
                return Health.down()
                    .withException(e)
                    .build();
            }
        };
    }
}

Vault Backend

spring:
  cloud:
    config:
      server:
        vault:
          host: localhost
          port: 8200
          scheme: https
          backend: secret
          default-key: application
          profile-separator: /
          kv-version: 2
          authentication: TOKEN
          token: ${VAULT_TOKEN}

Best Practices

Do	Don't
Use Git for version control	Store configs locally only
Encrypt sensitive values	Store passwords in plain text
Use profile-specific configs	Mix environments in one file
Enable fail-fast in production	Ignore config server failures
Use @RefreshScope sparingly	Refresh-scope everything

Production Checklist

• Config server highly available
• Git repo secured
• Sensitive values encrypted
• Retry configuration set
• fail-fast enabled
• Health checks configured
• Spring Cloud Bus for broadcast
• Actuator endpoints secured
• Label (branch) strategy defined
• Webhook for auto-refresh

When NOT to Use This Skill

• Single application - Use standard Spring Boot properties
• Kubernetes - Use ConfigMaps, Secrets
• Secrets only - Use Vault, AWS Secrets Manager
• Simple setup - Overhead may not be justified

Anti-Patterns

Anti-Pattern	Problem	Solution
Secrets in Git	Security vulnerability	Use encrypt or Vault
No fail-fast	App starts with wrong config	Enable spring.cloud.config.fail-fast
Missing @RefreshScope	Config changes need restart	Add annotation to beans
Polling config server	High load	Use webhook-based refresh
No backup config	Config server down = app down	Configure fallback

Quick Troubleshooting

Problem	Diagnostic	Fix
Config not loading	Check config server logs	Verify profile, label
Refresh not working	Check @RefreshScope	Add annotation, POST /actuator/refresh
Wrong environment	Check spring.profiles.active	Set correct profile
Git auth failing	Check credentials	Configure correct auth
Encryption not working	Check encrypt.key	Set encryption key

Reference Documentation

• Spring Cloud Config Reference