ArgoWorkflow 教程(一)--DevOps 另一选择？云原生 CICD 初体验

本文主要记录了如何使用 ArgoWorkflow 构建流水线，以及 ArgoWorkflow 中的 Workflow、Template 等概念模型。

本文主要分析以下问题：

1）如何创建流水线
2）Workflow、Template、template 自己的引用关系
3）Workflow 和 Template 之间的参数传递问题
4）ArgoWorkflow 流水线最佳实践

1.概念模型

接下来就是如何构建我们的流水线了，ArgoWorkflow 中流水线相关的概念如下：

Workflow：流水线，真正运行的流水线实例，类似于 Tekton 中的 pipelinerun
WorkflowTemplate：流水线模板，可以基于模板创建流水线，类似于 Tekton 中的 pipeline
ClusterWorkflowTemplate：集群级别的流水线模板，和 WorkflowTemplate 的关系类似于 K8s 中的 Role 和 ClusterRole
templates：Workflow 或者 Template 的最小组成单位，流水线由多个 template 组成。

WorkflowTemplate 和 ClusterWorkflowTemplate 暂时统称为 Template。

Workflow、Template(大写)、template(小写)之间的关系如下：

三者间关系比较复杂，官方也有提到这块因为一些历史遗留问题导致命名上比较混乱

个人理解：

template(小写)：为 Template(大写)的基本组成单位，可以理解为流水线中的步骤
Template(大写)：一条完整的流水线，一般由多个 template(小写) 组成
Workflow：真正运行的流水线实例，一般由 Template 直接创建，类似于流水线运行记录，每一条记录都是一个 Workflow

理清基本概念之后，接下来就看下看具体使用。

2.Workflow

在 ArgoWorkflow 中 Workflow 为流水线运行实例，每创建一个 Workflow 对象，都会触发流水线运行一次。

以下是一个简单的 Workflow 例子：

YAML 复制代码

apiVersion: argoproj.io/v1alpha1
kind: Workflow
metadata:
  generateName: steps-
spec:
  entrypoint: hello           # We reference our first "template" here
  templates:
  - name: hello               # The first "template" in this Workflow, it is referenced by "entrypoint"
    steps:                    # The type of this "template" is "steps"
    - - name: hello
        template: whalesay    # We reference our second "template" here
        arguments:
          parameters: [{name: message, value: "hello"}]

  - name: whalesay             # The second "template" in this Workflow, it is referenced by "hello"
    inputs:
      parameters:
      - name: message
    container:                # The type of this "template" is "container"
      image: docker/whalesay
      command: [cowsay]
      args: ["{{inputs.parameters.message}}"]

整个 Workflow 对象核心内容分为以下三部分：

entrypoint: 流水线入口，类似于代码中的 main 方法，此处一般引用某一个 template invocators 即可。
templates：模板列表，此处定义了流水线中的所有步骤以及步骤之间的先后顺序。
parameters：流水线中用到的参数，包括 arguments 块中的全局参数和 inputs 块中的局部参数两种

entrypoint

Workflow 中必须要指定 entrypoint，entrypoint 作为任务的执行起点，类似于程序中的 main 方法。

templates

具体见官方文档：#template-types

模板分为多种类型，根据类型的不同分为 template definitions （模板定义）以及 template invocators（模板调用器）。

template definitions（模板定义） ：该类型 template 用于定义具体步骤要执行的内容，例子中的 whalesay 模板就是该类型
- 包含 container, script, resource, suspend 等类型
template invocators（模板调用器） ：该类型 template 用于组合其他 template definitions(模版定义) ，定义步骤间的执行顺序等，例子中的 hello 模板就是该类型。
- 一般 entrypoint 就是该类型的模板
- 包含dag 和 steps 两种类型，例子中的 hello 模板就是 steps 类型。

吐槽一下：template 这里有点绕，如果能将 模板定义、模板调用器 拆分为两个不同的对象就比较清晰。

了解完 template 分类之后再回头看之前的 Workflow 例子就比较清晰了：

YAML 复制代码

apiVersion: argoproj.io/v1alpha1
kind: Workflow
metadata:
  generateName: steps-
spec:
  entrypoint: hello           # We reference our first "template" here
  templates:
  - name: hello               # The first "template" in this Workflow, it is referenced by "entrypoint"
    steps:                    # The type of this "template" is "steps"
    - - name: hello
        template: whalesay    # We reference our second "template" here
        arguments:
          parameters: [{name: message, value: "hello"}]

  - name: whalesay             # The second "template" in this Workflow, it is referenced by "hello"
    inputs:
      parameters:
      - name: message
    container:                # The type of this "template" is "container"
      image: docker/whalesay
      command: [cowsay]
      args: ["{{inputs.parameters.message}}"]

