Proper Usage of Environment Variables in Spring Boot YAML Configuration Files

Core Issues with Environment Variables in YAML Configuration

During Spring Boot application development, many developers encounter issues where environment variables fail to resolve properly in application.yml files. This often stems from misunderstandings about Spring's property placeholder syntax. Spring Boot employs specific ${} syntax to reference environment variables, which differs from the syntax used in some other frameworks.

Correct Environment Variable Reference Syntax

Spring Boot uses standard property placeholder syntax to reference environment variables. The correct format is ${VARIABLE_NAME}, where VARIABLE_NAME is the name of the environment variable. For example, when configuring server address and port:

spring:
  profiles: production
server:
  address: ${OPENSHIFT_DIY_IP}
  port: ${OPENSHIFT_DIY_PORT}

This syntax allows Spring Boot to retrieve corresponding values from environment variables at runtime and inject them into configuration properties.

Default Value Setting Mechanism

Spring Boot also supports setting default values for environment variables, which is particularly useful when environment variables are undefined. The syntax format is ${VARIABLE_NAME:default_value}. For example, in log level configuration:

logging:
  level:
    root: ${LOGGING_LEVEL_ROOT:info}

When the LOGGING_LEVEL_ROOT environment variable does not exist, the system will use the default value info. This mechanism ensures that applications can still operate normally when specific environment configurations are lacking.

Spring Boot Property Resolution Priority

Understanding Spring Boot's property source priority is crucial for proper environment variable configuration. Spring Boot checks various property sources in a specific order, with later sources able to override values from earlier ones. The complete property source order includes: command line arguments, JNDI properties, Java system properties, operating system environment variables, configuration file properties, and more.

Environment variables have relatively high priority in the property source order, meaning they can override default values defined in application.yml files. This design enables flexible configuration adjustments across different deployment environments.

Configuration Examples and Best Practices

In practical applications, it's recommended to manage sensitive information and environment-related configurations through environment variables, while retaining application default configurations in YAML files. For example:

database:
  url: ${DATABASE_URL:jdbc:postgresql://localhost:5432/mydb}
  username: ${DB_USERNAME:admin}
  password: ${DB_PASSWORD:secret}

server:
  port: ${SERVER_PORT:8080}
  address: ${SERVER_ADDRESS:0.0.0.0}

This configuration approach ensures both development environment convenience and production environment security requirements.

Troubleshooting and Validation

When environment variables fail to resolve correctly, you can use Spring Boot Actuator's /actuator/env endpoint to inspect all property values in the current environment. Additionally, ensure that environment variable names exactly match reference names, including case sensitivity.

In containerized deployment environments, it's also necessary to confirm that environment variables are properly set and passed to the application process. Verifying actual environment variable values through log output or debugging tools is an effective method for problem investigation.