Composer 로컬 개발 CLI 도구를 사용하여 로컬 Airflow 환경 실행

Managed Airflow (3세대) | Managed Airflow (2세대) | Managed Airflow (기존 1세대)

이 섹션에서는 Composer 로컬 개발 CLI 도구를 사용하여 로컬 Airflow 환경을 만들고 구성하고 실행하는 방법을 설명합니다.

Composer 로컬 개발 CLI 도구 정보

Composer 로컬 개발 CLI 도구는 Airflow 환경을 로컬에서 실행하여 관리형 Airflow의 Apache Airflow DAG 개발을 간소화합니다. 이 로컬 Airflow 환경은 특정 Managed Airflow 버전에서 사용하는 Managed Airflow 이미지를 사용합니다.

기존 Managed Airflow 환경을 기반으로 로컬 Airflow 환경을 만들 수 있습니다. 이 경우 로컬 Airflow 환경은 Managed Airflow 환경에서 설치된 PyPI 패키지 및 환경 변수 이름의 목록을 가져옵니다.

새로운 DAG 코드, PyPI 패키지 또는 Airflow 구성 옵션을 테스트하는 등의 테스트 및 개발 목적으로 이 로컬 Airflow 환경을 사용할 수 있습니다.

시작하기 전에

  • Composer 로컬 개발 CLI 도구는 composer-dev create 명령어를 실행하는 디렉터리에 로컬 Airflow 환경을 만듭니다. 나중에 로컬 Airflow 환경에 액세스하려면 처음 로컬 환경을 만든 경로에서 도구 명령어를 실행합니다. 로컬 환경의 모든 데이터는 로컬 환경을 만든 경로인 ./composer/<local_environment_name>에 있는 하위 디렉터리에 저장됩니다.

  • 컴퓨터에 Managed Airflow 이미지를 저장하기에 충분한 디스크 공간이 있어야 합니다. Composer 로컬 개발 CLI 도구는 각 Managed Airflow 버전에 대해 하나의 이미지 파일을 저장합니다. 예를 들어 Managed Airflow 버전이 서로 다른 로컬 Airflow 환경이 두 개 있으면 Composer 로컬 개발 CLI 도구는 두 개의 Managed Airflow 이미지를 저장합니다.

  • Composer 로컬 개발 CLI 도구는 색상 출력을 사용합니다. 다음과 같이 NO_COLOR=1 변수를 사용하여 색상 출력을 사용 중지할 수 있습니다. NO_COLOR=1 composer-dev <other commands>.

  • 로컬 환경이 하나만 있는 경우 run-airflow-cmd를 제외한 모든 composer-dev 명령어에서 로컬 환경의 이름을 생략할 수 있습니다.

  • Composer 로컬 개발 CLI 도구 종속 항목을 설치합니다.

  • Docker (Linux/macOS/Windows) 또는 Podman(Linux 또는 Windows)이 컴퓨터에 설치되어 실행 중이어야 합니다.

    Docker 또는 Podman이 실행 중인지 확인하려면 docker ps 또는 podman ps과 같은 Docker CLI 또는 Podman CLI 명령어를 실행합니다. 별도로 지정하지 않는 한 모든 안내는 Docker와 Podman 모두에 적용되며 모든 Docker 명령어는 이에 상응하는 Podman 명령어로 대체할 수 있습니다.

사용자 인증 정보 구성

아직 설정하지 않았다면 애플리케이션 기본 사용자 인증 정보에 사용할 새로운 사용자 인증 정보를 가져옵니다.

gcloud auth application-default login

Google 계정을 사용하여 gcloud CLI에 로그인합니다.

gcloud auth login

