Spring Boot Environment Variables: Externalized Configuration Guide for Production

Every production system I've worked on – from a SaaS billing platform processing $2M/month to a real-time analytics pipeline handling 50K events/sec – has one thing in common: configuration must change without code deploys. Hardcoding database URLs, API keys, or feature flags is a direct ticket to a pager-duty nightmare. Spring Boot's externalized configuration is your shield. It allows you to define defaults in application.properties, then override them with environment variables, command-line arguments, or profile-specific files at runtime. The Spring Environment abstraction merges these sources in a well-defined priority order: command-line args beat environment variables, which beat application.properties. This means you can ship the same artifact to dev, staging, and prod, and each environment configures itself through environment variables. But there's a catch – relaxed binding rules can trip you up. DB_URL becomes db.url, but DB_HOST becomes db.host. If you don't understand the binding rules, you'll waste hours debugging why my-app.database.url isn't overriding myapp.database.url. In this guide, I'll walk you through the mechanics, show you production patterns, and share war stories from incidents I've debugged at 3 AM. By the end, you'll externalize configuration like a senior engineer who's been burned one too many times.

Understanding Spring Boot's Property Resolution Order

Spring Boot merges configuration from multiple sources in a strict priority order. The highest priority wins. Here's the hierarchy from top (highest) to bottom (lowest): command-line arguments (--server.port=8081), JNDI attributes, system properties (-Dserver.port=8081), OS environment variables, application-{profile}.properties, application.properties, and @PropertySource on configuration classes. This means you can set a default port in application.properties as 8080, but if the production environment sets SERVER_PORT=8081 as an environment variable, Spring Boot will use 8081. The key insight: environment variables are case-insensitive and use relaxed binding. For example, SPRING_DATASOURCE_URL maps to spring.datasource.url. But be careful: MYAPP_DATABASE_URL maps to myapp.database.url (note the dot conversion from underscore). This is where most developers get confused. The binding rules convert uppercase to lowercase, replace underscores with dots, and remove hyphens. So MY-APP_DATABASE_URL becomes myapp.database.url. If you have a property like myapp.database-url, the environment variable MYAPP_DATABASEURL (no hyphen) won't work – you need MYAPP_DATABASE_URL. Always test your overrides by logging the resolved value.

import org.springframework.boot.CommandLineRunner;
import org.springframework.core.env.Environment;
import org.springframework.stereotype.Component;

@Component
public class PropertyResolutionDemo implements CommandLineRunner {

    private final Environment env;

    public PropertyResolutionDemo(Environment env) {
        this.env = env;
    }

    @Override
    public void run(String... args) {
        // Log resolved values to verify overrides
        String dbUrl = env.getProperty("spring.datasource.url");
        String serverPort = env.getProperty("server.port");
        System.out.println("Resolved DB URL: " + dbUrl);
        System.out.println("Resolved Server Port: " + serverPort);

        // Check if environment variable is present
        String envDbUrl = System.getenv("SPRING_DATASOURCE_URL");
        System.out.println("Env var SPRING_DATASOURCE_URL: " + envDbUrl);
    }
}

What the Official Docs Won't Tell You

The official Spring Boot documentation covers the basics well, but it glosses over the painful realities. First, environment variables from Docker or Kubernetes are injected as strings – even if you set SERVER_PORT=8081, Spring Boot treats it as a string and converts it internally. But if you have a custom property like myapp.feature.flag=true, the environment variable MYAPP_FEATURE_FLAG with value "true" (with quotes) will be a literal string "true" (including quotes), not a boolean. This happens when you use Docker Compose or Kubernetes ConfigMaps incorrectly. Second, the @Value annotation is fine for simple cases, but it doesn't support validation or complex types. I've seen teams use @Value("${myapp.database.url}") and then wonder why the application fails at startup with a missing property – the error message is cryptic. Third, profile-specific environment variables are a trap. You might set SPRING_PROFILES_ACTIVE=prod in the environment, but if you also have application-prod.properties with conflicting values, the profile-specific file wins over environment variables for the properties it defines. This leads to debugging nightmares. The fix: use @ConfigurationProperties with validation, log all resolved values, and never mix profile-specific files with environment variables for the same property.

