Some documentation

README.md

@@ -8,8 +8,7 @@ TODO
 
 TODO 
 
-#### Argo workflows & Multi-arch OKD
-
-Refers to [argo-workflows/README.md](argo-workflows/README.md) for more details.
+#### Argo Workflows & Multi-arch OKD
 
+Refers to [docs/argo-workflows-okd.md](docs/argo-workflows-okd.md) for more details.
 

argo-workflows/okd-workflows/20-build-multiarch-image.yaml

@@ -10,10 +10,17 @@ spec:
   arguments:
     parameters:
       - name: build-config-name
+        description: The name of a build config to use as source for the multiarch build
       - name: repo-url
         default: ""
+        description: | 
+          If a non-empty value is set for repo-url, the workflow will replace the URL of the source repo in 
+          the BuildConfig. This and branch are useful to test content from PR that are not merged yet.
       - name: branch
         default: ""
+        description: |
+          If a non-empty value is set for branch, the workflow will replace the ref of the source repo in the 
+          BuildConfig. This and repo-url are useful to test content from PR that are not merged yet.
       - name: architectures
   templates:
     - name: entrypoint

argo-workflows/okd-workflows/30-tpl-cleanup.yaml

@@ -24,6 +24,7 @@ spec:
             inline:
               resource:
                 action: create
+                # TODO this step should be removed once all the images are build successfully.
                 manifest: |
                   apiVersion: image.openshift.io/v1
                   kind: ImageStream

argo-workflows/okd-workflows/40-mirror-and-customize.yaml

@@ -7,33 +7,65 @@ spec:
   arguments:
     parameters:
       - name: architectures
+        value: arm64,amd64
+        description: |
+          A comma-separated list of architectures. Nodes for all the architecture must
+          be available to run the workflow. For example `arm64,amd64`.
       - name: cleanup
+        description: |
+          Setting this to 'true' will lead to the deletion of the ImageStreamTags already available and the cleanup of 
+          the memoization cache.
         enum:
           - "false"
           - "true"
-      - default: ""
-        name: os-image
+      - name: os-image
+        default: ""
+        description: |
+          If os-image is not empty,the workflow will import the given ref to the image as `machine-os-content` and 
+          with the name given in the `os-name` field. This is alternative to `os-buildconfig`.
         value: ""
       - name: os-name
+        enum:
+          - fedora-coreos
+          - centos-stream-coreos-9
+          - rhel-coreos
+        description: |
+          The name of the OS to be used by the final payload.
       - default: ""
         name: os-buildconfig
         value: ""
-      - default: quay.io/<org>/okd-release-argo:4.13.0-0.okd-2021-12-11-200126
-        name: release-image-location
-      - default: quay.io/<org>/okd-release-argo
-        name: release-mirror-location
+        description: |
+          The BuildConfig to build the machine-os-content from. This is alternative to `os-image`.
+      - name: release-image-location
+        description: |
+          The destination registry and image to store the release image.
+          For example: quay.io/<org>/okd-release-argo:4.13.0-0.okd-2021-12-11-200126
+      - name: release-mirror-location
+        description: |
+          The destination registry and image to store the components images.
+          For example: quay.io/<org>/okd-release-argo
       - default: registry-robot-token
         name: registry-credentials-secret-ref
+        description: The name of a dockerconfigjson secret to use for authenticating external registries.
       - name: initial-payload
+        description: If this parameter is not empty, the workflow will mirror the given payload into the local release ImageStream
       - name: buildconfigs-batched-list
