Spring Boot 애플리케이션 프로퍼티 외부화 모범 사례

소개

애플리케이션 설정을 코드와 분리하는 것은 운영과 개발 모두에 유리하다. Spring Boot에서는 다양한 방식으로 구성 값을 외부화할 수 있다. 이 글은 spring boot externalize properties 관점에서 시작해 실제 운영에서 도움이 되는 실무 중심의 권장 방식을 설명한다.

외부화가 필요한 이유

환경 분리

개발, 테스트, 운영 환경마다 설정이 달라진다. 설정을 외부로 빼면 빌드 산출물을 그대로 여러 환경에 배포할 수 있다. 이렇게 하면 배포 파이프라인이 단순해진다.

보안과 유연성

데이터베이스 비밀번호나 API 키 같은 민감 정보는 코드 저장소에 남기면 위험하다. 환경 변수나 비밀 관리 시스템을 이용해 민감 정보를 분리하면 보안 수준이 올라간다.

외부화 방법별 특징

application.properties / application.yml

로컬 개발에서 가장 간단한 방법이다. Spring Boot는 classpath와 외부 디렉토리의 설정 파일을 우선순위에 따라 로드한다. 그러나 파일 기반은 민감 정보 관리에 한계가 있다.

환경 변수와 커맨드라인 인자

컨테이너화된 환경에서 널리 쓰인다. 환경 변수는 배포 도구와 자연스럽게 통합된다. 또한 도커와 쿠버네티스에서 시크릿과 연계하기도 용이하다.

Spring Cloud Config

중앙 집중형 설정 관리가 필요할 때 유용하다. 여러 서비스가 공통 설정을 공유하거나 버전 관리를 하고 싶은 경우 선택지다. 보안, 캐시, 동적 리프레시 같은 추가 기능을 제공한다.

비밀 저장소(Vault, AWS Secrets Manager 등)

민감 정보는 전용 비밀관리 솔루션에 보관하는 것이 권장된다. 접근 제어와 감사 로그 기능을 통해 보안 요구사항을 충족할 수 있다.

구현 예제

간단한 YAML 예제와 @ConfigurationProperties 사용법을 통해 외부화 흐름을 확인한다.

spring:
  datasource:
    url: jdbc:postgresql://db.example.com:5432/mydb
    username: app_user
    password: ${DB_PASSWORD:}

app:
  feature:
    enabled: true

위 예제에서 password는 환경 변수 DB_PASSWORD로 대체된다. 기본값을 비워두면 외부 주입을 강제하는 효과가 있다.

@org.springframework.boot.context.properties.ConfigurationProperties(prefix = "app")
@org.springframework.stereotype.Component
public class AppProperties {
    private Feature feature = new Feature();

    public static class Feature {
        private boolean enabled;
        public boolean isEnabled() { return enabled; }
        public void setEnabled(boolean enabled) { this.enabled = enabled; }
    }

    public Feature getFeature() { return feature; }
    public void setFeature(Feature feature) { this.feature = feature; }
}

이 방식은 타입 안전한 구성 접근을 제공한다. 테스트와 문서화에도 도움이 된다.

운영 관점의 spring boot config best practices

• 환경별 설정은 profiles로 분리한다. profile 활성화로 환경 전환이 명확해진다.
• 민감 정보는 비밀 관리 솔루션으로 옮긴다. 키 값은 런타임에 주입한다.
• 설정 우선순위를 명확히 한다. 문서에 우선순위 규칙을 명시하면 혼동이 줄어든다.
• 동적 변경이 필요하면 Spring Cloud Config의 refresh 기능을 검토한다.
• 버전 관리가 필요한 공통 설정은 중앙 저장소(git)를 사용한다. 접근 제어를 적용한다.
• 컨테이너 환경에서는 환경 변수와 시크릿 매커니즘을 표준으로 정한다.
• 테스트 환경에서는 로컬 오버라이드를 허용하되, 민감 정보는 제외한다.
• 설정값의 기본값을 명확히 정의해 예상치 못한 동작을 방지한다.

운영 예시와 체크리스트

배포 전 점검 항목은 다음과 같다.

• 민감 정보가 코드 저장소에 포함되어 있지 않은지 확인
• 프로파일이 올바르게 설정되어 있는지 확인
• 중앙 설정을 사용하는 경우 권한과 암호화 설정 확인
• 로깅과 모니터링에서 설정 변경 이력을 추적할 수 있는지 확인

마무리

application properties 외부화는 단순한 작업처럼 보이지만, 운영 안정성과 보안에 큰 영향을 준다. spring boot externalize properties와 spring boot config best practices를 바탕으로 환경 분리, 민감 정보 관리, 중앙화된 구성 전략을 균형 있게 설계하면 운영 리스크를 줄일 수 있다.