import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.validation.annotation.Validated;
import jakarta.validation.constraints.NotBlank;
import jakarta.validation.constraints.Pattern;

@Validated
@ConfigurationProperties(prefix = "myapp.database")
public class DatabaseProperties {

    @NotBlank(message = "Database URL must not be blank")
    @Pattern(regexp = "^jdbc:mysql://.*", message = "URL must start with jdbc:mysql://")
    private String url;

    @NotBlank
    private String username;

    // Getters and setters
    public String getUrl() { return url; }
    public void setUrl(String url) { this.url = url; }
    public String getUsername() { return username; }
    public void setUsername(String username) { this.username = username; }
}

Using @Value vs @ConfigurationProperties for Environment Variables

The choice between @Value and @ConfigurationProperties depends on complexity. @Value is simple and works for single values: @Value("${myapp.api.key}") private String apiKey;. But it has limitations: no validation, no type conversion beyond basics, and it's hard to test because you can't easily mock the property source. @ConfigurationProperties is the enterprise-grade approach. It binds a group of related properties to a POJO with full validation support via Jakarta Bean Validation annotations. For example, you can define a PaymentGatewayProperties class with @NotBlank on the API key and @Min(1) on the retry count. The binding happens at startup, so failures are immediate and explicit. For environment variables, @ConfigurationProperties uses the same relaxed binding: PAYMENT_GATEWAY_API_KEY maps to payment.gateway.api-key if you set the prefix to payment.gateway. I recommend @ConfigurationProperties for any group of 2+ related properties. For single, simple properties (like a feature flag), @Value is fine – but always provide a default: @Value("${myapp.feature.new-checkout:false}"). One more thing: @Value doesn't support SpEL with environment variables directly – you need to use the Environment object for dynamic lookups.

import org.springframework.beans.factory.annotation.Value;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.stereotype.Component;
import jakarta.validation.constraints.Max;
import jakarta.validation.constraints.Min;

// Using @Value (simple, single property)
@Component
public class SimpleConfig {
    @Value("${myapp.feature.new-checkout:false}")
    private boolean newCheckoutEnabled;

    public boolean isNewCheckoutEnabled() { return newCheckoutEnabled; }
}

// Using @ConfigurationProperties (grouped, validated)
@Component
@ConfigurationProperties(prefix = "payment.gateway")
public class PaymentGatewayProperties {
    @Value("${payment.gateway.api-key}")
    private String apiKey;

    @Min(1) @Max(10)
    private int retryCount = 3;

    // getters and setters
    public String getApiKey() { return apiKey; }
    public void setApiKey(String apiKey) { this.apiKey = apiKey; }
    public int getRetryCount() { return retryCount; }
    public void setRetryCount(int retryCount) { this.retryCount = retryCount; }
}

Profile-Specific Configuration with Environment Variables

Spring Boot profiles allow you to define different configurations for different environments. You can have application-dev.properties, application-staging.properties, and application-prod.properties. But the real power comes from combining profiles with environment variables. Set the active profile via SPRING_PROFILES_ACTIVE environment variable. Then, environment variables can override profile-specific properties. For example, if application-prod.properties has myapp.database.url=jdbc:mysql://prod-db:3306/payments, you can override it with MYAPP_DATABASE_URL environment variable. The priority is: environment variable > profile-specific file > default file. This is useful for temporary overrides during incidents. But there's a common trap: if you define the same property in both application.properties and application-prod.properties, the profile-specific file wins over environment variables for that property? No – environment variables still win over profile-specific files. The confusion arises because developers often put all prod config in application-prod.properties and then try to override with environment variables, which works. But if you have a default in application.properties and a profile-specific override, the environment variable still wins. The real issue is when you have multiple profiles active – environment variables apply globally, not per profile. Use @Profile on beans to conditionally load components based on active profiles.

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Profile;

@Configuration
public class ProfileConfiguration {

    @Bean
    @Profile("dev")
    public DataSource devDataSource() {
        return new DataSource("jdbc:mysql://localhost:3306/dev");
    }

    @Bean
    @Profile("prod")
    public DataSource prodDataSource() {
        // URL comes from environment variable MYAPP_DATABASE_URL
        return new DataSource(System.getenv("MYAPP_DATABASE_URL"));
    }