-        default: |
+        description: |
+          The `buildconfigs-batched-list` represents a list of JSON objects lists.
+          Each JSON object is composed by the fields `buildConfig`, `overrideRepoUrl` and `overrideBranch`.
+          If `overrideRepoURL` and `overrideBranch` are not empty, they replace the default repositories and ref stored
+          in the `BuildConfig`.
+          JSON Objects in the same list can run concurrently. Each list of list is guaranteed to run sequentially.
+          Therefore, if any BuildConfig A depends on another BuildConfig B, B should be part of a list previously to the 
+          one where the build parameters for A are defined.
           [
-            [ { "buildConfig": "my-build-config-1", "overrideRepoUrl": "....", "overrideBranch": "my-branch" } ],
-            [ { "buildConfig": "my-build-config-on-batch-2", "overrideRepoUrl": "....", "overrideBranch": "my-branch" } ]
+            [ { "buildConfig": "bc-1", "overrideRepoUrl": "....", "overrideBranch": "my-branch" } ],
+            [ { "buildConfig": "bc-2-depending-on-bc-1", "overrideRepoUrl": "....", "overrideBranch": "my-branch" } ]
           ]
       - name: delete-istags
-        default: |
-          []
+        description: |
+          Any ImageStreamTags listed here will be deleted before starting the batched builds.
+        value: '[]'
   templates:
     - name: entrypoint
       steps:

argo-workflows/okd-workflows/50-build-okd-from-scratch.yaml

@@ -7,26 +7,58 @@ spec:
     parameters:
       - name: architectures
         default: arm64,amd64
+        description: |
+          A comma-separated list of architectures. Nodes for all the architecture must
+          be available to run the workflow. For example `arm64,amd64`.
       - name: cleanup
         default: "true"
+        description: |
+          Setting this to 'true' will lead to the deletion of the ImageStreamTags already available and the cleanup of 
+          the memoization cache.
         enum:
           - "true"
           - "false"
       - name: os-image
         default: ""
+        description: |
+          If os-image is not empty,the workflow will import the given ref to the image as `machine-os-content` and 
+          with the name given in the `os-name` field. This is alternative to `os-buildconfig`.
       - name: os-name
         default: "fedora-coreos"
+        description: |
+          The name of the OS to be used by the final payload.
       - name: os-buildconfig
         default: "fedora-coreos"
+        description: |
+          The BuildConfig to build the machine-os-content from. This is alternative to `os-image`.
       - name: release-image-location
-        default: quay.io/<org>/okd-release-argo:4.13.0-0.okd-2021-12-11-200126
+        description: |
+          The destination registry and image to store the release image.
+          For example: quay.io/<org>/okd-release-argo:4.13.0-0.okd-2021-12-11-200126
       - name: release-mirror-location
-        default: quay.io/<org>/okd-release-argo
+        description: |
+          The destination registry and image to store the components images.
+          For example: quay.io/<org>/okd-release-argo
       - default: registry-robot-token
         name: registry-credentials-secret-ref
+        description: The name of a dockerconfigjson secret to use for authenticating external registries.
       - name: initial-payload
         default: ""
+        description: |
+          The `buildconfigs-batched-list` represents a list of JSON objects lists.
+          Each JSON object is composed by the fields `buildConfig`, `overrideRepoUrl` and `overrideBranch`.
+          If `overrideRepoURL` and `overrideBranch` are not empty, they replace the default repositories and ref stored
+          in the `BuildConfig`.
+          JSON Objects in the same list can run concurrently. Each list of list is guaranteed to run sequentially.
+          Therefore, if any BuildConfig A depends on another BuildConfig B, B should be part of a list previously to the 
+          one where the build parameters for A are defined.
+          [
+            [ { "buildConfig": "bc-1", "overrideRepoUrl": "....", "overrideBranch": "my-branch" } ],
+            [ { "buildConfig": "bc-2-depending-on-bc-1", "overrideRepoUrl": "....", "overrideBranch": "my-branch" } ]
+          ]
       - name: buildconfigs-batched-list
