이 문서에서는 Dataflow에서 커스텀 컨테이너를 사용할 때 발생할 수 있는 문제의 문제 해결 안내를 제공합니다. 컨테이너나 작업자가 시작되지 않는 문제에 중점을 둡니다. 작업자가 작업을 시작할 수 있고 작업을 진행 중인 경우 파이프라인 문제 해결을 위한 일반 지침을 따르세요.
파이프라인을 시작하는 데 사용하는 Apache Beam SDK 버전과 언어 버전이 커스텀 컨테이너 이미지의 SDK 버전과 일치하는지 확인합니다.
Java를 사용하는 경우 파이프라인을 시작하는 데 사용하는 Java 주 버전이 컨테이너 이미지에 설치된 버전과 일치하는지 확인합니다.
Python을 사용하는 경우 파이프라인을 실행하는 데 사용하는 Python 주-부 버전이 컨테이너 이미지에 설치된 버전과 일치하며 이미지에 충돌하는 종속 항목이 없는지 확인합니다. pip check를 실행하여 확인할 수 있습니다.
커스텀 컨테이너와 관련된 작업자 로그 찾기
로그 탐색기를 사용해서 Dataflow 작업자 로그에서 컨테이너와 관련된 오류 메시지를 찾습니다.
로그 이름을 선택합니다. 커스텀 컨테이너 시작 오류는 다음 중 하나에 속할 가능성이 높습니다.
dataflow.googleapis.com/kubelet
dataflow.googleapis.com/docker
dataflow.googleapis.com/worker-startup
dataflow.googleapis.com/harness-startup
Dataflow Step 리소스를 선택하고 job_id를 지정합니다.
Error Syncing pod... 로그 메시지가 표시되면 일반적인 오류 안내를 따릅니다.
로그 탐색기에서 다음 쿼리를 사용하면 Dataflow 작업자 로그에서 이러한 로그 메시지를 쿼리할 수 있습니다.
resource.type="dataflow_step" AND jsonPayload.message:("IMAGE_URI") AND severity="ERROR"
일반적인 문제
커스텀 컨테이너를 사용할 때 일반적인 문제는 다음과 같습니다.
컨테이너 이미지를 가져올 수 없어 작업에 오류가 있거나 작업이 실패함
Dataflow 작업자는 커스텀 컨테이너 이미지에 액세스할 수 있어야 합니다.
잘못된 URL, 잘못 구성된 사용자 인증 정보 또는 네트워크 액세스 권한 누락으로 인해 작업자가 이미지를 가져올 수 없으면 작업자 시작이 실패합니다.
일괄 작업에서 어떠한 작업도 시작되지 않고 여러 작업자가 순차적으로 시작되지 못하면 Dataflow가 작업을 실패로 처리합니다. 그렇지 않으면 Dataflow는 오류를 로깅하지만 장기 실행 작업 상태를 유지하기 위해 추가적인 조치를 취하지 않습니다.
이 문제를 해결하는 방법에 대한 자세한 내용은 Dataflow 오류 문제 해결 페이지의 이미지 pull 요청 실패 오류를 참조하세요.
작업자가 시작되지 않거나 작업이 진행되지 않음
일부 경우에는 오류로 인해 SDK 컨테이너 시작에 실패할 때 Dataflow에서 오류가 영구적이거나 치명적인지 확인할 수 없습니다. 그런 후 Dataflow는 작업자를 다시 시작하려고 시도합니다.
명백한 오류는 없지만 dataflow.googleapis.com/kubelet에 [topologymanager] RemoveContainerINFO 수준 로그가 표시된다면 커스텀 컨테이너 이미지가 일찍 종료되어 장기 실행 작업자 SDK 프로세스가 시작되지 않은 경우입니다.
작업자가 성공적으로 시작되었지만 작업이 수행되지 않는 경우 오류로 인해 SDK 컨테이너가 시작되지 않을 수 있습니다. 이 경우 진단 권장사항에 다음과 같은 오류가 표시됩니다.
Failed to start container
또한 작업자 로그에는 다음과 같은 줄이 포함되지 않습니다.
Executing: python -m apache_beam.runners.worker.sdk_worker_main or Executing: java ... FnHarness
커스텀 명령어 인수 또는 Dockerfile에 설정된 ENTRYPOINT 오류가 있습니다. 예를 들어 커스텀 ENTRYPOINT는 기본 부팅 스크립트 /opt/apache/beam/boot를 시작하지 않거나 이 스크립트에 인수를 적절하게 전달하지 않습니다. 자세한 내용은 컨테이너 진입점 수정을 참조하세요.
출시 환경과 런타임 환경 간에 Apache Beam SDK 버전이 일치하지 않을 때 오류가 발생합니다. 하나의 실패 모드에서 Apache Beam SDK 파이프라인 옵션에 설정된 기본값이 인식되지 않을 수 있습니다.
예를 들어 작업자 로그에 sdk_worker_main.py: error: argument
--flink_version: invalid choice: '1.16' (choose
from '1.12', '1.13', '1.14', '1.15')과 같은 오류가 표시될 수 있습니다.
문제를 해결하려면 컨테이너 이미지에 파이프라인을 출시하는 데 사용하는 것과 동일한 버전의 Apache Beam SDK를 설치하세요. 자세한 내용은 실행 환경을 런타임 환경과 호환되도록 만들기를 참조하세요.
[[["이해하기 쉬움","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-03-24(UTC)"],[[["\u003cp\u003eThis guide focuses on troubleshooting Dataflow issues specifically related to custom containers that fail to start or prevent workers from functioning correctly.\u003c/p\u003e\n"],["\u003cp\u003eBefore contacting support, it is crucial to test your container image locally, check job and worker logs for errors, and ensure that the Apache Beam SDK and language versions match between the pipeline launch environment and the custom container image.\u003c/p\u003e\n"],["\u003cp\u003eWorker logs can be accessed using the Logs Explorer, specifically checking \u003ccode\u003edataflow.googleapis.com/kubelet\u003c/code\u003e, \u003ccode\u003edataflow.googleapis.com/docker\u003c/code\u003e, \u003ccode\u003edataflow.googleapis.com/worker-startup\u003c/code\u003e, or \u003ccode\u003edataflow.googleapis.com/harness-startup\u003c/code\u003e for container startup errors.\u003c/p\u003e\n"],["\u003cp\u003eCommon issues include problems with image access, dependency conflicts, mismatched SDK versions, incompatible CPU architectures, and errors in custom command arguments or Dockerfile \u003ccode\u003eENTRYPOINT\u003c/code\u003e configurations.\u003c/p\u003e\n"],["\u003cp\u003eThe \u003ccode\u003eError Syncing pod...\u003c/code\u003e log messages usually point to a known issue, which further guidance can be found in the provided common error page.\u003c/p\u003e\n"]]],[],null,["This document provides instructions for troubleshooting issues that might occur when using\ncustom containers with Dataflow. It focuses on issues with\ncontainers or workers not starting. If your workers are able to start and work\nis progressing, follow the general guidance for [Troubleshooting your pipeline](/dataflow/docs/guides/troubleshooting-your-pipeline).\n\nBefore contacting support, ensure that you have ruled out problems related\nto your container image:\n\n- Follow the steps to [test your container image locally](/dataflow/docs/guides/run-custom-container#testing-locally).\n- Search for errors in the [Job logs](/dataflow/docs/guides/troubleshooting-your-pipeline#check_job_error_messages) or in [Worker logs](#worker-logs), and compare any errors found with the [common error](/dataflow/docs/guides/common-errors) guidance.\n- Make sure that the Apache Beam SDK version and language version that you're using to launch the pipeline match the SDK version on your custom container image.\n- If using Java, make sure that the Java major version you use to launch the pipeline matches the version installed in your container image.\n- If using Python, make sure that the Python major-minor version you use to launch the pipeline matches the version installed in your container image, and that the image does not have conflicting dependencies. You can run [`pip check`](https://pip.pypa.io/en/stable/cli/pip_check/) to confirm.\n\nFind worker logs related to custom containers\n\nFine the Dataflow worker logs for container-related error messages can\nby using [Logs Explorer](https://console.cloud.google.com/logs/query):\n\n1. Select log names. Custom container startup errors are most likely to be in\n one of the following:\n\n - `dataflow.googleapis.com/kubelet`\n - `dataflow.googleapis.com/docker`\n - `dataflow.googleapis.com/worker-startup`\n - `dataflow.googleapis.com/harness-startup`\n2. Select the `Dataflow Step` resource and specify the `job_id`.\n\n| **Note:** You can also find the worker logs directly from the **Job** page. Select **Logs \\\u003e Worker Logs\n| \\\u003e Go to Logs Explorer**.\n\nIf you're seeing `Error Syncing pod...` log messages,\nfollow the common [error guidance](/dataflow/docs/guides/common-errors#error-syncing-pod).\nYou can query for these log messages in Dataflow worker logs by using\n[Logs Explorer](https://console.cloud.google.com/logs/query) with the following query: \n\n resource.type=\"dataflow_step\" AND jsonPayload.message:(\"\u003cvar translate=\"no\"\u003eIMAGE_URI\u003c/var\u003e\") AND severity=\"ERROR\"\n\nCommon Issues\n\nThe following are some common issues when using custom containers.\n\nJob has errors or failed because container image cannot be pulled\n\nDataflow workers must be able to access custom container images.\nIf the worker is unable to pull the image due to invalid URLs,\nmisconfigured credentials, or missing network access, the worker fails to\nstart.\n\nFor batch jobs where no work has started and several workers are unable to start\nsequentially, Dataflow fails the job. Otherwise,\nDataflow logs errors but does not take further action to avoid\ndestroying long-running job state.\n\nFor information about how to fix this issue, see\n[Image pull request failed with error](/dataflow/docs/guides/common-errors#error-pulling-container-image)\nin the Troubleshoot Dataflow errors page.\n\nWorkers are not starting or work is not progressing\n\nSometimes, if the SDK container fails to start due to an error,\nDataflow is unable to determine whether the error is permanent or\nfatal. Dataflow then continuously attempts to restart the worker.\n\nIf there are no obvious errors but you see `[topologymanager] RemoveContainer`\n`INFO`-level logs in `dataflow.googleapis.com/kubelet`, these logs indicate that the\ncustom container image is exiting early and did not start the long-running\nworker SDK process.\n\nIf workers have started successfully but no work is happening, an error might\nbe preventing the SDK container from starting. In this case, the following\nerror appears in the diagnostic recommendations: \n\n Failed to start container\n\nIn addition, the worker logs don't contain lines such as the following: \n\n Executing: python -m apache_beam.runners.worker.sdk_worker_main or Executing: java ... FnHarness\n\nFind specific errors in [Worker logs](#worker-logs) and check\n[common error guidance](/dataflow/docs/guides/common-errors).\n\nCommon causes for these issues include the following:\n\n- Problems with package installation, such as `pip` installation errors due to dependency issues. See [Error syncing pod ... failed to \"StartContainer\"](/dataflow/docs/guides/common-errors#error-syncing-pod).\n- If the container used is not compatible with the worker VM's CPU architecture, you might see errors like `exec format error`. For more information, see [Error syncing pod ... failed to \"StartContainer\"](/dataflow/docs/guides/common-errors#error-syncing-pod).\n- Errors with the custom command arguments or with the `ENTRYPOINT` set in the Dockerfile. For example, a custom `ENTRYPOINT` does not start the default boot script `/opt/apache/beam/boot` or does not pass arguments appropriately to this script. For more information, see [Modifying the container entrypoint](/dataflow/docs/guides/build-container-image#custom-entrypoint).\n- Errors when the Apache Beam SDK version is mismatched between the launch environment and the runtime environment. In one failure mode, the default values that are set in the Apache Beam SDK pipeline options might become unrecognized. For example, you might see errors such as `sdk_worker_main.py: error: argument\n --flink_version: invalid choice: '1.16' (choose\n from '1.12', '1.13', '1.14', '1.15')` in the worker logs. To remediate, install the same version of the Apache Beam SDK in the container image as you use to launch the pipeline. For more information, see [Make the launch environment compatible with the runtime environment](https://beam.apache.org/documentation/sdks/python-pipeline-dependencies#make-the-launch-environment-compatible-with-the-runtime-environment).\n\nThe container cannot be configured to execute as a custom user\n\nThe user for container execution is selected by the Dataflow\nservice. For more information, see [Runtime environment](/dataflow/docs/concepts/security-and-permissions#runtime_environment)."]]