Composer 로컬 개발 CLI 도구와 DAG에서 수행하는 모든 API 호출은 gcloud CLI에서 사용하는 계정에서 실행됩니다. 예를 들어 로컬 Airflow 환경의 DAG가 Cloud Storage 버킷의 콘텐츠를 읽는 경우 이 계정에 버킷 액세스 권한이 있어야 합니다. 이와 달리 Managed Airflow 환경에서는 환경의 서비스 계정이 호출을 수행합니다.

Composer 로컬 개발 CLI 도구 설치

Composer 로컬 개발 CLI 저장소를 클론합니다.

git clone https://github.com/GoogleCloudPlatform/composer-local-dev.git

클론된 저장소의 최상위 디렉터리에서 다음을 실행합니다.

pip install .

pip 구성에 따라서는 도구가 설치된 경로가 PATH 변수에 없을 수 있습니다. 이 경우 pip에 경고 메시지가 표시됩니다. 이 경고 메시지의 정보를 사용하여 운영체제의 PATH 변수에 이 디렉터리를 추가할 수 있습니다.

(Podman) Podman 구성

Podman을 사용하는 경우 다음 단계에 따라 구성하세요.

Linux

  1. Podman 사용자 서비스 소켓을 사용 설정합니다.

    composer-dev CLI는 표준 Docker API 호출을 통해 통신합니다. Docker 데몬을 모방하려면 사용자 수준에서 Podman의 백그라운드 서비스 소켓 래퍼를 활성화해야 합니다.

    먼저 사용자 수준 소켓이 이미 활성 상태인지 확인합니다.

    systemctl --user is-active podman.socket

    명령어가 inactive 또는 failed를 반환하는 경우 소켓을 사용 설정하고 시작합니다.

    # Enable and start Podman's user-level systemd socket
systemctl --user enable --now podman.socket

  2. Podman의 환경 변수를 구성합니다.

    셸 구성 파일(예: .bashrc 또는 .zshrc)에 다음 명령어를 추가합니다.

    export DOCKER_HOST="unix:///run/user/$UID/podman/podman.sock"

Windows

  1. WSL 2 구성 (.wslconfig)을 설정합니다. Podman 머신을 초기화하기 전에 WSL 2에 정의된 메모리 및 스왑 경계가 있는지 확인하세요. 이 기능이 없으면 멀티 컨테이너 배포로 인해 이미지 추출 중에 메모리 급증이 발생할 수 있습니다. 동시 다운로드 제한을 설정하는 것도 중요합니다.

    %USERPROFILE%\.wslconfig 파일을 변경하거나 만듭니다.

    [wsl2]
memory=4GB
swap=2GB

[registry]
max_concurrent_downloads = 2

  2. PowerShell에서 Podman 머신을 초기화합니다.

    podman machine init

  3. 머신을 시작합니다.

    podman machine start

이 단계를 완료하면 composer-dev CLI 명령어를 사용할 수 있습니다. 이 도구는 Windows에서 Podman 환경을 자동으로 감지하고 아키텍처 매핑을 조정합니다.

Managed Airflow 이미지로 로컬 Airflow 환경 만들기

사용 가능한 Managed Airflow 이미지를 나열하려면 다음을 실행합니다.

composer-dev list-available-versions --include-past-releases --limit 10

기본 매개변수로 로컬 Airflow 환경을 만들려면 다음을 실행합니다.

composer-dev create \
  --from-image-version IMAGE_VERSION \
  LOCAL_ENVIRONMENT_NAME

기타 매개변수:

composer-dev create LOCAL_ENVIRONMENT_NAME \
  --from-image-version IMAGE_VERSION \
  --project PROJECT_ID \
  --port WEB_SERVER_PORT \
  --dags-path LOCAL_DAGS_PATH \
  --plugins-path LOCAL_PLUGINS_PATH \
  --database DATABASE_ENGINE \
  --editable-dependencies EDITABLE_DEPENDENCY_PATH

