Micro-service Arch. Config

It’s critical to define and standardize the application boundaries, properties and conventions which standardizes the application accessibility for integration, before building the application.

In real-world microservice systems, ambiguity at the foundation leads to version conflicts, unstable builds, unclear ownership, and operational friction.

In below sections we’ll establish explicit, justified, and stable decisions that will remain consistent throughout the course.

Fixed baseline

A fixed Spring Boot baseline ensures Consistent auto-configuration behavior, Predictable dependency resolution and Reproducible builds across machines and environments.

In microservices, even minor version drift between services can introduce Classpath conflicts, Incompatible actuator endpoints or Runtime failures that are hard to diagnose.

This tutorial uses Spring Boot version:3.4.0 but you can choose the latest stable version available and it will automatically set the required version for other spring cloud dependencies.

This ensures:

• Uniform actuator behavior
• Consistent configuration property support
• Compatibility with modern Java LTS versions

Release train compatibility

Spring Cloud is not versioned independently per module. Instead, it is released as a coordinated release train tested against specific Spring Boot versions.

Spring Cloud Release Train:Compatible with Spring Boot 3.4.x (Defined via the official Spring Cloud BOM)

The Spring Cloud BOM is the single source of truth for all Spring Cloud dependency versions.

Ignoring this compatibility:

• Breaks service discovery, config clients, or gateways.
• Leads to subtle runtime issues rather than compile-time errors.

Transitive dependency control

Microservices pull in hundreds of transitive dependencies.

Without strict version control:

• Different services may run with different library versions.
• Bugs appear only in distributed execution, not locally.

Version management strategy

• Use Maven dependency management (BOM import).
• Do not declare Spring Cloud module versions individually.
• Avoid overriding managed versions unless explicitly documented.

Constraints

• No mixing of Spring Boot versions across services.
• No snapshot or milestone dependencies.
• No unmanaged Spring Cloud artifacts.

Port standardization strategy

In microservice architectures, ports are part of the contract, not an implementation detail.

Standardized ports provide:

• Faster local development (no guesswork)
• Easier debugging and log correlation
• Predictable monitoring and tracing configuration
• Lower onboarding friction for new developers

The following standard port allocation is followed in this tutorial series.

Environment assumptions

OS-agnostic design, all commands and configurations are compatible with Linux, macOS and Windows (where applicable).

SDK

• Java JDK Version: Java 21 (LTS)
• Rationale:
  • Fully supported by Spring Boot 3.4.x
  • Long-term support and performance improvements
  • Modern language features without instability

Build tool

Maven is used throughout the tutorial for build and release.

• Reasons:
  • Industry standard in Spring ecosystems
  • Strong BOM and dependency management support
  • Easier onboarding for most Java developers

Naming & Configuration conventions

In distributed systems, naming is a coordination mechanism.

Without proper naming conventions:

• Configuration repositories become unmanageable
• Environment-specific bugs increase
• Operational clarity is lost as systems scale

While naming Applications, use clear, service-oriented names

• Example:
  • currency-exchange-service
  • currency-conversion-service

Follow below approach for naming default and environment specific Configuration Files.

• Default: application.yml
• Environment-specific:
  • application-dev.yml
  • application-test.yml
  • application-prod.yml

Profiles are used strictly for

• Environment-specific behavior
• Infrastructure differences

Note:
→ Do not use business logic divergence by profile.

Config Server repository

config-repo/
├── currency-exchange-service.yml
├── currency-conversion-service.yml
├── api-gateway.yml
└── application.yml

Security assumptions

• Early sections use simplified security
• OAuth2 / JWT introduced later
• Security is progressive, not ignored

Logging & Tracing

• Centralized logging is assumed conceptually
• Zipkin is used for distributed tracing
• Logs must include:
  • Service name
  • Instance identifier
  • Correlation IDs where applicable

Summary

This section defines the stable foundation on which all subsequent tutorials are built. Every architectural, configuration, and tooling decision made here is intentional and will not change arbitrarily.

Learners are encouraged to treat these boundaries as contracts, not suggestions.