Max's edit

Author: max-cx

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

@@ -20,7 +20,7 @@ include::snippets/technology-preview.adoc[leveloffset=+1]
 
 . Create an AWS S3 bucket.
 
-. Create the following `trust.json` file for the AWS IAM policy that will set up a trust relationship for the AWS IAM role, created in the next step, with the service account of the TempoStack instance:
+. Create the following `trust.json` file for the AWS Identity and Access Management (AWS IAM) policy for the purpose of setting up a trust relationship for the AWS IAM role, which is created in the next step, with the service account of the `TempoStack` instance:
 +
 [source,yaml]
 ----
@@ -30,25 +30,33 @@ include::snippets/technology-preview.adoc[leveloffset=+1]
       {
         "Effect": "Allow",
         "Principal": {
-          "Federated": "arn:aws:iam::${<aws_account_id>}:oidc-provider/${<oidc_provider>}" # <1>
+          "Federated": "arn:aws:iam::<aws_account_id>:oidc-provider/<oidc_provider>" # <1>
         },
         "Action": "sts:AssumeRoleWithWebIdentity",
         "Condition": {
           "StringEquals": {
-            "${OIDC_PROVIDER}:sub": [
-              "system:serviceaccount:${<openshift_project_for_tempostack>}:tempo-${<tempostack_cr_name>}" # <2>
-              "system:serviceaccount:${<openshift_project_for_tempostack>}:tempo-${<tempostack_cr_name>}-query-frontend"
+            "<oidc_provider>:sub": [
+              "system:serviceaccount:<openshift_project_for_tempostack>:tempo-<tempostack_cr_name>" # <2>
+              "system:serviceaccount:<openshift_project_for_tempostack>:tempo-<tempostack_cr_name>-query-frontend"
            ]
          }
        }
      }
     ]
 }
 ----
-<1> OIDC provider that you have configured on the {product-title}. You can get the configured OIDC provider value also by running the following command: `$ oc get authentication cluster -o json | jq -r '.spec.serviceAccountIssuer' | sed 's~http[s]*://~~g'`.
-<2> Namespace in which you intend to create the TempoStack instance.
+<1> The OIDC provider that you have configured on the {product-title}.
+<2> The namespace in which you intend to create the `TempoStack` instance.
++
+[TIP]
+====
+You can also get the value for the configured OIDC provider by running the following command:
+----
+$ oc get authentication cluster -o json | jq -r '.spec.serviceAccountIssuer' | sed 's~http[s]*://~~g'
+----
+====
 
-. Create an AWS IAM role by attaching the `trust.json` policy file that you created:
+. Create an AWS IAM role by attaching the created `trust.json` policy file:
 +
 [source,terminal]
 ----
@@ -59,25 +67,25 @@ $ aws iam create-role \
       --output text
 ----
 
-. Attach an AWS IAM policy to the created role:
+. Attach an AWS IAM policy to the created AWS IAM role:
 +
 [source,terminal]
 ----
 $ aws iam attach-role-policy \
       --role-name "tempo-s3-access" \
       --policy-arn "arn:aws:iam::aws:policy/AmazonS3FullAccess"
 ----
-. Configure Cloud Provider environment for the tempo operator. In the case of AWS STS we need to add ROLEARN environment variable to the operator subcription.
+
+. Configure the cloud provider environment for the {TempoOperator}:
 [source,terminal]
 ----
-$ oc patch subscription <TEMPO_OPERATOR_SUB> \ <1>
-          -n <TEMPO_OPERATOR_NAMESPACE> \ <2>
-          --type='merge' -p '{"spec": {"config": {"env": [{"name": "ROLEARN", "value": "'"<ROLE_ARN>"'"}]}}}' <3>
-
+$ oc patch subscription <tempo_operator_sub> \ # <1>
+          -n <tempo_operator_namespace> \ # <2>
+          --type='merge' -p '{"spec": {"config": {"env": [{"name": "ROLEARN", "value": "'"<role_arn>"'"}]}}}' # <3>
 ----
 <1> Operator Subscription Name.
 <2> Namespace of the {TempoOperator}.
