📚 Sync docs from alaudadevops/tektoncd-operator on d9a71adfda077eb458d051aac93f41addfce332e

Source: [DEVOPS-37117] feat: java pipeline support deploy workload docs
Author: yzc
Ref: refs/heads/main
Commit: d9a71adfda077eb458d051aac93f41addfce332e

This commit automatically syncs documentation changes from the source-docs repository.

🔗 View source commit: AlaudaDevops/tektoncd-operator@d9a71ad
🤖 Synced on 2025-07-07 03:52:51 UTC

Author: yuzichen12123

.github/SYNC_INFO.md

@@ -1,10 +1,10 @@
 # Documentation Sync Information
 
-- **Last synced**: 2025-07-05 07:35:23 UTC
+- **Last synced**: 2025-07-07 03:52:51 UTC
 - **Source repository**: alaudadevops/tektoncd-operator
-- **Source commit**: [ec48bfab09387e492f3a8055666fd5aa11526573](https://github.com/alaudadevops/tektoncd-operator/commit/ec48bfab09387e492f3a8055666fd5aa11526573)
-- **Triggered by**: l-qing
-- **Workflow run**: [#8](https://github.com/alaudadevops/tektoncd-operator/actions/runs/16085926886)
+- **Source commit**: [d9a71adfda077eb458d051aac93f41addfce332e](https://github.com/alaudadevops/tektoncd-operator/commit/d9a71adfda077eb458d051aac93f41addfce332e)
+- **Triggered by**: yuzichen12123
+- **Workflow run**: [#9](https://github.com/alaudadevops/tektoncd-operator/actions/runs/16107170334)
 
 ## Files synced:
 - docs/

docs/en/pipelines/how_to/use-java-image-build-scan-deploy-pipeline.mdx

@@ -118,7 +118,7 @@ spec:
 - **build-extra-args**
   - **type**: string
   - **default**: ""
-  - **description**: Extra parameters passed for the build command when building images. WARNING - must be sanitized to avoid command injection. e.g., --build-arg key=value --label key=value
+  - **description**: Extra parameters passed for the build command when building images. WARNING - must be sanitized to avoid command injection (e.g. --build-arg key=value --label key=value).
 
 - **build-args**
   - **type**: array
@@ -133,7 +133,7 @@ spec:
 - **push-extra-args**
   - **type**: string
   - **default**: ""
-  - **description**: Extra parameters passed for the push command when pushing images. WARNING - must be sanitized to avoid command injection. e.g., --creds=username:password
+  - **description**: Extra parameters passed for the push command when pushing images. WARNING - must be sanitized to avoid command injection (e.g. --creds=username:password).
 
 ### Trivy Scanner
 
@@ -145,34 +145,39 @@ spec:
 - **trivy-extra-args**
   - **type**: string
   - **default**: ""
-  - **description**: Extra parameters passed for the trivy command when scanning images. WARNING - must be sanitized to avoid command injection. e.g., --insecure. You can use `--skip-db-update` `--skip-java-db-update` to skip updating vulnerability database.
+  - **description**: Extra parameters passed for the trivy command when scanning images. WARNING - must be sanitized to avoid command injection (e.g. --insecure). You can use `--skip-db-update` `--skip-java-db-update` to skip updating vulnerability database.
 
-### Update Workload
+### Deploy or upgrade workload
 
 - **workload-name**
   - **type**: string
   - **default**: ""
-  - **description**: The name of the workload to update.
+  - **description**: The name of the workload to deploy or upgrade. If it is not specified, `deploy-or-upgrade` task will be skipped.
 
 - **workload-kind**
   - **type**: string
   - **default**: Deployment
-  - **description**: The kind of workload to update, such as Deployment, StatefulSet, etc.
+  - **description**: The kind of workload to deploy or upgrade, such as Deployment, StatefulSet, etc.
 
 - **workload-namespace**
   - **type**: string
   - **default**: ""
-  - **description**: The namespace of the workload to update. If not specified, will use the namespace of the current TaskRun.
+  - **description**: The namespace of the workload to deploy or upgrade. If not specified, will use the namespace of the current TaskRun.
 
 - **workload-container**
   - **type**: string
-  - **default**: "*"
-  - **description**: This parameter is used to specify the container within the workload whose image needs to be updated. By default, the images of all containers in the workload will be updated.
+  - **default**: []
+  - **description**: This parameter is used to specify the containers within the workload whose image needs to be updated. By default, all of the container's image in the workload will be updated.
 
 - **workload-rollout-timeout**
   - **type**: string
   - **default**: "0"
-  - **description**: The timeout for the rollout to complete. If it is not specified or set to 0, it will never timeout.
+  - **description**: The length of time to wait before ending waiting workload ready, `0` means never. Any other values should contain a corresponding time unit (e.g. 1s, 2m, 3h).
+
+- **workload-manifests-dir**
+  - **type**: string
+  - **default**: ""
+  - **description**: The manifest of the workload to deploy. If it is not specified, will only update the image of the workload which is already in cluster. You can use the relative path to the manifest directory in the `source` workspace. For example: "manifests".
 
 ## Workspaces
 
@@ -196,7 +201,7 @@ The Task can be run on `linux/amd64` and `linux/arm64` platforms.
 
 ### Minimal Setup: Run End-to-End With Minimal Parameters
 
-Optional tasks (sonarqube-scanner, update-workload, etc.) will be gracefully skipped when unset or omitted.
+Optional tasks (`sonarqube-scanner`, `deploy-or-upgrade`, etc.) will be gracefully skipped when unset or omitted.
 
 ```yaml
 apiVersion: tekton.dev/v1
@@ -289,6 +294,49 @@ Here is some of the properties you can set:
 | sonar.sources                  | Comma-separated paths to directories containing main source files                                                                                                                                                      |
 | sonar.organization             | The organization in SonarQube where the project exists                                                                                                                                                                 |
 
+### Deploy or upgrade a workload
+
+You can deploy or upgrade a workload using the image built by the `build-image` task in this pipeline.
+
+By setting the `workload-manifests-dir` param, you can apply Kubernetes manifests from the specified directory to create or update the workload.
+
+Both JSON and YAML formats are supported. All manifests within the specified directory will be processed using `kubectl apply`. Note that `kubectl apply` does not traverse subdirectories.
+
+If the directory contains a Kustomize configuration file (e.g. `kustomization.yaml`, `kustomization.yml`, or `Kustomization`), it will be processed using `kubectl kustomize`.
+
+Here is an example structure of the `workload-manifests-dir`:
+
+```
+manifests
+├── deployment.yaml
+├── kustomization.yaml
+└── service.yaml
+```
+
+You can configure the following parameters:
+
+```yaml
+spec:
+  params:
+    # ...
+    - name: images
+      value:
+        - foo/bar:latest
+    - name: workload-name
+      value: bar
+    - name: workload-namespace
+      value: default
+    - name: workload-kind
+      value: Deployment
+    - name: workload-manifests-dir
+      value: manifests
+    # ...
+```
+
+If you prefer not to deploy the workload using manifests. Simply leave the `workload-manifests-dir` param empty. In that case, the task will only update the image of an existing workload in the cluster.
+
+You need to manage image pull secrets for the workload. If the new image is hosted in a different registry, make sure to create and configure the appropriate pull secret for your workload.
+
 ### Skip tasks with Params
 
 The pipeline supports skipping tasks using params:
@@ -298,7 +346,7 @@ The pipeline supports skipping tasks using params:
 | git-clone         | `skip-git-clone`  | `"false"` | If code already exists in `source` workspace, you can set this to `"true"` to skip cloning. |
 | sonarqube-scanner | `sonar-url`       | `""`      | Scan will be skipped if `sonar-url` is not set.                                             |
 | trivy-scanner     | `skip-trivy-scan` | `"false"` | Scan will be skipped if `skip-trivy-scan` is set to `"true"`.                               |
-| update-workload   | `workload-name`   | `""`      | If you don't want to update the workload, you can left `workload-name` empty.               |
+| deploy-or-upgrade | `workload-name`   | `""`      | If you don't want to deploy or upgrade the workload, you can left `workload-name` empty.    |
 
 ### Full Example with All Tasks
 
@@ -309,7 +357,7 @@ This example demonstrates how to use all tasks in the pipeline. It includes foll
 * Building the image and pushing the image to the registry.
 * Scanning the image with Trivy
 * Scanning the code with SonarQube
-* Updating the workload
+* Deploying or Upgrading the workload
 
 ```yaml
 apiVersion: tekton.dev/v1

docs/en/pipelines/trouble_shooting/using-multiple-pvc-workspaces-failed.mdx

@@ -0,0 +1,77 @@
+---
+weight: 10
+i18n:
+  title:
+    en: Unable to Use Multiple PVC Workspaces in Tekton
+    zh: 在 Tekton 中遇到无法使用多个基于 PVC 的工作区的问题
+title:
+---
+
+# Unable to Use Multiple PVC Workspaces in Tekton
+
+## Problem Description
+
+When running a `PipelineRun` or `TaskRun` in Tekton with **multiple `PersistentVolumeClaim` (PVC)**-based `workspaces`, the execution fails with an error similar to "more than one PersistentVolumeClaim is bound".
+
+This occurs even if all PVCs are valid and correctly declared.
+
+### Error Manifestation
+
+1. TaskRun execution fails with a status of `False`, and the reason is `TaskRunValidationFailed`:
+   ```bash
+   $ kubectl get taskruns -n ${namespace} ${taskrun_name}
+   NAME                     SUCCEEDED   REASON                       STARTTIME   COMPLETIONTIME
+   demo-hbfhd-foo           False       TaskRunValidationFailed      59s         59s
+   ```
+
+2. The TaskRun event displays an error message:
+   ```
+   [User error] more than one PersistentVolumeClaim is bound
+   ```
+
+## Root Cause Analysis
+
+By default, Tekton enables the **Affinity Assistant** feature to help co-locate TaskRun pods with their PVCs on the same node. This is especially useful for volumes with `ReadWriteOnce` access mode.
+
+However, when the Affinity Assistant is enabled:
+- Each `TaskRun` is limited to a **single PVC-based workspace**.
+- Binding more than one PVC triggers a **validation error**, preventing the TaskRun from running.
+
+This restriction is enforced to avoid complex scheduling issues and node affinity conflicts.
+
+## Troubleshooting
+
+To allow a `TaskRun` or `PipelineRun` to use **multiple PVC-based workspaces**, you must **disable the Affinity Assistant** by updating the Tekton feature flags.
+
+It is recommended to troubleshoot as follows:
+
+1. Edit the TektonConfig resource by setting `spec.pipeline.disable-affinity-assistant` as shown below:
+
+```yaml
+apiVersion: operator.tekton.dev/v1alpha1
+kind: TektonConfig
+spec:
+  pipeline:
+    disable-affinity-assistant: true
+```
+
+tips: the `disable-affinity-assistant` feature flag will be removed soon and the Affinity Assistant Modes will be only controlled by the `coschedule` feature flag.
+
+2. The `feature-flags` ConfigMap will be updated automatically.
+
+```yaml
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: feature-flags
+  namespace: tekton-pipelines
+data:
+  disable-affinity-assistant: "true"
+```
+
+3. No manual component restarts are required, changes will take effect automatically.
+
+## Related Content
+
+- [Tekton Affinity Assistant](https://tekton.dev/docs/pipelines/affinityassistants/)
+- [Tekton Workspaces](https://tekton.dev/docs/pipelines/workspaces/)