Update installation docs to include additional roles needed in WI (#1457)

* update docs

* comments

* comments

* update invalid link

* comment

* comments

* comments

Author: grac3gao-zz

README.md

@@ -16,7 +16,7 @@ Follow this guide to install Knative-GCP components on a platform of your
 choice.
 
 1. [Installing Knative-GCP](./docs/install/install-knative-gcp.md)
-1. [Installing Pub/Sub Enabled Service Account](./docs/install/pubsub-service-account.md)
+1. [Installing a Service Account for the Data Plane](./docs/install/dataplane-service-account.md)
 1. [Installing GCP Broker](./docs/install/install-gcp-broker.md)
 1. [Installing Broker with PubSub Channel](./docs/install/install-broker-with-pubsub-channel.md)
 1. [Managing Multiple Projects](./docs/install/managing-multiple-projects.md)

docs/examples/channel/README.md

@@ -11,7 +11,7 @@ intended to provide a durable messaging solution.
    install [Eventing](https://knative.dev/docs/eventing/) as part of the
    installation procedure.
 
-1. [Create a Pub/Sub enabled Service Account](../../install/pubsub-service-account.md)
+1. [Create a Service Account for the Data Plane](../../install/dataplane-service-account.md)
 
 ## Deployment
 
@@ -21,7 +21,7 @@ intended to provide a durable messaging solution.
       [Workload Identity](https://cloud.google.com/kubernetes-engine/docs/how-to/workload-identity),
       update `serviceAccountName` with the Kubernetes service account you
       created in
-      [Create a Pub/Sub enabled Service Account](../../install/pubsub-service-account.md),
+      [Create a Service Account for the Data Plane](../../install/dataplane-service-account.md),
       which is bound to the Pub/Sub enabled Google service account.
 
    1. If you are using standard Kubernetes secrets, but want to use a

docs/examples/cloudauditlogssource/README.md

@@ -10,7 +10,7 @@ directly publish to the underlying transport (Pub/Sub), in CloudEvents format.
 
 1. [Install Knative-GCP](../../install/install-knative-gcp.md)
 
-1. [Create a Pub/Sub enabled Service Account](../../install/pubsub-service-account.md)
+1. [Create a Service Account for the Data Plane](../../install/dataplane-service-account.md)
 
 1. Enable the `Cloud Audit Logs API` on your project:
 
@@ -39,7 +39,7 @@ directly publish to the underlying transport (Pub/Sub), in CloudEvents format.
       [Workload Identity](https://cloud.google.com/kubernetes-engine/docs/how-to/workload-identity),
       update `serviceAccountName` with the Kubernetes service account you
       created in
-      [Create a Pub/Sub enabled Service Account](../../install/pubsub-service-account.md),
+      [Create a Service Account for the Data Plane](../../install/dataplane-service-account.md),
       which is bound to the Pub/Sub enabled Google service account.
 
    1. If you are using standard Kubernetes secrets, but want to use a

docs/examples/cloudbuildsource/README.md

@@ -11,7 +11,7 @@ build completes.
 
 1. [Install Knative-GCP](../../install/install-knative-gcp.md)
 
-1. [Create a Pub/Sub enabled Service Account](../../install/pubsub-service-account.md)
+1. [Create a Service Account for Data Plane](../../install/dataplane-service-account.md)
 
 1. Enable the `Cloud Build API` and `Cloud Pub/Sub API`, on your project:
 
@@ -33,7 +33,7 @@ build completes.
       [Workload Identity](https://cloud.google.com/kubernetes-engine/docs/how-to/workload-identity),
       update `serviceAccountName` with the Kubernetes service account you
       created in
-      [Create a Pub/Sub enabled Service Account](../../install/pubsub-service-account.md),
+      [Create a Service Account for the Data Plane](../../install/dataplane-service-account.md),
       which is bound to the Pub/Sub enabled Google service account.
 
    1. If you are using standard Kubernetes secrets, but want to use a

docs/examples/cloudpubsubsource/README.md

@@ -11,7 +11,7 @@ events using a Push-compatible format.
 
 1. [Install Knative-GCP](../../install/install-knative-gcp.md)
 
-1. [Create a Pub/Sub enabled Service Account](../../install/pubsub-service-account.md)
+1. [Create a Service Account for the Data Plane](../../install/dataplane-service-account.md)
 
 ## Deployment
 
@@ -23,7 +23,7 @@ events using a Push-compatible format.
       [Workload Identity](https://cloud.google.com/kubernetes-engine/docs/how-to/workload-identity),
       update `serviceAccountName` with the Kubernetes service account you
       created in
-      [Create a Pub/Sub enabled Service Account](../../install/pubsub-service-account.md),
+      [Create a Service Account for the Data Plane](../../install/dataplane-service-account.md),
       which is bound to the Pub/Sub enabled Google service account.
 
    1. If you are using standard Kubernetes secrets, but want to use a

docs/examples/cloudschedulersource/README.md

@@ -21,7 +21,7 @@ scheduled events from
    gcloud app create --region=$APP_ENGINE_LOCATION
    ```
 
-1. [Create a Pub/Sub enabled Service Account](../../install/pubsub-service-account.md)
+1. [Create a Service Account for the Data Plane](../../install/dataplane-service-account.md)
 
 1. Enable the `Cloud Scheduler API` on your project:
 
@@ -37,7 +37,7 @@ scheduled events from
       [Workload Identity](https://cloud.google.com/kubernetes-engine/docs/how-to/workload-identity),
       update `serviceAccountName` with the Kubernetes service account you
       created in
-      [Create a Pub/Sub enabled Service Account](../../install/pubsub-service-account.md),
+      [Create a Service Account for the Data Plane](../../install/dataplane-service-account.md),
       which is bound to the Pub/Sub enabled Google service account.
 
    1. If you are using standard Kubernetes secrets, but want to use a

docs/examples/cloudstoragesource/README.md

@@ -10,7 +10,7 @@ Object Notifications for when a new object is added to Google Cloud Storage
 
 1. [Install Knative-GCP](../../install/install-knative-gcp.md)
 
-1. [Create a Pub/Sub enabled Service Account](../../install/pubsub-service-account.md)
+1. [Create a Service Account for the Data Plane](../../install/dataplane-service-account.md)
 
 1. Enable the `Cloud Storage API` on your project and give Google Cloud Storage
    permissions to publish to GCP Pub/Sub. Currently, we support two methods:
@@ -54,7 +54,7 @@ Object Notifications for when a new object is added to Google Cloud Storage
         ```
       - Option 2: Use `curl` to fetch the email:
         ```shell
-        export GCS_SERVICE_ACCOUNT=`curl -s -X GET -H "Authorization: Bearer \`GOOGLE_APPLICATION_CREDENTIALS=./cre-pubsub.json \
+        export GCS_SERVICE_ACCOUNT=`curl -s -X GET -H "Authorization: Bearer \`GOOGLE_APPLICATION_CREDENTIALS=./cre-dataplane.json \
           gcloud auth application-default print-access-token\`" \
           "https://www.googleapis.com/storage/v1/projects/$PROJECT_ID/serviceAccount" \
           | grep email_address | cut -d '"' -f 4`
@@ -84,7 +84,7 @@ Object Notifications for when a new object is added to Google Cloud Storage
       [Workload Identity](https://cloud.google.com/kubernetes-engine/docs/how-to/workload-identity),
       update `serviceAccountName` with the Kubernetes service account you
       created in
-      [Create a Pub/Sub enabled Service Account](../../install/pubsub-service-account.md),
+      [Create a Service Account for the Data Plane](../../install/dataplane-service-account.md),
       which is bound to the Pub/Sub enabled Google service account.
 
    1. If you are using standard Kubernetes secrets, but want to use a

docs/examples/keda/README.md

@@ -48,14 +48,14 @@ the `CloudPubSubSource` scalable. Note that you could do this for any of the
 
 1. [Install Knative-GCP](../../install/install-knative-gcp.md)
 
-1. [Create a Pub/Sub enabled Service Account](../../install/pubsub-service-account.md)
+1. [Create a Service Account for the Data Plane](../../install/dataplane-service-account.md)
 
 1. Given that KEDA queries StackDriver for metrics, give the Service Account
    created in the previous step permissions to do so.
 
    ```shell
    gcloud projects add-iam-policy-binding $PROJECT_ID \
-     --member=serviceAccount:cre-pubsub@$PROJECT_ID.iam.gserviceaccount.com \
+     --member=serviceAccount:cre-dataplane@$PROJECT_ID.iam.gserviceaccount.com \
      --role roles/monitoring.viewer
    ```
 

docs/examples/pullsubscription/README.md

@@ -13,7 +13,7 @@ does so using a Pull format.
 
 1. [Install Knative-GCP](../../install/install-knative-gcp.md)
 
-1. [Create a Pub/Sub enabled Service Account](../../install/pubsub-service-account.md)
+1. [Create a Service Account for the Data Plane](../../install/dataplane-service-account.md)
 
 ## Deployment
 
@@ -31,7 +31,7 @@ does so using a Pull format.
       [Workload Identity](https://cloud.google.com/kubernetes-engine/docs/how-to/workload-identity),
       update `serviceAccountName` with the Kubernetes service account you
       created in
-      [Create a Pub/Sub enabled Service Account](../../install/pubsub-service-account.md),
+      [Create a Service Account for the Data Plane](../../install/dataplane-service-account.md),
       which is bound to the Pub/Sub enabled Google service account.
 
    1. If you are using standard Kubernetes secrets, but want to use a

docs/examples/topic/README.md

@@ -10,7 +10,7 @@ construct used by higher-level objects, such as `Channel`.
 
 1. [Install Knative-GCP](../../install/install-knative-gcp.md)
 
-1. [Create a Pub/Sub enabled Service Account](../../install/pubsub-service-account.md)
+1. [Create a Service Account for the Data Plane](../../install/dataplane-service-account.md)
 
 ## Deployment
 
@@ -27,7 +27,7 @@ construct used by higher-level objects, such as `Channel`.
       [Workload Identity](https://cloud.google.com/kubernetes-engine/docs/how-to/workload-identity),
       update `serviceAccountName` with the Kubernetes service account you
       created in
-      [Create a Pub/Sub enabled Service Account](../../install/pubsub-service-account.md),
+      [Create a Service Account for the Data Plane](../../install/dataplane-service-account.md),
       which is bound to the Pub/Sub enabled Google service account.
 
    1. If you are using standard Kubernetes secrets, but want to use a

docs/install/authentication-mechanisms-gcp.md

@@ -140,7 +140,7 @@ gcloud projects add-iam-policy-binding $PROJECT_ID \
 ## Authentication Mechanism for the Data Plane
 
 Please check
-[Installing Pub/Sub Enabled Service Account](../install/pubsub-service-account.md).
+[Installing a Service Account for the Data Plane](../install/dataplane-service-account.md).
 
 ## Troubleshooting
 
@@ -428,13 +428,13 @@ kubectl get secret -n namespace
       ***
       **_To solve this issue_**, you can:
 
-    * Check the Google Cloud Service Account `cre-pubsub` for the Data Plane has
+    * Check the Google Cloud Service Account `cre-dataplane` for the Data Plane has
       all required permissions.
     * Check authentication configuration is correct for this resource instance.
 
       - If you are using Workload Identity for this resource instance, refer
         [here](./authentication-mechanisms-gcp.md/#workload-identity) to check
-        the Google Cloud Service Account `cre-pubsub`, and the Kubernetes
+        the Google Cloud Service Account `cre-dataplane`, and the Kubernetes
         Service Account in the namespace where this resource instance resides.
       - If you are using Kubernetes Secrets for this resource instance, refer
         [here](./authentication-mechanisms-gcp.md/#kubernetes-secrets) to check
@@ -465,13 +465,13 @@ kubectl get secret -n namespace
       type: Ready
       status: "False"
       message: 'rpc error: code = PermissionDenied desc = Permission iam.serviceAccounts.setIamPolicy
-        is required to perform this operation on service account projects/-/serviceAccounts/cre-pubsub@PROJECT_ID.iam.gserviceaccount.com.'
+        is required to perform this operation on service account projects/-/serviceAccounts/cre-dataplane@PROJECT_ID.iam.gserviceaccount.com.'
       reason: WorkloadIdentityFailed
       ```
       it is most likely that you didn't grant `iam.serviceAccountAdmin`
       permission of the Google Cloud Service Account to the Control Plane's
       Google Cloud Service Account `cloud-run-events`, refer to
-      [default scenario](../install/pubsub-service-account.md/#option-1-use-workload-identity)
+      [default scenario](../install/dataplane-service-account.md/#option-1-use-workload-identity)
       to grant permission.
     - If the `Condition` `Ready` has concurrency related error message like
       this:
@@ -484,5 +484,5 @@ kubectl get secret -n namespace
       ```
       the controller will retry it in the next reconciliation loop (the maximum
       retry period is 5 min). You can also use
-      [non-default scenario](../install/pubsub-service-account.md/#option-1-use-workload-identity)
+      [non-default scenario](../install/dataplane-service-account.md/#option-1-use-workload-identity)
       if this error lasts for a long time.

docs/install/pubsub-service-account.md renamed to docs/install/dataplane-service-account.md

@@ -1,4 +1,4 @@
-# Installing Pub/Sub Enabled Service Account
+# Installing a Service Account for the Data Plane
 
 Besides the control plane setup described in the general
 [installation guide](./install-knative-gcp.md), each of our resources have a
@@ -28,10 +28,10 @@ In general, we would just need permissions to receive messages
 (`roles/pubsub.subscriber`). However, in the case of the `Channel`, we would
 also need the ability to publish messages (`roles/pubsub.publisher`).
 
-1. Create a new Service Account named `cre-pubsub` with the following command:
+1. Create a new Service Account named `cre-dataplane` with the following command:
 
    ```shell
-   gcloud iam service-accounts create cre-pubsub
+   gcloud iam service-accounts create cre-dataplane
    ```
 
 1. Give that Service Account the necessary permissions on your project.
@@ -43,9 +43,24 @@ also need the ability to publish messages (`roles/pubsub.publisher`).
 
    ```shell
    gcloud projects add-iam-policy-binding $PROJECT_ID \
-     --member=serviceAccount:cre-pubsub@$PROJECT_ID.iam.gserviceaccount.com \
+     --member=serviceAccount:cre-dataplane@$PROJECT_ID.iam.gserviceaccount.com \
      --role roles/pubsub.editor
    ```
+   
+   ***Note:***
+   If you are going to use metrics and tracing to track your resources, 
+   you also need `roles/monitoring.metricWriter` for metrics functionality:
+      ```shell
+      gcloud projects add-iam-policy-binding $PROJECT_ID \
+        --member=serviceAccount:cre-dataplane@$PROJECT_ID.iam.gserviceaccount.com \
+        --role roles/monitoring.metricWriter
+      ```
+   and `roles/cloudtrace.agent` for tracing functionality:
+      ```shell
+      gcloud projects add-iam-policy-binding $PROJECT_ID \
+        --member=serviceAccount:cre-dataplane@$PROJECT_ID.iam.gserviceaccount.com \
+        --role roles/cloudtrace.agent
+      ```
 
 ## Configure the Authentication Mechanism for GCP (the Data Plane)
 
@@ -71,7 +86,7 @@ Plane:
 
 - **_Non-default scenario:_**
 
-  Using the Google Cloud Service Account `cre-pubsub` you just created and using
+  Using the Google Cloud Service Account `cre-dataplane` you just created and using
   [Option 1 (Recommended): Workload Identity](../install/authentication-mechanisms-gcp.md/#option-1-recommended-workload-identity)
   in
   [Authentication Mechanism for GCP](../install/authentication-mechanisms-gcp.md)
@@ -82,7 +97,7 @@ Plane:
   configuration in the Control Plane)
 
   You will have a Kubernetes Service Account after the above configuration,
-  which is bound to the Google Cloud Service Account `cre-pubsub`. Remember to
+  which is bound to the Google Cloud Service Account `cre-dataplane`. Remember to
   put this Kubernetes Service Account name as the `spec.serviceAccountName` when
   you create resources in the
   [example](https://github.com/google/knative-gcp/tree/master/docs/examples).
@@ -94,12 +109,12 @@ Plane:
   you can authorize the Controller to configure Workload Identity for you.
 
   You need to grant `iam.serviceAccountAdmin` permission of the Google Cloud
-  Service Account `cre-pubsub` you just created to the Control Plane's Google
+  Service Account `cre-dataplane` you just created to the Control Plane's Google
   Cloud Service Account `cloud-run-events` by:
 
   ```shell
   gcloud iam service-accounts add-iam-policy-binding \
-   cre-pubsub@$PROJECT_ID.iam.gserviceaccount.com  \
+   cre-dataplane@$PROJECT_ID.iam.gserviceaccount.com  \
    --member='serviceAccount:cloud-run-events@$PROJECT_ID.iam.gserviceaccount.com' \
    --role='roles/iam.serviceAccountAdmin'
   ```
@@ -118,22 +133,22 @@ Plane:
   default-auth-config: |
     clusterDefaults:
       workloadIdentityMapping:
-        default-cre-pubsub: cre-pubsub@$PROJECT_ID.iam.gserviceaccount.com
+        default-cre-dataplane: cre-dataplane@$PROJECT_ID.iam.gserviceaccount.com
   ```
 
-  Here, `default-cre-pubsub` refers to a Kubernetes Service Account bound to the
-  Google Cloud Service Account `cre-pubsub`. Remember to put this Kubernetes
+  Here, `default-cre-dataplane` refers to a Kubernetes Service Account bound to the
+  Google Cloud Service Account `cre-dataplane`. Remember to put this Kubernetes
   Service Account name as the `spec.serviceAccountName` when you create
   resources in the
   [example](https://github.com/google/knative-gcp/tree/master/docs/examples).
 
-  Kubernetes Service Account `default-cre-pubsub` doesn't need to exist in a
+  Kubernetes Service Account `default-cre-dataplane` doesn't need to exist in a
   specific namespace. Once it is set in the ConfigMap `config-gcp-auth`， the
   Control Plane will create it for you and configure the corresponding Workload
   Identity relationship between the Kubernetes Service Account
-  `default-cre-pubsub` and the Google Cloud Service Account `cre-pubsub` when
+  `default-cre-dataplane` and the Google Cloud Service Account `cre-dataplane` when
   you create resources using the Kubernetes Service Account
-  `default-cre-pubsub`.
+  `default-cre-dataplane`.
 
 A `Condition` `WorkloadIdentityConfigured` will show up under resources'
 `Status`, indicating the Workload Identity configuration status.  
@@ -142,26 +157,26 @@ as a result, any user who can create a resource can get access to the Google Clo
 Service Account which grants the `iam.serviceAccountAdmin` permission to the Controller.
 As an example, if you followed the instructions above, then any user that can make
 a Knative-GCP source or Channel (e.g. `CloudAuditLogsSource`, `CloudPubSubSource`,
-etc.) can cause the Kubernetes Service Account `default-cre-pubsub` to be created.
+etc.) can cause the Kubernetes Service Account `default-cre-dataplane` to be created.
 If they can also create Pods in that namespace, then they can make a Pod that uses
-the Google Service Account `cre-pubsub` credentials.
+the Google Service Account `cre-dataplane` credentials.
 
 ### Option 2. Export Service Account Keys And Store Them as Kubernetes Secrets
 
 1. Download a new JSON private key for that Service Account. **Be sure not to
    check this key into source control!**
 
    ```shell
-   gcloud iam service-accounts keys create cre-pubsub.json \
-   --iam-account=cre-pubsub@$PROJECT_ID.iam.gserviceaccount.com
+   gcloud iam service-accounts keys create cre-dataplane.json \
+   --iam-account=cre-dataplane@$PROJECT_ID.iam.gserviceaccount.com
    ```
 
 1. Create a secret on the Kubernetes cluster with the downloaded key. Remember
    to create the secret in the namespace your resources will reside. The example
    below does so in the `default` namespace.
 
    ```shell
-   kubectl --namespace default create secret generic google-cloud-key --from-file=key.json=cre-pubsub.json
+   kubectl --namespace default create secret generic google-cloud-key --from-file=key.json=cre-dataplane.json
    ```
 
    `google-cloud-key` and `key.json` are default values expected by our
@@ -178,5 +193,5 @@ the Google Service Account `cre-pubsub` credentials.
 1. Delete the service account
 
    ```shell
-   gcloud iam service-accounts delete cre-pubsub@$PROJECT_ID.iam.gserviceaccount.com
+   gcloud iam service-accounts delete cre-dataplane@$PROJECT_ID.iam.gserviceaccount.com
    ```