Merge "update dataflow job permissions doc strings"

-- Branch commit log -- commit fd297cccf05ea4e442656b4672d56ffe95388719 Author: gcpdiag team <[email protected]> Date: 2024-09-18T11:31:07Z update dataflow job permissions doc strings Change-Id: I5d4f041a30a776566735f9a74ec210fad74a661a GitOrigin-RevId: 94b61497a0156fd45985a5bca69ad590239a8d2c
GoogleCloudPlatform · Sep 18, 2024 · 87bf38a · 87bf38a
1 parent 94c5d4e
commit 87bf38a
Show file tree

Hide file tree

Showing 5 changed files with 82 additions and 39 deletions.
diff --git a/.../runbook/dataflow/dataflow_permissions.py → gcpdiag/runbook/dataflow/job_permissions.py b/.../runbook/dataflow/dataflow_permissions.py → gcpdiag/runbook/dataflow/job_permissions.py
@@ -11,7 +11,7 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
-"""Contains diagnostic tree for Dataflow Permissions Checks."""
+"""Module containing Dataflow Jobs permissions check diagnostic tree and custom steps."""
 
 from gcpdiag import runbook
 from gcpdiag.queries import crm, iam, logs
@@ -25,26 +25,38 @@
 
 
 def local_realtime_query(filter_str):
-  result = logs.realtime_query(project_id=op.get(flags.PROJECT_ID),
-                               start_time_utc=op.get(flags.START_TIME_UTC),
-                               end_time_utc=op.get(flags.END_TIME_UTC),
-                               filter_str=filter_str)
+  result = logs.realtime_query(
+      project_id=op.get(flags.PROJECT_ID),
+      start_time_utc=op.get(flags.START_TIME_UTC),
+      end_time_utc=op.get(flags.END_TIME_UTC),
+      filter_str=filter_str,
+  )
   return result
 
 
-class DataflowPermissions(runbook.DiagnosticTree):
-  """Analysis and Resolution of Dataflow Permissions issues.
+class JobPermissions(runbook.DiagnosticTree):
+  """Analysis and Resolution of Dataflow Jobs Permissions issues.
 
-  This  runbook investigates Dataflow permissions and recommends remediation steps.
+  This runbook investigates Dataflow permissions and recommends remediation steps.
 
   Areas Examined:
-  1. Dataflow user account permissions
-  2. Dataflow Service Account
-  3. Dataflow Worker Service Account
-  4. Dataflow Resource Permissions
+  - Dataflow User Account Permissions: Verify that individual Dataflow users have the necessary
+    permissions to access and manage Dataflow jobs (e.g., create,update,cancel).
+
+  - Dataflow Service Account Permissions: Verify that the Dataflow Service Account has the required
+    permissions to execute and manage the Dataflow jobs
+
+  - Dataflow Worker Service Account: Verify that the Dataflow Worker Service Account has the
+    necessary permissions for worker instances within a Dataflow job to access input and
+    output resources during job execution.
+
+  - Dataflow Resource Permissions: Verify that Dataflow resources (e.g., Cloud Storage buckets,
+    BigQuery datasets) have the necessary permissions to be accessed and used by Dataflow jobs.
+
+  By ensuring that Dataflow resources have the necessary permissions, you
+  can prevent errors and ensure that your jobs run smoothly.
   """
 
-  #Specify the parameters required for the runbook execution
   parameters = {
       flags.PROJECT_ID: {
           'type': str,
@@ -60,9 +72,9 @@ class DataflowPermissions(runbook.DiagnosticTree):
       },
       flags.WORKER_SERVICE_ACCOUNT: {
           'type': str,
-          'help': (
-              'Dataflow Service Account used for Dataflow Job Creation and execution'
-          ),
+          'help':
+              ('Dataflow Worker Service Account used for Dataflow Job Creation'
+               'and execution'),
           'required': True,
       },
       flags.CROSS_PROJECT_ID: {
@@ -71,7 +83,7 @@ class DataflowPermissions(runbook.DiagnosticTree):
           'help':
               ('Cross Project ID, where service account is located if it is not'
                ' in the same project as the Dataflow Job'),
-      }
+      },
   }
 
   def build_tree(self):
@@ -222,7 +234,13 @@ def execute(self):
 
 
 class DataflowResourcePermissions(runbook.Step):
-  """Check the Dataflow Resource permissions."""
+  """Check the Dataflow Resource permissions.
+
+  Verify that Dataflow resources have the necessary permissions to be accessed
+  and used by Dataflow jobs.
+  Ensure that the your Dataflow project Worker Service Account have the
+  required permissions to access and modify these resources.
+  """
 
   def execute(self):
     """Check the Dataflow Resource permissions."""
@@ -254,4 +272,4 @@ class DataflowPermissionsEnd(runbook.EndStep):
 
   def execute(self):
     """Permissions checks completed."""
-    op.info('Dataflow Permissions Checks Completed')
+    op.info('Dataflow Resources Permissions Checks Completed')
diff --git a/...ook/dataflow/dataflow_permissions_test.py → .../runbook/dataflow/job_permissions_test.py b/...ook/dataflow/dataflow_permissions_test.py → .../runbook/dataflow/job_permissions_test.py
@@ -11,15 +11,15 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
-"""Test class for dataflow/DataflowPermissions"""
+"""Test class for dataflow/JobPermissions"""
 
 from gcpdiag import config
 from gcpdiag.runbook import dataflow, snapshot_test_base
 
 
 class Test(snapshot_test_base.RulesSnapshotTestBase):
   rule_pkg = dataflow
-  runbook_name = 'dataflow/dataflow-permissions'
+  runbook_name = 'dataflow/job-permissions'
   config.init({'auto': True, 'interface': 'cli'})
 
   rule_parameters = [{

diff --git a/...taflow/snapshots/dataflow_permissions.txt → ...ok/dataflow/snapshots/job_permissions.txt b/...taflow/snapshots/dataflow_permissions.txt → ...ok/dataflow/snapshots/job_permissions.txt
@@ -1,15 +1,26 @@
 custom_flag=dataflow,[email protected],project_id=gcpdiag-
 dataflow1-aaaa,worker_service_account=dataflow-worker@gcpdiag-dataflow1-aaaa.iam.gserviceaccount.com
 
-dataflow/dataflow-permissions: Analysis and Resolution of Dataflow Permissions issues.
+dataflow/job-permissions: Analysis and Resolution of Dataflow Jobs Permissions issues.
 
-  This  runbook investigates Dataflow permissions and recommends remediation steps.
+  This runbook investigates Dataflow permissions and recommends remediation steps.
 
   Areas Examined:
-  1. Dataflow user account permissions
-  2. Dataflow Service Account
-  3. Dataflow Worker Service Account
-  4. Dataflow Resource Permissions
+  - Dataflow User Account Permissions: Verify that individual Dataflow users have the necessary
+    permissions to access and manage Dataflow jobs (e.g., create,update,cancel).
+
+  - Dataflow Service Account Permissions: Verify that the Dataflow Service Account has the required
+    permissions to execute and manage the Dataflow jobs
+
+  - Dataflow Worker Service Account: Verify that the Dataflow Worker Service Account has the
+    necessary permissions for worker instances within a Dataflow job to access input and
+    output resources during job execution.
+
+  - Dataflow Resource Permissions: Verify that Dataflow resources (e.g., Cloud Storage buckets,
+    BigQuery datasets) have the necessary permissions to be accessed and used by Dataflow jobs.
+
+  By ensuring that Dataflow resources have the necessary permissions, you
+  can prevent errors and ensure that your jobs run smoothly.
 
 [START]: Executing default start step for runbooks...
 [AUTOMATED STEP]: Check the Authenticated User account permissions.
@@ -55,6 +66,6 @@ dataflow/dataflow-permissions: Analysis and Resolution of Dataflow Permissions i
 [AUTOMATED STEP]: Check the Dataflow Resource permissions.
 [INFO]: No Cloud Storage buckets related errors found in the logs
 [END]: Permissions checks completed.
-[INFO]: Dataflow Permissions Checks Completed
+[INFO]: Dataflow Resources Permissions Checks Completed
 
 
diff --git a/...ic-trees/dataflow/dataflow-permissions.md → ...gnostic-trees/dataflow/job-permissions.md b/...ic-trees/dataflow/dataflow-permissions.md → ...gnostic-trees/dataflow/job-permissions.md
@@ -1,29 +1,40 @@
 ---
-title: "dataflow/Dataflow Permissions"
-linkTitle: "dataflow/dataflow-permissions"
+title: "dataflow/Job Permissions"
+linkTitle: "dataflow/job-permissions"
 weight: 3
 type: docs
 description: >
-  Analysis and Resolution of Dataflow Permissions issues.
+  Analysis and Resolution of Dataflow Jobs Permissions issues.
 ---
 
 **Product**: [Dataflow](https://cloud.google.com/dataflow)
 **Kind**: Debugging Tree
 
 ### Description
 
-This  runbook investigates Dataflow permissions and recommends remediation steps.
+This runbook investigates Dataflow permissions and recommends remediation steps.
 
   Areas Examined:
-  1. Dataflow user account permissions
-  2. Dataflow Service Account
-  3. Dataflow Worker Service Account
-  4. Dataflow Resource Permissions
+  - Dataflow User Account Permissions: Verify that individual Dataflow users have the necessary
+    permissions to access and manage Dataflow jobs (e.g., create,update,cancel).
+
+  - Dataflow Service Account Permissions: Verify that the Dataflow Service Account has the required
+    permissions to execute and manage the Dataflow jobs
+
+  - Dataflow Worker Service Account: Verify that the Dataflow Worker Service Account has the
+    necessary permissions for worker instances within a Dataflow job to access input and
+    output resources during job execution.
+
+  - Dataflow Resource Permissions: Verify that Dataflow resources (e.g., Cloud Storage buckets,
+    BigQuery datasets) have the necessary permissions to be accessed and used by Dataflow jobs.
+
+  By ensuring that Dataflow resources have the necessary permissions, you
+  can prevent errors and ensure that your jobs run smoothly.
 
 ### Executing this runbook
 
 ```shell
-gcpdiag runbook dataflow/dataflow-permissions \
+gcpdiag runbook dataflow/job-permissions \
   -p project_id=value \
   -p principal=value \
   -p worker_service_account=value \
@@ -36,7 +47,7 @@ gcpdiag runbook dataflow/dataflow-permissions \
 |------|----------|---------|------|------|
 | `project_id` | True | None | str | The Project ID of the resource under investigation |
 | `principal` | True | None | str | The authenticated user account email. This is the user account that is used to authenticate the user to the console or the gcloud CLI. |
-| `worker_service_account` | True | None | str | Dataflow Service Account used for Dataflow Job Creation and execution |
+| `worker_service_account` | True | None | str | Dataflow Worker Service Account used for Dataflow Job Creationand execution |
 | `cross_project_id` | False | None | str | Cross Project ID, where service account is located if it is not in the same project as the Dataflow Job |
 
 Get help on available commands

diff --git a/website/content/en/runbook/steps/dataflow/dataflow-resource-permissions.md b/website/content/en/runbook/steps/dataflow/dataflow-resource-permissions.md
@@ -12,7 +12,10 @@ description: >
 
 ### Description
 
-None
+Verify that Dataflow resources have the necessary permissions to be accessed
+  and used by Dataflow jobs.
+  Ensure that the your Dataflow project Worker Service Account have the
+  required permissions to access and modify these resources.