1）首先 whalesay 模板是一个 container 类型的 template，因此是 template definitions（模板定义）
2）其次 hello 是一个 steps 类型的 template，因此是 template invocators（模板调用器）
- 在该调用器中 steps 字段中定义了一个名为 hello 的步骤，该步骤引用的就是 whalesay template
3）entrypoint 指定的是 hello 这个 template invocators（模板调用器）

小结：entrypoint、template definitions、template invocators 这三个就是一个 Workflow 的必要组成。

parameters

Workflow 支持两种类型的参数：

arguments：全局参数，Workflow 下所有 template 都可使用
inputs：局部参数，仅当前 template 可使用

arguments 全局参数

spec.arguments用于定义全局参数，这部分参数在当前 Workflow 下的所有 Template 中都可以使用，可以使用 {{workflow.parameters.$name}} 语法来引用。

例如下面这个例子中指定了一个名为 message 的参数，并赋值为 hello world。

YAML 复制代码

  arguments:
    parameters:
      - name: message
        value: hello world

inputs 局部参数

Template 中可以使用 templates[*].inputs 字段来指定局部参数 ，这部分参数只有当前 Template 可以使用。可以通过{{inputs.parameters.$name}} 语法来引用参数。

下面这个例子则是声明了 template 需要一个名为 message 的参数，但是未提供具体值。

YAML 复制代码

  templates:
    - name: whalesay-template
      inputs:
        parameters:
          - name: message
      container:
        image: docker/whalesay
        command: [cowsay]
        args: ["{{inputs.parameters.message}}"]

参数传递

Workflow 中的全局参数值由用户指定，而局部参数中的值一般是由全局参数覆盖。

YAML 复制代码

apiVersion: argoproj.io/v1alpha1
kind: Workflow
metadata:
  generateName: steps-
spec:
  entrypoint: hello           # We reference our first "template" here
  templates:
  - name: hello               # The first "template" in this Workflow, it is referenced by "entrypoint"
    steps:                    # The type of this "template" is "steps"
    - - name: hello
        template: whalesay    # We reference our second "template" here
        arguments:
          parameters: [{name: message, value: "hello"}]

  - name: whalesay             # The second "template" in this Workflow, it is referenced by "hello"
    inputs:
      parameters:
      - name: message
    container:                # The type of this "template" is "container"
      image: docker/whalesay
      command: [cowsay]
      args: ["{{inputs.parameters.message}}"]

上述例子中，template whalesay 定义了一个名为 message 的局部参数，但是没有赋值，同时在 template 中又定义了一个名为 message 的参数，因此最终局部参数 message 会被全局参数 message 覆盖。

上述例子可以看成是这样的：

YAML 复制代码

  templates:
  - name: hello               # The first "template" in this Workflow, it is referenced by "entrypoint"
    steps:                    # The type of this "template" is "steps"
    - - name: hello
        template: whalesay    # We reference our second "template" here
        arguments:
          parameters: [{name: message, value: "hello"}]

  - name: whalesay             # The second "template" in this Workflow, it is referenced by "hello"
    inputs:
      parameters:
      - name: message
        value: "{{workflow.parameters.message}}"
    container:                # The type of this "template" is "container"
      image: docker/whalesay
      command: [cowsay]
      args: ["{{inputs.parameters.message}}"]

即：template 引用局部参数，局部参数来自全局参数，用户配置全局参数。

3.Template

根据前面描述可以指定，我们能直接创建 Workflow 对象来运行流水线，不过这种方式存在的一些问题：

1）如果 template 比较多的话，Workflow 对象就会特别大，修改起来比较麻烦
2）模板无法共享，不同 Workflow 都需要写一样的 template

因此，一般建议将 template 存到 WorkflowTemplate，Workflow 中只引用 Template 并提供参数即可。

而 ArgoWorkflow 中的工作流模板根据范围不同分为 WorkflowTemplate 和 ClusterWorkflowTemplate 两种。

WorkflowTemplate：命名空间范围，只能在同一命名空间引用
ClusterWorkflowTemplate：集群范围，任意命名空间都可以引用

WorkflowTemplate

下面是一个简单的 WorkflowTemplate 例子：

YAML 复制代码

apiVersion: argoproj.io/v1alpha1
kind: WorkflowTemplate
metadata:
  name: workflow-template-submittable
  namespace: default
