Spring Boot Config Data Migration Guide

Spring Boot Config Data Migration Guide

Spring Boot Config Data Migration Guide의 내용을 한글로 번역한 글입니다.

spring-projects/spring-boot

spring-projects/spring-boot

이 문서는 Spring Boot 2.4 이상에서 사용하기 위해 application.properties 및 application.yml 파일을 migration 하는데 도움을 주기 위한 것입니다.

Overview

Spring Boot 2.4는 application.properties 및 application.yml 파일이 처리되는 방식에 대한 정밀한 검사를 제공합니다.
업데이트된 로직은 외부 configuration이 로드되는 방식을 단순화하고 합리적 이도록 설계되었습니다.
또한 spring.config.import 지원과 같은 새로운 기능을 제공합니다.
업데이트된 디자인은 특정 속성 조합을 의도적으로 제한합니다. 즉 Spring Boot 2.3 또는 이전 버전에서 업그레이드할 때 몇 가지 사항을 변경해야 할 수 있습니다.

Legacy Mode

만약 application을 새로운 config data를 사용하도록 마이그레이션 할 준비가 되지 않은 경우 legacy mode로 전환해야 합니다.
이렇게 하려면 spring.config.use-legacy-processing property를 true로 설정해야 합니다.
property는 Spring Environment에서 설정되어야 합니다.
가장 쉬운 방법은 application.properties나 application.yml에 추가하는 것입니다.
예를 들면 src/main/resources/application.properties에 다음과 같이 추가하면 됩니다.

spring.config.use-legacy-processing=true

#any other properties

Simple Scenarios

많은 appilcation의 경우 기존 properties 파일을 변경할 필요가 없습니다.
특히 단일 application.properties 또는 application.yml 파일만 사용하는 경우, spring.profiles<.*> properties를 사용하지 않고 multi-document YAML을 사용하지 않으면 upgrade가 제대로 동작합니다.
advanced set-up이 있는 경우 이 문서의 나머지 부분에 있는 조언을 따라야 합니다.

Multi-document YAML Ordering

만약 multi-document YAML 파일을 사용하는 경우 ( ---- 구분자가 있는 파일) property source가 이제 문서가 선언된 순서대로 추가된다는 점을 알고 있어야 합니다.
Spring Boot 2.3 및 이전 버전에서는 profile activation order에 따라 개별 document가 추가되었습니다.
만약 각각의 properties를 override 하는 경우 "win"하려는 properties가 file에서 아래에 있는지 확인해야 합니다.
이는 YAML 내부의 문서를 다시 재 정렬할 수도 있다는 것을 의미합니다.

Profile Specific External Configuration

만약 jar 외부의 configuration을 사용하고 profile에 특정한 configuration file을 사용하는 경우 properties가 의도한 대로 로드되는지 확인하여야 합니다.
이전 버전의 Spring Boot의 경우 jar 외부의 application.properties file은 jar 내부의 appication-<profile>.properties를 override하지 않았습니다.
Spring Boot 2.4부터 외부의 file은 언제나 package의 file을 override 합니다. (profile에 특정되거나 또는 그렇지 않더라도)
이에 관련한 좀 더 자세한 변경 사항은 Github Issue 3845에서 확인할 수 있습니다.
또한 update 된 documentation에서 변경된 ordering에 대한 설명을 확인할 수 있습니다.

Profile Specific Documents

만약 multi-document YAML file과 같은 곳에서 spring.profiles property를 사용하고 있다면 spring.config.active.on-profile로 마이그레이션 해야 합니다.
이전 property와 마찬가지로 properties를 적용하기 위해 활성화해야 하는 profile list를 지정할 수 있습니다.
또한 (prod & cloud)와 같은 profile expression을 사용할 수 있습니다.

예를 들어 application.yaml에 아래와 같이 사용하였다면

spring:
  profiles: "prod"
secret: "production-password"

아래와 같이 migration 해주어야 합니다.

spring:
  config:
    activate:
      on-profile: "prod"
secret: "production-password"

Profile Activation

여전히 spring.profiles.active property를 사용하여 특정 profile을 활성화할 수 있습니다.
예를 들면 command line에서 다음처럼 실행할 수 있습니다.

$ java -jar myapp.jar --spring.profiles.active=prod

application.properties나 application.yaml에 설정할 수도 있지만 Spring Boot 2.4에서는 profile 별 문서에서 property를 설정할 수 없습니다.
즉,. 더 이상 spring.config.active.on-profile property가 있는 문서와 함께 사용할 수는 없습니다.

마찬가지로 spring.profiles.include property를 계속 사용할 수 있지만 profile에 특정되지 않은 문서에서만 사용할 수 있습니다.

예를 들어 아래 두번째 설정은 유효하지 않습니다.

# this document is valid
spring:
  profiles:
    active: "prod"

