docs: clarify Docker authentication for image pulling and in-Pod

This commit updates the "Configuring Docker Authentication" section to provide
a clearer distinction between the use cases of Docker authentication for:

1. Image Pulling Authentication: Using `dockercfg` and `dockerconfigjson`
   Secrets as `imagePullSecrets` to authenticate with Docker registries and
   pull container images during the Pod creation phase.

2. In-Pod Docker Authentication: Setting up Docker authentication within the
   Pod's container environment by generating a `~/.docker/config.json` file
   after the Pod is created and images are pulled. This authentication setup
   allows the Steps within the Pod to interact with Docker registries during
   execution.

The section explains that the Docker authentication credentials used for
in-Pod authentication are derived from the same Secrets specified as
`imagePullSecrets`, and Tekton follows the credential formatting and merging
rules defined by the Secret types.

The commit also maintains the existing examples for defining the Secret and
associating it with the ServiceAccount and Run.

Resolves #7737

docs/auth.md

@@ -41,8 +41,6 @@ refers to `TaskRuns` and `PipelineRuns` as `Runs` for the sake of brevity.
 
 ## Overview
 
-## Overview
-
 Tekton supports authentication for Git and Docker registries using Kubernetes Secrets. The supported Secret types are:
 
 <table>
@@ -192,7 +190,7 @@ Note: Github deprecated basic authentication with username and password. You can
    In the above example, the value for `tekton.dev/git-0` specifies the URL for which Tekton will use this `Secret`,
    as described in [Understanding credential selection](#understanding-credential-selection).
 
-1. In `serviceaccount.yaml`, associate the `Secret` with the desired `ServiceAccount`:
+2. In `serviceaccount.yaml`, associate the `Secret` with the desired `ServiceAccount`:
 
    ```yaml
    apiVersion: v1
@@ -203,7 +201,7 @@ Note: Github deprecated basic authentication with username and password. You can
      - name: basic-user-pass
    ```
 
-1. In `run.yaml`, associate the `ServiceAccount` with your `Run` by doing one of the following:
+3. In `run.yaml`, associate the `ServiceAccount` with your `Run` by doing one of the following:
 
    - Associate the `ServiceAccount` with your `TaskRun`:
 
@@ -231,7 +229,7 @@ Note: Github deprecated basic authentication with username and password. You can
          name: demo-pipeline
      ```
 
-1. Execute the `Run`:
+4. Execute the `Run`:
 
    ```shell
    kubectl apply --filename secret.yaml serviceaccount.yaml run.yaml
@@ -264,13 +262,13 @@ specified in the `Secret`.
    In the above example, the value for `tekton.dev/git-0` specifies the URL for which Tekton will use this `Secret`,
    as described in [Understanding credential selection](#understanding-credential-selection).
 
-1. Generate the `ssh-privatekey` value. For example:
+2. Generate the `ssh-privatekey` value. For example:
 
    `cat ~/.ssh/id_rsa`
 
-1. Set the value of the `known_hosts` field to the generated `ssh-privatekey` value from the previous step.
+3. Set the value of the `known_hosts` field to the generated `ssh-privatekey` value from the previous step.
 
-1. In `serviceaccount.yaml`, associate the `Secret` with the desired `ServiceAccount`:
+4. In `serviceaccount.yaml`, associate the `Secret` with the desired `ServiceAccount`:
 
    ```yaml
    apiVersion: v1
@@ -281,7 +279,7 @@ specified in the `Secret`.
      - name: ssh-key
    ```
 
-1. In `run.yaml`, associate the `ServiceAccount` with your `Run` by doing one of the following:
+5. In `run.yaml`, associate the `ServiceAccount` with your `Run` by doing one of the following:
 
    - Associate the `ServiceAccount` with your `TaskRun`:
 
@@ -310,7 +308,7 @@ specified in the `Secret`.
        name: demo-pipeline
    ```
 
-1. Execute the `Run`:
+6. Execute the `Run`:
 
    ```shell
    kubectl apply --filename secret.yaml,serviceaccount.yaml,run.yaml
@@ -378,7 +376,7 @@ the credentials specified in the `Secret`.
    In the above example, the value for `tekton.dev/docker-0` specifies the URL for which Tekton will use this `Secret`,
    as described in [Understanding credential selection](#understanding-credential-selection).
 
-1. In `serviceaccount.yaml`, associate the `Secret` with the desired `ServiceAccount`:
+2. In `serviceaccount.yaml`, associate the `Secret` with the desired `ServiceAccount`:
 
    ```yaml
    apiVersion: v1
@@ -389,7 +387,7 @@ the credentials specified in the `Secret`.
      - name: basic-user-pass
    ```
 
-1. In `run.yaml`, associate the `ServiceAccount` with your `Run` by doing one of the following:
+3. In `run.yaml`, associate the `ServiceAccount` with your `Run` by doing one of the following:
 
    - Associate the `ServiceAccount` with your `TaskRun`:
 
@@ -418,7 +416,7 @@ the credentials specified in the `Secret`.
          name: demo-pipeline
      ```
 
-1. Execute the `Run`:
+4. Execute the `Run`:
 
    ```shell
    kubectl apply --filename secret.yaml serviceaccount.yaml run.yaml
@@ -427,18 +425,20 @@ the credentials specified in the `Secret`.
 ## Configuring `docker*` authentication for Docker
 
 This section describes how to configure Docker authentication using the `dockercfg`
-and `dockerconfigjson` Secret types. These Secrets are used as `imagePullSecrets`
-to provide the necessary credentials for Tekton to pull container images from 
-private Docker registries when creating the Pod for a TaskRun or PipelineRun 
-(collectively referred to as "Run").
+and `dockerconfigjson` Secret types.
+
+### Image Pulling Authentication
+The `dockercfg` and `dockerconfigjson` Secrets are used as `imagePullSecrets` to
+provide the necessary credentials for Tekton to pull container images from
+private Docker registries during the Pod creation phase.
 
 When a Run is executed, Tekton creates a Pod to run the defined Steps. During 
 this Pod creation phase, Tekton uses the provided `imagePullSecrets` to 
-authenticate with the respective registries and pull the required container images. 
-This image pulling process is a crucial step that happens before the Steps 
-within the Pod can start executing.
+authenticate with the respective registries and pull the required container 
+images. This image pulling process is a crucial step that happens before the 
+Steps within the Pod can start executing.
 
-Note: If you specify both the Tekton `basic-auth` and the Kubernetes `dockercfg` 
+Note: If you specify both the Tekton `basic-auth` and the Kubernetes `dockercfg`
 or `dockerconfigjson` Secrets, Tekton merges all credentials from all specified 
 Secrets, but Tekton's basic-auth Secret overrides the Kubernetes Secrets.
 
@@ -452,7 +452,7 @@ Secrets, but Tekton's basic-auth Secret overrides the Kubernetes Secrets.
    For more information, see [Pull an Image from a Private Registry](https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/)
    in the Kubernetes documentation.
 
-1. In `serviceaccount.yaml`, associate the `Secret` with the desired `ServiceAccount`:
+2. In `serviceaccount.yaml`, associate the `Secret` with the desired `ServiceAccount`:
 
    ```yaml
    apiVersion: v1
@@ -463,7 +463,7 @@ Secrets, but Tekton's basic-auth Secret overrides the Kubernetes Secrets.
      - name: regcred
    ```
 
-1. In `run.yaml`, associate the `ServiceAccount` with your `Run` by doing one of the following:
+3. In `run.yaml`, associate the `ServiceAccount` with your `Run` by doing one of the following:
 
    - Associate the `ServiceAccount` with your `TaskRun`:
 
@@ -492,12 +492,30 @@ Secrets, but Tekton's basic-auth Secret overrides the Kubernetes Secrets.
          name: demo-pipeline
      ```
 
-1. Execute the build:
+4. Execute the build:
 
    ```shell
    kubectl apply --filename secret.yaml --filename serviceaccount.yaml --filename taskrun.yaml
    ```
 
+### In-Pod Docker Authentication
+In addition to image pulling authentication, Tekton also sets up Docker 
+authentication within the Pod's container environment. This authentication setup 
+allows the Steps within the Pod to interact with Docker registries during 
+execution, enabling operations like pushing or pulling images, or performing 
+other OCI image manipulations.
+
+After the Pod is created and the container images are pulled, Tekton generates 
+a `~/.docker/config.json` file within the container. This file contains the 
+necessary Docker authentication credentials, allowing the Steps to authenticate 
+with Docker registries during execution.
+
+The Docker authentication credentials used for in-Pod authentication are derived
+from the same Secrets specified as imagePullSecrets. Tekton follows the credential 
+formatting and merging rules defined by the dockercfg and dockerconfigjson Secret 
+types when generating the `~/.docker/config.json` file.
+
+
 ## Technical reference
 
 This section provides a technical reference for the implementation of the authentication mechanisms