Incorporated SME review comments

Author: Dhruv-Soni11

_topic_maps/_topic_map.yml

@@ -117,8 +117,8 @@ Topics:
   File: securing-webhooks-with-event-listeners
 - Name: Authenticating pipelines with repositories using secrets
   File: authenticating-pipelines-repos-using-secrets
-- Name: Using secrets from dedicated stores
-  File: using-secret-stores
+- Name: Using secrets from external secret stores
+  File: using-secrets-from-external-secret-stores
 - Name: Unprivileged building of container images using Buildah
   File: unprivileged-building-of-container-images-using-buildah
 - Name: Using buildah-ns tekton task

modules/op-csi-secrets.adoc

@@ -3,34 +3,48 @@
 // * secure/using-csi-secrets.adoc
 
 :_mod-docs-content-type: PROCEDURE
-[id="configuring-results_{context}"]
-= Consuming secrets from an external store such as Hashicorp Vault using the Secrets Store CSI Driver
+[id="consuming-secrets-csi_{context}"]
+= Consuming secrets from external stores using the Secrets Store CSI Driver
 
-If you want to use secrets from an external store that has a CSI (container storage interface) provider, for example, Hashicorp Vault, you can configure {pipelines-shortname} to consume these secrets using the Secrets Store CSI Driver.
+[role="_abstract"]
+To use secrets from an external secret store that has a Container Storage Interface (CSI) provider, such as HashiCorp Vault, you can configure {pipelines-shortname} to consume these secrets using the Secrets Store CSI Driver.
 
 .Prerequisites
 
-* You installed the Secrets Store CSI Driver. For information about installing the CSI Driver, see the link:https://docs.redhat.com/en/documentation/openshift_container_platform/4.19/html/storage/using-container-storage-interface-csi#persistent-storage-csi-secrets-store[Secrets Store CSI Driver] in the {OCP} documentation.
+* You installed the Secrets Store CSI Driver. For information about installing the CSI Driver, see the link:https://docs.redhat.com/en/documentation/openshift_container_platform/latest/html/storage/using-container-storage-interface-csi#persistent-storage-csi-secrets-store[Secrets Store CSI Driver] in the {OCP} documentation.
 
-* You installed the CSI provider for your external secret store. For information about installing Hashicorp Vault, including its CSI provider, on {OCP}, see link:https://developer.hashicorp.com/vault/docs/deploy/kubernetes/csi/installation[Install the Vault CSI provider] in the Hashicorp documentation.
+* You installed the CSI provider for your external secret store. For information about installing HashiCorp Vault, including its CSI provider, on {OCP}, see link:https://developer.hashicorp.com/vault/docs/deploy/kubernetes/csi/installation[Install the Vault CSI provider] in the Hashicorp documentation.
 +
 [NOTE]
 ====
-If you want to use an instance of Hashicorp Vault running outside your {OCP} cluster, you must provide the address to that instance in the Helm configuration when installing the CSI Provider. For infoamtion about providing an external Vault address, see link:https://developer.hashicorp.com/vault/docs/deploy/kubernetes/helm/configuration#externalvaultaddr[Configuration] in the Hashicorp documentation.
+To use an instance of HashiCorp Vault running outside your {OCP} cluster, you must provide the address to that instance in the Helm configuration when installing the CSI Provider. For information about providing an external Vault address, see link:https://developer.hashicorp.com/vault/docs/deploy/kubernetes/helm/configuration#externalvaultaddr[Configuration] in the Hashicorp documentation.
 ====
 
-* You configured authentication with the secret store for an {OCP} service account, for example, `pipeline-sa`. For information about configuring Kubernetes authentication with Hashicorp Vault, see link:https://developer.hashicorp.com/vault/docs/auth/kubernetes[Kubernetes auth method] in the Hashicorp documentation.
+* You configured authentication with the secret store for an {OCP} service account, for example, `pipeline-sa`. For information about configuring Kubernetes authentication with HashiCorp Vault, see link:https://developer.hashicorp.com/vault/docs/auth/kubernetes[Kubernetes auth method] in the HashiCorp documentation.
 +
 [NOTE]
 ====
 You must create the service account in the namespace in which you create pipelines and other Custom Resources (CRs) for {pipelines-shortname}.
 ====
 
+* Ensure that the Secrets Store CSI Driver service account has the required cluster-wide permissions to create service account tokens in all relevant namespaces. Without these permissions, pods will fail to start and you may encounter the following error:
++
+[source,terminal]
+----
+User "system:serviceaccount:csi-driver:secrets-store-csi-driver" cannot create resource "serviceaccounts/token" in API group "" in the namespace "tekton-vault"
+----
+
 .Procedure
 
