Dataflow security and permissions

Dataflow pipelines can be run locally (to perform tests on small datasets), or on managed Google Cloud resources using the Dataflow managed service. Whether running locally or in the cloud, your pipeline and its workers use a permissions system to maintain secure access to pipeline files and resources. Dataflow permissions are assigned according to the role that's used to access pipeline resources. This document explains the following concepts:

• Upgrading Dataflow VMs.
• Roles and permissions required for running local and Google Cloud pipelines.
• Roles and permissions required for accessing pipeline resources across projects.
• Types of data used in a Dataflow service and in data security.

Before you begin

Read about Google Cloud project identifiers in the Platform Overview. These identifiers include the project name, project ID, and project number.

Upgrade and patch Dataflow VMs

Dataflow uses Container-Optimized OS. Hence, the security processes of Container-Optimized OS also apply to Dataflow.

Batch pipelines are time-bound and do not require maintenance. When a new batch pipeline starts, the latest Dataflow image is used.

For streaming pipelines, if a security patch is immediately required, Google Cloud notifies you by using security bulletins. For streaming pipelines, we recommend that you use the --update option to restart your job with the latest Dataflow image.

Dataflow container images are available in the Google Cloud console.

Security and permissions for local pipelines

When you run locally, your Apache Beam pipeline runs as the Google Cloud account that you configured with the Google Cloud CLI executable. Hence, locally run Apache Beam SDK operations and your Google Cloud account have access to the same files and resources.

To list the Google Cloud account that you selected as your default, run the gcloud config list command.

Note: Local pipelines can output data to local destinations, such as local files, or to cloud destinations, such as Cloud Storage or BigQuery. If your locally run pipeline writes files to cloud-based resources such as Cloud Storage, it uses your Google Cloud account credentials and the Google Cloud project that you configured as the Google Cloud CLI default. For instructions about how to authenticate with your Google Cloud account credentials, see the quickstart for the language you're using.

Security and permissions for pipelines on Google Cloud

When you run your pipeline, Dataflow uses two service accounts to manage security and permissions:

• The Dataflow service account. The Dataflow service uses the Dataflow service account as part of the job creation request, such as to check project quota and to create worker instances on your behalf. Dataflow also uses the Dataflow service account during job execution to manage the job. This account is also known as the Dataflow service agent.

• The worker service account. Worker instances use the worker service account to access input and output resources after you submit your job. By default, workers use the Compute Engine default service account associated with your project as the worker service account. For the worker service account to be able to create, run, and examine a job, it must have the following roles:

  • roles/dataflow.admin
  • roles/dataflow.worker

In addition, when your Apache Beam pipelines access Google Cloud resources, you need to grant the required roles to your Dataflow project's worker service account. The worker service account needs to be able to access the resources while running the Dataflow job. For example, if your job writes to BigQuery, your service account must also have at least the roles/bigquery.dataEditor role. Examples of resources include:

• Cloud Storage buckets
• BigQuery datasets
• Pub/Sub topics and subscriptions
• Firestore datasets

Finally, to impersonate the service account, your user account must have the following role: iam.serviceAccounts.actAs. Depending on other project permissions, your user account might also need the roles/dataflow.developer role.

To add the required roles in your project, follow these steps.

Console

1. In the Google Cloud console, go to the IAM page.

   Go to IAM

2. Select your project.

3. In the row containing your user account, click Edit principal, and then click Add another role.

4. In the drop-down list, select the role Service Account User.

5. In the row containing the Compute Engine default service account, click Edit principal, and then click Add another role.

6. In the drop-down list, select the role Dataflow Worker.

7. Repeat for the Dataflow Admin and any roles required by resources used in your job, and then click Save.

   For more information about granting roles, see Grant an IAM role by using the console.

gcloud CLI

1. Grant the roles/iam.serviceAccountUser role to your user account. Run the following command:

   gcloud projects add-iam-policy-binding PROJECT_ID --member="user:EMAIL_ADDRESS --role=roles/iam.serviceAccountUser
   

   • Replace PROJECT_ID with your project ID.
   • Replace EMAIL_ADDRESS with the email address for the user account.