spec:
  entrypoint: whalesay-template
  arguments:
    parameters:
      - name: message
        value: tpl-argument-default
  templates:
    - name: whalesay-template
      inputs:
        parameters:
          - name: message
            value: tpl-input-default
      container:
        image: docker/whalesay
        command: [cowsay]
        args: ["{{inputs.parameters.message}}"]

可以看到 WorkflowTemplate 和 Workflow 参数是一模一样，只是将 yaml 中的 kind 由 Workflow 替换为 WorkflowTemplate 即可，这里就不在赘述了。

workflowMetadata

workflowMetadata 是 Template 中独有的一个字段，主要用于存储元数据 ，后续由这个 Template 创建出的 Workflow 都会自动携带上这些信息。

通过这些信息可以追踪到 Workflow 是由那个 Template 创建的。

使用方式就像下面这样，workflowMetadata 中指定了一个 label

YAML 复制代码

apiVersion: argoproj.io/v1alpha1
kind: WorkflowTemplate
metadata:
  name: workflow-template-submittable
spec:
  workflowMetadata:
    labels:
      example-label: example-value

然后由该 Template 创建的 Workflow 对象都会携带这个 label：

YAML 复制代码

apiVersion: argoproj.io/v1alpha1
kind: Workflow
metadata:
  annotations:
    workflows.argoproj.io/pod-name-format: v2
  creationTimestamp: "2023-10-27T06:26:13Z"
  generateName: workflow-template-hello-world-
  generation: 2
  labels:
    example-label: example-value
  name: workflow-template-hello-world-5w7ss
  namespace: default

ClusterWorkflowTemplate

类似于 WorkflowTemplate，可以理解为 k8s 中的 Role 和 ClusterRole 的关系。

和 WorkflowTemplate 所有参数都一致，只是将 yaml 中的 kind 替换为 ClusterWorkflowTemplate 即可。

小结

Template 中最好将以下三部分内容都配置好：

entrypoint：推荐，虽然可以在 Workflow 中指定，但是这样每次创建 Workflow 都需要先看一下 Template 中有哪些 template 了，比较麻烦，因此最好 Template 中直接填好
templates：必须，Template 的作用就是写模板
arguments：最好将默认值填上，这样 Workflow 在不指定任何参数时也能使用

当 Template 中将这三个核心内容都填好之后，Workflow 使用时就非常简单了。

4. TemplateRef

创建好 Template 之后就可以在 Workflow 中使用 TemplateRef 直接引用对应模板了，这样 Workflow 对象就会比较干净。

workflowTemplateRef

可以通过workflowTemplateRef字段直接引用 WorkflowTemplate。

注意📢：这里需要 Workflow 和 WorkflowTemplate 在同一个命名空间。

就像这样：

YAML 复制代码

apiVersion: argoproj.io/v1alpha1
kind: Workflow
metadata:
  generateName: workflow-template-hello-world-
spec:
  arguments:
    parameters:
      - name: message
        value: "from workflow"
  workflowTemplateRef:
    name: workflow-template-submittable

workflowTemplateRef 指定要引用的 Template 名字即可，这一句就相当于把对应 Template 中 spec 字段下的所有内容都搬过来了，包括 entrypoint、template 等。

Workflow 中一般只需要通过 argument 字段来实现参数覆盖，当然也可以不指定，若 Workflow 中不指定参数则会使用 Template 中提供的默认值

一个最精简的 Workflow 如下：

YAML 复制代码

apiVersion: argoproj.io/v1alpha1
kind: Workflow
metadata:
  generateName: workflow-template-hello-world-
spec:
  workflowTemplateRef:
    name: workflow-template-submittable

只有 workflowTemplateRef 字段，未提供 argument 参数。

和前面的 Workflow 对比起来，内容就更少了，因为大部分都写在 WorkflowTemplate 里了，Workflow 中一般只需要指定参数就行。

参数问题：

全局参数可以直接在 WorkflowTemplate 中使用，只需要到时候 Workflow 中有定义即可。
局部参数则必须在 WorkflowTemplate 中定义并赋值

具体见官方文档：#working-with-parameters

看起来就是 WorkflowTemplate 中最好使用全局参数，因为局部参数的值是直接定义在 WorkflowTemplate 中的，Workflow 中不能覆盖。

clusterWorkflowTemplateRef

和 workflowTemplateRef 类似，只需要增加 clusterScope: true 配置即可。

默认为 false，即 WorkflowTemplate

就像这样：

YAML 复制代码

