Cloud Composer는 환경 버킷의 특정 폴더를 환경에서 실행되는 Airflow 구성요소에 동기화합니다. 자세한 내용은 Cloud Storage에 저장된 데이터를 참고하세요. 이 페이지에서는 동기화 프로세스를 방해할 수 있는 문제와 문제 해결 방법을 설명합니다.
일반적인 문제
다음 섹션에서는 몇 가지 일반적인 파일 동기화 문제의 증상과 가능한 해결 방법을 설명합니다.
dags 및 plugins 폴더에서 다수의 DAG 및 플러그인 처리
/dags 및 /plugins 폴더의 콘텐츠가 해당 환경 버킷에서 Airflow 작업자 및 스케줄러의 로컬 파일 시스템으로 동기화됩니다.
이러한 폴더에 저장된 데이터가 많을수록 동기화를 수행하는 데 시간이 오래 걸립니다. 이러한 상황을 해결하려면 다음 안내를 따르세요.
/dags 및 /plugins 폴더의 파일 수를 제한합니다. 필요한 최소 파일만 저장합니다.
Airflow 스케줄러 및 작업자에 사용 가능한 디스크 공간을 늘립니다.
동기화 작업이 더 빠르게 수행되도록 Airflow 스케줄러 및 작업자의 CPU와 메모리를 늘립니다.
DAG 수가 매우 많으면 DAG를 여러 배치로 나누고, 이를 ZIP 파일로 압축하고, 이러한 보관 파일을 /dags 폴더에 배포합니다.
이렇게 하면 DAG 동기화 프로세스가 빨라집니다. Airflow 구성요소는 DAG를 처리하기 전 ZIP 파일을 추출합니다.
프로그래매틱 방식으로 DAG를 생성하는 것도 /dags 폴더에 저장되는 DAG 수를 제한하기 위한 방법일 수 있습니다.
프로그래매틱 방식으로 생성된 DAG를 예약 및 실행할 때 문제가 발생하지 않도록 하려면 DAG 문제 해결 페이지의 프로그래매틱 DAG 섹션을 참고하세요.
DAG 및 플러그인을 스케줄러, 작업자, 웹 서버로 동기화에 영향을 미치는 안티 패턴
Cloud Composer는 /dags 및 /plugins 폴더의 콘텐츠를 스케줄러와 작업자로 동기화합니다. /dags 및 /plugins 폴더의 특정 객체로 인해 이 동기화가 올바르게 작동하지 않거나 속도가 느려질 수 있습니다.
/dags 폴더가 스케줄러와 작업자로 동기화됩니다.
이 폴더는 웹 서버에 동기화되지 않습니다.
/plugins 폴더가 스케줄러, 작업자, 웹 서버로 동기화됩니다.
다음 문제가 발생할 수 있습니다.
[압축 트랜스코딩][storage-transcoding] 을 사용하는 gzip 압축 파일을 /dags 및 /plugins 폴더에 업로드했습니다. 일반적으로 gcloud storage cp 명령어에서 --gzip-local-all 플래그를 사용하여 데이터를 버킷에 업로드하는 경우에 발생합니다.
솔루션: 압축 트랜스코딩을 사용한 객체를 삭제하고 버킷에 다시 업로드합니다.
객체 중 하나는 '.'로 지정됩니다. 이러한 객체는 스케줄러와 작업자로 동기화되지 않으며 동기화가 중지될 수도 있습니다.
해결 방법: 객체의 이름을 변경합니다.
폴더와 DAG Python 파일의 이름이 동일합니다(예: a.py).
이 경우 DAG 파일이 Airflow 구성요소에 올바르게 동기화되지 않습니다.
솔루션: DAG Python 파일과 동일한 이름의 폴더를 삭제합니다.
/dags 또는 /plugins 폴더의 객체 중 하나의 이름 끝에는 / 기호가 있습니다. / 기호는 객체가 파일이 아닌 폴더라는 의미이므로 이러한 객체가 동기화 프로세스를 방해할 수 있습니다.
솔루션: 문제가 되는 객체 이름에서 / 기호를 삭제합니다.
/dags 및 /plugins 폴더에 불필요한 파일을 저장하지 마세요.
구현하는 DAG 및 플러그인은 이러한 구성요소 테스트를 저장하는 파일과 같은 추가 파일과 함께 제공되는 경우가 있습니다. 이러한 파일은 작업자 및 스케줄러로 동기화되며, 이러한 파일을 스케줄러, 작업자, 웹 서버에 복사하는 데 필요한 시간에 영향을 미칩니다.
솔루션: 추가 파일과 불필요한 파일을 /dags 및 /plugins 폴더에 저장하지 마세요.
스케줄러 및 작업자에서 Done [Errno 21] Is a directory: '/home/airflow/gcs/dags/...' 오류 생성
이 문제는 Cloud Storage의 객체에 중첩 네임스페이스가 있으며 동시에 스케줄러와 작업자에서 기존 Linux 파일 시스템을 사용하기 때문에 발생합니다. 예를 들어 폴더와 이름이 동일한 객체 모두 환경의 버킷에 추가할 수 있습니다. 버킷이 환경의 스케줄러와 작업자로 동기화되면 이 오류가 발생하여 태스크가 실패할 수 있습니다.
이 문제를 해결하려면 환경의 버킷에 중첩되는 네임스페이스가 없는지 확인합니다. 예를 들어 /dags/misc(파일) 및 /dags/misc/example_file.txt(다른 파일) 모두 버킷에 있으면 스케줄러에서 오류가 발생합니다.
[[["이해하기 쉬움","easyToUnderstand","thumb-up"],["문제가 해결됨","solvedMyProblem","thumb-up"],["기타","otherUp","thumb-up"]],[["이해하기 어려움","hardToUnderstand","thumb-down"],["잘못된 정보 또는 샘플 코드","incorrectInformationOrSampleCode","thumb-down"],["필요한 정보/샘플이 없음","missingTheInformationSamplesINeed","thumb-down"],["번역 문제","translationIssue","thumb-down"],["기타","otherDown","thumb-down"]],["최종 업데이트: 2025-08-26(UTC)"],[],[],null,["\u003cbr /\u003e\n\n\u003cbr /\u003e\n\n\n[Cloud Composer 3](/composer/docs/composer-3/troubleshooting-cloud-storage \"View this page for Cloud Composer 3\") \\| **Cloud Composer 2** \\| Cloud Composer 1\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\nCloud Composer synchronizes specific folders in your environment's bucket to Airflow components that run in your environment. See [Data stored in Cloud Storage](/composer/docs/composer-2/cloud-storage) for more information. This page refers to issues that could disrupt the synchronization process and how to troubleshoot them.\n\nCommon Issues\n\nThe following sections describe symptoms and potential fixes for some common file synchronization issues.\n\nHandling a large number of DAGs and plugins in dags and plugins folders\n\nContents of `/dags` and `/plugins` folders are synchronized from\nyour environment's bucket to local file systems of Airflow workers and\nschedulers.\n\nThe more data stored in these folders, the longer it takes to perform the\nsynchronization. To address such situations:\n\n- Limit the number of files in `/dags` and `/plugins` folders. Store only the\n minimum of required files.\n\n- Increase the disk space available to Airflow schedulers and workers.\n\n- Increase CPU and memory of Airflow schedulers and workers, so\n that the sync operation is performed faster.\n\n- In case of a very large number of DAGs, divide DAGs into batches, compress\n them into zip archives and deploy these archives into the `/dags` folder.\n This approach speeds up the DAGs syncing process. Airflow components\n extract zip archives before processing DAGs.\n\n- Generating DAGs in a programmatic way might also be a method for limiting\n the number of DAG files stored in the `/dags` folder.\n See the **Programmatic DAGs** section in the [DAGs Troubleshooting page](/composer/docs/composer-2/troubleshooting-dags#programmatic-dags) to avoid\n problems with scheduling and executing DAGs generated programmatically.\n\nAnti-patterns impacting DAGs and plugins syncing to schedulers, workers and web servers\n\nCloud Composer synchronizes the content of `/dags` and `/plugins`\nfolders to schedulers and workers. Certain objects in `/dags` and `/plugins`\nfolders might prevent this synchronization to work correctly or slow it down.\n\n- The `/dags` folder is synchronized to schedulers and workers.\n\n\n This folder is not synchronized to the web server.\n- The `/plugins` folder is synchronized to schedulers, workers and web servers.\n\nYou might encounter the following issues:\n\n- You uploaded gzip-compressed files that use\n \\[compression transcoding\\]\\[storage-transcoding\\] to `/dags` and `/plugins`\n folders. It usually happens if you use the `--gzip-local-all` flag in a\n `gcloud storage cp` command to upload data to the bucket.\n\n Solution: Delete the object that used compression transcoding and re-upload\n it to the bucket.\n- One of the objects is named '.'---such an object is not synchronized to\n schedulers and workers, and it might stop synchronizing at all.\n\n Solution: Rename the object.\n- A folder and a DAG Python file have the same names, for example `a.py`.\n In this case, the DAG file is not properly synchronized to Airflow\n components.\n\n Solution: Remove the folder that has the same name as the DAG Python file.\n- One of the objects in `/dags` or `/plugins` folders contains a `/` symbol\n at the end of the object's name. Such objects can interfere with the\n synchronization process because the `/` symbol means that an object is a\n folder, not a file.\n\n Solution: Remove the `/` symbol from the name of the problematic object.\n- Don't store unnecessary files in `/dags` and `/plugins` folders.\n\n Sometimes DAGs and plugins that you implement come with additional files,\n such as files that store tests for these components. These files are\n synchronized to workers and schedulers and impact the time needed to\n copy these files to schedulers, workers and web servers.\n\n Solution: Don't store any additional and unnecessary files in `/dags` and\n `/plugins` folders.\n\nDone \\[Errno 21\\] Is a directory: '/home/airflow/gcs/dags/...' error is generated by schedulers and workers\n\nThis problem happens because objects can have\noverlapping namespace in Cloud Storage, while at the same time\nschedulers and workers use conventional linux file systems. For example, it is possible\nto add both a folder and an object with the same name to an environment's\nbucket. When the bucket is synced to the environment's schedulers and workers,\nthis error is generated, which can lead to task failures.\n\nTo fix this problem, make sure that there are no overlapping namespaces in the\nenvironment's bucket. For example, if both `/dags/misc` (a file) and\n`/dags/misc/example_file.txt` (another file) are in a bucket, an error is\ngenerated by the scheduler.\n\nWhat's next\n\n- [Troubleshooting DAG Processor issues](/composer/docs/composer-2/troubleshooting-dag-processor#inspect-dag-processor-logs)\n- [Troubleshooting Airflow scheduler issues](/composer/docs/composer-2/troubleshooting-scheduling)\n- [Troubleshooting DAGs](/composer/docs/composer-2/troubleshooting-dags)"]]
