Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Docs: Some Documents Enhancement #1147

Merged
merged 3 commits into from
Oct 8, 2022
Merged

Docs: Some Documents Enhancement #1147

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
3952386
docs: document "GitLab + Jenkins + Harbor On Premise Toolchain" Chine…
daniel-hutao Oct 6, 2022
3dee1c7
docs: document "jenkins-pipeline Plugin" Chinese version add GitHub d…
daniel-hutao Oct 6, 2022
86681d9
fix: typos "develoeprs" in the document
daniel-hutao Oct 6, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
122 changes: 67 additions & 55 deletions docs/best-practices/gitlab-jenkins-harbor.zh.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,14 +30,14 @@

!!! hint "提示"

上述插件不是必选集，你可以根据实际情况灵活调整。比如你本地已经有 GitLab 环境了，那么你可以果断 `gitlab-ce-docker` 插件。
上述插件不是必选集，你可以根据实际情况灵活调整。比如你本地已经有 GitLab 环境了，那么你可以果断忽略 `gitlab-ce-docker` 插件。

上述插件的依赖关系为：

- jenkins-pipeline -> jenkins, gitlab-ce-docker, repo-scaffolding, harbor
- repo-scaffolding -> gitlab-ce-docker

!!! note "注意"
!!! note "说明"

A -> B 表示的是 A 依赖 B。

Expand Down Expand Up @@ -96,7 +96,7 @@

=== "gitlab-ce-docker 插件"

gitlab-ce-docker 插件的配置如下：
gitlab-ce-docker 插件的配置如下（该插件的详细文档参见[ gitlab-ce-docker 插件文档](../plugins/gitlab-ce-docker.zh.md)）：

```yaml title="Plugin Config with gitlab-ce-docker"
- name: gitlab-ce-docker
Expand All @@ -111,12 +111,10 @@
rmDataAfterDelete: false
imageTag: "rc"
```

关于 gitlab-ce-docker 插件的详细文档可以看[ gitlab-ce-docker 插件文档](../plugins/gitlab-ce-docker.zh.md)。

=== "jenkins 插件"

jenkins 插件的配置如下：
jenkins 插件的配置如下（该插件的详细文档参见[ jenkins 插件文档](../plugins/jenkins.zh.md)）：

```yaml title="Plugin Config with jenkins"
- name: jenkins
Expand Down Expand Up @@ -160,12 +158,10 @@
JCasC:
defaultConfig: true
```

关于 jenkins 插件的详细文档可以看[ jenkins 插件文档](../plugins/jenkins.zh.md)。

=== "harbor 插件"

harbor 插件的配置如下：
harbor 插件的配置如下（该插件的详细文档参见[ harbor 插件文档](../plugins/harbor.zh.md)）：

```yaml title="Plugin Config with harbor"
- name: harbor
Expand Down Expand Up @@ -207,8 +203,6 @@
accessMode: ReadWriteOnce
size: 1Gi
```

关于 harbor 插件的详细文档可以看[ harbor 插件文档](../plugins/harbor.zh.md)。

## 5、开始部署 GitLab + Jenkins + Harbor 工具链

Expand Down Expand Up @@ -401,42 +395,44 @@ Stdout: 53e30ad85faf7e9d6d18764450bb8458db46b388b690b7c8b7a7cc6d0deb283a
1. 执行命令：`kubectl edit cm coredns -n kube-system`；
2. 在 hosts(第20行左右) 部分添加和 /etc/hosts 一样的记录。

由于演示环境是 minikube 方式部署的 k8s 单节点集群，所以 DNS 问题相对复杂一些。首先你需要获取 minikube ip：
??? tip "minikube 环境额外配置内容"
steinliber marked this conversation as resolved.
Show resolved Hide resolved

```shell
$ minikube ip
192.168.49.2
```
如果你的环境是 docker-in-docker 的方式部署的 k8s 集群，比如用了 minikube，这时候 DNS 问题就会相对复杂一些。首先你需要获取 minikube ip：

如果你执行 `kubectl get ingress -A` 命令，可以看到 Ingress 用的 IP 地址就是这个：

```shell
NAMESPACE NAME CLASS HOSTS ADDRESS PORTS AGE
harbor harbor-ingress nginx harbor.example.com 192.168.49.2 80 129m
jenkins jenkins nginx jenkins.example.com 192.168.49.2 80 130m
```
```shell
$ minikube ip
192.168.49.2
```

然而主机 IP 并不是192.168.49.2，比如演示环境里是 44.33.22.11。因此想要访问到 GitLab、Jenkins、Harbor 几个服务并不是太容易。
如果你执行 `kubectl get ingress -A` 命令，可以看到 Ingress 用的 IP 地址就是这个：