다음과 같이 바꿉니다.

  • LOCAL_ENVIRONMENT_NAME을 이 로컬 Airflow 환경의 이름으로 바꿉니다.
  • IMAGE_VERSION을 Managed Airflow 이미지의 이름으로 바꿉니다.
  • PROJECT_ID를 프로젝트 ID로 바꿉니다.
  • WEB_SERVER_PORT를 Airflow 웹 서버가 리슨해야 하는 포트로 바꿉니다.
  • LOCAL_DAGS_PATH를 DAG 파일이 있는 로컬 디렉터리 경로로 바꿉니다.
  • LOCAL_PLUGINS_PATH를 플러그인 파일이 있는 로컬 디렉터리 경로로 바꿉니다.

  • DATABASE_ENGINE을 사용할 데이터베이스 엔진으로 바꿉니다. 가능한 값은 postgresql (기본값) 및 sqlite입니다.

  • (Linux/macOS만 해당) 편집 가능한 모드로 설치할 Python 패키지가 포함된 로컬 디렉터리의 경로가 있는 EDITABLE_DEPENDENCY_PATH 이 인수는 Windows에서 지원되지 않습니다.

    경로는 절대 경로 또는 상대 경로일 수 있습니다 (상대 경로는 현재 작업 디렉터리를 기준으로 확인됨). 이 디렉터리는 컨테이너 엔진에서 액세스할 수 있어야 합니다.

    수정 가능한 패키지를 여러 개 지정하려면 옵션을 반복합니다. 예: --editable-dependencies ./pkg1 --editable-dependencies ./pkg2

    pip install -e로 패키지를 설치하면 프로젝트 내의 해당 패키지에 변경사항이 즉시 적용됩니다.

예:

composer-dev create \
  --from-image-version composer-2.17.11-airflow-2.11.1 \
  example-local-environment

Managed Airflow 환경에서 로컬 Airflow 환경 만들기

다음 정보만 Managed Airflow 환경에서 가져옵니다.

  • 환경에서 사용되는 Managed Airflow 및 Airflow 버전입니다.

  • 환경에 설치된 커스텀 PyPI 패키지 목록

  • 사용자 환경에서 설정된 환경 변수 이름의 주석 처리된 목록

DAG 파일, DAG 실행 기록, Airflow 변수, 연결 등 환경의 다른 정보 및 구성 매개변수는 Managed Airflow 환경에서 복사되지 않습니다.

기존 Managed Airflow 환경에서 로컬 Airflow 환경을 만들려면 다음 안내를 따르세요.

composer-dev create LOCAL_ENVIRONMENT_NAME \
    --from-source-environment ENVIRONMENT_NAME \
    --location LOCATION \
    --project PROJECT_ID \
    --port WEB_SERVER_PORT \
    --dags-path LOCAL_DAGS_PATH \
    --plugins-path LOCAL_PLUGINS_PATH \
    --database DATABASE_ENGINE \
    --editable-dependencies EDITABLE_DEPENDENCY_PATH

다음과 같이 바꿉니다.

  • LOCAL_ENVIRONMENT_NAME을 로컬 Airflow 환경의 이름으로 바꿉니다.
  • ENVIRONMENT_NAME을 Managed Airflow 환경의 이름으로 바꿉니다.
  • LOCATION을 Managed Airflow 환경이 위치한 리전으로 바꿉니다.
  • PROJECT_ID를 프로젝트 ID로 바꿉니다.
  • WEB_SERVER_PORT를 로컬 Airflow 웹 서버의 포트로 바꿉니다.
  • LOCAL_DAGS_PATH를 DAG가 있는 로컬 디렉터리 경로로 바꿉니다.
  • LOCAL_PLUGINS_PATH를 플러그인 파일이 있는 로컬 디렉터리 경로로 바꿉니다.

  • DATABASE_ENGINE을 사용할 데이터베이스 엔진으로 바꿉니다. 가능한 값은 postgresql (기본값) 및 sqlite입니다.

  • (Linux/macOS만 해당) 편집 가능한 모드로 설치할 Python 패키지가 포함된 로컬 디렉터리의 경로가 있는 EDITABLE_DEPENDENCY_PATH 이 인수는 Windows에서 지원되지 않습니다.

    경로는 절대 경로 또는 상대 경로일 수 있습니다 (상대 경로는 현재 작업 디렉터리를 기준으로 확인됨). 이 디렉터리는 컨테이너 엔진에서 액세스할 수 있어야 합니다.

    수정 가능한 패키지를 여러 개 지정하려면 옵션을 반복합니다. 예: --editable-dependencies ./pkg1 --editable-dependencies ./pkg2

    pip install -e로 패키지를 설치하면 프로젝트 내의 해당 패키지에 변경사항이 즉시 적용됩니다.

