Spring Cloud Config Client

What is config client ?

Spring Cloud Config Client is a library that enables a Spring Boot microservice to fetch its configuration from a centralized Config Server at startup instead of relying solely on local property/config files.

It serves as the consumer-side component of centralized configuration management in a Spring Cloud-based microservice architecture that connects microservices to an externalized configuration source, ensuring consistent property management across the fleet.

Why config client exists ?

In distributed systems, managing configuration inside each individual service becomes unmanageable and error-prone as the number of microservices grows.

Manual updates lead to configuration drift and require risky re-deployments of the service even for simple value changes.

By externalizing configuration, services become environment-aware without being environment-dependent.

Spring Cloud Config Client exists to solve these architectural challenges:

• Externalizes configuration to decouple environment settings from the application code.
• Reduces redeployment cycles by allowing configuration updates without rebuilding JAR (app binary) files.
• Ensures consistency by providing a single “source of truth” for shared properties.
• Enables environment awareness, allowing the same binary to run in Dev, QA, or Prod.

When to use config client ?

Spring Cloud Config Client is essential for distributed systems where configuration must be governed centrally.

It is the preferred choice when multiple instances of a service must share identical settings or when security policies require secrets to be stored outside the application repository.

Spring Cloud Config Client should be used when:

• Multiple microservices share environment-specific configuration.
• Configuration must change without rebuilding artifacts.
• Consistency across service instances is critical.
• Teams want centralized governance of configuration values.

Insight:
It is especially effective when combined with Spring Cloud Config Server in multi-environment setups.

How config client fits into spring ecosystem ?

The Config Client operates during the bootstrap phase, contacting the Config Server before the main application context is fully initialized.

This ensures that all beans, including database connections and security filters, are configured with the correct values from the start.

The interaction flow is:

flowchart LR
    A[Spring Boot Service<br/><br/>Application Start]
    B[Spring Cloud Config Client<br/><br/>Bootstrap Phase]
    C[Spring Cloud Config Server]
    D[External Config Repository<br/><br/>Git / Versioned Store]
    E[Spring Environment<br/><br/>Property Sources]
    F[Spring ApplicationContext<br/><br/>Bean Initialization]

    A --> B
    B -->|Request config<br/>app name + profile| C
    C -->|Fetch config| D
    D -->|Return properties| C
    C -->|Resolved configuration| B
    B -->|Merge properties| E
    E --> F

Request flow

Below sequence diagram demonstrates the flow of Spring Cloud Config Client fetching configuration from Config Server.

sequenceDiagram
    autonumber
    participant Client as Microservice (Client)
    participant Server as Config Server
    participant Git as Git Repository/Vault
    
    Note over Client: 1. Service Start (Main Class)
    
    rect rgb(240, 248, 255)
    Note right of Client: Bootstrap Phase
    Client->>Client: Initialize Bootstrap Context
    Client->>Client: Resolve 'spring.application.name'
    Client->>Server: HTTP GET /service-name/profile
    end

    activate Server
    Server->>Git: Fetch properties for {app}-{profile}.yml
    Git-->>Server: Return YAML/Properties
    Server->>Server: Process & Merge Property Sources
    Server-->>Client: Return JSON PropertySource
    deactivate Server

    rect rgb(245, 245, 245)
    Note right of Client: Application Context Phase
    Client->>Client: Merge remote properties into Environment
    Client->>Client: Initialize Beans (@Value, @ConfigurationProperties)
    Client->>Client: Fully Started
    end

Developing config client app

Building a Spring Cloud Config Client involves adding the necessary starter dependency and defining the location of the Config Server. This process transforms a standard Spring Boot application into a configuration-aware microservice.

Enabling the config client

To enable Config Client behavior, include the Spring Cloud Config starter in your build file. This dependency triggers the auto-configuration logic required to communicate with the remote server.

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

Application configuration