2. Grant roles to your Compute Engine default service account. Run the following command once for each of the following IAM roles: roles/dataflow.admin, roles/dataflow.worker, and any roles required by resources used in your job.

   gcloud projects add-iam-policy-binding PROJECT_ID --member="serviceAccount:[e-mail]" --role=SERVICE_ACCOUNT_ROLE
   

   • Replace PROJECT_ID with your project ID.
   • Replace PROJECT_NUMBER with your project number. To find your project number, see Identify projects or use the gcloud projects describe command.
   • Replace SERVICE_ACCOUNT_ROLE with each individual role.

Dataflow service account

All projects that have used the resource Dataflow Job have a Dataflow Service Account, also known as the Dataflow service agent, which has the following email:

service-<project-number>@dataflow-service-producer-prod.iam.gserviceaccount.com

This service account is created and managed by Google and assigned to your project automatically upon first usage of the resource Dataflow Job.

As part of running the Dataflow pipeline, the Dataflow service manipulates resources on your behalf. For example, it creates additional VMs. When you run your pipeline on the Dataflow service, the service uses this service account.

This account is assigned the Dataflow Service Agent role on the project. It has the necessary permissions to run a Dataflow job in the project, including starting Compute Engine workers. This account is used exclusively by the Dataflow service and is specific to your project.

You can review the permissions of the Dataflow service account in the Google Cloud console or the Google Cloud CLI.

Console

1. Go to the Roles page.

   Go to Roles

2. If applicable, select your project.

3. In the list, click the title Cloud Dataflow Service Agent. A page opens that lists the permissions assigned to the Dataflow service account.

gcloud CLI

View the permissions of the Dataflow service account:

gcloud iam roles describe roles/dataflow.serviceAgent

Because Google Cloud services expect to have read/write access to the project and its resources, it's recommended that you do not change the default permissions automatically established for your project. If a Dataflow service account loses permissions to a project, Dataflow cannot launch VMs or perform other management tasks.

If you remove the permissions for the service account from the Identity and Access Management (IAM) policy, the account remains present, because it's owned by the Dataflow service.

Best practice: Create a bucket owned by your project to use as the staging bucket for Dataflow. The default bucket permissions allow Dataflow to use the bucket to stage the executable files of the pipeline.

Worker service account

Compute Engine instances execute Apache Beam SDK operations in the cloud. These workers use the worker service account of your project to access the files and other resources associated with the pipeline. The worker service account is used as the identity for all worker VMs, and all requests that originate from the VM use the worker service account. This service account is also used to interact with resources such as Cloud Storage buckets and Pub/Sub topics.

For the worker service account to be able to create, run, and examine a job, it must have the following roles:

• roles/dataflow.admin
• roles/dataflow.worker

Default worker service account

By default, workers use the Compute Engine default service account of your project as the worker service account. This service account has the following email:

<project-number>[e-mail]

This service account is automatically created when you enable the Compute Engine API for your project from the API Library in the Google Cloud console.

The Compute Engine default service account has broad access to the resources of your project, which makes it easy to get started with Dataflow. However, for production workloads, we recommend that you create a new service account with only the roles and permissions that you need.

Note: In the past, Dataflow users were able to deploy applications that authenticated as the Compute Engine default service account, even if they didn't have permission to impersonate the Compute Engine default service account. This legacy behavior still affects some organizations. For more information, see Requiring impersonation permissions when attaching service accounts to resources.

Specify a user-managed worker service account

If you want to create and use resources with fine-grained access control, you can create a user-managed service account. Use this account as the worker service account.

1. If you do not have a user-managed service account, create a service account.

2. Set the required IAM roles for your service account.

   • For the service account to be able to create, run, and examine a job, it must have the roles roles/dataflow.admin and roles/dataflow.worker, or a custom IAM role with the required permissions for those roles. For a list of the required permissions, see Roles.
   • Your service account might also need additional roles to use Google Cloud resources as required by your job, such as BigQuery, Pub/Sub, or Cloud Storage. For example, if your job reads from BigQuery, your service account must also have at least the roles/bigquery.dataViewer role.
   • Ensure that your user-managed service account has read and write access to the staging and temporary locations specified in the Dataflow job.
   • To impersonate the service account, your user account must have the iam.serviceAccounts.actAs permission.