예:

composer-dev create example-local-environment \
  --from-source-environment example-environment \
  --location us-central1 \
  --project example-project \
  --port 8081 \
  --dags-path ./example_directory/dags \
  --plugins-path ./example_directory/plugins \
  --database postgresql \
  --editable-dependencies ./pkg1

로컬 Airflow 환경 시작

로컬 Airflow 환경을 시작하려면 다음을 실행합니다.

composer-dev start LOCAL_ENVIRONMENT_NAME

다음과 같이 바꿉니다.

  • LOCAL_ENVIRONMENT_NAME을 로컬 Airflow 환경의 이름으로 바꿉니다.

로컬 Airflow 환경 중지 또는 다시 시작

로컬 Airflow 환경을 다시 시작하면 Composer 로컬 개발 CLI 도구가 환경이 실행되는 Docker 컨테이너를 다시 시작합니다. 모든 Airflow 구성요소가 중지되었다가 다시 시작됩니다. 따라서 재시작 중에 실행되는 모든 DAG 실행은 실패로 표시됩니다.

중지된 로컬 Airflow 환경을 다시 시작하거나 시작하려면 다음을 실행합니다.

composer-dev restart LOCAL_ENVIRONMENT_NAME

다음과 같이 바꿉니다.

  • LOCAL_ENVIRONMENT_NAME을 로컬 Airflow 환경의 이름으로 바꿉니다.

로컬 Airflow 환경을 중지하려면 다음을 실행합니다.

composer-dev stop LOCAL_ENVIRONMENT_NAME

DAG 추가 및 업데이트

DAG는 로컬 Airflow 환경을 만들 때 --dags-path 매개변수로 지정한 디렉터리에 저장됩니다. 기본적으로 이 디렉터리는 ./composer/<local_environment_name>/dags입니다. describe 명령어를 사용하여 환경에서 사용하는 디렉터리를 가져올 수 있습니다.

DAG를 추가하고 업데이트하려면 이 디렉터리의 파일을 변경하세요. 로컬 Airflow 환경을 다시 시작할 필요가 없습니다.

로컬 Airflow 환경 로그 보기

로컬 Airflow 환경을 실행하는 Docker 컨테이너에서 최근 로그를 볼 수 있습니다. 이렇게 하면 컨테이너 관련 이벤트를 모니터링하고 Airflow 로그에서 PyPI 패키지 설치로 인한 종속 항목 충돌과 같은 오류를 확인할 수 있습니다.

로컬 Airflow 환경을 실행하는 Docker 컨테이너에서 로그를 보려면 다음을 실행합니다.

composer-dev logs LOCAL_ENVIRONMENT_NAME --max-lines 10

로그 스트림을 따르려면 --max-lines 인수를 생략합니다.

composer-dev logs LOCAL_ENVIRONMENT_NAME

Airflow CLI 명령어 실행

로컬 Airflow 환경에서 Airflow CLI 명령어를 실행할 수 있습니다.

Airflow CLI 명령어를 실행하려면 다음 안내를 따르세요.

composer-dev run-airflow-cmd LOCAL_ENVIRONMENT_NAME \
  SUBCOMMAND SUBCOMMAND_ARGUMENTS