    // application-dev.properties:
    // myapp.database.url=jdbc:mysql://localhost:3306/dev
    // application-prod.properties:
    // myapp.database.url=jdbc:mysql://prod-db:3306/payments
    // Environment variable MYAPP_DATABASE_URL overrides both
}

Security Best Practices for Sensitive Configuration

Never, ever hardcode secrets in application.properties or environment variables in plain text. I've seen production database passwords in Git history – it's a career-limiting move. For Spring Boot, use environment variables for secrets, but ensure they are injected securely. In Kubernetes, use Secrets (not ConfigMaps) for sensitive data. In Docker Compose, use .env files that are excluded from version control. For cloud platforms, use their secret management services (AWS Secrets Manager, Azure Key Vault, GCP Secret Manager). Spring Boot can integrate with these via Spring Cloud Config or custom PropertySource implementations. Another pattern: use environment variables to point to a secrets file or vault path. For example, MYAPP_SECRETS_PATH=/etc/secrets and then read the file at startup. Avoid passing secrets as command-line arguments – they are visible in process listings. Also, never log resolved secrets. I've seen teams log the entire configuration at startup, including passwords. Use a custom EnvironmentPostProcessor to mask sensitive values before logging. Finally, consider using Spring Cloud Vault for dynamic secrets that rotate automatically. It's overkill for small projects, but for enterprise systems handling PCI or PII data, it's mandatory.

import org.springframework.boot.SpringApplication;
import org.springframework.boot.env.EnvironmentPostProcessor;
import org.springframework.core.env.ConfigurableEnvironment;
import org.springframework.core.env.MapPropertySource;
import java.util.HashMap;
import java.util.Map;

public class SecureEnvironmentPostProcessor implements EnvironmentPostProcessor {

    private static final String[] SENSITIVE_KEYS = {"password", "secret", "key", "token"};

    @Override
    public void postProcessEnvironment(ConfigurableEnvironment environment, SpringApplication application) {
        // Mask sensitive values before logging
        Map<String, Object> masked = new HashMap<>();
        for (String key : environment.getPropertySources().stream()
                .flatMap(ps -> ((MapPropertySource) ps).getSource().keySet().stream())
                .toList()) {
            if (isSensitive(key)) {
                masked.put(key, "****");
            }
        }
        // In production, you'd log the masked map instead of the full environment
        System.out.println("Configuration loaded (sensitive values masked): " + masked);
    }

    private boolean isSensitive(String key) {
        String lower = key.toLowerCase();
        for (String sensitive : SENSITIVE_KEYS) {
            if (lower.contains(sensitive)) {
                return true;
            }
        }
        return false;
    }
}

Debugging Environment Variable Overrides in Production

When things go wrong – and they will – you need tools to debug configuration. Spring Boot Actuator exposes the /actuator/env endpoint that shows all property sources and their values. But in production, you should secure this endpoint with authentication and ideally mask sensitive values. You can also use the /actuator/configprops endpoint to see @ConfigurationProperties beans with their resolved values. For real-time debugging, I've used a custom endpoint that dumps the resolved configuration for a specific prefix. Another technique: add a startup listener that logs the effective configuration for critical properties. This is especially useful when you have multiple property sources and want to verify the override chain. For Kubernetes environments, use kubectl exec to check environment variables inside the pod: kubectl exec <pod> -- env | grep MYAPP. But remember that environment variables set by Kubernetes may differ from what Spring Boot resolves due to relaxed binding. The most reliable way is to use the /actuator/env endpoint or a custom health check that logs resolved values. One more thing: if you use Spring Cloud Config, the configuration is fetched at startup and cached. Environment variables won't override remote config unless you configure the priority correctly. I've spent hours debugging why an environment variable wasn't taking effect – turned out the remote config server had a higher priority.

import org.springframework.boot.actuate.endpoint.annotation.Endpoint;
import org.springframework.boot.actuate.endpoint.annotation.ReadOperation;
import org.springframework.core.env.Environment;
import org.springframework.stereotype.Component;
import java.util.HashMap;
import java.util.Map;

@Component
@Endpoint(id = "config-debug")
public class ConfigDebugEndpoint {

