환경 시스템

환경 엔트리를 사용하면 런타임 코드가 공개 변수 이름이나 레지스트리 엔트리 ID로 설정을 참조할 수 있습니다.

이 페이지는 설정 레퍼런스입니다. YAML 펜스는 둘러싼 문서를 명시하지 않는 한 엔트리 조각입니다.

스토리지와 접근

환경 시스템은 스토리지와 접근을 분리합니다:

• 스토리지 - 값이 저장되는 곳 (OS, 파일, 메모리)
• 변수 - 스토리지의 값에 대한 명명된 참조

변수는 다음으로 참조할 수 있습니다:

• 공개 이름 - variable 필드 값
• 엔트리 ID - 전체 namespace:name 참조

변수를 엔트리 ID로만 접근해야 한다면 variable 필드를 생략하세요. 공개 이름을 먼저 차지한 변수가 그 단축 이름을 유지합니다. 같은 공개 이름을 사용하는 이후 변수도 등록되고 엔트리 ID로 접근할 수 있지만, 기존 단축 이름을 대체하지 않습니다.

엔트리 종류

스토리지 백엔드

메모리 스토리지

휘발성 인메모리 스토리지.

- name: runtime_env
  kind: env.storage.memory

파일 스토리지

간단한 KEY=VALUE 형식을 사용하는 영구 스토리지입니다. 빈 줄과 #으로 시작하는 줄은 무시되며, 값 줄에서 # 뒤의 텍스트는 주석으로 처리됩니다. 따옴표 값과 이스케이프 시퀀스는 특별하게 파싱되지 않습니다.

- name: app_config
  kind: env.storage.file
  file_path: /etc/app/config.env
  auto_create: true
  file_mode: 0600
  dir_mode: 0700

OS 스토리지

운영 체제 환경 변수에 대한 읽기 전용 접근.

- name: os_env
  kind: env.storage.os

항상 읽기 전용입니다. 설정 작업은 PERMISSION_DENIED를 반환합니다.

정적 스토리지

설정에 직접 정의된 값을 가진 읽기 전용 스토리지입니다. 값은 엔트리에 포함되며 런타임에 변경할 수 없습니다. 모듈이나 팩과 함께 배포되는 공개 설정 상수에 유용합니다.

- name: defaults
  kind: env.storage.static
  values:
    PUBLIC_API_HOST: "https://api.example.com"
    PUBLIC_WS_HOST: "wss://api.example.com/ws"
    APP_ENV: "production"

항상 읽기 전용입니다. 설정 작업은 PERMISSION_DENIED를 반환합니다.

라우터 스토리지

라우터는 여러 스토리지를 연결합니다. 캐시 미스가 발생하면 값을 찾을 때까지 순서대로 읽으며, 성공한 값은 라우터가 캐시하므로 이후 백엔드 스토리지의 직접 변경은 해당 라우터를 통해 보이지 않습니다. NOT_FOUND 이외의 오류는 폴백 검색을 중단합니다. 쓰기는 첫 번째 스토리지만 대상으로 합니다.

- name: config
  kind: env.storage.router
  storages:
    - app.config:memory    # Primary (writes here)
    - app.config:file      # Fallback
    - app.config:os        # Fallback

변수

변수는 공개 이름 또는 엔트리 ID를 스토리지 백엔드의 값에 매핑합니다.

- name: DATABASE_URL
  kind: env.variable
  variable: DATABASE_URL
  storage: app.config:file
  default: postgres://localhost/app
  readonly: false

변수 명명

변수 이름은 다음만 포함해야 합니다: a-z, A-Z, 0-9, _

접근 패턴

# Public variable - accessible by name "PORT"
- name: port_var
  kind: env.variable
  variable: PORT
  storage: app.config:os
  default: "8080"

# Private variable - accessible only by ID "app.config:internal_key"
- name: internal_key
  kind: env.variable
  storage: app.config:secrets

플레이스홀더 보간

등록된 변수는 ${env:NAME} 플레이스홀더로 엔트리 설정에 주입되며, 이 레지스트리를 기준으로 디코드 시점에 중앙에서 해석됩니다. 엔트리 종류가 불투명 필드로 표시한 경우를 제외하고 엔트리 설정 문자열이 해석됩니다. template.jet.source 같은 소스 필드는 불투명하므로 템플릿이나 프로그램 텍스트가 재작성되지 않습니다.

NAME은 등록된 변수의 공개 이름 또는 그 엔트리 ID(점/콜론을 포함한 레지스트리 id 형식, 예: app.env:tls_cert)입니다. 원시 OS 환경 변수가 아닙니다: OS 값은 해당 이름으로 env.storage.os 기반 변수가 등록된 경우에만 접근할 수 있습니다.

- name: api
  kind: http.service
  addr: ":443"
  tls:
    mode: manual
    cert: ${env:app.env:tls_cert}
    key:  ${env:app.env:tls_key}

전체 값이 단일 플레이스홀더인 필드는 인라인 기본값의 타입을 취합니다. 예를 들어 ${env:PORT|8080}은 정수를 생성하고 저장된 값을 정수로 강제 변환하지만, ${env:PORT|"8080"}은 문자열로 유지됩니다. 주변 텍스트와 섞인 플레이스홀더는 항상 문자열을 생성합니다. 변수 자체의 default가 플레이스홀더의 인라인 |default보다 먼저 적용됩니다. 아무것도 해석되지 않고 기본값도 없는 참조는 디코딩에 실패합니다.

해석은 디코드 시점에만 일어납니다: 저장된 레지스트리 엔트리는 원시 플레이스홀더를 유지하므로, 해석된 시크릿은 registry.get 결과나 영속 상태에 절대 나타나지 않습니다. 엔트리 ID로 변수를 참조하면(${env:ns:name}) 부트 시 해당 변수 뒤로 자동으로 정렬됩니다. 공개 이름으로 참조하면 의존성 엣지가 생기지 않습니다.

에러

런타임 접근

• env 모듈 - Lua 런타임 접근

참고

• 보안 모델 - 환경 변수에 대한 접근 제어
• 설정 가이드 - 애플리케이션 설정 패턴