예를 들면 다음과 같습니다.

composer-dev run-airflow-cmd example-local-environment dags list -o table

로컬 Airflow 환경 구성

Composer 로컬 개발 CLI 도구는 환경 변수 및 PyPI 패키지 요구사항과 같은 로컬 Airflow 환경의 구성 매개변수를 로컬 환경의 디렉터리(./composer/<local_environment_name>)에 저장합니다.

로컬 Airflow 환경이 시작될 때 구성이 적용됩니다. 예를 들어 충돌하는 PyPI 패키지 요구사항을 추가하면 로컬 환경을 시작할 때 Composer 로컬 개발 CLI 도구가 오류를 보고합니다.

Airflow 연결은 로컬 Airflow 환경의 데이터베이스에 저장됩니다. Airflow CLI 명령어를 실행하거나 연결 매개변수를 환경 변수에 저장하여 구성할 수 있습니다. 연결을 만들고 구성하는 방법에 대한 자세한 내용은 Airflow 문서의 연결 관리를 참조하세요.

로컬 Airflow 환경의 목록 및 상태 가져오기

사용 가능한 모든 로컬 Airflow 환경을 나열하고 상태를 표시하려면 다음 안내를 따르세요.

composer-dev list

특정 환경을 설명하고 환경의 이미지 버전, DAG 경로, 웹 서버 URL과 같은 세부정보를 가져오려면 다음 안내를 따르세요.

composer-dev describe LOCAL_ENVIRONMENT_NAME

다음과 같이 바꿉니다.

  • LOCAL_ENVIRONMENT_NAME을 로컬 Airflow 환경의 이름으로 바꿉니다.

로컬 Airflow 환경에서 사용하는 이미지 나열

Composer 로컬 개발 CLI 도구에서 사용하는 모든 이미지를 나열하려면 다음을 실행합니다.

docker images --filter=reference='*/cloud-airflow-releaser/*/*'

플러그인 설치 및 데이터 변경

로컬 Airflow 환경의 플러그인 및 데이터는 로컬 환경의 디렉터리(./composer/<local_environment_name>/data 및 ./composer/<local_environment_name>/plugins)에서 가져옵니다.

/data 및 /plugins 디렉터리의 콘텐츠를 변경하려면 이러한 디렉터리에 파일을 추가하거나 삭제합니다. Docker는 파일 변경사항을 로컬 Airflow 환경에 자동으로 전파합니다.

Composer 로컬 개발 CLI 도구는 데이터 및 플러그인용으로 다른 디렉터리를 지정하는 기능을 지원하지 않습니다.

환경 변수 구성

환경 변수를 구성하려면 환경 디렉터리 ./composer/<local_environment_name>/variables.env에서 variables.env 파일을 수정합니다.

variables.env 파일에는 환경 변수마다 한 줄씩 키-값 정의가 있어야 합니다. Airflow 구성 옵션을 변경하려면 AIRFLOW__SECTION__KEY 형식을 사용합니다. 사용 가능한 환경 변수에 대한 자세한 내용은 Airflow 구성 참조를 확인하세요.

EXAMPLE_VARIABLE=True
ANOTHER_VARIABLE=test
AIRFLOW__WEBSERVER__DAG_DEFAULT_VIEW=graph

변경사항을 적용하려면 로컬 Airflow 환경을 다시 시작합니다.

PyPI 패키지 설치 또는 삭제

PyPI 패키지를 설치하거나 삭제하려면 환경 디렉터리(./composer/<local_environment_name>/requirements.txt)에서 requirements.txt 파일을 수정합니다.

요구사항은 PEP-508에 지정된 형식을 따라야 합니다. 여기에는 각 요구사항이 소문자로 지정되어 있고, 패키지 이름과 선택적 추가 기능 및 버전 지정자로 구성되어 있습니다.