---

# this document is invalid
spring:
  config:
    activate:
      on-profile: "prod"
  profiles:
    include: "metrics"

이 제한을 도입한 이유는 on-profile condition이 한번만 평가되기 때문입니다.
이 제한이 없으면 spring.config.activate.on-profile 표현식이 평가 시기에 따라 다른 결과를 반환할 수 있습니다.

Profile Groups

Spring Boot 2.3 이전에 사용자들은 종종 active profile을 확장하기 위해 spring.profiles를 spring.profiles.include와 함께 결합하여 사용하였습니다.

예를 들면 아래와 같은 applicaiton.yaml file이 있을 수 있습니다.

spring.profiles: "debug"
spring.profiles.include: "debugdb,debugcloud"

이를 통해 java -jar --spring.profiles.active=debug를 실행하면 자동으로 debug, debugdb 그리고 debugcloud profile을 활성화 할 수 있었습니다.

이 예제를 Spring Boot 2.4 application.yaml로 migration 하면 다음과 같습니다.

spring:
  config:
    activate:
      on-profile: "debug"
  profiles:
    include: "debugdb,debugcloud"

위에서 설명한 바와 같이 profile 별 문서에서 spring.propfiles.include를 더 이상 사용할 수 없으므로 이 파일은 유효하지 않습니다.

이 사용 사례는 매우 일반적이므로 이를 지원하는 다른 방법을 제공하려고 노력했습니다.
Spring Boot 2.4에서는 profile groups 기능을 사용할 수 있습니다.

profile group을 사용하면 다음과 같이 말할 수 있습니다.

profile 'x'가 표시되면 'y' 및 'z' profile도 활성화 합니다.

profile group은 spring.profiles.group.<source> property로 정의됩니다.
예를 들어 위의 구성은 다음과 같이 작성됩니다.

spring:
  profiles:
    group:
      "debug": "debugdb,debugcloud"

spring.profile.group property는 profile 특정 문서에서 사용할 수 없습니다.
spring.config.activate.on-profile 속성이 있는 문서에서는 사용할 수 없습니다.

Migration Example

Spring Boot 2.3 application의 migration 예제를 살펴보겠습니다.
다음과 같은 jar 내부에 application.yaml과 함께 제공되는 application이 있다고 가정합니다.

spring.application.name: "customers"
---
spring.profiles: "production"
spring.profiles.include: "mysql,rabbitmq"
---
spring:
  profiles: "mysql"
  datasource:
    url: "jdbc:mysql://localhost/test"
    username: "dbuser"
    password: "dbpass"
---
spring:
  profiles: "rabbitmq"
  rabbitmq:
    host: "localhost"
    port: 5672
    username: "admin"
    password: "secret"

또한 app이 배포될 때 jar 옆에 application-prod.yaml file이 포함되어 있습니다.

spring:
  datasource:
    username: "proddbuser"
    password: "proddbpass"
  rabbitmq:
    username: "prodadmin"
    password: "prodsecret"

application을 migration 하려면 jar에 packasge된 application.yaml을 업데이트 하여 new property name을 사용할 수 있습니다.

spring.application.name: "customers"
---
spring:
  config:
    activate:
      on-profile: "production"
  profiles:
    include: "mysql,rabbitmq"
---
spring:
  config:
    activate:
      on-profile: "mysql"
  datasource:
    url: "jdbc:mysql://localhost/test"
    username: "dbuser"
    password: "dbpass"
---
spring:
config:
  activate:
    on-profile: "rabbitmq"
  rabbitmq:
    host: "localhost"
    port: 5672
    username: "admin"
    password: "secret"

이 것은 우리가 profile 특정 문서에서 spring.profiles.include를 사용하려고 시도한 것을 제외하고는 거의 동작합니다.
profile group을 사용하여 해당 속성을 migration 할 수 있습니다.

spring:
  application:
    name: "customers"
  profiles:
    group:
      "production": "mysql,rabbitmq"
---
spring:
  config:
    activate:
      on-profile: "mysql"
  datasource:
    url: "jdbc:mysql://localhost/test"
    username: "dbuser"
    password: "dbpass"
---
spring:
config:
  activate:
    on-profile: "rabbitmq"
  rabbitmq:
    host: "localhost"
    port: 5672
    username: "admin"
    password: "secret"

이 시점에서 migration이 완료되었으며 이전과 동일하게 동작해야 합니다.
production instance는 일반적인 방법(예: SPRING_PROFILES_ACTIVE=prod system environment variable)으로 profile을 설정할 수 있으며 이전 application-prod.yaml 파일이 선택됩니다.

원한다면 Spring Boot 2.4에서는 모든 외부 파일이 내부 파일을 재정의하므로 applicadtion-prod.yaml의 이름을 application.yaml로 바꿀 수 있습니다.