3. Grant the following roles to the Dataflow Service Account (service-<project-number>@dataflow-service-producer-prod.iam.gserviceaccount.com) and to the Compute Engine Service Agent (service-<project-number>@compute-system.iam.gserviceaccount.com). Both of these accounts are Google-managed service accounts on the user-managed service account. These accounts are in the same project as the user-managed service account, even if the Dataflow job runs in a different project.

   • Service Account Token Creator role (iam.serviceAccountTokenCreator)
   • Service Account User role (iam.serviceAccountUser)

   For instructions demonstrating how to grant roles to service accounts, see the Grant a single role section in the Manage access to service accounts page.

4. When you run your pipeline job, specify your service account.

   Java

   Use the --serviceAccount option and specify your service account when you run your pipeline job from the command line: --serviceAccount=my-service-account-name@<project-id>.iam.gserviceaccount.com

   Use the --service-account-email option and specify your service account when you run your pipeline job as a Flex template: --service-account-email=my-service-account-name@<project-id>.iam.gserviceaccount.com

   Python

   Use the --service_account_email option and specify your service account when you run your pipeline job: --service_account_email=my-service-account-name@<project-id>.iam.gserviceaccount.com

   Go

   Use the --service_account_email option and specify your service account when you run your pipeline job: --service_account_email=my-service-account-name@<project-id>.iam.gserviceaccount.com

You can get a list of the service accounts associated with your project from the Permissions page in the Google Cloud console.

The user-managed service account can be in the same project as your job, or in a different project. If the service account and the job are in different projects, you must configure the service account before you run the job.

Access Google Cloud resources

Your Apache Beam pipelines can access Google Cloud resources, either in the same Google Cloud project or in other projects. These resources include:

• Cloud Storage buckets
• BigQuery datasets
• Pub/Sub topics and subscriptions
• Firestore datasets

To ensure that your Apache Beam pipeline can access these resources, you need to use the resources' respective access control mechanisms to explicitly grant access to your Dataflow project worker service account.

If you use Assured Workloads features with Dataflow, such as EU Regions and Support with Sovereignty Controls, all Cloud Storage, BigQuery, Pub/Sub, I/O connectors, and other resources that your pipeline accesses must be located in your organization's Assured Workloads project or folder.

If you're using a user-managed worker service account, or accessing resources in other projects, then additional action might be needed. The following examples assume that the Compute Engine default service account is used, but you can also use a user-managed worker service account.

Access Cloud Storage buckets

To give your Dataflow project access to a Cloud Storage bucket, make the bucket accessible to your Dataflow project worker service account. You can use Cloud Storage Access Controls to grant the required access.

Note: Ensure that your worker service account permissions are consistent with your IAM settings. Due to the inconsistency between IAM and ACL policies, the Cloud Storage bucket might become inaccessible to your Dataflow jobs when the Cloud Storage bucket is migrated from fine-grained access to uniform bucket-level access. For more information, see Common error guidance.

To get a list of the service accounts associated with your Dataflow project, check the IAM & Admin page in the Google Cloud console. Once you have the account names, you can run gsutil commands to grant the project's service accounts ownership (read/write permission) to both the bucket and its contents.

To grant your Dataflow project's service accounts access to a Cloud Storage bucket, use the following command in your shell or terminal window:

gsutil acl ch -u <project-number>[e-mail]:OWNER gs://BUCKET_NAME

To grant your Dataflow project's service accounts access to the existing contents of a Cloud Storage bucket, use the following command in your shell or terminal window:

gsutil -m acl ch -r -u <project-number>[e-mail]:OWNER gs://BUCKET_NAME

Note: The -m option runs the command in parallel for quicker processing; the -r option runs the command recursively on resources within the bucket.

The prior command grants access only to existing resources. Granting the Dataflow project's service accounts default permission to the bucket allows it to access future resources added to the bucket:

  gsutil defacl ch -u <project-number>[e-mail]:OWNER gs://BUCKET_NAME

Tip: You can also set bucket permissions from the Google Cloud console. See Setting Bucket Permissions for more information.