+. To allow the CSI driver to mount secrets volumes, configure the namespace to allow privileged pod security:
++                                                                                                     
+[source,terminal]
+----
+$ oc label namespace tekton-vault pod-security.kubernetes.io/enforce=privileged
+----
+
 . In the namespace in which you create pipelines, for example, `tekton-vault`, create a `Role` resource that allows `get`, `list`, and `watch` operations for the `secrets` resource.
 +
-.Example definition of the `pipeline-role` role
 [source,yaml]
 ----
 apiVersion: rbac.authorization.k8s.io/v1
@@ -46,7 +60,6 @@ rules:
 
 . Create a `RoleBinding` resource that binds the `pipeline-role` role to the service account which you configured for authentication with the secret store, for example, `pipeline-sa`.
 +
-.Example definition of the `pipeline-role-binding` role binding
 [source,yaml]
 ----
 apiVersion: rbac.authorization.k8s.io/v1
@@ -66,7 +79,6 @@ subjects:
 
 . Create a `SecretProviderClass` CR that defines the secrets that your pipeline or task consumes and the mount path and filename (key) for each of these secrets.
 +
-.Example definition of the `vault-secret` `SecretProviderClass` CR
 [source,yaml]
 ----
 apiVersion: secrets-store.csi.x-k8s.io/v1
@@ -88,10 +100,14 @@ spec:
         secretPath: "secret/data/my-secret"
         secretKey: "password"
 ----
++
+[WARNING]
+====
+The `vaultAddress` parameter used in this example uses `http` and `vaultSkipTLSVerify`: `"true"` only for demonstration purposes. For production use, configure Vault with a secure `https` endpoint and do not skip TLS verification.
+====
 
 . In the definition of the task that consumes the secrets, define and mount a volume that uses the CSI secrets store driver and specifies the name of the `SecretProviderClass` CR. To minimise security exposure of secrets, mount them in the definition of a task and not of an entire pipeline.
 +
-.Example definition of a task that consumes secrets
 [source,yaml]
 ----
 apiVersion: tekton.dev/v1
@@ -123,17 +139,29 @@ spec:
 +
 [NOTE]
 ====
-The mount path that you specify in the pipeline or task definition overrides the path that you specify in the `SecretProviderClass` CR.
+* The mount path that you specify in the pipeline or task definition overrides the path that you specify in the `SecretProviderClass` CR.
+
+* This example provides secrets for demonstration purposes only. In production environment, do not log secrets as they are visible in pod logs.
 ====
 
 . In the `PipelineRun` or `TaskRun` CR, assign the service account that is authenticated with the secret store to the task:
 
 ** If you create a `PipelineRun` CR, use the `taskRunSpecs` section to assign the service account to the particular task. Do not assign the service account to the entire pipeline.
 +
-.Example `PipelineRun` CR
 [source,yaml]
 ----
 apiVersion: tekton.dev/v1
+kind: Pipeline
+metadata:
+  name: vault-secret-pipeline
+  namespace: tekton-vault
+spec:
+  tasks:
+    - name: read-secret
+      taskRef:
+        name: secret-task
+---
+apiVersion: tekton.dev/v1
 kind: PipelineRun
 metadata:
   name: vault-secret-pipeline-run
@@ -142,20 +170,21 @@ spec:
   pipelineRef:
     name: vault-secret-pipeline
   taskRunSpecs:
-    - pipelineTaskName: secret-task
+    - pipelineTaskName: read-secret
       serviceAccountName: pipeline-sa
 ----
 
 ** If you create a `TaskRun` CR, use the `serviceAccountName` setting to assign the service account.
 +
-.Example `TaskRun` CR
 [source,yaml]
 ----
+apiVersion: tekton.dev/v1
 kind: TaskRun
 metadata:
   name: vault-secret-task-run
+  namespace: tekton-vault
 spec:
   taskRef:
-    name: secretTask
+    name: secret-task
   serviceAccountName: pipeline-sa
 ----

secure/using-secret-stores.adoc

@@ -0,0 +1,18 @@
+:_mod-docs-content-type: ASSEMBLY
+include::_attributes/common-attributes.adoc[]
+[id="using-secrets-from-external-secret-stores"]
+= Using secrets from external secret stores
+:context: using-secrets-from-external-secret-stores
+
+toc::[]
+
+[role="_abstract"]
+You can configure pipelines to consume secrets from external secret stores by using the Secrets Store CSI Driver.
+
+include::modules/op-csi-secrets.adoc[leveloffset=+1]
+
+[role="_additional-resources"]
+[id="additional-resources_{context}"]
+== Additional resources
+
+link:https://secrets-store-csi-driver.sigs.k8s.io/getting-started/installation.html[Install the Secrets Store CSI Driver]