```shell
NAMESPACE NAME CLASS HOSTS ADDRESS PORTS AGE
harbor harbor-ingress nginx harbor.example.com 192.168.49.2 80 129m
jenkins jenkins nginx jenkins.example.com 192.168.49.2 80 130m
```

你需要在 `/etc/hosts` 里添加如下配置：
然而主机 IP 并不是192.168.49.2，比如是 44.33.22.11。因此想要访问到 GitLab、Jenkins、Harbor 几个服务并不是太容易。

```shell title="dns records"
44.33.22.11 gitlab.example.com
192.168.49.2 jenkins.example.com harbor.example.com
```
你需要在 `/etc/hosts` 里添加如下配置：

```shell title="dns records"
44.33.22.11 gitlab.example.com
192.168.49.2 jenkins.example.com harbor.example.com
```

因为 GitLab 是使用 docker 方式部署的，而 Jenkins 和 Harbor 是通过 k8s 方式部署，然后通过 Ingress 方式暴露服务，所以这里的 IP 并不一样。
因为 GitLab 是使用 docker 方式部署的，而 Jenkins 和 Harbor 是通过 k8s 方式部署，然后通过 Ingress 方式暴露服务，所以这里的 IP 并不一样。

这时候在当前主机上，就可以分别通过如下地址访问到 GitLab、Jenkins 和 Harbor 了：
这时候在当前主机上，就可以分别通过如下地址访问到 GitLab、Jenkins 和 Harbor 了：

- `GitLab`: http://gitlab.example.com:30080
- `Jenkins`: http://jenkins.example.com
- `Harbor`: http://harbor.example.com
- `GitLab`: http://gitlab.example.com:30080
- `Jenkins`: http://jenkins.example.com
- `Harbor`: http://harbor.example.com

接着你还需要修改 `CoreDNS` 的配置，在 ConfigMap `kube-system/coredns` 中添加静态解析记录：
接着你还需要修改 `CoreDNS` 的配置，在 ConfigMap `kube-system/coredns` 中添加静态解析记录：

1. 执行命令：`kubectl edit cm coredns -n kube-system`；
2. 在 hosts(第20行左右) 部分添加 `44.33.22.11 gitlab.example.com` 和 `192.168.49.2 harbor.example.com` 这两条静态域名解析记录。这样 Jenkins 才能顺利通过域名访问到 GitLab 和 Harbor。
1. 执行命令：`kubectl edit cm coredns -n kube-system`；
2. 在 hosts(第20行左右) 部分添加 `44.33.22.11 gitlab.example.com` 和 `192.168.49.2 harbor.example.com` 这两条静态域名解析记录。这样 Jenkins 才能顺利通过域名访问到 GitLab 和 Harbor。

这样 Jenkins 才能通过域名访问到 GitLab。

Expand Down Expand Up @@ -466,13 +462,17 @@ docker exec gitlab cat /etc/gitlab/initial_root_password | grep Password:

### 6.3、访问 Jenkins

前面你可能已经通过 `curl http://jenkins.example.com` 在主机内验证了 Jenkins 的网络连通性，但是远程想通过域名访问 Jenkins 并不容易。这时候你可以通过执行如下命令暴露 Jenkins 服务：
前面你可能已经通过 `curl http://jenkins.example.com` 在主机内验证了 Jenkins 的网络连通性，想要远程通过域名访问 Jenkins，你需要在自己的 PC 里配置 `44.33.22.11 jenkins.example.com` 静态域名解析记录。

```shell title="Port Forward"
kubectl port-forward service/jenkins --address 0.0.0.0 -n jenkins 32000:8080
```
??? tip "minikube 环境额外配置内容"

然后在自己的 PC 里配置 `44.33.22.11 jenkins.example.com` 静态域名解析记录，接着在浏览器里通过 `http://jenkins.example.com:32000` 访问到 Jenkins：
minikube 环境想要远程通过域名访问 Jenkins 并不容易。这时候你可以通过执行如下命令暴露 Jenkins 服务：

```shell title="Port Forward"
kubectl port-forward service/jenkins --address 0.0.0.0 -n jenkins 32000:8080
```

接着在浏览器里通过 `http://jenkins.example.com:32000` 就可以访问到 Jenkins 了：

<figure markdown>
![Jenkins login](./gitlab-jenkins-harbor/jenkins-login.png){ width="1000" }
Expand All @@ -488,13 +488,18 @@ Jenkins 的 admin 用户初始登录密码是 `changeme`，如果你仔细看了

### 6.4、访问 Harbor