The application.properties (or application.yml) file must specify the Config Server URL (where the configs are hosted and the name to identify app/service specific config to fetch.

Using the 'optional:` prefix is a best practice to allow the service to start even if the server is temporarily unreachable.

# Active profile
spring.cloud.config.profile=dev

# Service name used for lookup
spring.cloud.config.name=limits-service

# Config Server location
spring.config.import=optional:configserver:http://localhost:8888/

# Local fallback values (lowest priority)
limits-service.minimum=20
limits-service.maximum=21

Insight:
Remote configuration overrides local values unless explicitly disabled.

Property import mechanism (Spring Boot 2.4+)

`spring.config.import` is the standard property used by Spring Boot applications to specify and load configuration from external sources like a Spring Cloud Config Server.

This mechanism, introduced in Spring Boot 2.4, simplifies the bootstrap process by allowing applications to resolve remote properties directly within the standard application.yml or application.properties files.

Key behaviors of the Import mechanism

The transition to the import-based model, changed how applications react to the presence or absence of a Config Server. Understanding these behaviors is critical for designing resilient startup sequences in production environments.

Below points outline the functional characteristics of the `spring.config.import` property:

• “optional:” Prefix:
  • Adding this prefix allows the application to continue starting even if the Config Server is offline or unreachable.
• Strict Dependency:
  • Removing the `optional:` prefix forces the application to fail fast if it cannot establish a connection to the configuration source.
• Priority Precedence:
  • Values defined via the import location take precedence over the legacy `spring.cloud.config.uri` property.
• Multiple Fetch Events:
  • It is normal to observe multiple fetch requests during startup as Spring Boot resolves and activates specific profiles.

Legacy Bootstrap vs. modern Import

TBelow is the architectural shift in how Spring Cloud Config Clients connect to the server across different Spring Boot versions.

Defining configuration binding

The client maps external properties to strongly-typed Java beans using the @ConfigurationProperties annotation. This approach provides type safety and makes configuration easier to inject into service logic.

@ConfigurationProperties(prefix = "limits-service")
@Component
public class LimitsServiceConfiguration {

    private int minimum;
    private int maximum;

    // getters and setters
}

Insight:
This class maps external properties from config server having the prefix limits-service.*.

Consuming config in the service layer

Once bound, the configuration bean is injected into controllers or services via standard dependency injection.

This keeps the business logic isolated from the configuration source, as the controller only interacts with a local Java object.

@RestController
public class LimitsServiceController {

    @Autowired
    LimitsServiceConfiguration config;

    @GetMapping("/limits")
    public Limits retrieveLimits() {
        return new Limits(config.getMinimum(), config.getMaximum());
    }
}

Project Reference:
Refer the POC application for building a cloud client app Spring Cloud POC App - Config Client

Config client vs local config

Here’s the comparison of Spring Cloud Config Client with local configuration files to clarify when centralized configuration becomes necessary in distributed systems.

Configuration refresh strategies

Configuration refresh refers to the mechanism of updating property values in a running application without performing a full process restart.

Spring Cloud provides multiple strategies to handle these updates, ranging from manual triggers to automated events.

The table below summarizes the available strategies for propagating configuration changes in Spring Cloud, highlighting predictability, operational impact, and recommended usage.

Insight:
→Restart-based refresh prioritizes stability and predictability, making it the safest default choice.
→Runtime refresh strategies improve speed but introduce operational and behavioral risk, and should only be adopted with clear boundaries and discipline.

Config property resolution order

Property Resolution Order is the strict hierarchy Spring Boot follows to determine which value takes precedence when the same configuration key is defined in multiple locations.

In a Spring Cloud environment, remote properties fetched from the Config Server are designed to override local properties, ensuring centralized control.

This allows developers to define broad defaults locally while providing environment-specific overrides remotely.

The resolution behavior follows this descending priority:

• Remote Configuration:
  • Properties fetched from the Config Server (e.g., application-prod.yml).
• Local Profile Configuration:
  • Local files specific to a profile (e.g., application-dev.yml).
• Local Default Configuration:
  • The standard application.yml or application.properties.
• Framework Defaults:
  • Hardcoded values within the Spring Boot starters.

Architectural Note:
Local configuration should be treated as a safe fallback. It ensures the application can boot with “sane defaults” even if the Config Server is temporarily unavailable during an optional import.

Startup and runtime impacts

The following table details how different connectivity issues affect service availability based on the configuration of the `spring.config.import` property.

Summary:
→Using the optional: prefix prioritizes availability, allowing services to start with local defaults.
→While the mandatory mode prioritizes consistency, preventing services from running with potentially stale or incorrect data.

Security boundaries

Spring Cloud Config Security Boundaries define the logical separation between operational application settings and sensitive credentials.

In a production-grade architecture, Spring Cloud Config acts as a distribution mechanism for behavior-altering properties, while dedicated systems like HashiCorp Vault or AWS Secrets Manager handle identity and access materials.

Why security boundaries matter ?

Centralizing configuration simplifies management but creates a “single point of failure”.

For security, if boundaries are blurred, without a clear distinction between settings and secrets, organizations face systemic risks.

• Source Control Exposure:
  • Committing passwords to Git repositories makes them visible to anyone with read access.
• Leakage via Endpoints:
  • Standard Spring Boot Actuator endpoints (like /env) can expose raw configuration values if not properly secured.
• Audit Deficiencies:
  • Traditional Git histories rarely meet the compliance requirements for secret access auditing and rotation.
• Static Credentials:
  • Managing secrets in configuration files makes automated rotation and short-lived credentials nearly impossible to implement.

Configuration types: Safe vs. Sensitive

To maintain a secure posture, architects must categorize every property before deciding where it resides.

Follow below outlines to distinguish between Safe Configuration and Sensitive Secrets.

Note:
→Architectural Rule: If a property allows access to data or infrastructure, it is a secret and stays out of Spring Cloud Config.

Why it’s not a secrets manager ?

While it is technically possible to store secrets in Config Server, it is architecturally discouraged.

Spring Cloud Config is designed primarily for configuration distribution and versioning. While highly effective for application settings, it lacks the specialized security primitives required to function as a robust secrets manager.

The table below outlines the specific limitations that necessitate the use of a dedicated secret management system (like HashiCorp Vault or AWS Secrets Manager) for sensitive data.

Secure configuration architecture

To move from a basic setup to a production-ready environment, you must implement a Separation of Concerns model.

This architecture treats Spring Cloud Config as a distribution engine for application behavior, while offloading sensitive data to specialized security systems.

Comparison of secure configuration patterns

Below patterns represent the standard for modern microservices. Choosing the right one depends on your infrastructure maturity and compliance needs.

Critical security Anti-patterns

Avoid these common “shortcuts” that introduce systemic vulnerabilities into your distributed system.

Design guidelines for secure configuration

Adopt a “Secure by Design” approach using these non-negotiable guidelines for 2025 deployments:

1. Treat Config as Public:
   • Architect your system assuming any value in your Config Server might be exposed; strictly limit it to non-sensitive data.
2. Externalize Secret Lifecycle:
   • Use a dedicated system (Vault/AWS/Azure Secrets) to handle the creation, rotation, and audit logs of secrets.
3. Principle of Least Privilege:
   • Configure each client service to only fetch the specific file/profile required for its operation.
4. Audit Endpoints:
   • Actively monitor and secure the `/configprops` and `/env` Actuator endpoints using Spring Security.

Production readiness checklist

Use the checklist below before promoting to production.