-<3> ARN of the role previously created.
+<3> The AWS STS requires adding the `ROLEARN` environment variable to the Operator subcription. As the `<ROLE_ARN>` value, add the Amazon Resource Name (ARN) of the AWS IAM role that you created in step 3.
 
 . In the {product-title}, create an object storage secret with keys as follows:
 +
@@ -93,7 +101,8 @@ stringData:
 type: Opaque
 ----
 
-. When TempoStack CR is created you need to specify the credentialMode as follows:
+. When the  is created you need to specify the credentialMode as follows:
++
 [source,yaml]
 ----
 apiVersion: tempo.grafana.com/v1alpha1
@@ -105,13 +114,14 @@ spec:
   storage:
     secret:
       name: aws-sts
-      type: s3 <1>
-      credentialMode: token-cco <2>
+      type: s3 # <1>
+      credentialMode: token-cco # <2>
 ----
-<1> Currently this is the only backend supported togheter with CCO.
-<2> Credential mode should be set to token-cco.
-+
+<1> Currently, this is the only backend supported togheter with the CCO.
+<2> Must be set to the `token-cco` value.
+
 . For tempo monolithic will be similar:
++
 [source,yaml]
 ----
 apiVersion: tempo.grafana.com/v1alpha1
@@ -122,10 +132,10 @@ metadata:
 spec:
   storage:
     traces:
-      backend: s3 <1>
+      backend: s3 # <1>
       s3:
         secret: aws-sts
-        credentialMode: token-cco <2>
+        credentialMode: token-cco # <2>
 ----
-<1> Currently this is the only backend supported togheter with CCO.
-<2> Credential mode should be set to token-cco.
+<1> Currently, this is the only backend supported togheter with the CCO.
+<2> Must be set to the `token-cco` value.

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

@@ -3,97 +3,124 @@
 //* observability/distr_tracing/distr-tracing-tempo-installing.adoc
 
 :_mod-docs-content-type: PROCEDURE
-[id="distr-tracing-tempo-object-storage-setup-azure-sts-install_{context}"]
+[id="setting-up-azure-storage-with-security-token-service_{context}"]
 = Setting up the Azure storage with the Security Token Service
 
-You can set up Azure storage with the Security Token Service (STS) by using the Azure Command Line Interface (AZ CLI).
+You can set up the Azure storage with the Security Token Service (STS) by using the Azure Command Line Interface (Azure CLI).
 
 :FeatureName: Azure storage with the Security Token Service
 include::snippets/technology-preview.adoc[leveloffset=+1]
 
 .Prerequisites
 
-* You have installed the latest version of the AWS CLI.
-* Created an Azure Storage Account.
-* Created an Azure Blob Storage Container.
+* You have installed the latest version of the Azure CLI.
+* You have created an Azure storage account.
+* You have created an Azure blob storage container.
 
 .Procedure
-. Create an Azure Managed identity
+
+. Create an Azure managed identity:
++
 [source,terminal]
 ----
-az identity create \
-  --name <IDENTITY_NAME> \ <1>
-  --resource-group <RESOURCE_GROUP> \ <2>
-  --location <REGION> \ <3>
-  --subscription <SUBSCRIPTION_ID> <4>
+$ az identity create \
+  --name <identity_name> \ # <1>
+  --resource-group <resource_group> \ # <2>
+  --location <region> \ # <3>
+  --subscription <subscription_id> # <4>
 ----
-<1> Name of the identity to be created.
-<2> The Azure resource group where the identity will be created.
-<3> The Azure region; it should be the same region as the resource group.
+<1> Choose a name for the managed identity.
+<2> The Azure resource group where the identity is to be created.
+<3> The Azure region, which must be the same region as for the resource group.
 <4> Azure subscription ID.
+
+. Create a federated identity credential for the Kubernetes service account for use by all components except the frontend component:
 +
