Skip to content

Commit 427cb4e

Browse files
IronCore864steinliber
IronCore864
authored and
steinliber
committed
docs: udpate core concepts according to chinese update
Signed-off-by: Tiexin Guo <[email protected]>
1 parent ac94df2 commit 427cb4e

File tree

7 files changed

+415
-284
lines changed

7 files changed

+415
-284
lines changed

‎docs/core-concepts/apps.md‎

Lines changed: 276 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1 +1,277 @@
11
# Apps
2+
3+
## 1 Concept
4+
5+
An app in DevStream corresponds to a real-world application, and the app represents the whole software development lifecycle of that app, including source code management, code scaffolding, CI/CD (and their pipelines).
6+
7+
Using "App", you can easily create these for an application.
8+
9+
### 1.1 Apps
10+
11+
There are situations where you need to define multiple DevOps tools for an application/microservice. For example, for a web-app typed microservice, you might need the following:
12+
13+
- source code management, code repo scaffolding
14+
- continuous integration (the installation of the DevOps tool, the creation of the CI pipeline)
15+
- continuous deployment (the installation of the DevOps tool, the creation of the CD pipeline)
16+
17+
If you are managing more than one application/microservice (chances are, you will be managing more than one application in the real world), the configuration of DevStream can be quite long, hard to read and hard to manage if you are only using "Tools".
18+
19+
In order to solve this problem, DevStream provides another concept that is "App". You can easily define all DevOps tools and pipelines for an App with a couple of lines of YAML config, making the config file much easier to read and manage.
20+
21+
In essence, "App" will be converted to "Tool", which you do not have to worry about at all; let DevStream handle that.
22+
23+
## 1.2 pipelineTemplates
24+
25+
pipelineTemplates define CI/CD pipelines, so that they can be referred to and shared by different DevStream Apps, reducing the length of the config file to the next level.
26+
27+
## 2 Config
28+
29+
### 2.1 App
30+
31+
In the config, there is a `apps` section, which is a list, with each element having the following keys:
32+
33+
- name: the name of the app, unique
34+
- spec: application-specific information
35+
- repo: info about the code repository
36+
- repoTemplate: optional, same structure as "repo". If empty, DevStream will create/scaffold a repository from scratch.
37+
- ci: optional, a list of CI pipelines, each element can have the following keys:
38+
- type: the value can be a `template` or the name of a plugin
39+
- templateName: optional, if type is `template`, it defines which pipelineTemplate to use
40+
- vars: optional, variables to be passed to the template. Only works when type is `template`, apparently
41+
- options: optional
42+
- if type is the name of a plugin, the options are the options of that plugin
43+
- if type is `template`, the options here will override the ones in the template. Use full path to override, for example, `options.docker.registry.type`
44+
- cd: like `ci`, but stands for the list of CD pipelines. DevStream will execute CI first before CD
45+
46+
### 2.2 pipelineTemplate
47+
48+
Defined in the `pipelineTemplates` of the config, it's a list, with each element having the following keys:
49+
50+
- name: unique name of the pipelineTemplate, unique
51+
- type: corresponds to a plugin's name
52+
- options: options for that plugin
53+
54+
### 2.3 Local Variables
55+
56+
DevStream has a "var" section in the config, serving as global variables that can be referred to by all Tools and Apps.
57+
58+
Sometimes, however, we'd like to use the same DevOps tool with minor differences. For example, except the name of the project, everything else is different.
59+
60+
In this case, we can define a pipelineTemplate with a local variable, and when referring to it, we can pass different values to it:
61+
62+
```yaml hl_lines="13 15 23 30" title="pipelineTemplate and local variables"
63+
apps:
64+
- name: my-app
65+
spec:
66+
language: java
67+
framework: springboot
68+
repo:
69+
url: https://github.com/testUser/testApp.git
70+
branch: main
71+
ci:
72+
- type: github-actions # use a plugin directly without defining pipelineTemplates
73+
cd:
74+
- type: template # use a pipelineTemplate
75+
templateName: my-cd-template # corresponds to the name of the pipelineTemplate
76+
vars:
77+
appName: my-app # a local variable passed to the pipelineTemplate
78+
79+
pipelineTemplates:
80+
cd:
81+
- name: my-cd-template
82+
type: argocdapp
83+
options:
84+
app:
85+
name: [[ appName ]] # a local variable, passed to when referring to the template
86+
namespace: argocd
87+
destination:
88+
server: https://kubernetes.default.svc
89+
namespace: default
90+
source:
91+
valuefile: values.yaml
92+
path: charts/[[ appName ]]
93+
```
94+
95+
## 3 A Demo of the Whole Config
96+
97+
A whole config for an App:
98+
99+
```yaml
100+
apps:
101+
- name: testApp # name of the app
102+
spec: # app-specific info
103+
language: java # programming language of the app
104+
framework: springboot # framework of the app
105+
repo: # repository-related info for the app
106+
url: https://github.com/testUser/testApp.git
107+
branch: main
108+
repoTemplate: # optional, used for repository bootstrapping/scaffolding. If not empty, a repo will be created with scaffolding code
109+
url: https://github.com/devstream-io/dtm-repo-scaffolding-java-springboot.git
110+
vars:
111+
imageRepoOwner: repoOwner # variables used for repoTemplate
112+
ci: # CI pipelines, here we use github-actions
113+
- type: github-actions
114+
- name: testApp2
115+
spec:
116+
language: go
117+
framework: gin
118+
repo: # repository-related info for the app
119+
owner: test_user
120+
type: github
121+
branch: main
122+
repoTemplate: # optional, used for repository bootstrapping/scaffolding. If not empty, a repo will be created with scaffolding code
123+
org: devstream-io
124+
name: dtm-repo-scaffolding-java-springboot
125+
type: github
126+
ci: # CI pipelines, here we use github-actions
127+
- type: github-actions
128+
options:
129+
imageRepo:
130+
owner: repoOwner # override the plugin's options. Must use full YAML path.
131+
cd: # CD pipelines, here we use argocd
132+
- type: argocdapp
133+
```
134+
135+
If we apply this config, DevStream will create two repositories in GitHub, with scaffolding code provided by DevStream [SpringBoot](https://github.com/devstream-io/dtm-repo-scaffolding-java-springboot.git). App `testApp` will trigger CI in GitHub Actions upon each commit, and App `testApp2` will trigger build/push in GitHub Actions upon commit, and deploy using Argo CD.
136+
137+
### repo/repoTemplate Config
138+
139+
The `repo` and `repoTemplate` in the Config represent a code repository. You can define it with a single URL or a few key/values:
140+
141+
!!! note "two ways to configure code repo"
142+
143+
=== "using a single URL"
144+
145+
```yaml title=""
146+
repo:
147+
url: [email protected]:root/myapps.git # repo URL, supports both git and https
148+
apiURL: https://gitlab.example.com # not mandatory, if using gitlab and the URL protocol is git, here can be the GitLab API URL
149+
branch: "" # not mandatory, defaults to main for GitHub and master for GitLab
150+
```
151+
152+
This example shows that we use GitLab `[email protected]:root/myapps.git` for code clone, and DevStream uses `https://gitlab.example.com` to access GitLab API. Default branch is master.
153+
154+
=== "using detailed key/value config for the repo"
155+
156+
```yaml title=""
157+
repo:
158+
org: "" # only mandatory for GitHub organization
159+
owner："test_user" # if the repo belongs to a person. If the repo belongs to an org, use the org above.
160+
name: "" # optional, defaults to the name of the app
161+
baseURL: https://gitlab.example.com # optional. If GitLab, here we can put the GitLab domain.
162+
branch: master # not mandatory, defaults to main for GitHub and master for GitLab
163+
type: gitlab # mandatory, either gitlab or github
164+
```
165+
166+
This example shows that we use GitLab `https://gitlab.example.com`, repo name is the app name, belongs to owner `test_user`, with the default branch being "master".
167+
168+
### CI Config
169+
170+
The `CI` section in the config supports 4 types at the moment: `github-actions`/`gitlab-ci`/`jenkins-pipeline`/`template`.
171+
172+
`template` means to use a pipelineTemplate; and the other three types correspond to GitHub Actions, GitLab CI, and Jenkins, respectively.
173+
174+
Detailed config:
175+
176+
```yaml
177+
ci:
178+
- type: jenkins-pipieline # type of the CI
179+
options: # options for CI. If empty, CI will only run unit test.
180+
jenkins: # config for jenkins
181+
url: jenkins.exmaple.com # jenkins URL
182+
user: admin # jenkins user
183+
imageRepo: # docker image repo to be pushed to. If set, Ci will push the image after build.
184+
url: http://harbor.example.com # image repo URL. Defaults to dockerhub.
185+
owner: admin # image repo owner
186+
dingTalk: # dingtalk notification settings. If set, CI result will be pushed to dingtalk.
187+
name: dingTalk
188+
webhook: https://oapi.dingtalk.com/robot/send?access_token=changemeByConfig # callback URL for dingtalk.
189+
securityType: SECRET # use secret to encrypt dingtalk message
190+
securityValue: SECRETDATA # dingtalk secret encryption data
191+
sonarqube: # sonarqube config. If set, CI will test and execute sonarqube scan.
192+
url: http://sonar.example.com # sonarqube URL
193+
token: YOUR_SONAR_TOKEN # soanrqube token
194+
name: sonar_test
195+
```
196+
197+
The config above will trigger unit test and sonarqube code scan upon commit, then a Docker image will be built and pushed to dockerhub, and the result of the CI will be pushed to dingtalk.
198+
199+
If the same pipeline is required for multiple apps, the config can be long and redundant. So, DevStream provides the `template` type to share similar settings for diffrent Apps. Detailed example:
200+
201+
```yaml
202+
apps:
203+
- name: javaProject1
204+
spec:
205+
language: java
206+
framework: springboot
207+
repo:
208+
owner: testUser
209+
type: github
210+
repoTemplate:
211+
url: https://github.com/devstream-io/dtm-repo-scaffolding-java-springboot.git
212+
ci:
213+
- type: template # use a pipelineTemplate
214+
templateName: ci-pipeline # name of the pipelineTemplate
215+
vars:
216+
dingdingAccessToken: tokenForProject1 # variables for the pipelineTemplate
217+
dingdingSecretValue: secretValProject1
218+
- name: javaProject2
219+
spec:
220+
language: java
221+
framework: springboot
222+
repo:
223+
owner: testUser
224+
type: github
225+
repoTemplate:
226+
url: https://github.com/devstream-io/dtm-repo-scaffolding-java-springboot.git
227+
ci:
228+
- type: template # use a pipelineTemplate
229+
templateName: ci-pipeline # name of the pipelineTemplate
230+
vars:
231+
dingdingAccessToken: tokenForProject2 # variables for the pipelineTemplate
232+
dingdingSecretValue: secretValProject2
233+
234+
pipelineTemplates: # CI/CD pipeline templates
235+
- name: ci-pipeline # name of the pipelineTemplate
236+
type: jenkins-pipeline # type, supports jenkins-pipeline，github-actions and gitlab-ci at the moment
237+
options: # options, same as CI options
238+
jenkins:
239+
url: jenkins.exmaple.com
240+
user: admin
241+
imageRepo:
242+
url: http://harbor.example.com
243+
owner: admin
244+
dingTalk:
245+
name: dingTalk
246+
webhook: https://oapi.dingtalk.com/robot/send?access_token=[[ dingdingAccessToken ]] # local variable, passed to when referring to this template
247+
securityType: SECRET
248+
securityValue: [[ dingdingSecretValue ]] # local variable, passed to when referring to this template
249+
sonarqube:
250+
url: http://sonar.example.com
251+
token: sonar_token
252+
name: sonar_test
253+
254+
```
255+
256+
If we apply the above config, we will create two Jenkins pipelines for two apps, with the only difference being that the dingtalk notification will be sent to different groups.
257+
258+
### CD Config
259+
260+
At the moment, CD only supports `argocdapp`. Argo CD itself can be deployed with a Tool, and `argocdapp` is responsible for deploying the app in a Kubernetes cluster.
261+
262+
Detailed config example:
263+
264+
```yaml
265+
cd:
266+
- type: argocdapp
267+
options:
268+
app:
269+
name: hello # argocd app name
270+
namespace: argocd # argocd namespace
271+
destination:
272+
server: https://kubernetes.default.svc # Kubernetes cluster
273+
namespace: default # which namespace to deploy the app
274+
source:
275+
valuefile: values.yaml # helm values file
276+
path: charts/go-hello-http # helm chart path
277+
```

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

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -259,10 +259,10 @@ cd:
259259
- type: argocdapp
260260
options:
261261
app:
262-
name: hello # argocd 引用名称
262+
name: hello # argocd 应用名称
263263
namespace: argocd # argocd 的命名空间
264264
destination:
265-
server: https://kubernetes.default.svc # 部署的 kubernetes 服务地址
265+
server: https://kubernetes.default.svc # 部署的 Kubernetes 服务地址
266266
namespace: default # 应用要部署的命名空间
267267
source:
268268
valuefile: values.yaml # 项目中的 helm 变量文件名

0 commit comments

Comments
 (0)