From aaabddeae2375924c9e6d07ee31f6ae0bddf3196 Mon Sep 17 00:00:00 2001 From: Bird Date: Wed, 14 Dec 2022 11:42:04 +0800 Subject: [PATCH] docs: update core-concepts Signed-off-by: Bird --- docs/core-concepts/apps.md | 1 + docs/core-concepts/apps.zh.md | 162 ++++++++++++++---- docs/core-concepts/config.zh.md | 118 ++++--------- docs/core-concepts/output.md | 18 +- docs/core-concepts/output.zh.md | 85 ++++++++- docs/core-concepts/overview.md | 6 +- docs/core-concepts/overview.zh.md | 65 +++---- docs/core-concepts/state.zh.md | 53 +++++- docs/core-concepts/tools-apps.zh.md | 3 - .../core-concepts/{tools-apps.md => tools.md} | 0 docs/core-concepts/tools.zh.md | 56 ++++++ .../docs-contribution/mkdocs.zh.md | 1 + docs/includes/glossary.md | 19 ++ docs/install.md | 8 +- docs/install.zh.md | 16 +- mkdocs.yml | 6 +- 16 files changed, 427 insertions(+), 190 deletions(-) create mode 100644 docs/core-concepts/apps.md delete mode 100644 docs/core-concepts/tools-apps.zh.md rename docs/core-concepts/{tools-apps.md => tools.md} (100%) create mode 100644 docs/core-concepts/tools.zh.md create mode 100644 docs/includes/glossary.md diff --git a/docs/core-concepts/apps.md b/docs/core-concepts/apps.md new file mode 100644 index 000000000..a5c617fe0 --- /dev/null +++ b/docs/core-concepts/apps.md @@ -0,0 +1 @@ +# Apps diff --git a/docs/core-concepts/apps.zh.md b/docs/core-concepts/apps.zh.md index 1a8b3163a..37e7cf82e 100644 --- a/docs/core-concepts/apps.zh.md +++ b/docs/core-concepts/apps.zh.md @@ -1,23 +1,109 @@ -# 应用 +# 应用(Apps) -## 概念 +## 1 概念 -应用在 devstream 中表示对一个服务的生命周期配置，包括对服务的项目脚手架，CI 流程以及 CD 流程的配置，在 devstream 中使用应用可以使用少数几行配置就构建出服务的整条 CI/CD 流水线配置。 +应用在 DevStream 中表示对一个服务的生命周期配置，包括对服务的项目脚手架，CI 流程以及 CD 流程的配置，在 devstream 中使用应用可以使用少数几行配置就构建出服务的整条 CI/CD 流水线配置。 -## 应用配置 +### 1.1 应用(Apps) -应用的示例配置如下： +有时候，你需要为一个应用/微服务定义多个 工具。例如，对于一个 web 应用程序，你可能需要指定以下工具： + +- 仓库脚手架 +- 持续集成 +- 持续部署 + +如果你有多个应用需要管理，你需要在配置中创建多个 工具，这可能会很繁琐，而且配置文件难以阅读。 + +为了更容易地管理多个应用/微服务，DevStream 提供了另一层抽象，称为 应用。你可以在一个应用中定义所有内容（例如，上面提到的仓库脚手架、持续集成、持续部署等），只需要几行配置，就可以使配置文件更容易阅读和管理。 + +在底层，DevStream 仍然会将你的 应用 配置转换为 工具 的定义，但你不需要关心它。 + +## 1.2 流水线模板（pipelineTemplates） + +一个 DevStream 应用 可以引用一个或多个 流水线模板，这些模板主要是 CI/CD 定义，这样 应用 的定义可以更短，以在多个微服务之间共享公共的 CI/CD 流水线。 + +## 2 配置方式 + +### 2.1 应用 + +应用在配置中由 `apps` 来定义，它是一个数组，每个元素的字段如下： + +- 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 流水线。 + +### 2.2 流水线模板 + +流水线模板在配置中由 `pipelineTemplates` 来定义，它是一个数组，每个元素的字段如下： + +- name: 流水线模板的名称，必须是唯一的 +- type: 对应插件的名称 +- options: 插件的 Options （可能和原始的插件 Options 不同） + +### 2.3 局部变量 + +DevStream 已经有了全局变量，所有的 工具 和 应用 都可以直接引用。 + +但有时，我们想多次引用某个 DevOps 工具，但他们只有一些细微的差别。例如，除了项目名称不同，其他的都相同。 + +在这种情况下，我们可以定义一个流水线模板，在其中定义一个局部变量，然后在 应用 引用该流水线模板时，传入不同的值。 + +```yaml hl_lines="13 15 23 30" title="流水线模板的使用与局部变量" +apps: +- name: my-app + spec: + language: java + framework: springboot + repo: + url: https://github.com/testUser/testApp.git + branch: main + ci: + - type: github-actions # 不定义 pipelineTemplates，直接使用插件 + cd: + - type: template # 使用流水线模板 + templateName: my-cd-template # 对应 pipelineTemplates 中的 name + vars: + appName: my-app # 传入模板的变量 + +pipelineTemplates: +cd: +- name: my-cd-template + type: argocdapp + options: + app: + name: [[ appName ]] # 定义一个局部变量，在引用使用模板时传入 + namespace: argocd # argocd 的命名空间 + destination: + server: https://kubernetes.default.svc # 部署的 kubernetes 服务地址 + namespace: default # 应用要部署的命名空间 + source: + valuefile: values.yaml # 项目中的 helm 变量文件名 + path: charts/[[ appName ]] # 项目中的 helm 配置路径 +``` + +## 3 完整配置示例 + +应用 的真实示例配置如下： ```yaml apps: -- name: testApp #应用名称 +- name: testApp # 应用名称 spec: # 该配置项用于配置应用特定的信息 language: java #应用所使用的编程语言 framework: springboot #应用所使用的编程框架 repo: # 该配置项用于应用的代码仓库信息 url: https://github.com/testUser/testApp.git branch: main - repoTemplate: # 该配置用于创建应用的脚手架 + repoTemplate: # 可选，用于创建应用的脚手架。不为空时，会使用该脚手架创建应用的代码仓库 url: https://github.com/devstream-io/dtm-repo-scaffolding-java-springboot.git vars: imageRepoOwner: repoOwner # 用于渲染脚手架模版的变量 @@ -39,45 +125,49 @@ apps: - type: github-actions options: imageRepo: - owner: repoOwner + owner: repoOwner # 覆盖 插件/模板 原有的 Options，YAML 路径要写完全 cd: # 配置应用的 cd，如果为使用 argocdapp 运行应用的 cd 流程 - type: argocdapp ``` -使用该配置就会在 `gitlab` 仓库中创建两个应用，项目的脚手架均为 devstream 官方提供的 [springboot](https://github.com/devstream-io/dtm-repo-scaffolding-java-springboot.git) 项目。应用 `testApp` 会在每次代码提交后使用 `github-actions` 运行测试。应用 `testApp2` 会在每次代码提交后使用 `github-actions` 运行测试并构建镜像推送到 `repoOwner` 的镜像仓库中，最后使用 argocd 将应用部署到集群中。 +使用该配置就会在 `gitlab` 仓库中创建两个应用，项目的脚手架均为 DevStream 官方提供的 [SpringBoot](https://github.com/devstream-io/dtm-repo-scaffolding-java-springboot.git) 项目。应用 `testApp` 会在每次代码提交后使用 `github-actions` 运行测试。应用 `testApp2` 会在每次代码提交后使用 `github-actions` 运行测试并构建镜像推送到 `repoOwner` 的镜像仓库中，最后使用 Argo CD 将应用部署到集群中。 ### repo/repoTemplate 配置 -应用配置中的 `repo` 和 `repoTemplate` 均表示一个代码仓库，支持以下两种配置代码仓库的方式： +应用配置中的 `repo` 和 `repoTemplate` 均表示一个代码仓库，支持通过 url 或 详细字段来配置： -#### 使用 url 来配置代码仓库： +!!! note "两种配置代码仓库的方式" -```yaml - repo: - url: git@gitlab.example.com:root/myapps.git # url 表示仓库的地址，支持 git 地址和 http 地址 - apiURL: https://gitlab.example.com # 非必填，如果使用 gitlab 而且 url 使用的是 git 地址，则需要配置该字段用于表示 gitlab 的 api 请求地址 - branch: "" #非必填，github 默认为 main 分支，gitlab 默认为 master 分支 -``` - -该配置表示使用的仓库为 `gitlab`, 要使用 `git@gitlab.example.com:root/myapps.git` 来克隆代码，devstream 会使用使用 `https://gitlab.example.com` 和 gitlab 进行交互，仓库的主分支为 `master` 分支。 - -#### 使用仓库的详细字段来配置仓库： - -```yaml - repo: - org: "" # 非必填，仓库的拥有组织名称，如果使用 github 的组织则需要填写此字段 - owner："test_user" # 如果仓库是非组织的，则需要填写该字段表示仓库拥有者 - name: "" # 非必填，默认为应用名 - baseURL: https://gitlab.example.com # 非必填，如果使用 gitlab 则需要填写该字段表示 gitlab 的域名 - branch: master #非必填，github 默认为 main 分支，gitlab 默认为 master 分支 - type: gitlab #必填，表示该仓库的类型，目前支持 gitlab/github -``` - -该配置表示代码仓库使用的是 `gitlab` 且其地址为 `https://gitlab.example.com`，仓库名称为应用名，仓库的所有者为 `test_user`，主分支为 `master` 分支。 + === "使用 url 来配置" + + ```yaml title="" + repo: + url: git@gitlab.example.com:root/myapps.git # url 表示仓库的地址，支持 git 地址和 http 地址 + apiURL: https://gitlab.example.com # 非必填，如果使用 gitlab 而且 url 使用的是 git 地址，则需要配置该字段用于表示 gitlab 的 api 请求地址 + branch: "" # 非必填，github 默认为 main 分支，gitlab 默认为 master 分支 + ``` + + 该配置表示使用的仓库为 `gitlab`, 要使用 `git@gitlab.example.com:root/myapps.git` 来克隆代码，devstream 会使用使用 `https://gitlab.example.com` 和 gitlab 进行交互，仓库的主分支为 `master` 分支。 + + === "使用仓库的详细字段来配置" + + ```yaml title="" + repo: + org: "" # 非必填，仓库的拥有组织名称，如果使用 github 的组织则需要填写此字段 + owner："test_user" # 如果仓库是非组织的，则需要填写该字段表示仓库拥有者 + name: "" # 非必填，默认为应用名 + baseURL: https://gitlab.example.com # 非必填，如果使用 gitlab 则需要填写该字段表示 gitlab 的域名 + branch: master #非必填，github 默认为 main 分支，gitlab 默认为 master 分支 + type: gitlab #必填，表示该仓库的类型，目前支持 gitlab/github + ``` + + 该配置表示代码仓库使用的是 `gitlab` 且其地址为 `https://gitlab.example.com`，仓库名称为应用名，仓库的所有者为 `test_user`，主分支为 `master` 分支。 ### ci 配置 -应用配置中的 `ci` 目前支持 `github-actions`/`gitlab-ci`/`jenkins-pipeline`/`template` 4 种类型，前 3 种类型分别对应了 `github` 中的 actions 流水线，`gitlab` 中 ci 流水线和 `jenkins` 中的 pipeline，它们的具体配置如下： +应用配置中的 `ci` 目前支持 `github-actions`/`gitlab-ci`/`jenkins-pipeline`/`template` 4 种类型。 + +其中 `template` 类型表示使用 流水线模板 来运行流水线，前 3 种类型分别对应了 `github` 中的 actions 流水线，`gitlab` 中 ci 流水线和 `jenkins` 中的 pipeline，它们的具体配置如下： ```yaml ci: @@ -132,7 +222,7 @@ apps: - type: template # 表示该 ci 流程使用模版 templateName: ci-pipeline # ci 使用的模版名称 vars: - dingdingAccessToken: tokenForProject2 #用于渲染 ci 模版的变量 + dingdingAccessToken: tokenForProject2 # 设置传入模版 "ci-pipeline" 的变量 dingdingSecretValue: secretValProject2 pipelineTemplates: # 即配置的 ci/cd 模版 @@ -149,7 +239,7 @@ pipelineTemplates: # 即配置的 ci/cd 模版 name: dingTalk webhook: https://oapi.dingtalk.com/robot/send?access_token=[[ dingdingAccessToken ]] # 用于被 app 渲染的模版，这样就可以实现不同应用使用同一个模版发送通知到不同的钉钉群 securityType: SECRET - securityValue: [[ dingdingSecretValue ]] + securityValue: [[ dingdingSecretValue ]] # 局部变量，应用 在引用此模板时通过 vars 来传入 sonarqube: url: http://sonar.example.com token: sonar_token diff --git a/docs/core-concepts/config.zh.md b/docs/core-concepts/config.zh.md index 065f2dabf..3e14ccbf9 100644 --- a/docs/core-concepts/config.zh.md +++ b/docs/core-concepts/config.zh.md @@ -1,113 +1,65 @@ -# DevStream配置 +# 配置(Config) -TODO: 需要跟英文文档同步。请暂且阅读英文文档。 +DevStream使用 YAML 文件来声明 DevOps 工具链的配置。 -DevStream使用YAML文件来描述你的DevOps工具链配置。 +## 配置内容 -## 主配置文件 +正如概述中所提到的，配置包含了以下几个部分： -默认情况下，`dtm` 会使用当前目录下的`config.yaml`来作为主配置。 +- `config` +- `vars` +- `tools` +- `apps` +- `pipelineTemplates` -主配置包含三个部分： +其中，`config` 必选，`tools` 和 `apps` 至少有一个不为空，其余部分可选。 -- `state`: 指定DevStream状态存储位置 +## 组织方式 -### 主配置文件示例 +DevStream 支持两种组织配置的方式： -`config.yaml` 的结构通常如下： +- 单文件：你可以把这些部分写到一个 YAML 文件中 +- 目录：也可以把它们分开放到同一个文件夹下的多个 YAML 文件中，只要这些文件的名字以 `.yaml` 或 `.yml` 结尾，且内容拼接后包含了 DevStream 所需的各个部分即可。 -```yaml -varFile: variables.yaml -toolFile: tools.yaml -state: - backend: local - options: - stateFile: devstream.state -``` +然后在执行 `init` 等命令时，加上 `-f` 或 `--config-file` 参数指定配置文件/目录的路径。 -### varFile +如： -变量文件是一个用`key: value`格式来定义变量的YAML文件。 +- 单文件：`dtm init -f config.yaml` +- 目录：`dtm init -f dirname` -_At the moment, nested/composite values (for example, the value is a list/dictionary) are not supported yet._ +## 主配置 -`variables.yaml` 的结构通常如下: - -```yaml -githubUsername: daniel-hutao -repoName: dtm-test-go -defaultBranch: main -dockerhubUsername: exploitht -``` +指 DevStream 本身的配置，即 `config` 部分，比如状态存储的方式等。详见 [这里](./state.zh.md) -### toolFile +## 变量语法 -插件文件是一个包含多种插件的Yaml文件。 +DevStream 提供了变量语法。使用 `vars` 用来定义变量的值，而后可以在 `tools`、`apps`、`pipelineTemplates` 中使用，语法是 `[[ varName ]]`。 -- 插件文件只包含一个`tools` -- `tools`是一个定义多个插件的列表 -- 列表中的每个对象都定义了一个由DevStream插件管理的工具 - - `name`: 是一个不带下划线的字符串，用来定义插件的名称 - - `instanceID`: 插件id - - 你可以在一个插件文件中重复定义`name`，也可以在一个插件文件中重复定义`instanceID`，但是`name + instanceID`组合在一个插件文件中必须是唯一的 -- 每个插件都有一个可选字段，即“选项”，它又是一个包含该特定插件参数的字典。关于插件的参数，请参见本文档的“插件”部分 -- 每个插件都有一个可选字段，即“dependsOn”。继续阅读有关依赖项的详细信息。 - -`tools.yaml` 的结构通常如下: +示例： ```yaml +vars: + githubUsername: daniel-hutao # 定义变量 + repoName: dtm-test-go + defaultBranch: main + tools: - name: repo-scaffolding - instanceID: golang-github + instanceID: default options: destinationRepo: - owner: [[ githubUsername ]] + owner: [[ githubUsername ]] # 使用变量 name: [[ repoName ]] branch: [[ defaultBranch ]] scmType: github - vars: - ImageRepo: "[[ dockerhubUsername ]]/[[ repoName ]]" - sourceRepo: - org: devstream-io - name: dtm-scaffolding-golang - scmType: github -- name: jira-github-integ - instanceID: default - dependsOn: [ "repo-scaffolding.golang-github" ] - options: - owner: [[ githubUsername ]] - repo: [[ repoName ]] - jiraBaseUrl: https://xxx.atlassian.net - jiraUserEmail: foo@bar.com - jiraProjectKey: zzz - branch: main -``` - -### state - -`state`用来指定DevStream状态存储的位置，v0.5.0以前，DevStream仅支持状态记录存放在本地。 - -从v0.6.0开始，我们将支持`local`和`s3`两种存储。 - -更多状态存储细节请参见[DevStream状态存储](./state.zh.md) - -## 默认值 - -默认，`dtm` 使用 `config.yaml` 来作为主配置文件 - -### 指定主配置文件 - -你可以通过`dtm -f` or `dtm --config-file`来指定主配置文件。例如： - -```shell -dtm apply -f path/to/your/config.yaml -dtm apply --config-file path/to/your/config.yaml + # <后面略...> ``` -### varFile和toolFile默认没有值 +## 工具的配置 -对于`varFile`和`toolFile`, 默认没有任何值。 +`tools` 部分声明了工具链中的工具，详见 [这里](./tools.zh.md) -如果主配置中没有指定`varFile`，`dtm`将不会使用任何var文件，即使当前目录下已经有一个名为`variables.yaml`的文件。 +## 应用与流水线模板的配置 -同样，如果主配置中没有指定`toolFile`，即使当前目录下有`tools.yaml`文件，`dtm`也会抛出错误。 +`apps` 部分声明了 应用 的配置，`pipelineTemplates` 声明了 流水线模板，详见 [这里](./apps.zh.md) diff --git a/docs/core-concepts/output.md b/docs/core-concepts/output.md index 4afed4be9..b2cadb653 100644 --- a/docs/core-concepts/output.md +++ b/docs/core-concepts/output.md @@ -2,9 +2,9 @@ ## Introduction -In DevStream's configuration file, we can use _Output_ from one _Tool_ as the options values for another _Tool_. +In DevStream's configuration file, we can use Output from one Tool as the options values for another Tool. -For example, if _Tool_ A has an output, we can use its value as _Tool_ B's options. +For example, if Tool A has an output, we can use its value as Tool B's options. Notes: @@ -31,8 +31,8 @@ tools: kanbanBoardName: golang-demo-board ``` -- TOOL_NAME is "trello" -- TOOL_INSTANCE_ID is "default" +- `TOOL_NAME` is "trello" +- `TOOL_INSTANCE_ID` is "default" If the "trello" tool/plugin has an output key name "boardId", then we can use its value by the following syntax: @@ -44,11 +44,10 @@ ${{ trello.default.outputs.boardId }} Config: -```yaml ---- +```yaml hl_lines="2 3 20 31" tools: - name: repo-scaffolding - instanceID: default + instanceID: golang-github options: destinationRepo: owner: IronCore864 @@ -80,5 +79,6 @@ tools: ``` In this example: -- The "default" instance of tool `argocdapp` depends on the "default" instance of tool `repo-scaffolding` -- The "default" instance of tool `argocdapp` has an user option "options.source.repoURL", which uses the "default" instance of tool `repo-scaffolding`'s output "repoURL" (`${{ repo-scaffolding.golang-github.outputs.repoURL }}`) + +- The "default" instance of tool `argocdapp` depends on the "golang-github" instance of tool `repo-scaffolding` +- The "default" instance of tool `argocdapp` has a user option "options.source.repoURL", which uses the "golang-github" instance of tool `repo-scaffolding`'s output "repoURL" (`${{ repo-scaffolding.golang-github.outputs.repoURL }}`) diff --git a/docs/core-concepts/output.zh.md b/docs/core-concepts/output.zh.md index a28903885..bc05e7a8f 100644 --- a/docs/core-concepts/output.zh.md +++ b/docs/core-concepts/output.zh.md @@ -1,3 +1,84 @@ -# 输出 +# 输出(Output) -todo +## 介绍 + +在 DevStream 的配置文件中，我们在配置 工具 的 Options 时，可以使用其他 工具 的 输出 来填充。 + +例如，如果 工具 A 有一个输出，我们可以将这个输出值作为 工具 B 的 Options。 + +注意： + +- 当前，若 B 使用了 A 的输出，并不意味着 B "依赖于" A +- 如果 B 确实需要 "依赖于" A，即，我们想要保证在 B 运行之前行运行 A，我们仍然需要使用 `dependsOn` 关键字（详见上一节 "[核心概念](overview.zh.md)")。 + +## 语法 + +我们可以通过以下格式来使用插件输出： + +``` +${{ TOOL_NAME.TOOL_INSTANCE_ID.outputs.OUTPUT_KEY }} +``` + +例如，对于下面给定的配置： + +```yaml +tools: +- name: trello + instanceID: default + options: + owner: IronCore864 + repo: golang-demo + kanbanBoardName: golang-demo-board +``` + +- `TOOL_NAME` 是 "trello" +- `TOOL_INSTANCE_ID` 是 "default" + +如果 "trello" 这个 工具 有一个键为 "boardId" 的输出项，那么我们就能通过以下语法来引用对应的输出的值： + +``` +${{ trello.default.outputs.boardId }} +``` + +## 例子——真实使用场景 + +配置如下： + +```yaml hl_lines="2 3 20 31" +tools: +- name: repo-scaffolding + instanceID: golang-github + options: + destinationRepo: + owner: IronCore864 + name: golang-demo + branch: main + scmType: github + vars: + imageRepo: "ironcore864/golang-demo" + sourceRepo: + org: devstream-io + name: dtm-scaffolding-golang + scmType: github +- name: helm-installer + instanceID: argocd +- name: argocdapp + instanceID: default + dependsOn: [ "helm-installer.argocd", "repo-scaffolding.golang-github" ] + options: + app: + name: golang-demo + namespace: argocd + destination: + server: https://kubernetes.default.svc + namespace: default + source: + valuefile: values.yaml + path: helm/golang-demo + repoURL: ${{ repo-scaffolding.golang-github.outputs.repoURL }} +``` + +在这个例子中， + +- `argocdapp` 的 "default" 实例依赖于 `repo-scaffolding` 的 "golang-github" 实例 +- `argocdapp` 的 "default" 实例中有一个 options 是 "options.source.repoURL"，它引用了 `repo-scaffolding` 的 "golang-github" 实例的 "repoURL" 输出(`${{ repo-scaffolding.golang-github.outputs.repoURL }}`)。 diff --git a/docs/core-concepts/overview.md b/docs/core-concepts/overview.md index 9ad092166..df2dda2f1 100644 --- a/docs/core-concepts/overview.md +++ b/docs/core-concepts/overview.md @@ -33,9 +33,9 @@ Configurations in the main config contains multiple sections: - `config`: basic configuration of DevStream, at the moment mainly state-related settings. Read more [here](./state.md). - `vars`: variable definitions. Key/value pairs, which can be referred to in the tools/apps/pipelineTemplates sections. -- `tools`: a list of DevStream _Tools_, each containing its name, instanceID (unique identifier), and options. Read more [here](./tools-apps.md). -- `apps`: a list of _Apps_, another DevStream concept, each corresponding to a microservice. Read more [here](./tools-apps.md). -- `pipelineTemplates`: a list of templates which can be referred to by DevStream _Apps_. Read more [here](./tools-apps.md). +- `tools`: a list of DevStream _Tools_, each containing its name, instanceID (unique identifier), and options. Read more [here](./tools.md). +- `apps`: a list of _Apps_, another DevStream concept, each corresponding to a microservice. Read more [here](./apps.md). +- `pipelineTemplates`: a list of templates which can be referred to by DevStream _Apps_. Read more [here](./apps.md). --- diff --git a/docs/core-concepts/overview.zh.md b/docs/core-concepts/overview.zh.md index a9f2b020b..db31de669 100644 --- a/docs/core-concepts/overview.zh.md +++ b/docs/core-concepts/overview.zh.md @@ -1,63 +1,50 @@ # 概览 -您需要熟知以下概念：Git 核心概念，Docker, Kubernetes, 持续集成，持续交付以及 GitOps概念. 这些都是 DevStream 的核心概念。 +## 1 构架 -## DevStream的构架 - -以下构架图展示了 DevStream 大致的流程： ![](../images/architecture-overview.png) -## 工作流程 - -![config state resource-status workflow](../images/config_state_resource.png) - -## 配置，工具，状态和资源状态 - -构架文档阐述了 DevStream 的基本工作原理。请确保你在阅读文档其他部分之前完成此部分的阅读。 +上面的图展示了数据如何在 dtm 的各个模块中流动。 -### 1. 配置(Config) +本质上： -DevStream 在配置文件中定义了 DevOps 工具链。 +- DevStream 的核心(插件引擎)就像一个状态机，它根据配置和状态计算出需要执行的操作。 +- 接着 DevStream 核心调用“插件”来完成特定 DevOps 工具或它们之间的集成的 CRUD 操作。 -有三种配置文件： +--- -- 主配置文件(core config) -- 变量配置文件(variable config) -- 工具配置文件(tool config) +## 2 插件(Plugin) -主配置文件包含了以下内容： +插件 是 DevStream 的核心，由 dtm 负责下载、管理和调用。 -- `varFile`: 变量配置文件的路径 -- `toolFile`: 工具文件的路径 -- `pluginDir`: 插件目录的路径，默认为 `~/.devstream/plugins`, 或使用 `-d` 参数指定一个目录 -- `state`: 与 State 关联的设置。更多信息，请看[这里](./state.zh.md) +每个插件拥有一定的功能，涵盖了 DevOps 工具的安装、配置和集成，用户通过自由组合插件来构建自己的 DevOps 工具链。 -变量配置文件是一个包含了键值对的YAML文件，可以用于工具配置文件。 +开发者可以通过编写插件来扩展 DevStream，详见 [创建插件](../development/dev/creating-a-plugin.zh.md)。 -工具配置文件是一个名为 _Tools_ 的列表，其中每一个 _Tool_ 都包含了名称，实例ID（唯一标识）以及工具的选项(options)。 +--- -_注意: 你可以将多个YAML文件合并为同一个并用三个短横线(`---`)区分。更多信息见 [这里](https://stackoverflow.com/questions/50788277/why-3-dashes-hyphen-in-yaml-file) 和 [这里](https://www.javatpoint.com/yaml-structure)_。 +## 3 配置(Config) -### 2. 工具(Tool) +DevStream 在配置文件中定义了 DevOps 平台的期望状态（如插件列表、DevStream 自身的配置等）。 -- 每个 _Tool_ 对应一个插件, 即可用于安装和配置，也可用于整合 DevOps 的工具。 -- 每个 _Tool_ 有名称, (实例ID)InstanceID 和选项(Options), 定义在[这里](https://github.com/devstream-io/devstream/blob/main/internal/pkg/configmanager/toolconfig.go#L13)。 -- 每个 _Tool_ 可以使用`dependsOn` 字段指定其依赖项。 +配置文件可以是单个 YAML 文件，也可以是同个目录下的多个 YAML 文件，拥有以下几个部分： - `dependsOn` 是一个字符串数组, 其中每一个元素都是一个依赖。 每个依赖项都以 "TOOL_NAME.INSTANCE_ID" 为格式命名。 -例子见[这里](https://github.com/devstream-io/devstream/blob/main/examples/quickstart.yaml#L22)。 +- `config`: DevStream 的基本配置，目前主要是与 状态 相关的设置。更多信息请参考 [这里](./state.zh.md)。 +- `vars`: 变量的定义。键值对的形式，可以在 tools/apps/pipelineTemplates 部分中引用。 +- `tools`: DevStream 工具 的列表，每个工具包含插件名称、实例 ID(唯一标识符)和 Options。更多信息请参考 [这里](./tools.zh.md)。 +- `apps`: DevStream 应用 的列表，每个应用对应一个微服务。更多信息请参考 [这里](./apps.zh.md)。 +- `pipelineTemplates`: 一个流水线模板的列表，可以被 DevStream 应用 引用。更多信息请参考 [这里](./apps.zh.md)。 -### 3. 状态(State) +--- -_State_ 记录了当前 DevOps 工具链的状态，包括了每个工具的配置以及当下状态。 +## 4 状态(State) -- _State_ 实际上是一个记录了状态的 Map, 定义在[这里](https://github.com/devstream-io/devstream/blob/main/internal/pkg/statemanager/state.go#L24)。 -- Map 中的每一个状态都是一个包含了名称、插件、选项和资源的结构体，定义在[这里](https://github.com/devstream-io/devstream/blob/main/internal/pkg/statemanager/state.go#L16)。 +状态 记录了 DevStream 定义和创建的 DevOps 工具链和平台的当前状态。 -### 4. 资源状态(ResourceStatus) +状态 包含了所有组件的配置和它们对应的状态，这样 DevStream 核心模块就可以依靠它计算出，达到配置中定义的状态所需要的操作。 -- 我们称插件创建了 _资源(Resource)_，而插件的 `Read()` 接口返回了此资源的描述，该描述也作为资源的状态（State）的一部分保存。 +--- -配置-状态-资源状态 工作流： +## 5 工作流 -![config state resource-status workflow](../images/config_state_resource.png) +![配置-状态-资源状态 工作流](../images/config_state_resource.png) diff --git a/docs/core-concepts/state.zh.md b/docs/core-concepts/state.zh.md index ee6a08933..fb55163ac 100644 --- a/docs/core-concepts/state.zh.md +++ b/docs/core-concepts/state.zh.md @@ -1,3 +1,52 @@ -# 主配置文件中的状态 +# 状态(State) -todo +## 1 概念 + +状态记录了 DevStream 定义和创建的 DevOps 工具链和平台的当前状态。 + +状态包含了所有组件的配置和它们对应的状态，这样 DevStream 核心模块就可以依靠它计算出，达到配置中定义的状态所需要的操作。 + +我们可以在配置中指定使用哪种 `backend` 来存储状态，目前支持的 `backend` 有： + +- local +- k8s +- s3 + +## 2 配置方式 + +配置中的 `config.state` 部分指定了如何存储 DevStream 状态。 + +### 2.1 本地文件 + +```yaml +config: + state: + backend: local + options: + stateFile: devstream.state # 可选，默认为 devstream.state +``` + +### 2.2 Kubernetes + +```yaml +config: + state: + backend: k8s + options: + namespace: devstream # 可选, 默认是 "devstream", 不存在则自动创建 + configmap: state # 可选, 默认是 "state", 不存在则自动创建 +``` + +### 2.3 S3 + +```yaml +config: + state: + backend: s3 + options: + bucket: devstream-remote-state + region: ap-southeast-1 + key: devstream.state +``` + +_注意：`options` 下的 `bucket`、`region` 和 `key` 是 s3 后端的必填字段。_ diff --git a/docs/core-concepts/tools-apps.zh.md b/docs/core-concepts/tools-apps.zh.md deleted file mode 100644 index 71f40d036..000000000 --- a/docs/core-concepts/tools-apps.zh.md +++ /dev/null @@ -1,3 +0,0 @@ -# Tools and Apps 中文 - -TODO diff --git a/docs/core-concepts/tools-apps.md b/docs/core-concepts/tools.md similarity index 100% rename from docs/core-concepts/tools-apps.md rename to docs/core-concepts/tools.md diff --git a/docs/core-concepts/tools.zh.md b/docs/core-concepts/tools.zh.md new file mode 100644 index 000000000..de6ef0b25 --- /dev/null +++ b/docs/core-concepts/tools.zh.md @@ -0,0 +1,56 @@ +# 工具(Tools) + +## 1 概览 + +DevStream 视一切为 "工具"： + +- 每个 工具 对应一个 DevStream 插件，它可以安装、配置或集成一些 DevOps 工具。 +- 每个 工具 都有它的名称（对应插件名称）、实例 ID 和选项(Options)。 +- 每个 工具 都可以依赖其他的工具，通过 `dependsOn` 关键字指定。 + +依赖 `dependsOn` 是一个字符串数组，每个元素都是一个依赖项，格式是 "工具名.实例ID"。 + +## 2 配置方式 + +DevStream 通过在配置中定义 `tools` 来声明所需的工具集合： + +- `tools` 是一个定义多个 工具 的列表 +- 列表中的每个对象都定义了一个由 DevStream 插件管理的工具 + - `name`: 是一个不带下划线的字符串，用来定义插件的名称 + - `instanceID`: 实例的 ID，唯一标识一个工具实例 + - `name` 和 `instanceID` 可以分别重复，但是 `name + instanceID` 的组合必须唯一 +- 每个插件都有一个可选字段，"选项"(`options`)，每个插件的选项都是不同的，详情请参考[插件列表](../plugins/plugins-list.md)。 +- 每个插件都有一个可选字段，"依赖项"(`dependsOn`)，定义了该插件依赖的其他插件列表。如果 A 依赖了 B 和 C，那么 dtm 会在 B 和 C 插件执行成功后再执行 A 插件。 + +`tools` 的配置示例如下： + +```yaml +tools: +- name: repo-scaffolding + instanceID: golang-github + options: + destinationRepo: + owner: [[ githubUsername ]] + name: [[ repoName ]] + branch: [[ defaultBranch ]] + scmType: github + vars: + ImageRepo: "[[ dockerhubUsername ]]/[[ repoName ]]" + sourceRepo: + org: devstream-io + name: dtm-scaffolding-golang + scmType: github +- name: jira-github-integ + instanceID: default + dependsOn: [ "repo-scaffolding.golang-github" ] + options: + owner: [[ githubUsername ]] + repo: [[ repoName ]] + jiraBaseUrl: https://xxx.atlassian.net + jiraUserEmail: foo@bar.com + jiraProjectKey: zzz + branch: main +``` + +其中，[[ githubUsername ]]、[[ repoName ]] 等是全局变量，它们的值可以在 `vars` 字段中定义。 + diff --git a/docs/development/docs-contribution/mkdocs.zh.md b/docs/development/docs-contribution/mkdocs.zh.md index b5303256c..0b448be3d 100644 --- a/docs/development/docs-contribution/mkdocs.zh.md +++ b/docs/development/docs-contribution/mkdocs.zh.md @@ -31,6 +31,7 @@ ## i18n（国际化） 目前，我们支持两种语言： + - 英文 - 简体中文 diff --git a/docs/includes/glossary.md b/docs/includes/glossary.md new file mode 100644 index 000000000..24ef22076 --- /dev/null +++ b/docs/includes/glossary.md @@ -0,0 +1,19 @@ +*[dtm]: Short for Devstream （Devstream 简称 dtm） +*[Config]: TODO(introduce of config) +*[配置]: 由一个或一组 YAML 文件组成，定义了 DevStream 需要的所有信息 +*[Plugin]: TODO(introduce of plugin) +*[Plugins]: TODO(introduce of plugin) +*[插件]: TODO(插件的介绍) +*[Tool]: Each Tool corresponds to a DevStream plugin, which can either install, configure, or integrate some DevOps tools +*[Tools]: Each Tool corresponds to a DevStream plugin, which can either install, configure, or integrate some DevOps tools +*[工具]: 每个工具(Tool)对应了一个 DevStream 插件，它可以安装、配置或集成一些 DevOps 工具 +*[App]: TODO(introduce of app) +*[Apps]: TODO(introduce of app) +*[应用]: TODO(应用的介绍) +*[PipelineTemplate]: TODO(introduce of pipelineTemplate) +*[PipelineTemplates]: TODO(introduce of pipelineTemplate) +*[流水线模板]: TODO(流水线模板的介绍) +*[Output]: TODO(introduce of output) +*[输出]: 每个工具(Tool)可能会有些输出，这是一个 map，可以在配置其他工具时引用 +*[State]: State records the current status of your DevOps toolchain and platform defined and created by DevStream. +*[状态]: 记录了当前 DevOps 工具链的状态，包括每个工具的配置以及当下状态。 diff --git a/docs/install.md b/docs/install.md index 0502b479b..ff8ec279b 100644 --- a/docs/install.md +++ b/docs/install.md @@ -11,14 +11,14 @@ In your working directory, run: ```shell -sh -c "$(curl -fsSL https://download.devstream.io/download.sh) +sh -c "$(curl -fsSL https://download.devstream.io/download.sh)" ``` This will download the corresponding `dtm` binary to your working directory according to your OS and chip architecture, and grant the binary execution permission. > Optional: you can then move `dtm` to a place which is in your PATH. For example: `mv dtm /usr/local/bin/`. -## 2 Install with [asdf](https://asdf-vm.com/) +## 2 Install dtm with [asdf](https://asdf-vm.com/) ```shell # Plugin @@ -30,10 +30,10 @@ asdf install dtm latest # Set a version globally (on your ~/.tool-versions file) asdf global dtm latest # Now dtm commands are available -dtm --help +dtm help ``` -## 3 Download manually from the Release page +## 3 Download manually from the GitHub Release page You could find the latest version of `dtm` on the [Release](https://github.com/devstream-io/devstream/releases/) page and click Download. Note that there are multiple versions of `dtm` available, so you will need to choose the correct version for your operating system and chip architecture. Once downloaded locally, you can choose to rename it, move it to the directory containing `$PATH` and give it executable permissions, for example, on Linux you can do this by running the following command. diff --git a/docs/install.zh.md b/docs/install.zh.md index a8320a06a..2bfd8970f 100644 --- a/docs/install.zh.md +++ b/docs/install.zh.md @@ -11,7 +11,7 @@ 进入你的工作目录，运行： ```shell -sh -c "$(curl -fsSL https://download.devstream.io/download.sh) +sh -c "$(curl -fsSL https://download.devstream.io/download.sh)" ``` 这个命令会根据你的操作系统和芯片架构下载对应的 `dtm` 二进制文件到你的工作目录中，并赋予二进制文件执行权限。 @@ -21,19 +21,19 @@ sh -c "$(curl -fsSL https://download.devstream.io/download.sh) ## 2 用 [asdf](https://asdf-vm.com/) 安装 ```shell -# Plugin +# 安装 dtm 插件 asdf plugin add dtm -# Show all installable versions +# 列出所有可用版本 asdf list-all dtm -# Install specific version +# 安装特定版本 asdf install dtm latest -# Set a version globally (on your ~/.tool-versions file) +# 设置全局版本 (在 ~/.tool-versions 文件中) asdf global dtm latest -# Now dtm commands are available -dtm --help +# 现在你就能使用 dtm 了 +dtm help ``` -## 3 从 Release 页面手动下载 +## 3 从 GitHub Release 页面手动下载 在 [Release](https://github.com/devstream-io/devstream/releases/) 页面找到当前最新版本 `dtm`，然后点击下载。 需要注意的是当前 `dtm` 提供了多个版本，你需要根据操作系统和芯片架构选择自己需要的正确版本。下载到本地后，你可以选择将其重命名，移入包含在"$PATH"的目录里并赋予其可执行权限，比如在 Linux 上你可以执行如下命令完成这些操作： diff --git a/mkdocs.yml b/mkdocs.yml index 002d9f9dd..3b630e82c 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -23,12 +23,15 @@ repo_name: devstream repo_url: https://github.com/devstream-io/devstream site_description: The DevStream Docs markdown_extensions: +- abbr - toc: permalink: true - pymdownx.snippets: base_path: - "docs" - "docs/../internal/pkg/show/config/plugins/" + auto_append: + - includes/glossary.md - pymdownx.highlight: anchor_linenums: true auto_title: true @@ -102,7 +105,8 @@ nav: - install*.md - Core Concepts: - core-concepts/overview*.md - - core-concepts/tools-apps*.md + - core-concepts/tools*.md + - core-concepts/apps*.md - core-concepts/state*.md - core-concepts/config*.md - core-concepts/output*.md