Skip to content

Commit 9ceab91

Browse files
aFlyBird0aFlyBird0
committed
docs: refactor config and output
Signed-off-by: Bird <aflybird0@gmail.com>
1 parent 61fdeea commit 9ceab91

8 files changed

Lines changed: 210 additions & 190 deletions

File tree

‎.lycheeignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@ https://fonts.gstatic.com/
88
.*xxx.*
99
.*changeme.*
1010
.*example.*
11+
.*test.*
1112
.*YOUR_.*
1213
https://id.atlassian.net
1314
https://JIRA_ID.atlassian.net

‎docs/best-practices/gitops.zh.md‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,5 @@
11
# GitOps
22

3-
<span id="0-目标"></span>
43
## 0 目标
54
在本教程中，我们将尝试通过 DevStream 来实现以下目标：
65

@@ -38,7 +37,7 @@
3837

3938
## 2 概览
4039

41-
DevStream 将使用下面的插件来实现[第 0 节](#0-目标)中描述的目标：
40+
DevStream 将使用下面的插件来实现[第 0 节](#)中描述的目标：
4241

4342
1. [repo-scaffolding](../plugins/repo-scaffolding.md)
4443
2. [github-actions](../plugins/github-actions.md)

‎docs/core-concepts/config.md‎

Lines changed: 104 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -2,19 +2,19 @@
22

33
DevStream uses YAML files to define your DevOps platform.
44

5-
## Sections
5+
## 1 Sections Overview
66

77
As aforementioned in the overview, there are several sections in the config:
88

99
- `config`
10-
- `vars`
1110
- `tools`
1211
- `apps`
1312
- `pipelineTemplates`
13+
- `vars`
1414

1515
Among which, `config` is mandatory, and you should have at least either `tools` or `apps`. Others are optional.
1616

17-
## Config File V.S. Config Folder
17+
## 2 Config File V.S. Config Folder
1818

1919
DevStream supports both:
2020

@@ -28,11 +28,22 @@ Examples:
2828
- single file: `dtm init -f config.yaml`
2929
- directory: `dtm init -f dirname`
3030

31-
## The Main Config
31+
## 3 Sections Detail
32+
33+
### 3.1 The Main Config
3234

3335
DevStream's own config, the `config` section, contains where to store the state. See [here](./state.md) for more details.
3436

35-
## Variables
37+
38+
### 3.2 Tools Config
39+
40+
The `tools` section defines DevOps tools. Read [this](./tools.md) for all the detail.
41+
42+
### 3.3 Apps/pipelineTemplates Config
43+
44+
The `apps` section defines Apps and the `pipelineTemplates` defines templates for pipelines. See [here](./apps.md) for more detail.
45+
46+
### 3.4 Variables
3647

3748
DevStream supports variables. Define key/values in the `vars` section and refer to it in the `tools`, `apps` and `pipelineTemplates` sections.
3849

@@ -58,10 +69,94 @@ tools:
5869
# ...
5970
```
6071

61-
## Tools Config
72+
## 4 Expanded Features
6273

63-
The `tools` section defines DevOps tools. Read [this](./tools.md) for all the detail.
74+
### 4.1 Environment Variables
6475

65-
## Apps/pipelineTemplates Config
76+
Similar to "variables", you can use `[[env "env_key"]]` to refer to environment variables.
77+
78+
### 4.2 Output
79+
80+
#### Introduction
81+
82+
In DevStream's configuration file, we can use Output from one Tool as the options values for another Tool.
83+
84+
For example, if Tool A has an output, we can use its value as Tool B's options.
85+
86+
Notes:
87+
88+
- At the moment, B using A's output doesn't mean B "depends on" A.
89+
- 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.)
90+
91+
#### Syntax
92+
93+
To use the output, follow this format:
94+
95+
```
96+
${{ TOOL_NAME.TOOL_INSTANCE_ID.outputs.OUTPUT_KEY }}
97+
```
98+
99+
For example, given config:
100+
101+
```yaml
102+
tools:
103+
- name: trello
104+
instanceID: default
105+
options:
106+
owner: IronCore864
107+
repo: golang-demo
108+
kanbanBoardName: golang-demo-board
109+
```
110+
111+
- `TOOL_NAME` is "trello"
112+
- `TOOL_INSTANCE_ID` is "default"
113+
114+
If the "trello" tool/plugin has an output key name "boardId", then we can use its value by the following syntax:
115+
116+
```
117+
${{ trello.default.outputs.boardId }}
118+
```
119+
120+
#### Real-World Usage Example
121+
122+
Config:
123+
124+
```yaml hl_lines="2 3 20 31"
125+
tools:
126+
- name: repo-scaffolding
127+
instanceID: golang-github
128+
options:
129+
destinationRepo:
130+
owner: IronCore864
131+
name: golang-demo
132+
branch: main
133+
scmType: github
134+
vars:
135+
imageRepo: "ironcore864/golang-demo"
136+
sourceRepo:
137+
org: devstream-io
138+
name: dtm-scaffolding-golang
139+
scmType: github
140+
- name: helm-installer
141+
instanceID: argocd
142+
- name: argocdapp
143+
instanceID: default
144+
dependsOn: [ "helm-installer.argocd", "repo-scaffolding.golang-github" ]
145+
options:
146+
app:
147+
name: golang-demo
148+
namespace: argocd
149+
destination:
150+
server: https://kubernetes.default.svc
151+
namespace: default
152+
source:
153+
valuefile: values.yaml
154+
path: helm/golang-demo
155+
repoURL: ${{ repo-scaffolding.golang-github.outputs.repoURL }} # pay attention here
156+
```
157+
158+
In this example:
159+
160+
- The "default" instance of tool `argocdapp` depends on the "golang-github" instance of tool `repo-scaffolding`
161+
- 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 }}`)
66162

67-
The `apps` section defines Apps and the `pipelineTemplates` defines templates for pipelines. See [here](./apps.md) for more detail.

‎docs/core-concepts/config.zh.md‎

Lines changed: 103 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -2,19 +2,19 @@
22

33
DevStream使用 YAML 文件来声明 DevOps 工具链的配置。
44

5-
## 配置内容
5+
## 1 配置内容概览
66

77
正如概述中所提到的，配置包含了以下几个部分：
88

99
- `config`
10-
- `vars`
1110
- `tools`
1211
- `apps`
1312
- `pipelineTemplates`
13+
- `vars`
1414

1515
其中，`config` 必选，`tools` 和 `apps` 至少有一个不为空，其余部分可选。
1616

17-
## 组织方式
17+
## 2 组织方式
1818

1919
DevStream 支持两种组织配置的方式：
2020

@@ -28,11 +28,21 @@ DevStream 支持两种组织配置的方式：
2828
- 单文件：`dtm init -f config.yaml`
2929
- 目录：`dtm init -f dirname`
3030

31-
## 主配置
31+
## 3 配置内容详解
32+
33+
### 3.1 主配置
3234

3335
指 DevStream 本身的配置，即 `config` 部分，比如状态存储的方式等。详见 [这里](./state.zh.md)
3436

35-
## 变量语法
37+
### 3.2 工具的配置
38+
39+
`tools` 部分声明了工具链中的工具，详见 [这里](./tools.zh.md)
40+
41+
### 3.2 应用与流水线模板的配置
42+
43+
`apps` 部分声明了 应用 的配置，`pipelineTemplates` 声明了 流水线模板，详见 [这里](./apps.zh.md)
44+
45+
### 3.3 变量
3646

3747
DevStream 提供了变量语法。使用 `vars` 用来定义变量的值，而后可以在 `tools`、`apps`、`pipelineTemplates` 中使用，语法是 `[[ varName ]]`。
3848

@@ -56,10 +66,94 @@ tools:
5666
# <后面略...>
5767
```
5868

59-
## 工具的配置
69+
## 4 拓展语法
6070

61-
`tools` 部分声明了工具链中的工具，详见 [这里](./tools.zh.md)
71+
### 4.1 环境变量
6272

63-
## 应用与流水线模板的配置
73+
类似于"变量"，你可以使用 `[[env "env_key"]]` 的方式来引用环境变量。
74+
75+
### 4.2 输出(Output)
76+
77+
#### 介绍
78+
79+
在 DevStream 的配置文件中，我们在配置 工具 的 Options 时，可以使用其他 工具 的 输出 来填充。
80+
81+
例如，如果 工具 A 有一个输出，我们可以将这个输出值作为 工具 B 的 Options。
82+
83+
注意：
84+
85+
- 当前，若 B 使用了 A 的输出，并不意味着 B "依赖于" A
86+
- 如果 B 确实需要 "依赖于" A，即，我们想要保证在 B 运行之前行运行 A，我们仍然需要使用 `dependsOn` 关键字（详见上一节 "[核心概念](overview.zh.md)")。
87+
88+
#### 语法
89+
90+
我们可以通过以下格式来使用插件输出：
91+
92+
```
93+
${{ TOOL_NAME.TOOL_INSTANCE_ID.outputs.OUTPUT_KEY }}
94+
```
95+
96+
例如，对于下面给定的配置：
97+
98+
```yaml
99+
tools:
100+
- name: trello
101+
instanceID: default
102+
options:
103+
owner: IronCore864
104+
repo: golang-demo
105+
kanbanBoardName: golang-demo-board
106+
```
107+
108+
- `TOOL_NAME` 是 "trello"
109+
- `TOOL_INSTANCE_ID` 是 "default"
110+
111+
如果 "trello" 这个 工具 有一个键为 "boardId" 的输出项，那么我们就能通过以下语法来引用对应的输出的值：
112+
113+
```
114+
${{ trello.default.outputs.boardId }}
115+
```
116+
117+
#### 例子——真实使用场景
118+
119+
配置如下：
120+
121+
```yaml hl_lines="2 3 20 31"
122+
tools:
123+
- name: repo-scaffolding
124+
instanceID: golang-github
125+
options:
126+
destinationRepo:
127+
owner: IronCore864
128+
name: golang-demo
129+
branch: main
130+
scmType: github
131+
vars:
132+
imageRepo: "ironcore864/golang-demo"
133+
sourceRepo:
134+
org: devstream-io
135+
name: dtm-scaffolding-golang
136+
scmType: github
137+
- name: helm-installer
138+
instanceID: argocd
139+
- name: argocdapp
140+
instanceID: default
141+
dependsOn: [ "helm-installer.argocd", "repo-scaffolding.golang-github" ]
142+
options:
143+
app:
144+
name: golang-demo
145+
namespace: argocd
146+
destination:
147+
server: https://kubernetes.default.svc
148+
namespace: default
149+
source:
150+
valuefile: values.yaml
151+
path: helm/golang-demo
152+
repoURL: ${{ repo-scaffolding.golang-github.outputs.repoURL }}
153+
```
154+
155+
在这个例子中，
156+
157+
- `argocdapp` 的 "default" 实例依赖于 `repo-scaffolding` 的 "golang-github" 实例
158+
- `argocdapp` 的 "default" 实例中有一个 options 是 "options.source.repoURL"，它引用了 `repo-scaffolding` 的 "golang-github" 实例的 "repoURL" 输出(`${{ repo-scaffolding.golang-github.outputs.repoURL }}`)。
64159

65-
`apps` 部分声明了 应用 的配置，`pipelineTemplates` 声明了 流水线模板，详见 [这里](./apps.zh.md)

0 commit comments

Comments
 (0)