    private final Environment env;

    public ConfigDebugEndpoint(Environment env) {
        this.env = env;
    }

    @ReadOperation
    public Map<String, Object> debugConfig() {
        Map<String, Object> result = new HashMap<>();
        // Add critical properties for debugging
        result.put("spring.datasource.url", env.getProperty("spring.datasource.url"));
        result.put("myapp.feature.new-checkout", env.getProperty("myapp.feature.new-checkout"));
        result.put("activeProfiles", String.join(",", env.getActiveProfiles()));
        return result;
    }
}

Environment Variables in Docker and Kubernetes

Containerized environments add another layer of complexity. In Docker, you can pass environment variables via -e flag or an env file: docker run -e MYAPP_DATABASE_URL=jdbc:mysql://db:3306/app myapp:latest. In Docker Compose, use the environment key or env_file. In Kubernetes, use ConfigMaps for non-sensitive data and Secrets for sensitive data. Both can be injected as environment variables or mounted as files. The key difference: environment variables in Kubernetes are static – they are set when the pod starts and cannot change without restarting the pod. For dynamic configuration, use mounted files that a sidecar can update. Spring Boot can watch for file changes using spring.config.import=optional:file:/etc/config/ with spring.cloud.kubernetes.config enabled. Another gotcha: Kubernetes environment variable names must follow the DNS-1123 label format – uppercase letters, digits, and underscores only. No hyphens. So MYAPP-DATABASE-URL is invalid. Use MYAPP_DATABASE_URL instead. Also, if you use a ConfigMap with data field, the values are plain strings. If you use binaryData, they are base64-encoded. For Secrets, the values are base64-encoded in the YAML but decoded when injected as environment variables. Always verify the final value inside the pod.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: myapp
spec:
  template:
    spec:
      containers:
      - name: myapp
        image: myapp:1.0.0
        env:
        - name: SPRING_PROFILES_ACTIVE
          value: "prod"
        - name: MYAPP_DATABASE_URL
          valueFrom:
            secretKeyRef:
              name: db-secret
              key: url
        - name: MYAPP_DATABASE_USERNAME
          valueFrom:
            configMapKeyRef:
              name: app-config
              key: db-username
        envFrom:
        - configMapRef:
            name: app-config
        - secretRef:
            name: app-secrets

Advanced: Custom Property Sources and Spring Cloud Config

Sometimes environment variables aren't enough. You might need to fetch configuration from a remote source like a database, a REST API, or a vault. Spring Boot allows you to implement custom PropertySource objects that are added to the Environment. For example, you can create a DatabasePropertySource that reads configuration from a database table. Or integrate with Spring Cloud Config Server, which centralizes configuration for multiple microservices. Spring Cloud Config uses a Git backend by default, but you can also use JDBC, Redis, or Vault. The key concept: custom property sources can be ordered relative to environment variables. If you want your database configuration to override environment variables, add it with higher priority. But be careful: if you have multiple sources with the same property, the highest priority wins. I've seen teams create a custom source that loads secrets from AWS Secrets Manager and then wonder why environment variables don't override them – because the custom source was added with higher priority. Always define your priority strategy explicitly. Another advanced pattern: use @ConditionalOnProperty to conditionally enable beans based on environment variables. For example, enable a feature only if MYAPP_FEATURE_NEW_CHECKOUT=true. This is cleaner than if-else in code.

import org.springframework.core.env.PropertySource;
import org.springframework.stereotype.Component;

@Component
public class CustomPropertySource extends PropertySource<String> {

    public CustomPropertySource() {
        super("custom-database-source");
    }

    @Override
    public Object getProperty(String name) {
        // Simulate fetching from database
        if ("myapp.database.url".equals(name)) {
            return "jdbc:mysql://custom-db:3306/app";
        }
        if ("myapp.feature.flag".equals(name)) {
            return "true";
        }
        return null;
    }
}

// Register in configuration
@Configuration
public class CustomPropertySourceConfig implements EnvironmentAware {
    @Override
    public void setEnvironment(Environment environment) {
        ConfigurableEnvironment env = (ConfigurableEnvironment) environment;
        env.getPropertySources().addFirst(new CustomPropertySource());
    }
}