前面你可能已经通过 `curl http://harbor.example.com` 在主机内验证了 Harbor 的网络连通性，同样你可以通过 `docker login harbor.example.com:80` 命令来尝试登录 Harbor。不过远程通过域名访问 Harbor 同样不容易。这时候你可以通过执行如下命令暴露 Harbor 服务：
前面你可能已经通过 `curl http://harbor.example.com` 在主机内验证了 Harbor 的网络连通性，同样你可以通过 `docker login harbor.example.com:80` 命令来尝试登录 Harbor。
然后在自己的 PC 里配置 `44.33.22.11 harbor.example.com` 静态域名解析记录。

```shell title="Port Forward"
kubectl port-forward service/harbor-portal --address 0.0.0.0 -n harbor 30180:80
```
??? tip "minikube 环境额外配置内容"

然后在自己的 PC 里配置 `44.33.22.11 harbor.example.com` 静态域名解析记录，接着在浏览器里通过 `http://harbor.example.com:30180` 访问到 Harbor：
minikube 环境想要远程通过域名访问 Harbor 同样不容易。这时候你可以通过执行如下命令暴露 Harbor 服务：

```shell title="Port Forward"
kubectl port-forward service/harbor-portal --address 0.0.0.0 -n harbor 30180:80
```

接着你可以在浏览器里通过 `http://harbor.example.com:30180` 访问到 Harbor：

<figure markdown>
![Harbor login](./gitlab-jenkins-harbor/harbor-login.png){ width="1000" }
Expand All @@ -503,15 +508,18 @@ kubectl port-forward service/harbor-portal --address 0.0.0.0 -n harbor 30180:80

Harbor 的 admin 用户初始登录密码是 `Harbor12345`，你可以尝试用 `admin/Harbor12345` 登录 Harbor 检查功能是否正常，不过你同样不需要在 Harbor 上进行任何额外的操作。

// TODO(daniel-hutao): Harbor dashboard 截图
<figure markdown>
![Harbor dashboard](./gitlab-jenkins-harbor/harbor-dashboard.png){ width="1000" }
<figcaption>Harbor dashboard</figcaption>
</figure>

## 7、准备流水线相关插件的配置（plugin config）

本节继续介绍 repo-scaffolding 和 jenkins-pipeline 两个插件对应的 plugin configs。你可以点击下方 tag 按钮进行切换：

=== "repo-scaffolding 插件"

repo-scaffolding 插件的配置如下：
repo-scaffolding 插件的配置如下（该插件的详细文档参见[ repo-scaffolding 插件文档](../plugins/repo-scaffolding.zh.md)）：

```yaml
- name: repo-scaffolding
Expand All @@ -529,11 +537,11 @@ Harbor 的 admin 用户初始登录密码是 `Harbor12345`，你可以尝试用
repo: dtm-repo-scaffolding-java-springboot
repoType: github
```

关于 repo-scaffolding 插件的详细文档可以看[ repo-scaffolding 插件文档](../plugins/repo-scaffolding.zh.md)。

=== "jenkins-pipeline 插件"

jenkins-pipeline 插件的配置如下（该插件的详细文档参见[ jenkins-pipeline 插件文档](../plugins/jenkins-pipeline.zh.md)）：

```yaml
- name: jenkins-pipeline
instanceID: default
Expand All @@ -554,14 +562,18 @@ Harbor 的 admin 用户初始登录密码是 `Harbor12345`，你可以尝试用
user: admin
```

!!! Warning "注意"

这里需要注意的是 Jenkins 的访问地址需要使用 `http://44.33.22.11:32000`，而不能用域名，因为当前部署架构下 GitLab 并不能解析到 `jenkins.example.com` 这个域名。
而且 GitLab 也无法直接访问到 `http://44.33.22.11:32000` 这个地址，这里还需要通过 kubectl port-forward 的访问转发一次流量。
另外 minikube 环境里 GitLab 也无法直接访问到 `http://44.33.22.11:32000` 这个地址，这里还需要通过 kubectl port-forward 的访问转发一次流量。

在正式的企业环境里，只需要保证 GitLab 能够访问到 Jenkins 即可，如果你的企业里可以通过配置 DNS 等方式让 GitLab 能够完成 jenkins.example.com 域名的解析，
而且对应的 IP (和端口)可以从 GitLab 访问到，那就可以在这里配置域名。

??? tip "minikube 环境额外配置内容"

接着我们执行如下命令保证 Jenkins 可以从 `http://44.33.22.11:32000` 访问到：
你可以执行如下命令保证 Jenkins 可以从 `http://44.33.22.11:32000` 访问到：

```shell title="Port Forward"
kubectl port-forward service/jenkins --address 0.0.0.0 -n jenkins 32000:8080
```
Expand Down
Binary file added docs/best-practices/gitlab-jenkins-harbor/harbor-dashboard.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
2 changes: 1 addition & 1 deletion docs/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

## What is DevStream?