To determine whether your Google Cloud project owns a particular Cloud Storage bucket, you can use the following console command:

gsutil acl get gs://<your-bucket>

The command outputs a JSON string similar to the following example:

[
  {
    "entity": "project-owners-123456789",
    "projectTeam": {
      "projectNumber": "123456789",
      "team": "owners"
    },
    "role": "OWNER"
  },
  ....
]

The relevant entries are the ones for which the "role" is owner. The associated projectNumber tells you which project owns that bucket. If the project number doesn't match your project's number, you need to either:

• Create a new bucket that is owned by your project.
• Give the appropriate accounts access to the bucket.

To create a new bucket in the Google Cloud project in which you're using Dataflow, use the following console command:

gsutil mb -p <Project to own the bucket> <bucket-name>

Access BigQuery datasets

You can use the BigQueryIO API to access BigQuery datasets, in the same project where you're using Dataflow or in a different project. For the BigQuery source and sink to operate properly, the following two accounts must have access to any BigQuery datasets that your Dataflow job reads from or writes to:

• The Google Cloud account that you use to run the Dataflow job.
• The worker service account that runs the Dataflow job.

You might need to configure BigQuery to explicitly grant access to these accounts. See BigQuery Access Control for more information on granting access to BigQuery datasets using either the BigQuery page or the BigQuery API.

Among the required BigQuery permissions, the bigquery.datasets.get IAM permission is required by the pipeline to access a BigQuery dataset. Typically, most BigQuery IAM roles include the bigquery.datasets.get permission, but the roles/bigquery.jobUser role is an exception.

For example, if your Google Cloud account is [e-mail] and the project number of the project where you execute the Dataflow job is 123456789, the following accounts must all be granted access to the BigQuery Datasets used: [e-mail], and [e-mail].

Access Pub/Sub topics and subscriptions

To access a Pub/Sub topic or subscription, use the Identity and Access Management features of Pub/Sub to set up permissions for the worker service account.

Permissions from the following Pub/Sub roles are relevant:

• roles/pubsub.subscriber is required to consume data.
• roles/pubsub.editor is required to create a Pub/Sub subscription.
• roles/pubsub.viewer is recommended, so that Dataflow can query the configurations of topics and subscriptions. This configuration has two benefits:
  • Dataflow can check for unsupported settings on subscriptions that might not work as expected.
  • If the subscription does not use the default ack deadline of 10 seconds, performance improves. Dataflow repeatedly extends the ack deadline for a message while it's being processed by the pipeline. Without pubsub.viewer permissions, Dataflow is unable to query the ack deadline, and therefore must assume a default deadline. This configuration causes Dataflow to issue more modifyAckDeadline requests than necessary.
  • If VPC Service Controls is enabled on the project that owns the subscription or topic, IP address-based ingress rules don't allow Dataflow to query the configurations. In this case, an ingress rule based on the worker service account is required.

For more information and some code examples that demonstrate how to use the Identity and Access Management features of Pub/Sub, see Sample use case: cross-project communication.

Access Firestore

To access a Firestore database (in Native mode or Datastore mode), add your Dataflow worker service account (for example, <project-number>[e-mail]) as editor of the project that owns the database, or use a more restrictive Datastore role like roles/datastore.viewer. Also, enable the Firestore API in both projects from the API Library in the Google Cloud console.

Access images for projects with a trusted image policy

If you have a trusted image policy set up for your project and your boot image is located in another project, ensure that the trusted image policy is configured to have access to the image. For example, if you're running a templated Dataflow job, ensure that the policy file includes access to the dataflow-service-producer-prod project. This Google Cloud project contains the images for template jobs.

Data access and security

The Dataflow service works with two kinds of data:

• End-user data. This data is processed by a Dataflow pipeline. A typical pipeline reads data from one or more sources, implements transformations of the data, and writes the results to one or more sinks. All the sources and sinks are storage services that are not directly managed by Dataflow.

• Operational data. This data includes all the metadata that is required for managing a Dataflow pipeline. This data includes both user-provided metadata such as a job name or pipeline options and also system-generated metadata such as a job ID.

The Dataflow service uses several security mechanisms to keep your data secure and private. These mechanisms apply to the following scenarios:

• Submitting a pipeline to the service
• Evaluating a pipeline
• Requesting access to telemetry and metrics during and after a pipeline execution
• Using a Dataflow service such as Shuffle or Streaming Engine

Data locality

Note: We recommend that you always specify a region when you run a pipeline. Support for default regions would be discontinued in a future release.

All the core data processing for the Dataflow service happens in the region that is specified in the pipeline code. If a region is not specified, the default region us-central1 is used. If you specify that option in the pipeline code, the pipeline job can optionally read and write from sources and sinks in other regions. However, the actual data processing occurs only in the region that is specified to run the Dataflow VMs.

Pipeline logic is evaluated on individual worker VM instances. You can specify the zone in which these instances and the private network over which they communicate are located. Ancillary computations for the platform depend on metadata such as Cloud Storage locations or file sizes.

Dataflow is a regional service. For more information about data locality and regional endpoints, see Regional endpoints.

Data in a pipeline submission

The IAM permissions for your Google Cloud project control access to the Dataflow service. Any principals who are given editor or owner rights to your project can submit pipelines to the service. To submit pipelines, you must authenticate using the Google Cloud CLI. After you're authenticated, your pipelines are submitted using the HTTPS protocol. For instructions about how to authenticate with your Google Cloud account credentials, see the quickstart for the language that you're using.

Data in a pipeline evaluation

As part of evaluating a pipeline, temporary data might be generated and stored locally in the worker VM instances or in Cloud Storage. Temporary data is encrypted at rest and does not persist after a pipeline evaluation concludes. Such data can also be stored in the Shuffle service or Streaming Engine service (if you have opted for the service) in the same region as specified in the Dataflow pipeline.

Java

By default, Compute Engine VMs are deleted when the Dataflow job completes, regardless of whether the job succeeds or fails. Consequently, the associated Persistent Disk, and any intermediate data that might be stored on it, is deleted. The intermediate data stored in Cloud Storage can be found in sublocations of the Cloud Storage path that you provide as your --stagingLocation and/or --tempLocation. If you're writing output to a Cloud Storage file, temporary files might be created in the output location before the Write operation is finalized.

Python

By default, Compute Engine VMs are deleted when the Dataflow job completes, regardless of whether the job succeeds or fails. Consequently, the associated Persistent Disk, and any intermediate data that might be stored on it, is deleted. The intermediate data stored in Cloud Storage can be found in sublocations of the Cloud Storage path that you provide as your --staging_location and/or --temp_location. If you're writing output to a Cloud Storage file, temporary files might be created in the output location before the Write operation is finalized.

Go

By default, Compute Engine VMs are deleted when the Dataflow job completes, regardless of whether the job succeeds or fails. Consequently, the associated Persistent Disk, and any intermediate data that might be stored on it, is deleted. The intermediate data stored in Cloud Storage can be found in sublocations of the Cloud Storage path that you provide as your --staging_location and/or --temp_location. If you're writing output to a Cloud Storage file, temporary files might be created in the output location before the Write operation is finalized.

Data in pipeline logs and telemetry

Information stored in Cloud Logging is primarily generated by the code in your Dataflow program. The Dataflow service might also generate warning and error data in Cloud Logging, but this data is the only intermediate data that the service adds to logs. Cloud Logging is a global service.

Telemetry data and associated metrics are encrypted at rest, and access to this data is controlled by your Google Cloud project's read permissions.

Data in Dataflow services

If you use Dataflow Shuffle or Dataflow Streaming for your pipeline, do not specify the zone pipeline options. Instead, specify the region and set the value to one of the regions where Shuffle or Streaming is currently available. Dataflow auto-selects the zone in the region that you specify. The end-user data in transit stays within the worker VMs and in the same zone. These Dataflow jobs can still read and write to sources and sinks that are outside the VM zone. The data in transit can also be sent to Dataflow Shuffle or Dataflow Streaming services, however the data always remains in the region specified in the pipeline code.

Recommended practice

We recommend that you use the security mechanisms available in the underlying cloud resources of your pipeline. These mechanisms include the data security capabilities of data sources and sinks such as BigQuery and Cloud Storage. It's also best not to mix different trust levels in a single project.