환경 변수

개요

프로젝트를 렌더링할 때마다 반드시 설정되도록 하고 싶은 환경 변수가 있을 수 있습니다. 예를 들어 환경 변수를 다음과 같은 용도로 사용할 수 있습니다.

  1. 데이터를 다운로드할 서버의 URL 제공
  2. 프록시 서버 주소 설정(예: HTTP_PROXY)
  3. 원격 서버 접근 자격 증명 제공(아래에서 환경 변수에 저장된 자격 증명 사용 모범 사례를 다룹니다)
  4. 실행 코드 동작 튜닝(예: OMP_NUM_THREADS, ARROW_IO_THREADS 등)
  5. 언어 인터프리터 옵션 제공(예: PYTHONINSPECT, TZDIR)
  6. 사용할 Python과 R 버전 결정(예: QUARTO_PYTHON, QUARTO_R, PY_PYTHON, RETICULATE_PYTHON)

Quarto 프로젝트는 표준 환경 변수 세트를 정의할 수 있고, 활성 프로젝트 프로필에 따라 환경 변수를 다르게 정의할 수도 있습니다. 또한 로컬 시스템에만 정의되고 버전 관리에 포함되지 않는 환경 변수를 사용할 수도 있습니다.

환경 파일

프로젝트 루트에 _quarto.yml과 함께 _environment 파일을 두면, 프로젝트 구성을 읽을 때 파일에 정의된 값이 환경 변수로 설정됩니다. 예:

_environment
HTTP_PROXY="https://proxy.example.com/"
OMP_NUM_THREADS=4

이 환경 변수는 Quarto 실행 컨텍스트와 하위 프로세스(예: Jupyter 커널) 모두에서 사용할 수 있습니다.

환경 파일에 정의된 변수는 외부 환경에 이미 존재하는 정의보다 우선하지 않습니다. 대신 같은 이름의 외부 변수가 없을 때 적용되는 기본값을 제공합니다.

환경 파일에 주석을 추가하거나 다른 환경 변수를 참조할 수 있습니다. 예:

_environment
# database server
DATABASE_SERVER=https://db.example.com
DATABASE_API=${DATABASE_SERVER}/api

다른 환경 변수를 참조할 때는 같은 파일에 정의되어 있거나 외부 환경에 이미 존재해야 합니다. 환경 파일 문법에 대한 자세한 내용은 환경 변수 파싱 규칙을 참고하세요.

프로필 환경

프로젝트 프로필을 사용해 다양한 상황에 맞게 프로젝트를 조정한다면, 프로필과 함께 활성화되는 사용자 정의 환경 파일을 만들 수 있습니다. 예를 들어 production 프로필이 있다면 _environment-production에 정의한 변수가 읽혀 적용됩니다.

여기서는 OMP_NUM_THREADS 환경 변수를 사용자 지정해 운영 환경에서 더 많은 코어를 사용하도록 합니다.

_environment-production
OMP_NUM_THREADS=16

프로필 환경은 기본 _environment와 병합되므로, 프로필에서 달라지는 변수만 정의하고 나머지는 기본값에 의존할 수 있습니다.

Important

환경 변수로 지정해야 하는 비밀(예: 액세스 토큰)이 있다면 프로필 환경을 사용하지 않는 것이 좋습니다(대개 버전 관리에 포함되기 때문). 이에 대한 권장 기법은 아래 비밀 관리에서 다룹니다.

로컬 환경

프로젝트를 로컬에서 작업할 때 일부 환경 변수는 다른 값을 쓰고 싶을 수 있습니다. 예를 들어 Python 실행에 대한 추가 진단 출력을 제공하는 변수를 추가할 수 있습니다.

이를 위해 _environment.local 파일을 만들 수 있습니다. 로컬 파일의 값은 기본 파일의 값을 덮어씁니다.

_environment.local
PYTHONDEVMODE=1

_environment.local은 버전 관리에 포함하도록 의도된 파일이 아닙니다. 대신 내 시스템에서만 활성화하고 싶은 값에 사용합니다. 이를 위해 Quarto가 프로젝트 .gitignore에 다음 항목을 자동으로 추가합니다.

.gitignore
/_*.local

이는 환경 변수에 비밀이 포함되어 있을 때 특히 유용하며, 다음 섹션에서 더 자세히 살펴봅니다.

비밀 관리

자격 증명이나 인증 토큰은 자주 환경 변수를 통해 코드에 전달됩니다. 많은 경우 이러한 자격 증명은 프로젝트 렌더링에 필요합니다(예: 프로젝트가 원격 데이터베이스나 웹 서비스에 접근하는 경우).

이러한 자격 증명이 버전 관리에 포함되지 않도록 하는 것이 특히 중요합니다. 보통 다음을 조합해 해결합니다.

  1. 서버나 CI 서비스에서 실행할 때는 환경 변수를 암호화된 비밀로 제공합니다. 방법은 서비스마다 다릅니다(GitHub Actions는 암호화된 비밀, Posit Connect는 콘텐츠 변수 지원 등).

  2. 로컬 개발에서는 _environment.local 파일에 변수를 정의합니다(Quarto는 기본적으로 이 파일을 버전 관리에서 제외). 예를 들어 로컬 환경 파일에 AWS 자격 증명을 지정할 수 있습니다.

    _environment.local
    AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI

한 가지 남는 문제는 이러한 변수가 항상 지정되도록 보장하는 것입니다. 다음 섹션의 필수 변수에서 이를 해결하는 방법을 설명합니다.

필수 변수

프로젝트를 렌더링하려면 반드시 지정해야 하는 환경 변수가 있다면 _environment.required 파일을 만들 수 있습니다. 이 파일은 로컬 작업의 시작점으로 _environment.local에 복사할 수 있으며, 서버 환경에서 어떤 변수가 필요한지에 대한 문서 역할도 합니다.

AWS 자격 증명 예시로 돌아가면, _environment.required 파일은 프로젝트 렌더링에 이 자격 증명이 필요함을 문서로 제공합니다.

_environment.required
AWS_ACCESS_KEY_ID=
AWS_SECRET_ACCESS_KEY=

그 다음 .local 파일(역시 버전 관리에 포함되지 않음)에 실제 자격 증명을 채웁니다.

_environment.local
AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI

또한 이 프로젝트를 렌더링하려는 모든 서버 환경은 필수 변수가 지정되었는지 검증할 수 있으며, 지정되지 않았다면 적절한 오류 메시지와 함께 실행을 실패하게 할 수 있습니다.