Dataflow를 사용하여 파이프라인을 실행하면 Dataflow 실행기는 파이프라인 코드와 종속 항목을 Cloud Storage 버킷에 업로드하고 Dataflow 작업을 만듭니다. 이 Dataflow 작업은Google Cloud의 관리형 리소스에서 파이프라인을 실행합니다.
Apache Beam Java SDK 버전 2.54.0 이상을 사용하는 일괄 파이프라인의 경우 기본적으로 Runner v2가 사용 설정됩니다.
Apache Beam Java SDK를 사용하는 파이프라인의 경우 다국어 파이프라인을 실행하거나 커스텀 컨테이너를 사용하거나 Spanner 또는 Bigtable 변경 내역 파이프라인을 사용할 때 Runner v2가 필요합니다. 다른 경우에는 기본 실행기를 사용합니다.
Apache Beam Python SDK 버전 2.21.0 이상을 사용하는 파이프라인의 경우 기본적으로 Runner v2가 사용 설정됩니다. Apache Beam Python SDK 버전 2.45.0 이상을 사용하는 파이프라인의 경우 Dataflow Runner v2가 사용할 수 있는 유일한 Dataflow Runner입니다.
Go용 Apache Beam SDK에서는 Dataflow Runner v2가 사용할 수 있는 유일한 Dataflow Runner입니다.
Runner v2는 일부 파이프라인에 도움이 되는 서비스 기반 아키텍처를 사용합니다.
Dataflow Runner v2를 사용하면 Python 컨테이너를 사전 빌드하여 VM 시작 시간과 수평 자동 확장 성능을 개선할 수 있습니다. 자세한 내용은 Python 종속 항목 사전 빌드를 참조하세요.
Dataflow Runner v2에는 스트리밍 작업에 Streaming Engine이 필요하므로 Dataflow Runner v2가 필요한 모든 Apache Beam 변환에도 스트리밍 작업에 Streaming Engine을 사용해야 합니다. 예를 들어 Python용 Apache Beam SDK의 Pub/Sub 라이트 I/O 커넥터는 Dataflow Runner v2가 필요한 교차 언어 변환입니다. 이 변환을 사용하는 작업 또는 템플릿에 대해 스트리밍 엔진을 사용 중지하려고 시도하면 작업이 실패합니다.
Apache Beam Java SDK를 사용하는 스트리밍 파이프라인의 경우 Runner v2에서는 MapState 및 SetState 클래스가 지원되지 않습니다. Java 파이프라인에서 MapState 및 SetState 클래스를 사용하려면 Streaming Engine을 사용 설정하고 Runner v2를 사용 중지한 후 Apache Beam SDK 버전 2.58.0 이상을 사용합니다.
Dataflow 기본 템플릿은 생성 시 사용된 Dataflow 실행자와 다른 버전으로 실행할 수 없습니다. 즉, Google에서 제공하는 기본 템플릿에서는 Runner v2를 사용 설정할 수 없습니다. 커스텀 템플릿에서 Runner v2를 사용 설정하려면 템플릿을 빌드할 때 --experiments=use_runner_v2 플래그를 설정해야 합니다.
알려진 자동 확장 문제로 인해 스테이트풀(Stateful) 처리가 필요한 일괄 Java 파이프라인에서는 Runner v2가 기본적으로 사용 중지됩니다.
이러한 파이프라인에 대해 Runner v2를 사용 설정할 수는 있지만(자세한 내용은 Runner v2 사용 설정 참조), 이 경우 파이프라인 성능에 심각한 병목이 발생할 수 있습니다.
Runner v2 사용 설정
Dataflow Runner v2를 사용 설정하려면 Apache Beam SDK에 대한 구성 안내를 따르세요.
Java
Dataflow Runner v2에는 Apache Beam Java SDK 버전 2.30.0 이상이 필요하며 버전 2.44.0 이상이 권장됩니다.
Apache Beam Java SDK 버전 2.54.0 이상을 사용하는 일괄 파이프라인의 경우 기본적으로 Runner v2가 사용 설정됩니다.
Runner v2를 사용 설정하려면 use_runner_v2 실험을 사용하여 작업을 실행합니다. 자세한 내용은 실험용 파이프라인 옵션 설정을 참조하세요.
Python
Apache Beam Python SDK 버전 2.21.0 이상을 사용하는 파이프라인의 경우 기본적으로 Runner v2가 사용 설정됩니다.
작업자 VM 로그는 로그 탐색기 및 Dataflow 모니터링 인터페이스를 통해 제공됩니다.
작업자 VM 로그에는 실행기 하네스 프로세스의 로그 및 SDK 프로세스의 로그가 포함됩니다. VM 로그를 사용하여 작업 문제를 해결할 수 있습니다.
Runner v2 문제 해결
Dataflow Runner v2를 사용하여 작업 문제를 해결하려면 표준 파이프라인 문제 해결 단계를 수행합니다.
다음 목록은 Dataflow Runner v2가 작동하는 방법에 대한 추가 정보를 제공합니다.
Dataflow Runner v2 작업은 작업자 VM에서 두 가지 유형의 프로세스(SDK 프로세스 및 실행기 하네스 프로세스)를 실행합니다. 파이프라인 및 VM 유형에 따라 하나 이상의 SDK 프로세스가 존재할 수 있지만 VM당 실행기 하네스 프로세스는 하나만 있습니다.
SDK 프로세스가 사용자 코드 및 기타 언어별 함수를 실행합니다. 실행기 하네스 프로세스는 다른 모든 것을 관리합니다.
실행기 하네스 프로세스는 Dataflow에서 작업을 요청하기 전에 모든 SDK 프로세스가 연결되기를 기다립니다.
SDK 프로세스 시작 중에 작업자 VM이 종속 항목을 다운로드하고 설치하면 작업이 지연될 수 있습니다. 라이브러리를 시작하거나 설치할 때와 같이 SDK 프로세스 중에 문제가 발생하면 작업자가 해당 상태를 비정상으로 보고합니다. 시작 시간이 증가하면 프로젝트에서 Cloud Build API를 사용 설정하고 다음 매개변수를 사용하여 파이프라인을 제출합니다.--prebuild_sdk_container_engine=cloud_build
Dataflow Runner v2는 체크포인트를 사용하므로 각 작업자는 추가 처리를 위해 변경사항을 전송하기 전에 변경사항을 버퍼링하는 동안 최대 5초까지 기다릴 수 있습니다. 따라서 지연 시간이 약 6초일 수 있습니다.
사용자 코드의 문제를 진단하려면 SDK 프로세스에서 작업자 로그를 검사합니다. 실행기 하네스 로그에서 오류를 발견하면 지원팀에 문의하여 버그를 신고하세요.
Dataflow 다국어 파이프라인과 관련된 일반적인 오류를 디버깅하려면 다국어 파이프라인 팁 가이드를 참조하세요.
[[["이해하기 쉬움","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-09-04(UTC)"],[[["\u003cp\u003eDataflow Runner v2 is enabled by default for batch pipelines using Apache Beam Java SDK 2.54.0 or later and Python SDK 2.21.0 or later, and is the only available runner for Go SDK.\u003c/p\u003e\n"],["\u003cp\u003eRunner v2 supports multi-language pipelines, allowing the use of transforms from other Apache Beam SDKs, such as using Java transforms from a Python pipeline or vice versa.\u003c/p\u003e\n"],["\u003cp\u003eRunner v2 requires Streaming Engine for all streaming jobs and includes specific limitations for certain classes within the Apache Beam Java SDK, such as \u003ccode\u003eMapState\u003c/code\u003e and \u003ccode\u003eSetState\u003c/code\u003e.\u003c/p\u003e\n"],["\u003cp\u003eTo use Runner v2 when it is not enabled by default or to disable it when it is, the \u003ccode\u003e--experiments=use_runner_v2\u003c/code\u003e or \u003ccode\u003e--experiments=disable_runner_v2\u003c/code\u003e flags can be used, respectively, depending on the SDK.\u003c/p\u003e\n"],["\u003cp\u003eTroubleshooting Runner v2 involves monitoring both SDK process and runner harness process logs, with the SDK processes running user code and the runner harness managing other tasks.\u003c/p\u003e\n"]]],[],null,["# Use Dataflow Runner v2\n\nWhen you use Dataflow to run your pipeline, the\nDataflow runner uploads your pipeline code and dependencies to a\nCloud Storage bucket and creates a Dataflow job. This\nDataflow job runs your pipeline on managed resources in\nGoogle Cloud.\n\n- For batch pipelines that use the Apache Beam Java SDK versions 2.54.0 or later, Runner v2 is enabled by default.\n- For pipelines that use the Apache Beam Java SDK, Runner v2 is required when running multi-language pipelines, using custom containers, or using Spanner or Bigtable change stream pipelines. In other cases, use the default runner.\n- For pipelines that use the Apache Beam Python SDK versions 2.21.0 or later, Runner v2 is enabled by default. For pipelines that use the Apache Beam Python SDK versions 2.45.0 and later, Dataflow Runner v2 is the only Dataflow runner available.\n- For the Apache Beam SDK for Go, Dataflow Runner v2 is the only Dataflow runner available.\n\nRunner v2 uses a services-based architecture that benefits\nsome pipelines:\n\n- Dataflow Runner v2 lets you pre-build your Python\n container, which can improve VM startup times and Horizontal Autoscaling\n performance. For more information, see\n [Pre-build Python dependencies](/dataflow/docs/guides/build-container-image#prebuild).\n\n- Dataflow Runner v2 supports\n [multi-language pipelines](https://beam.apache.org/documentation/programming-guide/#multi-language-pipelines),\n a feature that enables your Apache Beam pipeline to use transforms defined in\n other Apache Beam SDKs. Dataflow Runner v2 supports\n [using Java transforms from a Python SDK pipeline](https://beam.apache.org/documentation/sdks/python-multi-language-pipelines/)\n and\n [using Python transforms from a Java SDK pipeline](https://beam.apache.org/documentation/sdks/java-multi-language-pipelines/).\n When you run Apache Beam pipelines without Runner v2, the\n Dataflow runner uses language-specific workers.\n\nLimitations and restrictions\n----------------------------\n\nDataflow Runner v2 has the following requirements:\n\n- Dataflow Runner v2 requires [Streaming Engine](/dataflow/docs/streaming-engine) for streaming jobs.\n- Because Dataflow Runner v2 requires Streaming Engine for streaming jobs, any Apache Beam transform that requires Dataflow Runner v2 also requires the use of Streaming Engine for streaming jobs. For example, the [Pub/Sub Lite I/O\n connector](https://beam.apache.org/releases/pydoc/current/apache_beam.io.gcp.pubsublite.html) for the Apache Beam SDK for Python is a cross-language transform that requires Dataflow Runner v2. If you try to disable Streaming Engine for a job or template that uses this transform, the job fails.\n- For streaming pipelines that use the Apache Beam Java SDK, the classes [`MapState`](https://beam.apache.org/releases/javadoc/current/index.html?org/apache/beam/sdk/state/MapState.html) and [`SetState`](https://beam.apache.org/releases/javadoc/current/index.html?org/apache/beam/sdk/state/SetState.html) are not supported with Runner v2. To use the `MapState` and `SetState` classes with Java pipelines, enable Streaming Engine, disable Runner v2, and use the Apache Beam SDK version 2.58.0 or later.\n- For batch and streaming pipelines that use the Apache Beam Java SDK, the class [`AfterSynchronizedProcessingTime`](https://beam.apache.org/releases/javadoc/current/org/apache/beam/sdk/transforms/windowing/AfterSynchronizedProcessingTime.html) isn't supported.\n- Dataflow [classic\n templates](/dataflow/docs/guides/templates/running-templates) can't be run with a different version of the Dataflow runner than they were built with. This means that Google-provided classic templates can't enable Runner v2. To enable Runner v2 for custom templates, set the `--experiments=use_runner_v2` flag when you build the template.\n- Due to a known autoscaling issue, Runner v2 is disabled by default for batch Java pipelines that require [stateful processing](https://beam.apache.org/documentation/programming-guide/#state-and-timers). You can still enable Runner v2 for those pipelines (see [Enable Runner v2](/dataflow/docs/runner-v2#enable)), but pipeline performance might be severely bottlenecked.\n\nEnable Runner v2\n----------------\n\nTo enable Dataflow Runner v2, follow the configuration\ninstructions for your Apache Beam SDK. \n\n### Java\n\nDataflow Runner v2 requires the Apache Beam Java SDK\nversions 2.30.0 or later, with version 2.44.0 or later being recommended.\n\nFor batch pipelines that use the Apache Beam Java SDK versions\n2.54.0 or later, Runner v2 is enabled by default.\n\nTo enable Runner v2, run your job with the `use_runner_v2` experiment. For\nmore information, see\n[Set experimental pipeline options](/dataflow/docs/guides/setting-pipeline-options#experimental).\n\n### Python\n\nFor pipelines that use the Apache Beam Python SDK versions\n2.21.0 or later, Runner v2 is enabled by default.\n\nDataflow Runner v2 isn't supported with the Apache Beam\nPython SDK versions 2.20.0 and earlier.\n\nIn some cases, your pipeline might not use Runner v2 even though\nthe pipeline runs on a supported SDK version. To run the job with Runner v2,\nset the `use_runner_v2` experiment. For more information, see\n[Set experimental pipeline options](/dataflow/docs/guides/setting-pipeline-options#experimental).\n\n### Go\n\nDataflow Runner v2 is the only Dataflow runner\navailable for the Apache Beam SDK for Go. Runner v2 is enabled by default.\n\nDisable Runner v2\n-----------------\n\nTo disable Dataflow Runner v2, follow the configuration\ninstructions for your Apache Beam SDK. \n\n### Java\n\nTo disable Runner v2, set the `disable_runner_v2` experiment. For more\ninformation, see\n[Set experimental pipeline options](/dataflow/docs/guides/setting-pipeline-options#experimental).\n\n### Python\n\nDisabling Runner v2 is not supported with the Apache Beam Python SDK\nversions 2.45.0 and later.\n\nFor earlier versions of the Python SDK, if your job is identified as using the\n`auto_runner_v2` experiment, you can disable Runner v2 by setting the\n`disable_runner_v2` experiment. For more information, see\n[Set experimental pipeline options](/dataflow/docs/guides/setting-pipeline-options#experimental).\n\n### Go\n\nDataflow Runner v2 can't be disabled in Go. Runner v2 is the\nonly Dataflow runner available for the Apache Beam SDK for\nGo.\n\nMonitor your job\n----------------\n\nUse the monitoring interface to view\n[Dataflow job metrics](/dataflow/docs/guides/using-monitoring-intf),\nsuch as memory utilization, CPU utilization, and more.\n\nWorker VM logs are available through the\n[Logs Explorer](/logging/docs/view/logs-explorer-interface) and the\n[Dataflow monitoring interface](/dataflow/docs/guides/monitoring-overview).\nWorker VM logs include logs from the runner harness process and logs from the SDK\nprocesses. You can use the VM logs to troubleshoot your job.\n\nTroubleshoot Runner v2\n----------------------\n\nTo troubleshoot jobs using Dataflow Runner v2, follow\n[standard pipeline troubleshooting steps](/dataflow/docs/guides/troubleshooting-your-pipeline).\nThe following list provides additional information about how\nDataflow Runner v2 works:\n\n- Dataflow Runner v2 jobs run two types of processes on the worker VM: SDK process and the runner harness process. Depending on the pipeline and VM type, there might be one or more SDK processes, but there is only one runner harness process per VM.\n- SDK processes run user code and other language-specific functions. The runner harness process manages everything else.\n- The runner harness process waits for all SDK processes to connect to it before starting to request work from Dataflow.\n- Jobs might be delayed if the worker VM downloads and installs dependencies during the SDK process startup. If issues occur during an SDK process, such as when starting up or installing libraries, the worker reports its status as unhealthy. If the startup times increase, enable the Cloud Build API on your project and submit your pipeline with the following parameter: `--prebuild_sdk_container_engine=cloud_build`.\n- Because Dataflow Runner v2 uses checkpointing, each worker might wait for up to five seconds while buffering changes before sending the changes for further processing. As a result, latency of approximately six seconds is expected.\n\n| **Note:** The pre-build feature requires the Apache Beam SDK for Python, version 2.25.0 or later.\n\n- To diagnose problems in your user code, examine the worker logs from the SDK processes. If you find any errors in the runner harness logs, [contact Support](https://console.cloud.google.com/support) to file a bug.\n- To debug common errors related to Dataflow multi-language pipelines, see the [Multi-language Pipelines Tips](https://cwiki.apache.org/confluence/display/BEAM/Multi-language+Pipelines+Tips) guide."]]