변경사항을 적용하려면 로컬 Airflow 환경을 다시 시작합니다.

다른 Managed Airflow 이미지로 전환

Composer 로컬 개발 CLI 도구로 Managed Airflow 이미지를 사용하고 이미지 간에 전환할 수 있습니다. 시작 시 로컬 Airflow 환경의 구성 매개변수가 적용되므로 이 접근 방식은 Managed Airflow 환경 업그레이드와 다릅니다.

예를 들어 새 Managed Airflow 버전이 출시된 후 기존 로컬 Airflow 환경 구성을 유지하면서 새 버전을 사용하도록 환경을 전환할 수 있습니다. 또 다른 예시로 특정 Managed Airflow 버전 내의 여러 Airflow 버전 간에 전환할 수 있습니다.

로컬 Airflow 환경에서 사용하는 환경의 이미지를 변경하려면 다음 안내를 따르세요.

  1. 로컬 환경 구성 파일 ./composer/<local_environment_name>/config.json을 수정합니다.

  2. composer_image_version 매개변수의 값을 변경합니다. 사용 가능한 값을 보려면 사용 가능한 이미지를 나열하면 됩니다.

  3. 변경사항을 적용하려면 로컬 Airflow 환경을 다시 시작합니다.

로컬 Airflow 환경 삭제

주의: 로그 및 구성과 같은 환경에서 모든 필수 데이터를 저장했는지 확인하세요.

로컬 Airflow 환경을 삭제하려면 다음 명령어를 실행하세요.

composer-dev remove LOCAL_ENVIRONMENT_NAME

환경이 실행 중이면 --force 플래그를 추가하여 강제로 삭제합니다.

Docker 이미지 삭제

Composer 로컬 개발 CLI 도구로 다운로드한 모든 이미지를 삭제하려면 다음을 실행합니다.

docker rmi $(docker images --filter=reference='*/cloud-airflow-releaser/*/*' -q)

추가 구성 및 문제 해결

이 섹션에서는 일반적인 문제의 해결 방법과 Composer 로컬 개발 CLI 도구와 다른 도구 및 서비스의 상호작용을 구성하기 위한 추가 구성 단계를 제공합니다.

셸 탭 완성

composer-dev CLI는 Bash, Zsh, Fish 셸의 탭 자동 완성을 지원합니다. 탭 자동 완성을 사용하면 도움말 텍스트를 참고하지 않고도 사용 가능한 하위 명령어와 옵션을 확인할 수 있습니다.

Zsh

완료 스크립트를 생성하고 ~/.zshrc에서 소싱합니다.

_COMPOSER_DEV_COMPLETE=zsh_source composer-dev > ~/.composer-dev-complete.zsh

그런 다음 ~/.zshrc에 추가합니다.

echo 'source ~/.composer-dev-complete.zsh' >> ~/.zshrc

Bash

완료 스크립트를 생성하고 ~/.bashrc에서 소싱합니다.

_COMPOSER_DEV_COMPLETE=bash_source composer-dev > ~/.composer-dev-complete.bash

그런 다음 ~/.bashrc에 추가합니다.

echo 'source ~/.composer-dev-complete.bash' >> ~/.bashrc

물고기

완료 스크립트를 생성하고 Fish 완료 디렉터리에 저장합니다.

_COMPOSER_DEV_COMPLETE=fish_source composer-dev > ~/.config/fish/completions/composer-dev.fish

Kubernetes 클러스터와 상호작용

기본적으로 ~/.kube/config 파일은 마운트되지 않습니다. 환경을 시작하기 전에 KUBECONFIG 환경 변수를 내보내 Kubernetes 구성 파일의 경로를 지정할 수 있습니다.

export KUBECONFIG=~/.kube/config

호스트 머신에서 다른 서비스와 상호작용

