Fix docs for on rollback for script run (#4774)

* Add docs about the behavior when to rollback for SCRIPT_RUN stage Signed-off-by: Yoshiki Fujikane <ffjlabo@gmail.com> * Add example for SCRIPT_RUN stage Signed-off-by: Yoshiki Fujikane <ffjlabo@gmail.com> * Fix docs Signed-off-by: Yoshiki Fujikane <ffjlabo@gmail.com> --------- Signed-off-by: Yoshiki Fujikane <ffjlabo@gmail.com>
pipe-cd · Feb 6, 2024 · 6111944 · 6111944
1 parent 5cca5e7
commit 6111944
Show file tree

Hide file tree

Showing 5 changed files with 131 additions and 9 deletions.
diff --git a/...n/docs-dev/user-guide/managing-application/customizing-deployment/script-run.md b/...n/docs-dev/user-guide/managing-application/customizing-deployment/script-run.md
@@ -8,12 +8,11 @@ description: >
 
 `SCRIPT_RUN` stage is one stage in the pipeline and you can execute any commands.
 
-> Note: This feature is at the alpha status.
+> Note: This feature is at the alpha status and currently only for the application kind of KubernetesApp.
 
 ## How to configure SCRIPT_RUN stage
 
 Add a `SCRIPT_RUN` to your pipeline and write commands. 
-The commands run in the directory where this application configuration file exists.
 
 ```yaml
 apiVersion: pipecd.dev/v1beta1
@@ -49,19 +48,77 @@ spec:
             sleep 10
 ```
 
+You can define the command as `run`.
+Also, if you want to some values as variables, you can define them as `env`.
+
+The commands run in the directory where this application configuration file exists.
+
 ![](/images/script-run.png)
 
-Note:
-1. You can use `SCRIPT_RUN` stage with any current supporting application kind.
+# When to rollback
+
+You can define the command as `onRollback` to execute when to rollback similar to `run`.
+Execute the command to rollback SCRIPT_RUN to the point where the deployment was canceled or failed.
+
+```yaml
+apiVersion: pipecd.dev/v1beta1
+kind: KubernetesApp
+spec:
+  name: canary-with-script-run
+  labels:
+    env: example
+    team: product
+  pipeline:
+    stages:
+      - name: K8S_CANARY_ROLLOUT
+        with:
+          replicas: 10%
+      - name: WAIT
+        with:
+          duration: 10s
+      - name: SCRIPT_RUN
+        with:
+          env:
+            MSG: "execute script1"
+            R_MSG: "rollback script1"
+          run: |
+            echo $MSG
+            sleep 10
+          onRollback: |
+            echo $R_MSG
+            sleep 10
+      - name: K8S_PRIMARY_ROLLOUT
+      - name: K8S_CANARY_CLEAN
+```
+
+![](/images/script-run-onRollback.png)
+
+The command defined as `onRollback` is executed as `SCRIPT_RUN_ROLLBACK` stage after each `ROLLBACK` stage.
 
+When there are multiple SCRIPT_RUN stages, they are executed in the same order as SCRIPT_RUN on the pipeline.
+Also, only for the executed SCRIPT_RUNs are rollbacked.
+
+For example, consider when deployment proceeds in the following order from 1 to 7.
+```
+1. K8S_CANARY_ROLLOUT
+2. WAIT
+3. SCRIPT_RUN
+4. K8S_PRIMARY_ROLLOUT
+5. SCRIPT_RUN
+6. K8S_CANARY_CLEAN
+7. SCRIPT_RUN
+```
+
+Then
+- If 3 is canceled or fails while running, only SCRIPT_RUN of 3 will be rollbacked.
+- If 4 is canceled or fails while running, only SCRIPT_RUN of 3 will be rollbacked.
+- If 6 is canceled or fails while running, only SCRIPT_RUNs 3 and 5 will be rollbacked. The order of executing is 3 -> 5.
+
+# Note
+1. You can use `SCRIPT_RUN` stage with only the application kind of `KubernetesApp`. Soon we will implement it. for other application kinds.
 
 2. The public piped image available in PipeCD main repo (ref: [Dockerfile](https://github.com/pipe-cd/pipecd/blob/master/cmd/piped/Dockerfile)) is based on [alpine](https://hub.docker.com/_/alpine/) and only has a few UNIX command available (ref: [piped-base Dockerfile](https://github.com/pipe-cd/pipecd/blob/master/tool/piped-base/Dockerfile)). If you want to use your commands, you can:
 
 - Prepare your own environment container image then add [piped binary](https://github.com/pipe-cd/pipecd/releases) to it.
 - Build your own container image based on `ghcr.io/pipe-cd/piped` image.
 - Manually update your running piped container (not recommended).
-
-# When to rollback
-
-Even if a rollback occurs, the command will not be executed again.
-In the near future, we are considering the ability to run this command also on rollback.
diff --git a/docs/static/images/script-run-onRollback.png b/docs/static/images/script-run-onRollback.png
diff --git a/examples/kubernetes/script-run/app.pipecd.yaml b/examples/kubernetes/script-run/app.pipecd.yaml
@@ -0,0 +1,28 @@
+apiVersion: pipecd.dev/v1beta1
+kind: KubernetesApp
+spec:
+  name: script-run
+  labels:
+    env: example
+    team: product
+  pipeline:
+    stages:
+      - name: K8S_CANARY_ROLLOUT
+        with:
+          replicas: 10%
+      - name: WAIT
+        with:
+          duration: 10s
+      - name: SCRIPT_RUN
+        with:
+          env:
+            MSG: "execute script1"
+            R_MSG: "rollback script1"
+          run: |
+            echo $MSG
+            sleep 10
+          onRollback: |
+            echo $R_MSG
+            sleep 10
+      - name: K8S_PRIMARY_ROLLOUT
+      - name: K8S_CANARY_CLEAN
diff --git a/examples/kubernetes/script-run/deployment.yaml b/examples/kubernetes/script-run/deployment.yaml
@@ -0,0 +1,26 @@
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: script-run
+  labels:
+    app: script-run
+spec:
+  replicas: 2
+  revisionHistoryLimit: 2
+  selector:
+    matchLabels:
+      app: script-run
+      pipecd.dev/variant: primary
+  template:
+    metadata:
+      labels:
+        app: script-run
+        pipecd.dev/variant: primary
+    spec:
+      containers:
+      - name: helloworld
+        image: gcr.io/pipecd/helloworld:v0.45.0
+        args:
+          - server
+        ports:
+        - containerPort: 9085
diff --git a/examples/kubernetes/script-run/service.yaml b/examples/kubernetes/script-run/service.yaml
@@ -0,0 +1,11 @@
+apiVersion: v1
+kind: Service
+metadata:
+  name: script-run
+spec:
+  selector:
+    app: script-run
+  ports:
+    - protocol: TCP
+      port: 9085
+      targetPort: 9085