feat: Introduce new MultiContainerRun function to run pods with two c…

…ontainers (#3095)
kanisterio · Oct 3, 2024 · 7723a4a · 7723a4a
1 parent 64f1866
commit 7723a4a
Show file tree

Hide file tree

Showing 9 changed files with 704 additions and 4 deletions.
diff --git a/docs/functions.rst b/docs/functions.rst
@@ -150,6 +150,82 @@ Example:
         - |
           echo "Example"
 
+MultiContainerRun
+-----------------
+
+MultiContainerRun spins up a new pod with two containers connected
+via shared `emptyDir`_ volume.
+It's similar to KubeTask, but allows using multiple images to move backup data.
+"background" container is one responsible for generating data, while "output" container
+should export it to destination.
+The main difference between these containers is that phase outputs can only be generated
+from the "output" container.
+The function also supports an optional init container to set up the volume contents.
+
+.. csv-table::
+   :header: "Argument", "Required", "Type", "Description"
+   :align: left
+   :widths: 5,5,5,15
+
+   `namespace`, No, `string`, namespace in which to execute (the pod will be created in controller's namespace if not specified)
+   `backgroundImage`, Yes, `string`, image to be used in "background" container
+   `backgroundCommand`, Yes, `[]string`,  command list to execute in "background" container
+   `outputImage`, Yes, `string`, image to be used in "output" container
+   `outputCommand`, Yes, `[]string`,  command list to execute in "output" container
+   `initImage`, No, `string`, image to be used in init container of the pod
+   `initCommand`, No, `[]string`, command list to execute in init container of the pod
+   `podOverride`, No, `map[string]interface{}`, specs to override default pod specs with
+   `podAnnotations`, No, `map[string]string`, custom annotations for the temporary pod that gets created
+   `podLabels`, No, `map[string]string`, custom labels for the temporary pod that gets created
+   `sharedVolumeMedium`, No, `string`, medium setting for shared volume. See `emptyDir`_.
+   `sharedVolumeSizeLimit`, No, `string`, sizeLimit setting for shared volume. See `emptyDir`_.
+   `sharedVolumeDir`, No, `string`, directory to mount shared volume. Defaults to `/tmp`
+
+.. _emptyDir: https://kubernetes.io/docs/concepts/storage/volumes/#emptydir
+
+Example:
+
+.. code-block:: yaml
+  :linenos:
+
+  - func: MultiContainerRun
+    name: examplePhase
+    args:
+      namespace: "{{ .Deployment.Namespace }}"
+      podOverride:
+        containers:
+        - name: export
+          imagePullPolicy: IfNotPresent
+      podAnnotations:
+        annKey: annValue
+      podLabels:
+        labelKey: labelValue
+      sharedVolumeMedium: Memory
+      sharedVolumeSizeLimit: 1Gi
+      sharedVolumeDir: /tmp/
+      initImage: ubuntu
+      initCommand:
+        - bash
+        - -c
+        - |
+          mkfifo /tmp/pipe-file
+      backgroundImage: ubuntu
+      backgroundCommand:
+        - bash
+        - -c
+        - |
+          for i in {1..10}
+          do
+            echo $i
+            sleep 0.1
+          done > /tmp/pipe-file
+      outputImage: ubuntu
+      outputCommand:
+        - bash
+        - -c
+        - |
+          cat /tmp/pipe-file
+
 ScaleWorkload
 -------------
 

diff --git a/docs/spelling_wordlist.txt b/docs/spelling_wordlist.txt
@@ -63,3 +63,6 @@ webhook
 Kopia
 kopia
 hostname
+emptyDir
+sizeLimit
+init
diff --git a/docs_new/functions.md b/docs_new/functions.md
@@ -129,6 +129,72 @@ Example:
         echo "Example"
 ```
 
+### MultiContainerRun
+
+MultiContainerRun spins up a new pod with two containers connected via shared [emptyDir](https://kubernetes.io/docs/concepts/storage/volumes/#emptydir) volume.
+It's similar to KubeTask, but allows using multiple images to move backup data.
+"background" container is one responsible for generating data, while "output" container
+should export it to destination.
+The main difference between these containers is that phase outputs can only be generated from the
+"output" container.
+The function also supports an optional init container to set up the volume contents.
+
+
+  | Argument    | Required | Type                    | Description |
+  | ----------- | :------: | ----------------------- | ----------- |
+  | namespace   | No       | string                  | namespace in which to execute (the pod will be created in controller's namespace if not specified) |
+  | backgroundImage       | Yes | string            | image to be used in "background" container |
+  | backgroundCommand     | Yes | []string          | command list to execute in "background" container |
+  | outputImage           | Yes | string            | image to be used in "output" container |
+  | outputCommand         | Yes | []string          | command list to execute in "output" container |
+  | initImage             | No  | string            | image to be used in init container of the pod |
+  | initCommand           | No  | []string          | command list to execute in init container of the pod |
+  | podOverride           | No  | map[string]interface{}  | specs to override default pod specs with |
+  | podAnnotations        | No  | map[string]string | custom annotations for the temporary pod that gets created |
+  | podLabels             | No  | map[string]string | custom labels for the temporary pod that gets created |
+  | sharedVolumeMedium    | No  | string            |  medium setting for shared volume. See [emptyDir](https://kubernetes.io/docs/concepts/storage/volumes/#emptydir). |
+  | sharedVolumeSizeLimit | No  | string            | sizeLimit setting for shared volume. See [emptyDir](https://kubernetes.io/docs/concepts/storage/volumes/#emptydir). |
+  | sharedVolumeDir       | No  | string            | directory to mount shared volume, defaults to `/tmp` |
+
+
+Example:
+
+``` yaml
+- func: MultiContainerRun
+  name: examplePhase
+  args:
+    namespace: "{{ .Deployment.Namespace }}"
+    podOverride:
+      containers:
+      - name: export
+        imagePullPolicy: IfNotPresent
+    podAnnotations:
+      annKey: annValue
+    podLabels:
+      labelKey: labelValue
+    sharedVolumeMedium: Memory
+    sharedVolumeSizeLimit: 1Gi
+    sharedVolumeDir: /tmp/
+    backgroundImage: ubuntu
+    backgroundCommand:
+      - bash
+      - -c
+      - |
+        mkfifo /tmp/pipe-file
+        for i in {1..10}
+        do
+          echo $i
+          sleep 0.1
+        done > /tmp/pipe-file
+    outputImage: ubuntu
+    outputCommand:
+      - bash
+      - -c
+      - |
+        while [ ! -e /tmp/pipe-file  ]; do sleep 1; done
+        cat /tmp/pipe-file
+```
+
 ### ScaleWorkload
 
 ScaleWorkload is used to scale up or scale down a Kubernetes workload.