Max's edit

Author: max-cx

modules/distr-tracing-tempo-object-storage-setup-gcp-sts-install.adoc

@@ -17,88 +17,91 @@ include::snippets/technology-preview.adoc[leveloffset=+1]
 
 .Procedure
 
-. Create a GCS bucket.
+. Create a GCS bucket on the Google Cloud Platform (GCP).
 
 . Create or reuse a service account with Google's Identity and Access Management (IAM):
 +
-[source,terminal]
+[source,bash]
 ----
-SERVICE_ACCOUNT_EMAIL=$(gcloud iam service-accounts create <IAM_SA_NAME> \ # <1>
+SERVICE_ACCOUNT_EMAIL=$(gcloud iam service-accounts create <iam_service_account_name> \ # <1>
     --display-name="Tempo Account" \
-    --project <PROJECT_ID>  \ # <2>
+    --project <project_id>  \ # <2>
     --format='value(email)' \ 
     --quiet)
 ----
-<1> Name of the service account in Google Cloud.
-<2> Project ID of the service account in Google Cloud.
+<1> The name of the service account on the GCP.
+<2> The project ID of the service account on the GCP.
 
-. Bind the required GCP roles to the created SA at the project level:
+. Bind the required GCP roles to the created service account at the project level:
 +
 [source,terminal]
 ----
-$ gcloud projects add-iam-policy-binding <PROJECT_ID> \
+$ gcloud projects add-iam-policy-binding <project_id> \
     --member "serviceAccount:$SERVICE_ACCOUNT_EMAIL" \
-  --role="roles/iam.workloadIdentityUser"
-
-$ gcloud projects add-iam-policy-binding <PROJECT_ID> \
+  --role="roles/iam.workloadIdentityUser" \
+&&
+  gcloud projects add-iam-policy-binding <project_id> \
     --member "serviceAccount:$SERVICE_ACCOUNT_EMAIL" \
     --role "roles/storage.objectAdmin"
-
 ----
-. Retrieve the `POOL_ID` of the Google Cloud Workload Identity Pool associated with the OpenShift cluster.
+
+. Retrieve the `POOL_ID` value of the Google Cloud Workload Identity Pool that is associated with the cluster:
 +
 [source,terminal]
 ----
-$ OIDC_ISSUER=$(oc get authentication.config cluster -o jsonpath='{.spec.serviceAccountIssuer}')
-
-$ POOL_ID=$(echo "$OIDC_ISSUER" | awk -F'/' '{print $NF}' | sed 's/-oidc$//')
+$ OIDC_ISSUER=$(oc get authentication.config cluster -o jsonpath='{.spec.serviceAccountIssuer}') \
+&&
+  POOL_ID=$(echo "$OIDC_ISSUER" | awk -F'/' '{print $NF}' | sed 's/-oidc$//')
 ----
-.  Allow Kubernetes Service Accounts to impersonate the Google Service Account, SERVICE_ACCOUNT_EMAIL is the output of the commant used to created the service account in the step 2.
+
+.  Permit the Kubernetes Service Accounts to impersonate the Google Service Account:
 +
 [source,terminal]
 ----
-$ gcloud iam service-accounts add-iam-policy-binding "$SERVICE_ACCOUNT_EMAIL" \
+$ gcloud iam service-accounts add-iam-policy-binding "$SERVICE_ACCOUNT_EMAIL" \ # <1>
   --role="roles/iam.workloadIdentityUser" \
-  --member="principal://iam.googleapis.com/projects/<PROJECT_NUMBER>/locations/global/workloadIdentityPools/<POOL_ID>/subject/system:serviceaccount:<TEMPO_NAMESPACE>:tempo-<TEMPO_NAME>" \
-  --project=<PROJECT_ID> \
-  --quiet
-
-$ gcloud iam service-accounts add-iam-policy-binding "$SERVICE_ACCOUNT_EMAIL" \
+  --member="principal://iam.googleapis.com/projects/<project_number>/locations/global/workloadIdentityPools/<pool_id>/subject/system:serviceaccount:<tempo_namespace>:tempo-<tempo_name>" \
+  --project=<project_id> \
+  --quiet \
+&&
+  gcloud iam service-accounts add-iam-policy-binding "$SERVICE_ACCOUNT_EMAIL" \
   --role="roles/iam.workloadIdentityUser" \
-  --member="principal://iam.googleapis.com/projects/$PROJECT_NUMBER/locations/global/workloadIdentityPools/$POOL_ID/subject/system:serviceaccount:${TEMPO_NAMESPACE}:tempo-${TEMPO_NAME}-query-frontend" \
-  --project="$PROJECT_ID" \
+  --member="principal://iam.googleapis.com/projects/<project_number>/locations/global/workloadIdentityPools/<pool_id>/subject/system:serviceaccount:<tempo_namespace>:tempo-<tempo_name>-query-frontend" \
+  --project=<project_id> \
   --quiet
 ----
-. Create credential file used by Tempo Stack, this will be in the key.json key in the storage secret:
+<1> The `$SERVICE_ACCOUNT_EMAIL` is the output of the command in step 2.
+
+. Create a credential file for the `key.json` key of the storage secret for use by the `TempoStack` custom resource:
 +
 [source,terminal]
 ----
 $ gcloud iam workload-identity-pools create-cred-config \
-    "projects/<PROJECT_NUMBER>/locations/global/workloadIdentityPools/$POOL_ID/providers/<PROVIDER_ID>" \
+    "projects/<project_number>/locations/global/workloadIdentityPools/<pool_id>/providers/<provider_id>" \
     --service-account="$SERVICE_ACCOUNT_EMAIL" \
-    --credential-source-file=/var/run/secrets/storage/serviceaccount/token \
+    --credential-source-file=/var/run/secrets/storage/serviceaccount/token \ # <1>
     --credential-source-type=text \
-    --output-file=<OUTPUT_FILE_PATH> #<1>
+    --output-file=<output_file_path> # <2>
 ----
-<1> Path where the file will be writed
-+
-Note: credential-source-file should be always point to /var/run/secrets/storage/serviceaccount/token, this is where the operator will mount the token
+<1> The `credential-source-file` parameter must always point to the `/var/run/secrets/storage/serviceaccount/token` path because the Operator mounts the token from this path.
+<2> The path for saving the output file.
+
 . Get the correct audience as follows:
 +
 [source,terminal]
 ----
 gcloud iam workload-identity-pools providers describe "$PROVIDER_NAME" --format='value(oidc.allowedAudiences[0])'
 ----
-+
-. Create storage secret to be used by Tempo.
+
+. Create a storage secret for the {TempoShortName}.
 +
 [source,terminal]
 ----
-kubectl -n <TEMPO_NAMESPACE> create secret generic gcs-secret \
-  --from-literal=bucketname="<BUCKET_NAME> \ #<1>
-  --from-literal=audience="<AUDIENCE> \      #<2>
-  --from-file=key.json=<OUTPUT_FILE_PATH>    #<3>
+kubectl -n <tempo_namespace> create secret generic gcs-secret \
+  --from-literal=bucketname="<bucket_name> \ # <1>
+  --from-literal=audience="<audience> \      # <2>
+  --from-file=key.json=<output_file_path>    # <3>
 ----
-<1> Bucket name of the Google Cloud Storage
-<2> Audience we get in the previous step
-<3> This is the file we created with gcloud iam workload-identity-pools create-cred-config command.
+<1> The bucket name of the Google Cloud Storage.
+<2> The audience that you got in the previous step.
+<3> The credential file that you created in step 6.