+        description: |
+          Any ImageStreamTags listed here will be deleted before starting the batched builds.
         value: |
           [ [
             {"buildConfig":"agent-installer-node-agent","overrideRepoUrl":"","overrideBranch":""},

argo-workflows/okd-workflows/50-mirror-and-rebuild-okd.yaml

@@ -7,26 +7,57 @@ spec:
     parameters:
       - name: architectures
         default: arm64,amd64
+        description: |
+          A comma-separated list of architectures. Nodes for all the architecture must
+          be available to run the workflow. For example `arm64,amd64`.
       - name: cleanup
         default: "true"
+        description: |
+          Setting this to 'true' will lead to the deletion of the ImageStreamTags already available and the cleanup of 
+          the memoization cache.
         enum:
           - "true"
           - "false"
       - name: os-image
         default: ""
+        description: |
+          If os-image is not empty,the workflow will import the given ref to the image as `machine-os-content` and 
+          with the name given in the `os-name` field. This is alternative to `os-buildconfig`.
       - name: os-name
         default: "fedora-coreos"
+        description: |
+          The name of the OS to be used by the final payload.
       - name: os-buildconfig
         default: "fedora-coreos"
+        description: |
+          The BuildConfig to build the machine-os-content from. This is alternative to `os-image`.
       - name: release-image-location
-        default: quay.io/<org>/okd-release-argo:4.13.0-0.okd-2021-12-11-200126
+        description: |
+          The destination registry and image to store the release image.
+          For example: quay.io/<org>/okd-release-argo:4.13.0-0.okd-2021-12-11-200126
       - name: release-mirror-location
-        default: quay.io/<org>/okd-release-argo
+        description: |
+          The destination registry and image to store the components images.
+          For example: quay.io/<org>/okd-release-argo
       - default: registry-robot-token
         name: registry-credentials-secret-ref
+        description: The name of a dockerconfigjson secret to use for authenticating external registries.
       - name: initial-payload
         default: ""
+        description: If this parameter is not empty, the workflow will mirror the given payload into the local release ImageStream
       - name: buildconfigs-batched-list
+        description: |
+          The `buildconfigs-batched-list` represents a list of JSON objects lists.
+          Each JSON object is composed by the fields `buildConfig`, `overrideRepoUrl` and `overrideBranch`.
+          If `overrideRepoURL` and `overrideBranch` are not empty, they replace the default repositories and ref stored
+          in the `BuildConfig`.
+          JSON Objects in the same list can run concurrently. Each list of list is guaranteed to run sequentially.
+          Therefore, if any BuildConfig A depends on another BuildConfig B, B should be part of a list previously to the 
+          one where the build parameters for A are defined.
+          [
+            [ { "buildConfig": "bc-1", "overrideRepoUrl": "....", "overrideBranch": "my-branch" } ],
+            [ { "buildConfig": "bc-2-depending-on-bc-1", "overrideRepoUrl": "....", "overrideBranch": "my-branch" } ]
+          ]
         value: |
           [ [
           { "buildConfig": "installer", "overrideRepoUrl": "", "overrideBranch": "" },
@@ -47,9 +78,10 @@ spec:
           ], [
           { "buildConfig": "artifacts", "overrideRepoUrl": "", "overrideBranch": "" }
           ] ]
-#    { "buildConfig": "ironic", "overrideRepoUrl": "", "overrideBranch": "" },
-#    { "buildConfig": "ironic-agent", "overrideRepoUrl": "", "overrideBranch": "" },
-#    { "buildConfig": "ironic-hardware-inventory-recorder", "overrideRepoUrl": "", "overrideBranch": "" },
+        # TODO: re-enable these BuildConfigs once ironic builds are fixed.
+        # { "buildConfig": "ironic", "overrideRepoUrl": "", "overrideBranch": "" },
+        # { "buildConfig": "ironic-agent", "overrideRepoUrl": "", "overrideBranch": "" },
+        # { "buildConfig": "ironic-hardware-inventory-recorder", "overrideRepoUrl": "", "overrideBranch": "" },
       - name: delete-istags
         value: |
           [

argo-workflows/operator-deployment/README.md

@@ -1,7 +1,3 @@
 ### Argo workflows on OKD
 
-The manifests in this folder allow to deploy argo workflows, and need yet further works, like:
-
-- TLS certs generation and configuration
-- Use SSO mode for authentication?
--  ...
+The manifests in this folder allow to deploy argo workflows in OKD. They should be considered very experimental.