-. Create federated credentials. Federated credentials allow Kubernetes service accounts to authenticate as the Azure managed identity without storing secrets or using service principals. You need to create one per Kubernetes service account. In this case, the operator will create one service account for all components and one specific for the frontend component.
 [source,terminal]
 ----
-az identity federated-credential create \
-  --name <CREDENTIAL_NAME> \ <1>
-  --identity-name <IDENTITY_NAME> \
-  --resource-group <RESOURCE_GROUP> \
-  --issuer <CLUSTER_ISSUER> \ <2>
-  --subject <TEMPO_SA_SUBJECT> \ <3>
-  --audiences <AUDIENCE> <4>
-----
-<1> Name of the federated credential.
-<2> The OIDC issuer URL of the Kubernetes cluster. You can get it using the following command: `oc get authentication cluster -o json | jq -r .spec.serviceAccountIssuer`
-<3> The Kubernetes service account subject, in the format: `system:serviceaccount:<namespace>:tempo-<tempo-instance-name>`
-<4> The expected audience used to validate tokens, commonly set to `api://AzureADTokenExchange`.
+$ az identity federated-credential create \ # <1>
+  --name <credential_name> \ # <2>
+  --identity-name <identity_name> \
+  --resource-group <resource_group> \
+  --issuer <cluster_issuer> \ # <3>
+  --subject <tempo_sa_subject> \ # <4>
+  --audiences <audience> # <5>
+----
+<1> Federated identity credentials allow Kubernetes service accounts to authenticate as an Azure managed identity without storing secrets or using an Azure service principal identity.
+<2> Choose a name for the federated credential.
+<3> The URL of the OpenID Connect (OIDC) issuer for your cluster.
+<4> The service account subject for your cluster in the following format: `system:serviceaccount:<namespace>:tempo-<tempostack_instance_name>`.
+<5> The expected audience, which is to be used for validating the issued tokens for the federated identity credential. This is commonly set to `api://AzureADTokenExchange`.
++
+[TIP]
+====
+You can get the URL of the OpenID Connect (OIDC) issuer for your cluster by running the following command:
+----
+$ oc get authentication cluster -o json | jq -r .spec.serviceAccountIssuer
+----
+====
+
+. Create a federated identity credential for the Kubernetes service account for use by the frontend component:
 +
-Create frontend federated credential.
 [source,terminal]
 ----
-az identity federated-credential create \
-  --name <CREDENTIAL_NAME>-frontend \ <1>
-  --identity-name <IDENTITY_NAME> \
-  --resource-group <RESOURCE_GROUP> \
-  --issuer <CLUSTER_ISSUER> \
-  --subject <TEMPO_SA_QUERY_FRONTEND_SUBJECT> \ <2>
-  --audiences <AUDIENCE> | jq
+$ az identity federated-credential create \ # <1>
+  --name <credential_name>-frontend \ # <2>
+  --identity-name <identity_name> \
+  --resource-group <resource_group> \
+  --issuer <cluster_issuer> \
+  --subject <tempo_sa_query_frontend_subject> \ # <3>
+  --audiences <audience> | jq
 ----
-<1> Name of the federated credential.
-<2> The Kubernetes service account subject, in the format: `system:serviceaccount:<namespace>:tempo-<tempo-instance-name>`
+<1> Federated identity credentials allow Kubernetes service accounts to authenticate as an Azure managed identity without storing secrets or using an Azure service principal identity.
+<2> Choose a name for the frontend federated identity credential.
+<3> The service account subject for your cluster in the following format: `system:serviceaccount:<namespace>:tempo-<tempostack_instance_name>`.
+
+. Assign the Storage Blob Data Contributor role to the Azure service principal identity of your created Azure managed identity:
 +
-. Assign the "Storage Blob Data Contributor" role to the managed identity's service principal.
 [source,terminal]
 ----
-az role assignment create \
-  --assignee <ASSIGNEE_NAME> \ <1>
+$ az role assignment create \
+  --assignee <assignee_name> \ # <1>
   --role "Storage Blob Data Contributor" \
