diff --git a/.lycheeignore b/.lycheeignore index 3a74192d4..e62ffe5bd 100644 --- a/.lycheeignore +++ b/.lycheeignore @@ -8,6 +8,7 @@ https://fonts.gstatic.com/ .*xxx.* .*changeme.* .*example.* +.*test.* .*YOUR_.* https://id.atlassian.net https://JIRA_ID.atlassian.net diff --git a/docs/best-practices/gitops.zh.md b/docs/best-practices/gitops.zh.md index 6ff113045..a6582780e 100644 --- a/docs/best-practices/gitops.zh.md +++ b/docs/best-practices/gitops.zh.md @@ -1,6 +1,5 @@ # GitOps - ## 0 目标 在本教程中，我们将尝试通过 DevStream 来实现以下目标： @@ -38,7 +37,7 @@ ## 2 概览 -DevStream 将使用下面的插件来实现[第 0 节](#0-目标)中描述的目标： +DevStream 将使用下面的插件来实现[第 0 节](#)中描述的目标： 1. [repo-scaffolding](../plugins/repo-scaffolding.md) 2. [github-actions](../plugins/github-actions.md) diff --git a/docs/core-concepts/config.md b/docs/core-concepts/config.md index 2f4b78668..0f1b85408 100644 --- a/docs/core-concepts/config.md +++ b/docs/core-concepts/config.md @@ -2,19 +2,19 @@ DevStream uses YAML files to define your DevOps platform. -## Sections +## 1 Sections Overview As aforementioned in the overview, there are several sections in the config: - `config` -- `vars` - `tools` - `apps` - `pipelineTemplates` +- `vars` Among which, `config` is mandatory, and you should have at least either `tools` or `apps`. Others are optional. -## Config File V.S. Config Folder +## 2 Config File V.S. Config Folder DevStream supports both: @@ -28,11 +28,22 @@ Examples: - single file: `dtm init -f config.yaml` - directory: `dtm init -f dirname` -## The Main Config +## 3 Sections Detail + +### 3.1 The Main Config DevStream's own config, the `config` section, contains where to store the state. See [here](./state.md) for more details. -## Variables + +### 3.2 Tools Config + +The `tools` section defines DevOps tools. Read [this](./tools.md) for all the detail. + +### 3.3 Apps/pipelineTemplates Config + +The `apps` section defines Apps and the `pipelineTemplates` defines templates for pipelines. See [here](./apps.md) for more detail. + +### 3.4 Variables DevStream supports variables. Define key/values in the `vars` section and refer to it in the `tools`, `apps` and `pipelineTemplates` sections. @@ -58,10 +69,94 @@ tools: # ... ``` -## Tools Config +## 4 Expanded Features -The `tools` section defines DevOps tools. Read [this](./tools.md) for all the detail. +### 4.1 Environment Variables -## Apps/pipelineTemplates Config +Similar to "variables", you can use `[[env "env_key"]]` to refer to environment variables. + +### 4.2 Output + +#### Introduction + +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. + +Notes: + +- At the moment, B using A's output doesn't mean B "depends on" A. +- If B needs to "depend on" A, i.e., we want to make sure A runs first before B runs, we still need to use the `dependsOn` keyword (see the previous section "[Core Concepts](overview.md)" for more details.) + +#### Syntax + +To use the output, follow this format: + +``` +${{ TOOL_NAME.TOOL_INSTANCE_ID.outputs.OUTPUT_KEY }} +``` + +For example, given config: + +```yaml +tools: +- name: trello + instanceID: default + options: + owner: IronCore864 + repo: golang-demo + kanbanBoardName: golang-demo-board +``` + +- `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: + +``` +${{ trello.default.outputs.boardId }} +``` + +#### Real-World Usage Example + +Config: + +```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 }} # pay attention here +``` + +In this example: + +- 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 }}`) -The `apps` section defines Apps and the `pipelineTemplates` defines templates for pipelines. See [here](./apps.md) for more detail. diff --git a/docs/core-concepts/config.zh.md b/docs/core-concepts/config.zh.md index 3e14ccbf9..ca243a2fc 100644 --- a/docs/core-concepts/config.zh.md +++ b/docs/core-concepts/config.zh.md @@ -2,19 +2,19 @@ DevStream使用 YAML 文件来声明 DevOps 工具链的配置。 -## 配置内容 +## 1 配置内容概览 正如概述中所提到的，配置包含了以下几个部分： - `config` -- `vars` - `tools` - `apps` - `pipelineTemplates` +- `vars` 其中，`config` 必选，`tools` 和 `apps` 至少有一个不为空，其余部分可选。 -## 组织方式 +## 2 组织方式 DevStream 支持两种组织配置的方式： @@ -28,11 +28,21 @@ DevStream 支持两种组织配置的方式： - 单文件：`dtm init -f config.yaml` - 目录：`dtm init -f dirname` -## 主配置 +## 3 配置内容详解 + +### 3.1 主配置 指 DevStream 本身的配置，即 `config` 部分，比如状态存储的方式等。详见 [这里](./state.zh.md) -## 变量语法 +### 3.2 工具的配置 + +`tools` 部分声明了工具链中的工具，详见 [这里](./tools.zh.md) + +### 3.2 应用与流水线模板的配置 + +`apps` 部分声明了 应用 的配置，`pipelineTemplates` 声明了 流水线模板，详见 [这里](./apps.zh.md) + +### 3.3 变量 DevStream 提供了变量语法。使用 `vars` 用来定义变量的值，而后可以在 `tools`、`apps`、`pipelineTemplates` 中使用，语法是 `[[ varName ]]`。 @@ -56,10 +66,94 @@ tools: # <后面略...> ``` -## 工具的配置 +## 4 拓展语法 -`tools` 部分声明了工具链中的工具，详见 [这里](./tools.zh.md) +### 4.1 环境变量 -## 应用与流水线模板的配置 +类似于"变量"，你可以使用 `[[env "env_key"]]` 的方式来引用环境变量。 + +### 4.2 输出(Output) + +#### 介绍 + +在 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 }}`)。 -`apps` 部分声明了 应用 的配置，`pipelineTemplates` 声明了 流水线模板，详见 [这里](./apps.zh.md) diff --git a/docs/core-concepts/output.md b/docs/core-concepts/output.md deleted file mode 100644 index b2cadb653..000000000 --- a/docs/core-concepts/output.md +++ /dev/null @@ -1,84 +0,0 @@ -# Output - -## Introduction - -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. - -Notes: - -- At the moment, B using A's output doesn't mean B "depends on" A. -- If B needs to "depend on" A, i.e., we want to make sure A runs first before B runs, we still need to use the `dependsOn` keyword (see the previous section "[Core Concepts](overview.md)" for more details.) - -## Syntax - -To use the output, follow this format: - -``` -${{ TOOL_NAME.TOOL_INSTANCE_ID.outputs.OUTPUT_KEY }} -``` - -For example, given config: - -```yaml -tools: -- name: trello - instanceID: default - options: - owner: IronCore864 - repo: golang-demo - kanbanBoardName: golang-demo-board -``` - -- `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: - -``` -${{ trello.default.outputs.boardId }} -``` - -## Real-World Usage Example - -Config: - -```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 }} # pay attention here -``` - -In this example: - -- 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 deleted file mode 100644 index bc05e7a8f..000000000 --- a/docs/core-concepts/output.zh.md +++ /dev/null @@ -1,84 +0,0 @@ -# 输出(Output) - -## 介绍 - -在 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/plugins/helm-installer/jenkins.zh.md b/docs/plugins/helm-installer/jenkins.zh.md index c716a1aef..2fe0faf52 100644 --- a/docs/plugins/helm-installer/jenkins.zh.md +++ b/docs/plugins/helm-installer/jenkins.zh.md @@ -303,7 +303,7 @@ workflows: | 在上一小节我们看到了 jenkins 插件的状态中保存了一个 outputs 字段，内容是 `jenkins_url: http://jenkins.jenkins:8080`， 所以其他插件的配置中可以通过`${{jenkins.default.outputs.jenkins_url}}` 的语法读取到 `http://jenkins.jenkins:8080`。 -更多关于"插件输出"的内容，请阅读[这个文档](../../core-concepts/output.zh.md)。 +更多关于"插件输出"的内容，请阅读[这个文档](../../core-concepts/config.zh.md#42-output)。 ## 5、离线环境部署 diff --git a/mkdocs.yml b/mkdocs.yml index d2837eb1f..df2918b49 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -109,7 +109,6 @@ nav: - core-concepts/apps*.md - core-concepts/state*.md - core-concepts/config*.md - - core-concepts/output*.md - Commands: - commands/autocomplete*.md - commands/*.md