DevStream is an open-source DevOps toolchain manager that is of the develoeprs, by the develoeprs, for the develoeprs.
DevStream is an open-source DevOps toolchain manager that is of the developers, by the developers, for the developers.

Discover the DevOps practice that suits you best. DevStream will take care of the rest.

Expand Down
50 changes: 41 additions & 9 deletions docs/plugins/jenkins-pipeline.zh.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,14 +2,16 @@

`jenkins-pipeline` 插件用于打通 GitHub/GitLab 和 Jenkins，实现自动化创建 Jenkins Pipeline 的功能。

*注意：当前只支持 GitLab，GitHub 将在近期被支持。*

本文将演示：

1. 通过 [`repo-scaffolding`](../repo-scaffolding.zh) 插件在 GitLab 上创建一个 Java Sprint Boot 项目脚手架；
2. 通过 `jenkins-pipeline` 插件在 Jenkins 上创建一条 Java Spring Boot 的 CI 流水线；
3. 通过 `jenkins-pipeline` 插件实现在 GitLab 和 Jenkins 上分别配置相应参数，实现当 GitLab 上的代码库有 push 或者 merge 事件时，自动触发 Jenkins 上的流水线运行，同时流水线的执行结果自动回写到 GitLab 上。

!!! tip "提示"

GitHub 与 GitLab 的主要区别在于 DevStream tool config 的 options.scm.cloneURL 以及所需要的 token 等不同。

## 1、前置要求

**必须满足**
Expand All @@ -20,7 +22,9 @@
- Jenkins 与 GitLab、Harbor 网络互通
- 执行 dtm 的主机与 Jenkins、GitLab 网络互通

*注意：当前插件暂时只支持对接使用 dtm 部署的 Jenkins。*
!!! warning "注意"

当前插件暂时只支持对接使用 dtm 部署的 Jenkins。

本文基于如下环境编写：

Expand All @@ -38,6 +42,16 @@ export GITLAB_TOKEN=YOUR_GITLAB_TOKEN
export GITLAB_SSHKEY=YOUR_REPO_PRIVATE_KEY
```

!!! tip "提示"

如果是 GitHub，则这里的环境变量改成：

```shell
export IMAGE_REPO_PASSWORD=YOUR_IMAGE_REPO_PASSWORD
export GITHUB_TOKEN=YOUR_GITHUB_TOKEN
export GITHUB_SSHKEY=YOUR_REPO_PRIVATE_KEY
```

然后准备 DevStream 插件配置：

```yaml
Expand Down Expand Up @@ -123,35 +137,53 @@ tools:

首先你可以在 GitLab 上可以看 repo scaffolding 的效果，dtm 为你创建了一个 Java Spring Boot 项目脚手架：

![repo-scaffolding](./jenkins-pipeline/repo-scaffolding.png)
<figure markdown>
![Repo scaffolding](./jenkins-pipeline/repo-scaffolding.png){ width="1000" }
<figcaption>Repo scaffolding</figcaption>
</figure>

- **Pipeline**

接着你可以在 Jenkins 上看到刚才 dtm 为你创建的 Pipeline：

![pipeline](./jenkins-pipeline/pipeline.png)
<figure markdown>
![Pipeline](./jenkins-pipeline/pipeline.png){ width="1000" }
<figcaption>Pipeline</figcaption>
</figure>

如果你点开这个 test-job，就能看到它已经被触发了一次，执行结果如下：

![pipeline](./jenkins-pipeline/pipeline-console.png)
<figure markdown>
![Pipeline console](./jenkins-pipeline/pipeline-console.png){ width="1000" }
<figcaption>Pipeline console</figcaption>
</figure>

- **状态回写**

然后你可以回到 GitLab，看一下 Jenkins Pipeline 的执行结果有没有被成功回写：

![gitlab status](./jenkins-pipeline/gitlab-status.png)
<figure markdown>
![GitLab status](./jenkins-pipeline/gitlab-status.png){ width="1000" }
<figcaption>GitLab status</figcaption>
</figure>

- **检查镜像**

通过 Jenkins 的日志你可以找到刚才 push 的镜像地址为 `harbor.example.com:80/library/spring-demo:latest`：

![jenkins logs](./jenkins-pipeline/jenkins-logs.png)
<figure markdown>
![Jenkins' logs](./jenkins-pipeline/jenkins-logs.png){ width="1000" }
<figcaption>Jenkins' logs</figcaption>
</figure>

// TODO(daniel-hutao): 补充 Harbor 截图

最后你可以通过 `docker pull` 下载该镜像：

![docker pull](./jenkins-pipeline/docker-pull.png)
<figure markdown>
![Docker pulling](./jenkins-pipeline/docker-pull.png){ width="1000" }
<figcaption>Docker pulling</figcaption>
</figure>

## 配置详解

Expand Down