-  --scope "/subscriptions/<SUBSCRIPTION_ID>
+  --scope "/subscriptions/<subscription_id>
 ----
-<1> Managed identity principal. Can be obtained with the following command: `az ad sp list --all --filter "servicePrincipalType eq 'ManagedIdentity'" | jq -r --arg idName <IDENTITY_NAME> '.[] | select(.displayName == $idName) | .appId'`
+<1> The Azure service principal identity of the Azure managed identity that you created in step 1.
 +
-. Fetch the client ID of the existing managed identity.
-[source,terminal]
+[TIP]
+====
+You can get the `<assignee_name>` value by running the following command:
+----
+$ az ad sp list --all --filter "servicePrincipalType eq 'ManagedIdentity'" | jq -r --arg idName <identity_name> '.[] | select(.displayName == $idName) | .appId'`
+----
+====
+
+. Fetch the client ID of the Azure managed identity that you created in step 1:
++
+[source,bash]
 ----
 CLIENT_ID=$(az identity show \
-  --name <IDENTITY_NAME> \
-  --resource-group <RESOURCE_GROUP> \
+  --name <identity_name> \ # <1>
+  --resource-group <resource_group> \ # <2>
   --query clientId \
   -o tsv)
 ----
+<1> Copy and paste the `<identity_name>` value from step 1.
+<2> Copy and paste the `<resource_group>` value from step 1.
+
+. Create a Kubernetes secret for the Azure workload identity federation (WIF):
 +
-. Create a Kubernetes secret for Azure WIF.
 [source,terminal]
 ----
-kubectl create -n <TEMPO_NAMESPACE> secret generic azure-secret \
-  --from-literal=container=<$AZURE_STORAGE_AZURE_CONTAINER> \ <1>
-  --from-literal=account_name=<AZURE_STORAGE_AZURE_ACCOUNTNAME> \ <2>
-  --from-literal=client_id=<CLIENT_ID> \ <3>
-  --from-literal=audience=<AUDIENCE> \ <4>
-  --from-literal=tenant_id=<TENANT_ID> <5>
-----
-<1> Azure Blob storage container.
-<2> Azure Storage account name.
-<3> Client ID of the managed identity (obtained in the previous step).
-<4> Audience, optional (defaults to `api://AzureADTokenExchange`).
-<5> Azure Tenant ID.
+$ kubectl create -n <tempo_namespace> secret generic azure-secret \
+  --from-literal=container=<azure_storage_azure_container> \ # <1>
+  --from-literal=account_name=<azure_storage_azure_accountname> \ # <2>
+  --from-literal=client_id=<client_id> \ # <3>
+  --from-literal=audience=<audience> \ # <4>
+  --from-literal=tenant_id=<tenant_id> # <5>
+----
+<1> The name of the Azure Blob Storage container.
+<2> The name of the Azure Storage account.
+<3> The client ID of the managed identity that you fetched in the previous step.
+<4> Optional: Defaults to `api://AzureADTokenExchange`.
+<5> Azure Tenant ID.

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.

observability/distr_tracing/distr-tracing-tempo-installing.adoc

@@ -38,8 +38,18 @@ include::modules/distr-tracing-tempo-storage-ref.adoc[leveloffset=+1]
 
 include::modules/distr-tracing-tempo-object-storage-setup-aws-sts-install.adoc[leveloffset=+2]
 
+[role="_additional-resources"]
+.Additional resources
+
+* link:https://docs.aws.amazon.com/cli/[AWS Command Line Interface Documentation] (AWS Documentation)
+
 include::modules/distr-tracing-tempo-object-storage-setup-azure-sts-install.adoc[leveloffset=+2]
 
+[role="_additional-resources"]
+.Additional resources
+
+* link:https://learn.microsoft.com/en-us/cli/azure/install-azure-cli-linux[Install the Azure CLI on Linux] (Azure documentation)
+
 include::modules/distr-tracing-tempo-object-storage-setup-gcp-sts-install.adoc[leveloffset=+2]
 
 [role="_additional-resources"]