Managed Airflow 환경의 localhost는 Docker 또는 Podman 컨테이너의 네트워크 작동 방식 때문에 호스트 머신이 아닌 컨테이너 자체를 가리킵니다. 편의를 위해 composer-dev CLI 도구는 host.docker.internal 도메인 별칭을 통해 머신에 액세스하도록 컨테이너의 네트워크를 구성합니다. 예:

  • Redis: Redis이 포트 6379에서 실행되는 경우 localhost:6379 대신 host.docker.internal:6379를 사용합니다.
  • PostgreSQL: PostgreSQL이 포트 25432에서 실행되는 경우 localhost:25432 대신 host.docker.internal:25432를 사용합니다.
  • 기타 서비스: host.docker.internal:<PORT> 패턴을 따릅니다.

macOS에서 로컬 환경을 시작할 수 없음

Docker가 액세스할 수 없는 디렉터리에 composer-dev 패키지를 설치한 경우 로컬 환경이 시작되지 않을 수 있습니다.

예를 들어 macOS에서 기본 Homebrew 구성으로 Python을 설치하는 경우처럼 /opt 디렉터리에 Python을 설치하면 composer-dev 패키지도 /opt 디렉터리에 설치됩니다. Docker는 Apple의 샌드박스 규칙을 준수하므로 /opt 디렉터리를 기본적으로 사용할 수 없습니다. 또한 UI(설정 > 리소스 > 파일 공유)를 통해 추가할 수도 없습니다.

이 경우 Composer 로컬 개발 CLI 도구는 다음 예시와 비슷한 오류 메시지를 생성합니다.

