应用(Apps)

    有时候，你需要为一个应用/微服务定义多个 工具。例如，对于一个 web 应用程序，你可能需要指定以下工具：

    • 仓库脚手架
    • 持续集成
    • 持续部署

    如果你有多个应用需要管理，你需要在配置中创建多个 工具，这可能会很繁琐，而且配置文件难以阅读。

    为了更容易地管理多个应用/微服务，DevStream 提供了另一层抽象，称为 应用。你可以在一个应用中定义所有内容（例如，上面提到的仓库脚手架、持续集成、持续部署等），只需要几行配置，就可以使配置文件更容易阅读和管理。

    在底层，DevStream 仍然会将你的 应用 配置转换为 工具 的定义，但你不需要关心它。

    一个 DevStream 应用 可以引用一个或多个 流水线模板，这些模板主要是 CI/CD 定义，这样 应用 的定义可以更短，以在多个微服务之间共享公共的 CI/CD 流水线。

    2.1 应用

    应用在配置中由 来定义，它是一个数组，每个元素的字段如下：

    • name: 应用的名称，必须是唯一的
    • spec: 配置应用特定的信息
    • repo: 代码仓库信息
    • repoTemplate: 可选。结构和 repo 一致。若非空，DevStream 将使用项目脚手架来创建仓库。
    • ci: 可选，一个 CI 流水线的数组，每个元素包含以下字段：
      • type: 类型。值为 template 或某个插件的名称。
      • templateName: 可选。当 type 为 template 时，指定使用的模板名称。
      • vars: 可选。传入模板的变量，仅当 type 为 template 时有效。
      • options: 可选。
        • 当 type 是某个插件名时，就是该插件的 Options
        • 当 type 为 template 时，覆盖模板中的 Options。你需要写清想要覆盖的选项的完整路径，例如 options.docker.registry.type。
    • cd: 与 ci 类似，是 CD 流水线列表。dtm 会先执行 ci 流水线，再执行 cd 流水线。

    流水线模板在配置中由 pipelineTemplates 来定义，它是一个数组，每个元素的字段如下：

    • name: 流水线模板的名称，必须是唯一的
    • type: 对应插件的名称
    • options: 插件的 Options （可能和原始的插件 Options 不同）

    2.3 局部变量

    DevStream 已经有了全局变量，所有的 工具 和 应用 都可以直接引用。

    在这种情况下，我们可以定义一个流水线模板，在其中定义一个局部变量，然后在 应用 引用该流水线模板时，传入不同的值。

    流水线模板的使用与局部变量

    应用 的真实示例配置如下：

    YAML

    1. apps:
    2. - name: testApp # 应用名称
    3.   spec: # 该配置项用于配置应用特定的信息
    4.     language: java #应用所使用的编程语言
    5.     framework: springboot #应用所使用的编程框架
    6.   repo: # 该配置项用于应用的代码仓库信息
    7.     url: https://github.com/testUser/testApp.git
    8.     branch: main
    9.   repoTemplate: # 可选，用于创建应用的脚手架。不为空时，会使用该脚手架创建应用的代码仓库
    10.     vars:
    11.       imageRepoOwner: repoOwner # 用于渲染脚手架模版的变量
    12.   ci: # 配置应用的 ci 流程，如下即为使用 github-actions 运行应用 ci 流程
    13.   - type: github-actions
    14. - name: testApp2
    15.   spec:
    16.     language: go
    17.     framework: gin
    18.   repo: # 该配置项用于应用的代码仓库信息
    19.     owner: test_user
    20.     type: github
    21.     branch: main
    22.   repoTemplate: # 该配置用于创建应用的脚手架
    23.     org: devstream-io
    24.     name: dtm-repo-scaffolding-java-springboot
    25.     type: github
    26.   ci: # 配置应用的 ci 流程，如下即为使用 github-actions 运行应用 ci 流程
    27.   - type: github-actions
    28.     options:
    29.       imageRepo:
    30.         owner: repoOwner # 覆盖 插件/模板 原有的 Options，YAML 路径要写完全
    31.   cd: # 配置应用的 cd，如果为使用 argocdapp 运行应用的 cd 流程
    32.   - type: argocdapp

    使用该配置就会在 gitlab 仓库中创建两个应用，项目的脚手架均为 DevStream 官方提供的 项目。应用 testApp 会在每次代码提交后使用 运行测试。应用 testApp2 会在每次代码提交后使用 github-actions 运行测试并构建镜像推送到 repoOwner 的镜像仓库中，最后使用 Argo CD 将应用部署到集群中。

    应用配置中的 repo 和 repoTemplate 均表示一个代码仓库，支持通过 url 或 详细字段来配置：

    两种配置代码仓库的方式

    使用 url 来配置使用仓库的详细字段来配置

    1.   repo:
    2.     org: "" # 非必填，仓库的拥有组织名称，如果使用 github 的组织则需要填写此字段
    3.     owner："test_user" # 如果仓库是非组织的，则需要填写该字段表示仓库拥有者
    4.     name: "" # 非必填，默认为应用名
    5.     baseURL:  https://gitlab.example.com # 非必填，如果使用 gitlab 则需要填写该字段表示 gitlab 的域名
    6.     branch: master #非必填，github 默认为 main 分支，gitlab 默认为 master 分支
    7.     type:  gitlab #必填，表示该仓库的类型，目前支持 gitlab/github

    该配置表示代码仓库使用的是 gitlab 且其地址为 https://gitlab.example.com，仓库名称为应用名，仓库的所有者为 test_user，主分支为 master 分支。

    ci 配置

    应用配置中的 ci 目前支持 github-actions/gitlab-ci/jenkins-pipeline/template 4 种类型。

    其中 template 类型表示使用 流水线模板 来运行流水线，前 3 种类型分别对应了 github 中的 actions 流水线，gitlab 中 ci 流水线和 jenkins 中的 pipeline，它们的具体配置如下：

    YAML

    上述的配置即会在应用更新推送到代码仓库后先并行执行单元测试和代码扫描，然后构建镜像推送到代码仓库，流程都成功后发送通知消息到指定的钉钉群中。如果所有应用都要配置一遍该类型 ci, 那配置就会变得比较繁琐，所以 devstream 还提供了 template 用于在多个应用间共享 ci 的流程配置，具体如下所示：

    YAML

    1. apps:
    2. - name: javaProject1
    3.   spec:
    4.     language: java
    5.     framework: springboot
    6.   repo:
    7.     owner: testUser
    8.     type: github
    9.   repoTemplate:
    11.   - type: template # 表示该 ci 流程使用模版
    12.     templateName: ci-pipeline # ci 使用的模版名称
    13.     vars:
    14.       dingdingAccessToken: tokenForProject1 #用于渲染 ci 模版的变量
    15.       dingdingSecretValue: secretValProject1
    16. - name: javaProject2
    17.   spec:
    18.     language: java
    19.     framework: springboot
    20.   repo:
    21.     owner: testUser
    22.     type: github
    23.   repoTemplate:
    24.     url: https://github.com/devstream-io/dtm-repo-scaffolding-java-springboot.git
    25.   ci:
    26.   - type: template # 表示该 ci 流程使用模版
    27.     templateName: ci-pipeline # ci 使用的模版名称
    28.     vars:
    29.       dingdingAccessToken: tokenForProject2 # 设置传入模版 "ci-pipeline" 的变量
    30.       dingdingSecretValue: secretValProject2
    32. pipelineTemplates: # 即配置的 ci/cd 模版
    33. - name: ci-pipeline # 模版名称
    34.   type: jenkins-pipeline #模版类型，支持 jenkins-pipeline，github-actions 和 gitlab-ci
    35.   options: # options 和 ci 的 options 完全一致
    36.     jenkins:
    37.       url: jenkins.exmaple.com
    38.       user: admin
    39.     imageRepo:
    40.       url: http://harbor.example.com
    41.       owner: admin
    42.     dingTalk:
    43.       name: dingTalk
    44.       webhook: https://oapi.dingtalk.com/robot/send?access_token=[[ dingdingAccessToken ]] # 用于被 app 渲染的模版，这样就可以实现不同应用使用同一个模版发送通知到不同的钉钉群
    45.       securityType: SECRET
    46.       securityValue: [[ dingdingSecretValue ]] # 局部变量，应用 在引用此模板时通过 vars 来传入
    47.     sonarqube:
    48.         url: http://sonar.example.com
    49.         name: sonar_test

    使用以上的配置，就会创建两个和上述流程一致的 jenkins 流水线，不同之处只在于两个应用通知的钉钉群不一样。

    应用的 cd 配置目前只支持 argocdapp，可以使用 来将应用部署在集群中，具体配置如下：