apiVersion: argoproj.io/v1alpha1
kind: Workflow
metadata:
  generateName: workflow-template-hello-world-
spec:
  entrypoint: whalesay
  templates:
  - name: whalesay
    steps:                              # You should only reference external "templates" in a "steps" or "dag" "template".
      - - name: call-whalesay-template
          templateRef:                  # You can reference a "template" from another "WorkflowTemplate or ClusterWorkflowTemplate" using this field
            name: cluster-workflow-template-whalesay-template   # This is the name of the "WorkflowTemplate or ClusterWorkflowTemplate" CRD that contains the "template" you want
            template: whalesay-template # This is the name of the "template" you want to reference
            clusterScope: true          # This field indicates this templateRef is pointing ClusterWorkflowTemplate
          arguments:                    # You can pass in arguments as normal
            parameters:
            - name: message
              value: "hello world"

核心部分：

YAML 复制代码

  workflowTemplateRef:
    name: cluster-workflow-template-submittable
    clusterScope: true

当指定为集群范围时，ArgoWorkflow 会去搜索 ClusterWorkflowTemplate 对象，否则会在当前命名空间搜索 WorkflowTemplate。

templateRef

除了使用 workflowTemplateRef / clusterWorkflowTemplateRef 引用整个 WorkflowTemplate 之外，还可以使用 templateRef 参数来实现引用 WorkflowTemplate 中的某一个 template。

注意📢：根据官方文档，最好不要在 steps 和 dag 类型的 template 之外使用 templateRef 。

YAML 复制代码

apiVersion: argoproj.io/v1alpha1
kind: Workflow
metadata:
  generateName: workflow-template-hello-world-
spec:
  entrypoint: whalesay
  templates:
  - name: whalesay
    steps:                              # You should only reference external "templates" in a "steps" or "dag" "template".
      - - name: call-whalesay-template
          templateRef:                  # You can reference a "template" from another "WorkflowTemplate" using this field
            name: workflow-template-1   # This is the name of the "WorkflowTemplate" CRD that contains the "template" you want
            template: whalesay-template # This is the name of the "template" you want to reference
          arguments:                    # You can pass in arguments as normal
            parameters:
            - name: message
              value: "hello world"

5. 参数优先级测试

由于有多个地方都可以设置参数，同时又有全局参数和局部参数等区别，对于参数具体逻辑不是很清晰，因此测试了一下具体的参数传递情况。

一共有三个地方可以设置参数：

1）WorkflowTemplate 中 arguments 全局参数
2）WorkflowTemplate 中 inputs 局部参数
3）Workflow 中 arguments 全局参数

注意📢：在 workflowTemplateRef 这种引用方式下， Workflow 中是无法指定 input 值的。

对于不同情况做了测试，最终结论如下为：

Workflow 中的 argument > Template 中的 argument > Template 中的 input

只要提供了更高优先级的参数，低优先级的就会覆盖

Argument > Input 即全局参数优先级高于局部参数
Workflow > Template 即流水线参数可以覆盖模板中的默认值

6. 小结

ArgoWorkflow 中的工作流包括以下概念：

Workflow
Template：WorkflowTemplate、ClusterWorkflowTemplate
TemplateRef：workflowTemplateRef、clusterWorkflowTemplateRef
Template

关系如图所示

一个 Workflow / WorkflowTemplate 中包含三部分参数：

entrypoint：入口，必填的，值是 Template 的名字
- 可以来源于 Workflow，也就是显式写在 Workflow 里面
- 也可以来源于 WorkflowTemplate，即 Workflow 中不写该字段，在 WorkflowTemplate 中写
- 最好直接写在 WorkflowTemplate 中
arguments：参数，同样 Workflow 和 WorkflowTemplate 都可以指定，且 Workflow 中的 arguments 优先级高于 WorkflowTemplate
templates：模板，这部分包含了 Workflow 具体要执行的动作
- 这部分建议全定义在 WorkflowTemplate 中，Workflow 中直接引用 WorkflowTemplate 即可

最佳实践：

1）使用 Template 来管理流水线，并在 WorkflowTemplate 中定义好 entrypoint 和 templates 以及 arguments
- Template 中指定 entrypoint、templates、arguments 等信息
2）Workflow 中使用 TemplateRef 直接引用已存在的 Template，并指定 arguments 进行覆盖

参数优先级：Workflow 中的 argument > Template 中的 argument > Template 中的 input

【ArgoWorkflow 系列】 持续更新中，搜索公众号【探索云原生】订阅，阅读更多文章。