Failed to create container with an error: 400 Client Error for ...
Bad Request ("invalid mount config for type "bind": bind source path does not exist:
/opt/homebrew/lib/python3.9/site-packages/composer_local_dev/docker_files/entrypoint.sh

Possible reason is that composer-dev was installed in the path that is
not available to Docker. See...")

다음 솔루션 중 하나를 사용할 수 있습니다.

  • Docker가 패키지에 액세스할 수 있도록 Python 또는 composer-dev 패키지를 다른 디렉터리에 설치합니다.
  • ~/Library/Group\ Containers/group.com.docker/settings.json 파일을 수동으로 수정하고 /opt를 filesharingDirectories에 추가합니다.

호스트에서 마운트된 파일 및 디렉터리에 대한 컨테이너 사용자 액세스

기본적으로 Managed Airflow 환경의 컨테이너는 UID가 999인 airflow 사용자로 실행됩니다. 사용자는 호스트에서 마운트된 파일 및 디렉터리(예: ~/.config/gcloud/application_default_credentials.json)에 액세스할 수 있어야 합니다.

알려진 문제:

  • google.auth.exceptions.DefaultCredentialsError: Your default credentials were not found: 기본 사용자 airflow (999)로 컨테이너를 실행할 때 생성될 수 있으며 호스트 디렉터리 ~/.config/gcloud/에 사용자의 실행 권한이 누락되어 있습니다.
  • [Errno 13] Permission denied: '/home/airflow/.config/gcloud/application_default_credentials.json': 기본 사용자 airflow (999)로 컨테이너를 실행하고 호스트 파일 ~/.config/gcloud/application_default_credentials.json에 사용자의 읽기 권한이 누락된 경우 생성될 수 있습니다.

Linux 또는 macOS에서는 composer/<LOCAL_ENVIRONMENT_NAME>/variables.env에 COMPOSER_CONTAINER_RUN_AS_HOST_USER=True를 추가하여 컨테이너를 현재 호스트 사용자로 실행하는 것이 좋습니다.이 기능은 Windows에서는 사용할 수 없으므로 컨테이너 내부의 사용자가 액세스할 수 있도록 호스트에 마운트된 파일 및 디렉터리의 권한을 업데이트해야 할 수 있습니다.

(Podman) 기업 사용자의 권한 또는 lchown 오류 수정

루트 없는 Podman이 기본 회사 사용자 ID와 중복되는 사용자 네임스페이스를 자동으로 할당하여 lchown: invalid argument 또는 권한 오류가 발생하는 것을 방지하려면 하위 범위를 4백만 블록 위로 수동으로 푸시해야 합니다.

  1. 루트 권한으로 /etc/subuid 및 /etc/subgid을 엽니다(예: sudo nano /etc/subuid).

  2. 사용자 이름 항목을 다음과 같이 정확하게 업데이트하거나 추가합니다.

    YOUR_USERNAME:4000000:3000000

  3. 두 파일을 모두 저장하고 다음을 실행하여 새 네임스페이스 매핑 규칙을 Podman에 적용합니다.

    podman system migrate

(Podman) 멈춘 파일 및 권한 거부 오류 삭제

이전 컨테이너가 있는 동안 subuid 범위를 업데이트한 경우 현재 네임스페이스가 자체 데이터 캐시에 액세스할 수 없습니다.

호스트 수준 루트 권한을 사용하여 로컬 스토리지 그래프를 강제 삭제합니다.

podman rm -fa
podman volume rm --all --force
podman system migrate

(Podman) DNS 실패 ('이름 또는 서비스를 알 수 없음') 수정

Airflow 컨테이너에서 데이터베이스 컨테이너(your-environment-name)의 호스트 이름을 변환하거나 확인할 수 없다는 psycopg2.OperationalError가 생성되면 Podman의 내부 가상 브리지 네트워크가 동기화되지 않은 것입니다.

런타임 상태를 플러시하고 netavark 및 aardvark-dns가 깨끗한 라우팅 테이블을 재생성하도록 강제합니다.

podman rm -fa
podman network prune --force

rm -rf /run/user/$UID/containers/*
rm -rf /run/user/$UID/netavark/*
rm -rf COMPOSER_LOCAL_DEV_PATH/composer/*

podman system migrate

(Podman) 엔진 상태 확인

Podman이 워크플로를 루트 권한 없이 관리하고 시스템 Docker로 구성을 우회하지 않는지 확인하려면 다음을 실행하세요.

  1. 네트워크 DNS 백엔드를 확인합니다.

    podman info | grep -A 3 -i "dns"

    출력에는 backend: netavark와 aardvark-dns의 유효한 실행 파일 경로가 포함되어야 합니다.

  2. 프로세스 소유권 매핑을 확인합니다. 환경이 실행 중인 상태에서 호스트 프로세스 소유자를 확인합니다.

    ps -ef | grep -i "postgres"

    가장 왼쪽 열에 subuid 맵 범위에 해당하는 높은 UID 번호 (예: 4000069)가 표시되어야 하며, 이는 완전히 루트 없이 실행되고 있음을 증명합니다.

(Podman, Windows) 배포 중 파이프 오류 수정

배포 중에 데이터베이스 또는 Airflow 컨테이너가 파이프 오류와 함께 즉시 종료되면 Podman이 메모리 한도에 도달한 것일 수 있습니다. 이 문제를 해결하려면 .wslconfig 파일에서 메모리 및 스왑 한도를 늘려 보세요.

  1. PowerShell에서 다음 명령어를 실행하여 Podman 머신과 WSL 2 가상 머신을 중지합니다.

    podman machine stop
wsl --shutdown

  2. %USERPROFILE%\.wslconfig 파일을 변경하여 스왑 및 메모리 제한을 조정합니다. 참고로 WSL 구성 참조를 확인하세요.

  3. 다음을 실행하여 Podman 머신을 시작합니다.

    podman machine start

오류가 발생하면 Windows 가상화 및 네트워킹 스택을 강제 재설정해 보세요. 이렇게 하려면 관리자 권한으로 PowerShell을 열고 다음을 실행합니다.

Restart-Service -Name vmms -Force
Restart-Service -Name hns -Force
wsl --shutdown

다음 단계