Cloud Composer 1 | Cloud Composer 2 | Cloud Composer 3
이 섹션에서는 Composer 로컬 개발 CLI 도구를 사용하여 로컬 Airflow 환경을 만들고 구성하고 실행하는 방법을 설명합니다.
Composer 로컬 개발 CLI 도구 정보
Composer 로컬 개발 CLI 도구는 Airflow 환경을 로컬에서 실행하여 Cloud Composer의 Apache Airflow DAG 개발을 간소화합니다. 이 로컬 Airflow 환경은 특정 Cloud Composer 버전의 이미지를 사용합니다.
기존 Cloud Composer 환경을 기반으로 로컬 Airflow 환경을 만들 수 있습니다. 이 경우 로컬 Airflow 환경은 Cloud Composer 환경에서 설치된 PyPI 패키지 및 환경 변수 이름의 목록을 가져옵니다.
새로운 DAG 코드, PyPI 패키지 또는 Airflow 구성 옵션을 테스트하는 등의 테스트 및 개발 목적으로 이 로컬 Airflow 환경을 사용할 수 있습니다.
시작하기 전에
Composer 로컬 개발 CLI 도구는
composer-dev create명령어를 실행하는 디렉터리에 로컬 Airflow 환경을 만듭니다. 나중에 로컬 Airflow 환경에 액세스하려면 처음 로컬 환경을 만든 경로에서 도구 명령어를 실행합니다. 로컬 환경의 모든 데이터는 로컬 환경을 만든 경로인./composer/<local_environment_name>에 있는 하위 디렉터리에 저장됩니다.컴퓨터에 Cloud Composer 이미지를 저장하기에 충분한 디스크 공간이 있어야 합니다. Composer 로컬 개발 CLI 도구는 각 Cloud Composer 버전에 대해 하나의 이미지 파일을 저장합니다. 예를 들어 서로 다른 Cloud Composer 버전을 사용하는 로컬 Airflow 환경이 두 개 있으면 Composer 로컬 개발 CLI 도구는 두 개의 Cloud Composer 이미지를 저장합니다.
Composer 로컬 개발 CLI 도구는 색상 출력을 사용합니다. 다음과 같이
NO_COLOR=1변수를 사용하여 색상 출력을 사용 중지할 수 있습니다.NO_COLOR=1 composer-dev <other commands>.로컬 환경이 하나만 있는 경우
run-airflow-cmd를 제외한 모든composer-dev명령어에서 로컬 환경의 이름을 생략할 수 있습니다.Composer 로컬 개발 CLI 도구 종속 항목을 설치합니다.
- Python 버전 3.7~3.10(
pip포함) - Google Cloud CLI
- Python 버전 3.7~3.10(
Docker를 설치합니다. 로컬 시스템에 Docker를 설치되어 실행 중이어야 합니다. Docker가 실행 중인지 확인하려면
docker ps와 같은 Docker CLI 명령어를 실행하면 됩니다.
사용자 인증 정보 구성
아직 설정하지 않았다면 애플리케이션 기본 사용자 인증 정보에 사용할 새로운 사용자 인증 정보를 가져옵니다.
gcloud auth application-default login
Google 계정을 사용하여 gcloud CLI에 로그인합니다.
gcloud auth login
Composer 로컬 개발 CLI 도구와 DAG에서 수행하는 모든 API 호출은 gcloud CLI에서 사용하는 계정에서 실행됩니다. 예를 들어 로컬 Airflow 환경의 DAG가 Cloud Storage 버킷의 콘텐츠를 읽는 경우 이 계정에 버킷 액세스 권한이 있어야 합니다. 이와 달리 Cloud Composer 환경에서는 환경의 서비스 계정이 호출을 수행합니다.
Composer 로컬 개발 CLI 도구 설치
Composer 로컬 개발 CLI 저장소를 클론합니다.
git clone https://github.com/GoogleCloudPlatform/composer-local-dev.git
클론된 저장소의 최상위 디렉터리에서 다음을 실행합니다.
pip install .
pip 구성에 따라서는 도구가 설치된 경로가 PATH 변수에 없을 수 있습니다. 이 경우 pip에 경고 메시지가 표시됩니다. 이 경고 메시지의 정보를 사용하여 운영체제의 PATH 변수에 이 디렉터리를 추가할 수 있습니다.
특정 Cloud Composer 버전을 사용하여 로컬 Airflow 환경 만들기
Cloud Composer의 사용 가능한 버전을 나열하려면 다음을 실행합니다.
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 \
--from-image-version IMAGE_VERSION \
--project PROJECT_ID \
--port WEB_SERVER_PORT \
--dags-path LOCAL_DAGS_PATH \
LOCAL_ENVIRONMENT_NAME
다음과 같이 바꿉니다.
IMAGE_VERSION을 Cloud Composer 이미지 이름으로 바꿉니다.PROJECT_ID를 프로젝트 ID로 바꿉니다.WEB_SERVER_PORT를 Airflow 웹 서버가 리슨해야 하는 포트로 바꿉니다.LOCAL_DAGS_PATH를 DAG 파일이 있는 로컬 디렉터리 경로로 바꿉니다.LOCAL_ENVIRONMENT_NAME을 이 로컬 Airflow 환경의 이름으로 바꿉니다.
예를 들면 다음과 같습니다.
composer-dev create \
--from-image-version composer-2.9.7-airflow-2.9.3 \
example-local-environment
Cloud Composer 환경에서 로컬 Airflow 환경 만들기
다음 정보만 Cloud Composer 환경에서 가져옵니다.
- 이미지 버전(사용자 환경에서 사용되는 Cloud Composer 및 Airflow 버전)
- 환경에 설치된 커스텀 PyPI 패키지 목록
사용자 환경에서 설정된 환경 변수 이름의 주석 처리된 목록
DAG 파일, DAG 실행 기록, Airflow 변수, 연결 등 환경의 다른 정보 및 구성 매개변수는 Cloud Composer 환경에서 복사되지 않습니다.
기존 Cloud Composer 환경에서 로컬 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
다음과 같이 바꿉니다.
LOCAL_ENVIRONMENT_NAME을 로컬 Airflow 환경의 이름으로 바꿉니다.ENVIRONMENT_NAME을 Cloud Composer 환경의 이름으로 바꿉니다.LOCATION을 Cloud Composer 환경이 있는 리전으로 바꿉니다.PROJECT_ID를 프로젝트 ID로 바꿉니다.WEB_SERVER_PORT를 로컬 Airflow 웹 서버의 포트로 바꿉니다.LOCAL_DAGS_PATH를 DAG가 있는 로컬 디렉터리 경로로 바꿉니다.
예를 들면 다음과 같습니다.
composer-dev create example-local-environment \
--from-source-environment example-environment \
--location us-central1 \
--project example-project \
--port 8081 \
--dags-path example_directory/dags
로컬 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 환경을 다시 시작합니다.
다른 Cloud Composer 이미지로 전환
Composer 로컬 개발 CLI 도구로 임의의 Cloud Composer 이미지를 사용하고 이미지 간에 전환할 수 있습니다. 시작 시 로컬 Airflow 환경의 구성 매개변수가 적용되므로 이 접근 방식은 Cloud Composer 환경 업그레이드와 다릅니다.
예를 들어 새 Cloud Composer 버전이 출시된 후 기존 로컬 Airflow 환경 구성을 유지하면서 새 버전을 사용하도록 환경을 전환할 수 있습니다. 또 다른 예시로 특정 Cloud Composer 버전 내의 여러 Airflow 버전 간에 전환할 수 있습니다.
로컬 Airflow 환경에서 사용하는 환경의 이미지를 변경하려면 다음 안내를 따르세요.
로컬 환경 구성 파일
./composer/<local_environment_name>/config.json을 수정합니다.composer_image_version매개변수의 값을 변경합니다. 사용 가능한 값을 보려면 사용 가능한 Cloud Composer 버전을 나열하면 됩니다.변경사항을 적용하려면 로컬 Airflow 환경을 다시 시작합니다.
로컬 Airflow 환경 삭제
주의: 로그 및 구성과 같은 환경에서 모든 필수 데이터를 저장했는지 확인하세요.
로컬 Airflow 환경을 삭제하려면 다음 명령어를 실행하세요.
composer-dev remove LOCAL_ENVIRONMENT_NAME
환경이 실행 중이면 --force 플래그를 추가하여 강제로 삭제합니다.
Docker 이미지 삭제
Composer 로컬 개발 CLI 도구로 다운로드한 모든 이미지를 삭제하려면 다음을 실행합니다.
docker rmi $(docker images --filter=reference='*/cloud-airflow-releaser/*/*' -q)
문제 해결
이 섹션에서는 일반적인 문제의 해결방법을 제공합니다.
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에 추가합니다.